Claude Code forgets everything the moment a session ends. This gives it a memory that survives — so it remembers what you told it last week, and looks things up cheaply instead of re-reading your whole codebase to answer "where is X used?" Everything runs locally on your machine: no API key, no cloud.
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.
Claude Code talks to one small Memory Server on your machine using just two actions — save a memory and search past memories. The server keeps five kinds of memory, each good at a different question, and a set of hooks keeps them all fresh automatically.
flowchart TD
You(["You"]) -->|"ask / do work"| CC["Claude Code<br/>(the agent)"]
CC <-->|"save · search"| MS["Memory Server<br/>local · no cloud · no API key"]
subgraph M["Five kinds of memory — one per question"]
direction LR
L1["1 · Vector memory<br/>have we discussed this before?"]
L2["2 · Fact files<br/>the exact facts, cheap"]
L3["3 · Obsidian vault<br/>the story + logs, for humans"]
L4["4 · Code graphs<br/>where is X used? what breaks?"]
L5["5 · Brain files<br/>one-page summary per repo"]
end
MS --> L1 & L2 & L3 & L4 & L5
H["Hooks keep it all fresh<br/>session start · every edit · save · session stop"] -.-> MS
| # | Kind | The question it answers | What it actually is |
|---|---|---|---|
| 1 | Vector memory | "Have we discussed something like this before?" | A local search over past sessions by meaning — a paraphrase still finds the right note, and exact tokens like error strings match too. Uses a local database with built-in embeddings, no API key needed. |
| 2 | Fact files | "What exactly did you tell me?" | Plain-text notes, one fact per file, with a tiny always-loaded index (MEMORY.md). The full facts are read only when they're needed, so they cost nothing until then. |
| 3 | Obsidian vault | "Show me the story." | Human-readable session logs, per-project notes, and a running lessons-learned file — browsable by you, not just the agent. |
| 4 | Code graphs | "Where is this used? What breaks if I change it?" | A map of your codebase's structure, so Claude checks the map instead of re-reading every file. |
| 5 | Brain files | "Give me the one-pager on this repo." | A single PROJECT_BRAIN.md per project — stack, conventions, priorities — refreshed automatically as you work. |
The payoff: continuity across sessions, and far fewer tokens spent — see docs/TOKEN_EFFICIENCY.md for the techniques and docs/STATS.md for real numbers. New terms (MCP, embedding, hook) are defined in docs/ARCHITECTURE.md.
A live 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 --opengit clone https://github.com/jushayden/claude-code-memory-cache
cd claude-code-memory-cache
python install.pyRun install.py with the Python you want the memory server and hooks to use. It installs the dependencies, writes memory_server/config.py, and asks before it registers the MCP servers, merges the hooks into ~/.claude/settings.json (after a backup) or copies the code-scout subagent. It never edits your CLAUDE.md. For an unattended run, pass --yes plus --vault PATH or --no-vault; --dry-run shows what it would do. On Windows, clone into a short path such as C:\src: pip fails on paths over 260 characters.
Or let your agent do it: paste docs/AGENTIC_SETUP.md into Claude Code.
memory_server/ the Memory Server (layers 1–3): server.py, storage.py, hybrid.py, obsidian.py,
plus the session hooks: auto-log, pre-compaction snapshot, session handoff
scripts/ hooks: fingerprint_gate.py (graphify), crg_refresh.py (code-review-graph, in the
background), graph_nudge.py (points searches at the graph), brain_refresh.py
(keeps PROJECT_BRAIN.md current); optional patch_code_review_graph.py,
embed_service.py, embed_graphs.py
config/ CLAUDE.md + settings.json (hooks) templates, and the code-scout subagent
visualizer/ OPTIONAL live memory graph (docs/VISUALIZER.md)
docs/ architecture, setup, token efficiency, security, stats, visualizer
install.py guided installer (also runs unattended with flags)
- Architecture — the diagram, the five layers in plain English, the hooks, and a glossary
- Setup — manual install, step by step
- Agentic setup — let your Claude install it
- Codex setup — wire Codex into the same store, so both tools share one memory
- Real numbers — measured costs, savings, and an honest list of what turned out useless
- Token efficiency — the techniques that cut token use
- Visualizer — the optional live memory graph
- Security — scrub checklist before you publish your own setup
Python 3.10+, Claude Code, and (optional but recommended) Obsidian. Nothing in this repo runs on Node.
MIT — see LICENSE.