Passive persistent memory for Claude Code.

An MCP server + hook set that gives Claude Code long-term memory across sessions — stored in SQLite with full-text search, scored by BM25-weighted relevance decay, bounded by hard token budgets, and auto-injected on every prompt without Claude needing to call a tool.

git clone https://github.com/mitre88/memorex
cd memorex
chmod +x install.sh
./install.sh

Restart Claude Code after installing.

The same memorex binary ships a CLI so you can inspect and manage the local database without opening Claude Code:

memorex ls                      # list recent memories
memorex search "auth"           # FTS search
memorex show 42                 # print a single memory
memorex pin 42                  # pin / unpin so decay doesn't touch it
memorex rm 42                   # delete a memory
memorex history 42              # revision history for #42
memorex stats                   # compact one-liner (add --json for JSON)
memorex prune --yes             # really delete cold memories
memorex backup                  # copy the db into ~/.memorex/backups
memorex import --from claude-md ~/.claude/CLAUDE.md
memorex import --from obsidian  ~/Documents/Obsidian\ Vault
memorex import --from engram    ~/engram-dump.json
memorex gain                    # last-7d analytics: inject rate, tokens, top memories
memorex gain --history          # per-day inject/token trend
memorex gain --json             # machine-readable summary
memorex doctor                  # health check (DB, schema, hooks, capacity)
memorex doctor --json           # scriptable diagnostics; exit 0/1/2 by worst level
memorex embed-status            # how many memories have a semantic embedding
memorex embed-rebuild           # backfill missing embeddings (needs MEMOREX_EMBEDDINGS=1)
memorex help

Calling memorex with no arguments still starts the MCP stdio server (that's how Claude Code launches it).

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Build
npm run build

# Lint
npm run lint

# Format
npm run format

src/
├── __tests__/          # Test suite (Vitest)
├── db/                 # Database layer (SQLite + FTS5)
├── hooks/              # Session lifecycle hooks
├── tools/              # MCP tool implementations
├── types/              # Shared TypeScript types
└── utils/              # Utilities (config, logging, session, security)

• SQLite + FTS5 BM25 — fast full-text search, title weighted 10× over body, zero external APIs
• Decay scoring — memories fade by type (project: 14d, feedback: 90d, user: 180d, reference: 365d)
• Token budgets — search results capped to a configurable token limit, most relevant first
• Passive auto-inject — a UserPromptSubmit hook prepends top-3 relevant memories to every prompt without Claude calling a tool
• Compaction survival — a PreCompact hook snapshots recent prompts + files touched into a 7-day project memory so long sessions don't go amnesic
• Knowledge graph — every save auto-links to related memories; memory_related traverses neighbors
• Git-root aware — project memories bind to git rev-parse --show-toplevel, not the current working dir, so sub-directory work doesn't fragment memory
• Anti-bloat guards — hard cap of 200 memories, 5 saves per session, containment-based fuzzy dedup, auto-prune on session end
• Observability — every prompt is logged to an inject_events table (success or skip); memorex gain reports inject rate, tokens injected, top memories shown, hit-ratio estimate
• Diagnostics — memorex doctor validates DB integrity, schema version, FTS index sync, file permissions, hook wiring, and capacity headroom
• Hybrid semantic search (opt-in) — set MEMOREX_EMBEDDINGS=1 and run memorex embed-rebuild. Search reranks the top FTS hits with cosine similarity against a local 384-dim sentence embedding (all-MiniLM-L6-v2). Catches paraphrases and non-English queries that BM25 misses. ~22 MB one-time model download, no API calls.
• 4 memory types: user, project, feedback, reference

All data stored locally at ~/.memorex/memories.db.

MIT