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

| Command | Description | |---|---| | npx claude-memory-fts | Start MCP server (used by Claude Code) | | npx claude-memory-fts --context | Output top 30 facts (used by hook script) | | npx claude-memory-fts --setup-hook | Auto-configure context injection hook |

Configuration

| Environment Variable | Default | Description | |---|---|---| | MEMORY_DB_PATH | ~/.claude/memory.db | Path to the SQLite database file |

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.

| Parameter | Type | Required | Description | |---|---|---|---| | fact | string | yes | The information to remember | | category | string | no | One of: preference, decision, personal, technical, project, workflow, general |

memory_search

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

| Parameter | Type | Required | Description | |---|---|---|---| | keyword | string | yes | Search keyword or phrase | | limit | number | no | Max results (default: 10) |

memory_update

Update a memory's content or category by ID.

| Parameter | Type | Required | Description | |---|---|---|---| | id | number | yes | Memory ID | | fact | string | no | New content (omit to keep current) | | category | string | no | New category (omit to keep current) |

memory_list

List all saved memories grouped by category.

| Parameter | Type | Required | Description | |---|---|---|---| | category | string | no | Filter by category | | limit | number | no | Max results (default: 50) |

memory_delete

Delete a memory by ID.

| Parameter | Type | Required | Description | |---|---|---|---| | id | number | yes | Memory 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