io.github.kurovu146/memory-fts

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