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://contextresource 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:
- Creates
~/.claude/scripts/memory-context.sh - Adds a
UserPromptSubmithook to~/.claude/settings.json - 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
- FTS5 + BM25 and semantic vector similarity run in parallel
- Results are merged and deduplicated using Reciprocal Rank Fusion (k=60)
- Facts appearing in both lists get naturally boosted
- If both return empty, falls back to LIKE substring matching
- 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