# 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

```bash
# 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:

```json
{
  "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):
```json
"env": { "MEMORY_DIR": ".claude/memory" }
```

**Shared memory across projects**:
```json
"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