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