Claude Code memory that survives /compact, /clear, cold boots, and crashes. Drop-in install. The harness enforces memory — not Claude's discipline.
Searching for Claude memory, Claude Code memory, persistent agent memory, or memory across sessions? — you're in the right place. Memory Road gives Claude Code a real, queryable memory of everything it has done, and mechanically injects that memory into every prompt so the agent can't forget to use it. Scroll down to The problem to see the pain it fixes.
First time here? The simplest entry point to the broader pattern is the PreCompact hook recipes repo — tiny scripts that save state right before
/compactsummarizes it. PreCompact is one hook. Memory Road is what you build once you realize one hook isn't enough.
Your Claude Code agent forgets everything between sessions. This fixes that. Forever.
Every Claude Code session starts blank. Every /compact half-forgets. Every model upgrade resets state. The agent re-derives the same architecture five times a week. You exhaustedly re-onboard it every Monday. It misses promised follow-ups because it forgot it made them. It contradicts itself because session-X-it didn't know what session-Y-it decided.
Memory Road fixes this. One install. Your agent remembers across sessions · /compacts · model upgrades · 529 cascades · laptop reboots. Forever.
Memory Road is three things working together, plus on-demand backfill. There is exactly one always-on process (the substrate). Everything else is cheap, event-driven, or on-demand.
┌────────────────────────────────┐
│ CLAUDE CODE AGENT │
│ reads the cortex packet that │
│ the harness injects every │
│ single prompt — can't forget │
└──────────────┬─────────────────┘
▲ │
hook-injected │ │ JSONL transcripts
cortex packet │ │ (every event)
EVERY prompt │ ▼
┌─────┴──────────────────────────────────┐
│ 1. SUBSTRATE · continuity-kernel.service │
│ ALWAYS ON · LLM-FREE · SACRED │
│ captures every event → SQLite forever│
│ renders the cortex packet │
└──────────────┬───────────────────────────┘
│
┌────────────────────┼────────────────────────┐
▼ ▼ ▼
2. CORTEX PACKET 4. HOURLY ROLLUPS on-demand BACKFILL
project_continuity (cron · :00 mechanical (primary agent's own
_state.md :05 one-LLM-call essence) sub-agents · $0 · parallel)
"remembers last "filled in every hour "complete the historical
session" on the hour" blob when you ask"
3. INJECTION (the crown jewel) = SessionStart + UserPromptSubmit hooks
6. WATCHDOG = kernel_watchdog.sh restarts the substrate if it ever stops
Why it's built this way: the substrate is sacred and additive-only — if any LLM layer fails, the raw signal is untouched. The injection is harness-enforced, so memory is a property of the harness, not of any one Claude's discipline. The expensive comprehension work runs on demand, not as always-on burners (those were retired — see below).
- 🧱 The substrate never forgets.
continuity-kernel.servicecaptures every Claude Code event into SQLite forever, LLM-free, ~3.96M events and counting. It cannot be rate-limited and it cannot be killed (a watchdog restarts it every minute if it ever stops). - 📨 The cortex packet remembers your last session. The kernel re-renders
project_continuity_state.mdevery few minutes — identity, working state, recent episodes, open loops, resume instruction. - 🔒 Harness-enforced injection — Claude literally cannot forget. A
UserPromptSubmithook injects the age-stamped cortex packet into every prompt. The agent sees its memory before it sees your message. There is no path around it. - 🎯 Idempotent operator Monitor. The boot hook arms exactly one Telegram/inbox watcher per session — never 0, never 2 — and a verify hook screams if it ever drops or gets orphaned by
/compact. - ⏱️ Hourly rollups, on the hour. A mechanical rollup (
$0) writes a grep-able timeline; a synth rollup fires one subscription Opus call to distill the hour's essence — and skips the LLM entirely on quiet hours so cost stays near zero. - 🪶 On-demand backfill by agents. Completing the historical blob (chunking + summaries) is done by the primary agent's own in-harness sub-agents, in parallel, at
$0— not by always-on burner daemons.
git clone https://github.com/<your-org>/memory-road.git
cd memory-road
# 1. SUBSTRATE · the one always-on process (captures events forever)
sudo bash setup/install_substrate.sh
# 2. INJECTION · the hooks + crons (cortex packet + monitor + hourly rollups)
bash setup/install_hooks.sh
# 3. Verify
bash examples/smoke_test.shThat's it. The substrate captures from second zero. The hooks inject the cortex packet into every prompt. The crons fill memory in every hour on the hour. See INSTALL.md for the full walkthrough + path config.
In late May 2026, a cleanup agent (running as a different Claude Code session) trimmed an old bullet from MEMORY.md that read · "Read project_continuity_state.md on startup." It looked redundant. The cleanup agent removed it.
The continuity-kernel kept writing memory packets every few minutes. For 16 days. Nobody read them.
The verbatim quote in the regression hunt notes ·
"It was never a hard hook. And I recently broke the soft one."
A bullet in MEMORY.md is a soft hook · it depends on Claude reading + obeying it. The harness needs to enforce this · not Claude's discipline.
The fix is a SessionStart hook that cats the packet into Claude's context BEFORE the agent sees any user prompt, plus a UserPromptSubmit hook that re-injects the age-stamped packet on every single turn. The harness runs the shell command. There is no path around it.
Memory becomes a property of the harness · not a property of any one Claude's discipline.
That's the founding doctrine. Everything else follows.
# Your agent now auto-injects the cortex packet on every prompt
"What did we decide about the auth flow?"
# → the packet is already in context · the agent answers from memory
# Explicit semantic recall
python3 bin/recall.py "auth flow decisions" # (your path may vary · see INSTALL.md)
# Check what's unfinished (optional HUNTSMAN tool)
sqlite3 /root/wc/runtime/continuity_kernel.db \
"SELECT description FROM huntsman_flags WHERE status='open' LIMIT 20;"
# Run an on-demand backfill wave (complete the historical blob)
# → see OPERATIONS.md "Run an on-demand backfill wave"memory-road/
├── README.md ← you are here
├── ARCHITECTURE.md ← the 6 pieces + on-demand backfill + retired-burners note
├── INSTALL.md ← substrate + hooks + crons (drop-in)
├── OPERATIONS.md ← verify it's alive · run a backfill wave · troubleshoot
├── FORCE_MEMORY_USE.md ← harness-enforced injection (the hard hook)
├── doctrines/ ← LOCKED principles (scar tissue from real failures)
├── bin/ ← continuity_kernel.py + backfill helpers + optional tools
├── hooks/ ← the REAL live hooks this system runs on
├── schema/ ← SQL tables
├── setup/ ← systemd · cron · settings.json example
└── examples/ ← smoke test
Memory Road originally ran a fleet of always-on LLM comprehension workers (FURROW / SCRIBE / CHRONICLER "snow plows") that spawned a fresh claude -p --model opus every ~15 seconds to chunk and summarize history in real time. The math killed them:
~17,000 subscription Opus calls/day ≈ 58% of the weekly quota burned mid-week, every week.
The episode-chunking + summarization work was not load-bearing for "the agent remembers our last conversation" — the substrate, the cortex packet, the PreCompact snapshot, and the hourly rollups already deliver that. So on 2026-06-07 the burners were retired. Burn dropped ~95%. Memory still works forever.
Completing the historical blob is now done on demand by the primary agent's own sub-agents — pure additive inserts into episode_summaries, kernel untouched. A recent wave: 8 agents summarized 672 episodes at $0. See ARCHITECTURE.md.
The optional comprehension tools (huntsman.py, cartographer.py, miner_smith.py) still exist and still produce useful data — but they run on demand, never as always-on daemons. Comprehension layers are SKILLS, not DAEMONS. Skills fire on intent. Daemons burn whether anyone needs them or not.
Most "agent memory" tools dump everything into a vector database. Search is fuzzy · context is lossy · meaning is squished into 384 dimensions.
Memory Road keeps the road. Every event · every episode · every decision · every unfinished thread · structured · queryable · timestamped · traceable in SQLite. Vector search (sqlite-vec) is the SIDECAR, not the substrate. You can answer "what did I decide three weeks ago" with a real SQL query · not a fuzzy similarity score.
The road has milestones. The vector blob has fog.
Memory Road was built by the operator and his Claude Code agent (Opus, 1M context). With critical insights from a sibling laptop Claude. Real incidents. Real corrections. Real fixes. Locked across months of work.
Founding doctrine (April 14, 2026) · "Never ask the primary agent to be the sole author of its own memory."
Use it. Fork it. Improve it. Send a PR. If this gives your Claude Code agent persistent memory and saves you tokens, drop a ⭐.
If you ship Memory Road on a new agent, tell us. Email rickyponline@gmail.com. We're collecting the stories.
Stop asking your agent to remember. Make the harness do it.
🌊 Built with the agent 🌊