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.

Related MCP server: Memory MCP

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

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"]
    }
  }
}

Tools

11 MCP tools, organized by function.

Store & retrieve

Browse

Connect

Maintain

Explore

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

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.

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.

• 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

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

The database uses WAL mode for safe concurrent access.

License

MIT