Claude Code Memory Cache

Persistent, token-efficient memory for Claude Code. Give the agent a memory that survives across sessions, projects, and machines — a "cache" for everything it should remember between runs, so it stops forgetting what you told it last week and stops re-reading your whole codebase to answer "where is X used?"

The optional live memory graph (2D view shown; a full 3D mode with hologram effects is one click away), from one real installation after ~3 months of use. Every node is one of your memories — the graph starts empty and grows as your sessions save them, clustered by meaning and pulsing as sessions think. Measured results from the same installation: docs/STATS.md.

⚠️ Unofficial. Not affiliated with Anthropic. "Claude" is a trademark of Anthropic; this is an independent community project.

What it is

Five cooperating memory layers, kept fresh automatically by hooks:

1. Vector memory — hybrid recall of past sessions: semantic search (ChromaDB, local, no API cost) fused with keyword BM25 per query, so exact tokens like error strings and env var names rank as well as paraphrases → memory_server/
2. File memory — a compact MEMORY.md index + one-fact-per-file store, read on demand
3. Obsidian vault — session logs, per-project notes, a Lessons file, a cross-project Brain Map
4. Code knowledge graphs — graphify + code-review-graph, so Claude queries structure instead of grepping files
5. Brain files — a PROJECT_BRAIN.md per project, auto-refreshed

The result: continuity across sessions, and much lower token use (see docs/TOKEN_EFFICIENCY.md).

Optional eye candy: a live 3D graph of your memory — semantic clusters, a hologram mode, and nodes that pulse in real time as your sessions search and save. One command: python visualizer/graph_server.py --open.

Quickstart

git clone https://github.com/jushayden/claude-code-memory-cache
cd claude-code-memory-cache
pip install -r requirements.txt
python install.py            # guided: deps check, config, snippets to merge, vault seeding

Or let your agent do it — paste docs/AGENTIC_SETUP.md into Claude Code.

What's in here

memory_server/   the memory MCP server (ChromaDB + Obsidian): server.py, storage.py, obsidian.py
visualizer/      OPTIONAL live 3D memory graph (docs/VISUALIZER.md)
scripts/         hook helpers (fingerprint_gate.py — skips graph rebuilds on non-structural edits)
config/          CLAUDE.md + settings.json (hooks) templates
docs/            architecture, setup, token efficiency, security, stats, visualizer
install.py       guided installer

Docs

• Architecture — the 5 layers + hooks + data flow
• Setup — manual install (step by step)
• Agentic setup — let your Claude install it
• Real numbers — measured costs, savings, and the honest list of what was useless
• Token efficiency — the 7 techniques that cut token use
• Visualizer — the optional live 3D memory graph (pulses on real activity)
• Security — scrub checklist before you publish your own setup

Requirements

Python 3.10+, Node 20+, Claude Code, and (optional but recommended) Obsidian.

License

MIT — see LICENSE.