claude-memory-fts

Long-term memory MCP server for Claude Code. Stores facts in a local SQLite database with hybrid search (FTS5 + semantic vector similarity) and automatic context injection.

Features

• Hybrid search — FTS5 keyword search + semantic vector similarity, merged via Reciprocal Rank Fusion (RRF)
• Semantic understanding — find memories by meaning, not just keywords (powered by all-MiniLM-L6-v2 embeddings)
• Auto context injection — top 30 most important memories injected into every prompt via hook
• Importance ranking — facts ranked by access frequency, recency decay, and category weight
• Access tracking — tracks how often each memory is accessed
• Upsert — automatically updates existing facts instead of duplicating
• Categorized — organize by type: preference, decision, technical, project, workflow, personal, general
• MCP Resources — exposes `memory://context` resource for session context
• Zero config — works out of the box, stores data in `~/.claude/memory.db`

Install

# Add to Claude Code
claude mcp add memory -- npx claude-memory-fts

# Auto-configure context injection hook (recommended)
npx claude-memory-fts --setup-hook

The `--setup-hook` command automatically:

1. Creates `~/.claude/scripts/memory-context.sh`

2. Adds a `UserPromptSubmit` hook to `~/.claude/settings.json`

3. Top 30 memories are injected into every prompt automatically

CLI Commands

Configuration

Example with custom path:

claude mcp add memory -e MEMORY_DB_PATH=/path/to/my/memory.db -- npx claude-memory-fts

Tools

`memory_save`

Save a fact to long-term memory.

`memory_search`

Hybrid search: runs FTS5 and semantic search in parallel, merges results with RRF. Falls back to LIKE for partial matches.

`memory_update`

Update a memory's content or category by ID.

`memory_list`

List all saved memories grouped by category.

`memory_delete`

Delete a memory by ID.

Resources

`memory://context`

MCP resource exposing top 30 facts ranked by importance score:

• Access frequency — frequently accessed facts score higher (capped at 20 points)
• Recency — recently updated facts score higher (10 points, decays over 90 days)
• Category weight — preference/decision (3), workflow/technical (2), project/personal (1), general (0)

How It Works

Search Pipeline

1. FTS5 + BM25 and semantic vector similarity run in parallel

2. Results are merged and deduplicated using Reciprocal Rank Fusion (k=60)

3. Facts appearing in both lists get naturally boosted

4. If both return empty, falls back to LIKE substring matching

5. Access count is tracked on every search hit

Embeddings

• Model: all-MiniLM-L6-v2 (384 dimensions, ~23MB)
• Generated locally via `@xenova/transformers` — no API calls, no data leaves your machine
• Embeddings are created on save and backfilled on server startup
• Cosine similarity with 0.3 threshold to filter noise

Storage

• SQLite with WAL mode for fast concurrent reads/writes
• FTS5 virtual table synced via triggers for real-time full-text indexing
• Embeddings stored as BLOB columns alongside facts

Development

git clone https://github.com/kurovu146/claude-memory-mcp.git
cd claude-memory-mcp
npm install
npm run build
npm test

License

MIT