A Claude Code plugin that gives Claude fully automatic, per-project cognitive memory — powered by local embeddings and hybrid search.
- Auto-loads relevant context at session start using git signals (branch, commits, modified files)
- Auto-saves a structured session summary when the session ends
- Auto-recalls matching memories when Bash errors occur
- Auto-merges near-duplicate memories on store (≥95% cosine similarity)
- Auto-consolidates based on activity weight — reviews duplicates, stale entries, and emerging patterns
- Adaptive context budget — dynamically allocates injection slots based on result quality, not fixed caps
- Two-phase recency scoring — strongly favors recent work (0–7 days) with gradual long-term decay
- Content-length penalty — prevents verbose, generic memories from dominating search results
- Noise filtering — suppresses trivial sessions, junk procedurals, and low-substance episodics
All data stays local. Everything is scoped to the current project via the working directory.
- Node.js >= 18
- Claude Code CLI
git clone https://github.com/d2a8k3u/claude-code-memory.git claude-memory
cd claude-memory
./install.shThe installer builds the MCP server, registers it globally, adds hooks to ~/.claude/settings.json, and symlinks skills. Restart Claude Code after installation.
Note: On first use, the plugin downloads a ~90 MB embedding model (all-MiniLM-L6-v2) from Hugging Face. This happens once and is cached locally. The first session start may take 10-30 seconds depending on your connection.
Run /memory-init in any project to populate the memory from existing project files (README, package.json, CLAUDE.md, git history, etc.).
- SessionStart — clears working memories, decays stale importance, injects relevant context via adaptive budget allocation
- During session — Claude uses 10 MCP tools automatically (store, search, get, update, delete, list, batch-store, relate, graph, health)
- PostToolUse — on Bash errors, extracts error terms and surfaces matching memories
- Stop — analyzes the session transcript with noise filtering and saves structured memories (episodic, procedural, semantic, pattern)
| Type | Purpose | Example |
|---|---|---|
episodic |
What happened | "Fixed auth bug — missing null check on refresh token" |
semantic |
Project facts | "API uses JWT with refresh token rotation, tokens in Redis" |
procedural |
How-to | "Deploy: merge to develop, CI builds, auto-deploy to staging" |
working |
Session scratchpad | Hypotheses, intermediate results (auto-cleared next session) |
pattern |
Consolidated insights | "Error handling: always use Result types with typed errors" |
Memories can be linked with relations: relates_to, depends_on, contradicts, extends, implements, derived_from.
Hybrid search combining FTS5 full-text and semantic vectors (cosine similarity via sqlite-vec). Falls back to text-only when embeddings are unavailable. Results are reranked with a cross-encoder (ms-marco-TinyBERT-L-2-v2) for accurate relevance scoring.
Scoring combines text relevance, importance, recency, and access frequency with configurable per-channel weight presets (e.g. branch queries favor recency, project-level queries favor importance). Verbose memories receive a content-length penalty to keep results focused.
SQLite database at .claude/memory-db/memory.sqlite inside each project. Includes FTS5 and vec0 virtual tables for fast search.
| Skill | Description |
|---|---|
/memory-init |
Bootstrap project memory from codebase files (README, package.json, git history, etc.) |
/memory-maintain |
Deduplicate, consolidate, clean junk records, and split large memories |
Architecture
claude-memory/
├── install.sh # Installer
├── server/src/
│ ├── index.ts # MCP server entry point
│ ├── cli.ts # Hook runner entry point
│ ├── database.ts # SQLite + FTS5 + vec0
│ ├── memory.ts # 10 MCP tool handlers
│ ├── embeddings.ts # Local embeddings (all-MiniLM-L6-v2, 384-dim)
│ ├── thresholds.ts # Centralized similarity/scoring configuration
│ └── cli/
│ ├── session-start.ts # Budget allocation, context injection
│ ├── session-end.ts # Transcript analysis, memory creation
│ ├── error-context.ts # Error pattern matching
│ ├── pattern-detector.ts # Shared pattern clustering logic
│ └── transcript.ts # Transcript parsing with noise filtering
├── skills/
│ ├── memory-init/ # /memory-init bootstrap skill
│ └── memory-maintain/ # /memory-maintain cleanup skill
├── agents/memory-curator.md # Maintenance sub-agent
└── hooks/hooks.json.template # Reference hook config
TypeScript · MCP SDK · better-sqlite3 · sqlite-vec · @huggingface/transformers · Zod · tsup
See CONTRIBUTING.md.
