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

claude-memory

Persistent, searchable memory for Claude Code — backed by SQLite, semantic embeddings, and full-text search. Connected via MCP.

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+

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:

./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)

// 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 (384 dimensions) via 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>

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.

# standalone
node tools/visualize.js

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

Open 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

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