<p align="center">
  <img src="assets/banner.svg" alt="claude-memory" width="680">
</p>

# claude-memory

Persistent, searchable memory for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) — backed by SQLite, semantic embeddings, and full-text search. Connected via [MCP](https://modelcontextprotocol.io).

Everything runs locally. No API keys. No cloud services. Your data never leaves your machine.

---

> **Claude remembers.** Across sessions. Across projects. Forever.

```
You: "What do you remember about my auth setup?"

Claude: *searches 847 memories semantically*
        *finds 3 relevant entries across 2 projects*
        *ranks by importance, recency, and relevance*

"Based on my memory: you use JWT with refresh token rotation,
 the auth middleware lives in src/middleware/auth.ts, and you
 switched from Passport to a custom solution last month because..."
```

## Why this exists

Claude Code ships with `MEMORY.md` — a per-project markdown file, capped at ~200 lines, loaded in full every message. It works for small notes. It doesn't scale.

| | `MEMORY.md` | `claude-memory` |
|---|---|---|
| **Scope** | Single project | Global — all projects, all sessions |
| **Search** | None (full file loaded every turn) | Semantic + full-text hybrid search |
| **Capacity** | ~200 lines before truncation | Unlimited (SQLite) |
| **Structure** | Flat markdown | Categories, tags, relations, importance |
| **Duplicates** | Manual | Automatic 85% similarity detection |
| **Relevance** | All or nothing | Importance scoring with time decay |
| **Connections** | None | Typed relationship graph |

## Quick start

> Requires **Node.js 18+**

```bash
git clone https://github.com/Tim-Fischer-zh/claude-memory.git
cd claude-memory
./install.sh
```

Restart Claude Code. The embedding model (~23MB) downloads on first use — subsequent starts are instant.

To uninstall:

```bash
./uninstall.sh          # backs up your database
./uninstall.sh --force  # deletes everything, no backup
```

<details>
<summary>What the installer does</summary>
<br>

1. Copies source to `~/.claude/memory-server/`
2. Runs `npm install` and compiles TypeScript
3. Registers the MCP server in `~/.claude.json` (merges safely — won't overwrite your other servers)
4. Installs Claude rules to `~/.claude/rules/` (won't overwrite custom rules)

```json
// Added to ~/.claude.json
{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["~/.claude/memory-server/dist/index.js"]
    }
  }
}
```
</details>

---

## Tools

11 MCP tools, organized by function.

### Store & retrieve

| Tool | What it does |
|:-----|:------------|
| `remember` | Store knowledge with category, tags, and source tracking. Checks for duplicates — warns if >85% similar memory exists. |
| `recall` | Hybrid search: semantic similarity + full-text matching + importance scoring. Finds "JWT middleware" when you search "auth setup". |
| `update_memory` | Modify content, category, tags, or importance. Auto re-embeds on content change. |
| `forget` | Delete a memory and cascade to its embedding and relationships. |

### Browse

| Tool | What it does |
|:-----|:------------|
| `list_categories` | Overview of categories, entry counts, and embedding model status. |


### Connect

| Tool | What it does |
|:-----|:------------|
| `relate` | Link two memories: `related`, `supersedes`, `caused_by`, `contradicts`, `supports`, `depends_on`. |
| `find_related` | Traverse the relationship graph + find semantically similar entries. |

### Maintain

| Tool | What it does |
|:-----|:------------|
| `consolidate` | Scan for clusters of duplicate/similar memories. Returns groups ranked by similarity. |
| `merge` | Combine multiple memories into one. Preserves relationships, merges tags, deletes originals. |

### Explore

| Tool | What it does |
|:-----|:------------|
| `visualize` | Open the memory graph UI in the browser — force-directed graph, categories, search, stats. |

---

## How it works

### Semantic search

Memories are embedded locally using [all-MiniLM-L6-v2](https://huggingface.co/Xenova/all-MiniLM-L6-v2) (384 dimensions) via [Transformers.js](https://huggingface.co/docs/transformers.js). Searching *"immutability preferences"* finds a memory stored as *"always use functional patterns, never mutate state"* — no keyword overlap needed.

The model loads in the background. Until ready, search falls back to full-text only — the server is always responsive.

### Hybrid ranking

Every search combines three signals:

```
score = semantic_similarity × 0.5
      + full_text_relevance × 0.2
      + importance_score    × 0.3
```

Importance blends manual priority, access frequency, and pin status with time decay:

```
importance = (manual_importance × 0.4 + access_frequency × 0.3 + pinned × 0.3)
           × decay

decay = pinned ? 1.0 : e^(-0.005 × days_since_last_access)
```

Frequently accessed, manually prioritized, or pinned memories rank higher. Unused memories fade — unless pinned.

### Deduplication

When storing, the server checks cosine similarity against all existing memories. If a match exceeds **85% similarity**, it returns the existing memory instead of creating a duplicate.

### Relationship graph

Memories form a directed graph:

```
"Use JWT for auth"       ──caused_by──▶  "Security audit findings"
"Switch to bun"          ──supersedes──▶  "Use npm for all projects"
"Redis caching layer"    ──depends_on──▶  "Redis deployment config"
"Use REST not GraphQL"   ──contradicts─▶  "Evaluate GraphQL for API"
```

`find_related` traverses explicit edges and surfaces semantically similar entries — giving you both explicit and implicit connections.

### Consolidation

Over time, small related memories accumulate:

```
"Tim uses TypeScript for all projects"     ┐
"Always use strict TypeScript"              ├── 87% similar → merge candidates
"TypeScript with strict mode is preferred"  ┘
```

`consolidate` finds these clusters. `merge` combines them into one clean entry, preserving all relationships.

### Source tracking

Every memory can record where it came from:

- **`source_project`** — project directory (e.g. `~/projects/my-app`)
- **`source_session`** — Claude Code session ID
- **`source_file`** — file being worked on

### Agent support

The installed rules ensure every agent and subagent:

1. Calls `recall` before starting work to load relevant context
2. Has access to memory tools for storing findings
3. Sets `source_project` when remembering

This works with the Agent tool, Tasks, agent teams, swarms, and pipelines.

---

## Performance

<p align="center">
  <img src="assets/benchmarks.svg" alt="Benchmark results" width="800">
</p>

<details>
<summary>Run the benchmark yourself</summary>
<br>

```bash
node tools/benchmark.js
```

Seeds 1,000 test memories if your database has fewer than 50, runs all benchmarks, then cleans up. Your real data is never modified.
</details>

---

## Visualizer

Built-in web UI for exploring your memory database — force-directed graph, category filters, search, and live stats.

```bash
# standalone
node tools/visualize.js

# or via Claude
"show me my memory"  →  Claude runs the visualize tool
```

Open [localhost:4200](http://localhost:4200).

<details>
<summary>Features</summary>
<br>

- **Force graph** — D3 force-directed layout, edges for typed relationships
- **Cluster mode** — group nodes by category
- **Radial mode** — circular layout by category
- **Sidebar** — searchable, filterable card list synced with the graph
- **Tooltips** — hover any node for content, tags, importance
- **Stats bar** — total memories, relations, embeddings, recalls, pinned count
- **Color-coded** — distinct colors per category, edge colors per relation type
- **Interactive** — drag, zoom, click-to-highlight

</details>

---

## Architecture

```
┌─────────────┐     stdio/MCP     ┌──────────────────┐     ┌──────────┐
│             │◄─────────────────►│  Memory Server   │────►│  SQLite  │
│  Claude Code │                   │                  │     │  + FTS5  │
│             │                   │  index.ts        │     │  + WAL   │
└─────────────┘                   │  db.ts           │     └──────────┘
                                  │  embeddings.ts   │────►┌──────────┐
                                  └──────────────────┘     │ MiniLM   │
                                                           │ L6-v2    │
                                                           └──────────┘
```

### Schema

```sql
memories (
  id, content, category, tags,
  source_project, source_session, source_file,
  importance, access_count, last_accessed_at, pinned,
  created_at, updated_at
)

memory_embeddings (
  memory_id  → memories.id,
  embedding  BLOB  -- Float32Array × 384
)

memory_relations (
  source_id  → memories.id,
  target_id  → memories.id,
  relation_type  -- related | supersedes | caused_by | contradicts | supports | depends_on
)

memories_fts  -- FTS5 virtual table over content, category, tags
```

### Project structure

```
src/
  index.ts          MCP server — tool definitions, request handling
  db.ts             Database — schema, queries, scoring, relations
  embeddings.ts     Embedding model — lazy loading, cosine similarity
rules/
  memory.md         Claude rule — automatic memory usage
  agents.md         Agent rule — memory-aware agent spawning
tools/
  visualize.js      Web UI — D3 force graph, category explorer
  benchmark.js      Performance benchmarks
install.sh          Safe installer (preserves existing config)
uninstall.sh        Uninstaller with database backup
```

### Storage paths

| Path | Contents |
|:-----|:---------|
| `~/.claude/memory-server/dist/` | Compiled server |
| `~/.claude/memory-server/memory.db` | Your knowledge base |
| `~/.claude/memory-server/models/` | Cached embedding model (~23MB) |
| `~/.claude/rules/claude-memory.md` | Installed Claude rule |
| `~/.claude/rules/claude-memory-agents.md` | Agent awareness rule |

The database uses WAL mode for safe concurrent access.

---

## License

MIT