Claude Memory MCP Server

A Model Context Protocol (MCP) server that provides persistent memory for Claude Code sessions. Records observations, builds knowledge graphs, and enables cross-session learning.

Quick Start

1. Clone the repository

# Clone to a permanent location (e.g., ~/tools or /opt)
git clone https://github.com/eliasonAdvising/claude-memory-mcp.git ~/tools/claude-memory-mcp
cd ~/tools/claude-memory-mcp
uv sync

2. Add to your project

Create or edit .mcp.json in your project root:

{
  "mcpServers": {
    "memory": {
      "command": "uv",
      "args": ["--directory", "/home/YOUR_USER/tools/claude-memory-mcp", "run", "claude-memory"],
      "env": {
        "MEMORY_DIR": ".claude/memory"
      }
    }
  }
}

Important: Replace /home/YOUR_USER/tools/claude-memory-mcp with the actual path where you cloned the repo.

3. Restart Claude Code

The MCP server loads when Claude Code starts. After adding the configuration, restart Claude Code to activate the memory tools.

4. Verify installation

In Claude Code, the memory tools should now be available. Try:

• Ask Claude to "add an observation about something you learned"
• Ask Claude to "show the memory index"

Features

• Observation Memory: Record discoveries, gotchas, decisions, and trade-offs
• Knowledge Graph: Store domain concepts with typed relationships
• Progressive Disclosure: Index shows what exists; fetch details on-demand
• Cross-Session Learning: Memory persists across Claude Code sessions
• Domain Agnostic: Works for any domain (programming, accounting, medicine, etc.)

Configuration

Environment Variable	Default	Description
MEMORY_DIR	.claude/memory	Directory for memory YAML files (relative to project root)
LOG_LEVEL	INFO	Logging level (DEBUG, INFO, WARNING, ERROR)

Memory Location Options

Per-project memory (recommended for most cases):

"env": { "MEMORY_DIR": ".claude/memory" }

Shared memory across projects:

"env": { "MEMORY_DIR": "/home/YOUR_USER/.claude-memory" }

Tools Reference

Observation Tools

Tool	Description
memory_add_observation	Record an observation (discovery, gotcha, decision, trade-off, etc.)
memory_get_observation	Retrieve a specific observation by ID
memory_search_observations	Search observations by keyword
memory_get_timeline	Get observations around a specific point in time
memory_get_index	Get progressive disclosure index (shows what exists, retrieval cost)

Knowledge Graph Tools

Tool	Description
memory_add_concept	Add a concept to a knowledge cluster
memory_get_concept	Retrieve a concept and its details
memory_find_solutions	Find concepts that solve a problem via graph traversal
memory_find_related	Find related concepts via BFS traversal
memory_add_connection	Add a typed relationship between concepts
memory_get_knowledge_index	Get knowledge graph overview

Observation Types

Type	Icon	Use For
discovery	💡	New insights or learnings
gotcha	🔴	Traps, pitfalls, things that don't work as expected
decision	🟤	Choices made with reasoning
trade-off	⚖️	Compromises between competing concerns
problem-solution	🟡	Problem encountered and how it was solved
pattern-emerged	⚡	Recurring patterns noticed
tool-success	🔧	Tool usage that worked well
tool-failure	❌	Tool usage that failed
note	📝	General notes

Relationship Types

The knowledge graph supports typed relationships for conceptual (not just keyword) retrieval:

Relationship	Meaning	Example
resolved_by	X is solved/fixed by Y	"timeout_error" resolved_by "retry_with_backoff"
prevents	X prevents Y from happening	"input_validation" prevents "sql_injection"
causes	X causes Y	"memory_leak" causes "oom_crash"
enables	X makes Y possible	"async_io" enables "concurrent_requests"
requires	X needs Y first	"deployment" requires "passing_tests"
depends_on	X depends on Y (context-sensitive)	"feature_x" depends_on "api_v2"
is_a	X is a type of Y	"postgresql" is_a "relational_database"
part_of	X is a component of Y	"auth_middleware" part_of "api_gateway"
related_to	X and Y are connected	"caching" related_to "performance"
contrasts_with	X is an alternative to Y	"rest_api" contrasts_with "graphql"

Memory File Structure

.claude/memory/
├── observations.yaml    # Session observations with metadata
└── knowledge.yaml       # Knowledge graph with clusters and connections

Both files are YAML for human readability and LLM-native processing.

Usage Examples

Recording a discovery

"Claude, I just learned that the API rate limits reset at midnight UTC, not per-request.
Please record this as a discovery."

Finding solutions to a problem

"What solutions do we have for handling rate limit errors?"

Claude will use memory_find_solutions to traverse the knowledge graph.

Building domain knowledge

"Add a concept: In our accounting system, journal entries must balance (debits = credits).
This is part of the double-entry bookkeeping cluster."

Adding to Multiple Projects

You only need to clone the repository once. Then add the .mcp.json configuration to each project where you want memory.

Each project gets its own memory (stored in .claude/memory/ within that project), unless you configure a shared MEMORY_DIR.

Troubleshooting

Tools not appearing

1. Check that .mcp.json is in your project root
2. Verify the path to claude-memory-mcp is correct
3. Restart Claude Code

Memory not persisting

1. Check MEMORY_DIR path exists and is writable
2. Look for error messages in Claude Code output

"uv: command not found"

Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh

License

MIT