Persistent memory for AI coding agents.
Three-layer memory system that gives Claude Code long-term recall across sessions. CLI-enforced archiving — the tool handles numbering, timestamps, and indexing. The agent only writes summaries. No patches, no forks.
Architecture
Each layer serves a different purpose. Together they give the agent full continuity without bloating context.
Features
Not a flat file. A structured system with lifecycle management, automatic archival, and searchable history.
Layer 1: MEMORY.md holds stable facts, user preferences, and project patterns. Always in context. Agent maintains it proactively.
MEMORY.mdLayer 2: EPHEMERAL.md carries context between sessions. Written at session end, automatically promoted to an archive log on exit.
EPHEMERAL.mdLayer 3: Sequentially numbered archive logs. Not loaded into context. Searchable on demand with Grep.
archive-log-XXX.mdTwo hooks, zero effort. PreCompact creates checkpoints on compaction. SessionEnd promotes EPHEMERAL.md on exit. Nothing falls through the cracks.
checkpointSessionEnd hook runs recall-echo promote on exit. Session summaries are archived immediately — no waiting for the next session.
Run recall-echo status to see MEMORY.md line count, archive log count, hook configuration, and warnings at a glance.
Archive logs include YAML frontmatter: sequence number, timestamp, trigger type, and topics. Plain markdown you can build tooling on.
frontmatterLifecycle
The agent manages its own memory autonomously. You don't need to tell it to remember — the protocol is in its rules.
Runs recall-echo promote as a safety net. MEMORY.md is already in context via auto-load. Reads latest archive log if needed.
Updates MEMORY.md with stable facts as they're confirmed. Searches archive logs when historical context is needed.
PreCompact hook runs recall-echo checkpoint. CLI creates the log file, the agent fills in the sections. Nothing is lost.
Agent writes EPHEMERAL.md with a session summary. SessionEnd hook runs recall-echo promote, archiving it automatically on exit.
Install
Works with any existing Claude Code setup. The installer is idempotent — run it again to update the protocol without losing your memory.
Install
Initialize
Start a new Claude Code session