Claude-Mnemo
Structured memory system for Claude Code. Captures every tool call in real time, extracts durable observations and turn summaries via a background agent, and feeds them back into future sessions — so conversations start with context, not from scratch.
How It Works
Claude-Mnemo hooks into five points of the Claude Code lifecycle:
| Hook | Trigger | What it does |
|---|
| SessionStart | Session begins / resumes / clears / post-compact | Injects recent session summaries, turn highlights, and active memories into context |
| UserPromptSubmit | Every user message | Creates (or resumes) the session + a new turn row in SQLite |
| PostToolUse | Every tool call | Writes a raw observation (tool_name + input + result), enqueues it for extraction, wakes the worker |
| Stop | Agent finishes a turn | Backfills the assistant response + tool counts, enqueues a turn-stop job |
| PreCompact | Main agent is about to compact | Synchronously flushes the worker queue for this session and pushes a final session summary |
Extraction does not run inside the hook process. Hooks write to SQLite and return; a long-lived worker (Bun HTTP server on 127.0.0.1:37778) picks up the work asynchronously, sends it to Mnemosyne (an isolated Claude Agent SDK query session), and writes the extracted titles, content, insights, tags, and types back into the same database.
Data Model
Session [S12] one per conversation
Turn [T3] one per user prompt (promptNumber scoped to session)
Observation [O87] one per tool call
Memory [M4] durable cross-session knowledge
Turns carry a type tag: 🔴 bugfix · 🟣 feature · 🔄 refactor · ✅ change · 🔵 discovery · ⚖️ decision.
Memories are the durable layer — user feedback, project decisions, gotchas, and patterns — with scope either global or an absolute project path.
Queue + Crash Safety
All pending extraction work lives in a single pending_queue table keyed by a monotonic seq (AUTOINCREMENT). Hooks write to pending_queue inside the same SQLite transaction as the observation or turn-stop update, so a crashed worker or killed hook never drops work — the next worker boot resumes from the queue in FIFO order.
Installation
In Claude Code, add the marketplace and install:
/plugin marketplace add KawaiiLLM/claude-mnemo
/plugin install claude-mnemo
Bun is the only runtime dependency — bun-runner.js auto-installs it if missing. Marketplace and source installs ship with prebuilt plugin/scripts/*.cjs entrypoints, so hooks, MCP, and the worker run without a post-install build.
From Source
git clone https://github.com/KawaiiLLM/claude-mnemo.git
cd claude-mnemo
npm install
npm run build
Then symlink the built plugin:
ln -s "$(pwd)/plugin" ~/.claude/plugins/claude-mnemo
For contributors, npm run build refreshes the committed release artifacts in plugin/scripts/.
Usage
Once installed, Claude-Mnemo works automatically — hooks fire on every session, the worker extracts in the background, and SessionStart injects context on the next launch.
Two skills expose the read and write paths to the main agent:
mnemo-recall — Reading Past Work
Auto-loaded when the user asks questions like "did we already do this?", "how did we fix X last time?", or "show me the exact tool calls from last Thursday". Documents the full recall + replay API.
Quick reference:
recall() # recent sessions
recall(query="auth race") # FTS across all layers
recall(query="type:bugfix file:src/auth.ts") # typed filters
recall(time="-7d") # relative time window
recall(id="S12") # session summary
recall(id="S12/T3") # turn by promptNumber
recall(id="S12/T3..7", depth="expanded") # turn range with content
recall(id="S12/T3/O*") # observations in a turn
recall(id="O87", depth="expanded") # specific observation
recall(id="M*") # all active memories
replay(id="S12") # transcript turn overview
replay(id="S12/T3", depth="expanded") # exact prompt + response + tool I/O
replay(id="S12/T3/Tool2", depth="full") # single tool call, untruncated
