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

bash

# 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 UserPromptSubmit hook 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:

Terminal

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

bash

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

License

MIT