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"

Related MCP server: Knowledge Graph Memory Server

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

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

Knowledge Graph Tools

Observation Types

Relationship Types

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

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