code-recall
erikhuang76821/code-recall
Ledger local de decisões que sobrevive compactação de contexto
Ver no GitHubDaemon-less, zero-dependency memory layer for AI coding agents - survives context compaction, works across every IDE/CLI (Claude Code, Cursor, Codex, Copilot, Gemini...)
Instalação
npx convez-ai erikhuang76821/code-recall1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Evitar que agentes IA revisitem decisões de código já settadas
- Documentar e rastrear tentativas falhas para não replicar erros
- Manter raciocínio de design disponível após context window reset
Veredito

Solução pragmática e minimalista para um problema real em sessões longas com agentes IA — mantém raciocínio vivo sem infraestrutura pesada. Zero deps, viaja com o repo, faz exatamente o que promete.
README
A tradução para o português deste README ainda está na fila.
🌟 Code Recall — your coding agent's decision log
Remember why you built it this way, what didn't work, and what's still current — kept across context compaction.
Code Recall is the Decision Persistence Layer for AI coding agents. It preserves the thing projects lose most easily and rebuild most expensively — why a choice was made, and which paths are proven dead ends — AI-maintained, local, zero-dependency, and kept from rotting across context compaction. Not a memory database; not a governance platform. Think "Git for decisions."
Requirements · Node ≥ 10.12 (anything since 2018; CI runs Node 18 / 20 × Linux / Windows).
🔭 Vision
Coding is commoditizing. The next differentiator isn't who writes code faster — it's who keeps decisions from being lost, rotting, or silently re-litigated. AI IDEs are already strong at Retrieval → Reasoning → CodeGen, but nearly blank on persisting the Decision (why) → dead-ends (what failed) layer — it lives only in the chat and evaporates on the next compaction. Code Recall aims to be the local, zero-dependency foundation for that layer: no cloud, no data egress, travels with the repo, so every AI agent sees current truth before it acts.
🧭 What it fills, and what it does not replace
Claude Code already has /init (codebase overview) and /handoff (session transfer). It has no decision log — that's the gap Code Recall fills.
Does NOT replace:
/init— codebase overview generation/handoff— a one-time conversation handoffCLAUDE.md/AGENTS.md— your standing project instructions (Code Recall lives alongside them)- RAG / vector / semantic memory — that's retrieval; this is decision rationale
Preserves (what projects lose most):
- Decisions & constraints — why it's the way it is
- Failed attempts — which paths not to retry (don't retry X because Y)
- Goal & the thread in progress — where you're mid-work (compaction can't erase it)
…and unlike a doc you'd forget to update, it's re-injected every session, snapshotted before compaction, and expired/superseded decisions auto-retire (ADR status lifecycle).
😫 The Problem
What large projects lose most easily isn't "where did I get to" (the code/git shows that) — it's:
- Why it was done this way + which paths are proven dead ends — these live only in the chat and evaporate the moment the window compacts → re-litigating settled decisions, re-walking dead ends (the most expensive waste).
- Mid-task auto-compaction: the agent loses the thread, redoes work, even reverses what it just wrote.
- Switching tools (Claude Code ↔ Cursor ↔ Copilot), memory isn't shared — you re-explain every time.
- Memory tools (mem0 / supermemory, etc.) want a DB, vectors, the cloud, paid APIs — too heavy for "I just want the coding agent to remember decisions, without shipping my code to a cloud."
🎯 The Solution
Code Recall follows a "subtractive" philosophy: condense memory into a few static Markdown files, and let lifecycle hooks re-inject the task digest automatically at session start / after compaction, while the agent keeps rewriting the ledger per the protocol.
✨ Core features
- 🍃 Zero-dependency: no DB, no background service, no network, zero npm runtime deps; 100% local files, code never leaves.
- 🛡️ Compaction survival: PreCompact snapshots before compaction; the post-compaction session re-anchors with the full TASK.md — the strongest in its class, backed by a CI regression test.
- 🤝 Cross-tool: one
.ai/memory/, read by every IDE/CLI via theAGENTS.mdprotocol;git clonecarries it along. - ⚡ Token discipline: only a ≤200-token digest is injected each session (the whole ledger is not stuffed into context); zero cost in non-Code-Recall projects.
- 🔎 Searchable: zero-dep BM25 lexical search (English & Chinese), covering cross-month recall.
- 🧹 Anti-rot: temporal/supersede/expire model +
doctorlint + an optional git pre-commit gate minimize "stale ledger misleads you." - 🪟 Windows-first: PowerShell installer, native Windows 11 support.
🚀 Quick Start
1. Initialize project memory (once per project)
# After npm publish — no clone needed (still zero runtime deps)
npx coderecall init
# Or from source
node path/to/code-recall/coderecall.js init # macOS / Linux
node path\to\code-recall\coderecall.js init # Windows
Creates .ai/memory/ and inserts a protocol section into AGENTS.md (the instruction-style hook for tools without native hooks):
| File | Purpose |
|---|---|
TASK.md | Current goal & progress: GOAL / NOW / NEXT + checklist |
DECISIONS.md | Decision log (ADR-grade): Context / Decision / Consequences + status (proposed/accepted/superseded/deprecated) |
LESSONS.md | Pitfalls + root cause ("don't retry X because Y") |
Git ownership (hybrid by default): init writes a .gitignore block — durable team knowledge (DECISIONS.md / LESSONS.md + archives) is committed, while each developer's volatile working state (TASK.md / sessions.md / pre-compaction snapshots) stays local. So TASK.md won't cause multi-dev NOW:/NEXT: merge conflicts, and git history isn't flooded by machine edits. Want a solo private repo to track live state too? Delete the TASK.md lines from the block. (The committed AGENTS.md deliberately does not embed live NOW:/NEXT:, to avoid leaking state.)
2. Install global hooks (once per machine, Claude Code only)
powershell -ExecutionPolicy Bypass -File install.ps1 # Windows
sh install.sh # macOS / Linux
The installer only merges into ~/.claude/settings.json: backs up first, never clobbers existing hooks, idempotent. Uninstall: install.ps1 -Uninstall / install.sh --uninstall.
3. Done
No manual steps after that — hooks auto-inject the task digest at every session start / after compaction, and the agent rewrites the ledger per the protocol.
Other tools (Cursor / Copilot / Windsurf / Cline / Roo / Gemini / Codex): run node coderecall.js sync --all to generate each tool's instruction stub + native config; the protocol text itself is their hook.
🧰 Command Reference
node coderecall.js <command> # or, after publish: npx coderecall <command>
| Command | What it does |
|---|---|
init | Create .ai/memory/ + AGENTS.md protocol section + CLAUDE.md stub |
sync [--all] | Refresh AGENTS.md; --all also writes per-tool stubs + Gemini/Cursor native config |
status | Show GOAL/NOW/NEXT, checklist, file sizes, drift, freshness |
doctor [--selftest] | Health check (hooks/ledger/paths/lint/Codex 32KiB); --selftest also runs the regression test |
score [--json] | Rate working-state health (GOAL clarity / NEXT actionability / blockers reasoned / freshness) |
decision "<title>" [--context/--decision/--consequences/--status/--confidence] [--supersedes "<old title/substr>"] | Record an ADR decision in one line; --supersedes explicitly retires a prior decision (independent of title similarity) |
search <query> [--limit N] [--history] | Lexical search — current truth only by default (superseded/deprecated/archive excluded); --history includes them (labeled [superseded]) |
decisions [--all] | HEAD view: list current accepted decisions (--all includes superseded/deprecated) |
digest [--compact] | Print the session-injection digest (debugging) |
consolidate | Archive done items (monthly), retire superseded/expired entries, dedupe, age-flag |
snapshot | Write a manual snapshot |
mcp | Run the zero-dep stdio MCP server (memory write-back as tool calls) |
precommit [--strict] | Used by the git hook: refresh digest + lint (--strict blocks) |
install-githook [--strict] / remove-githook | Install/remove the git pre-commit gate |
deinit [--yes] | Cleanly remove from a project (dry-run by default) |
selftest / version | Run the compaction-survival regression test / print version |
🧠 How it Works
Code Recall listens to AI-tool lifecycle hooks and accesses memory automatically:
- Session Start — read a ≤200-token digest from
.ai/memory/and inject it as context. - Context Compaction —
precompact.jssnapshots the transcript tail before compaction; the post-compaction session re-anchors with the full TASK.md. - End of turn —
stop.jsmaintains a heartbeat + a boundedsessions.mdtimeline. - Pull-based recall — when needed, use
coderecall search(BM25) or the MCP tools to fetch memory on demand, not permanently occupying context.
┌───────────────────────────────┐
│ <project>/.ai/memory/ │
│ TASK.md (GOAL/NOW/NEXT) │
│ DECISIONS.md (dated entries) │
│ LESSONS.md (failures+why) │
│ sessions.md (timeline) │
│ archive/ (snapshots) │
└──────┬───────────────▲────────┘
read+inject │ │ write/rewrite
┌───────────────────────┤ │ (recitation / MCP tools)
│ │ │
┌───────▼────────┐ ┌──────────▼─────┐ ┌─────┴──────────┐
│ sessionstart.js│ │ precompact.js │ │ stop.js │
│ digest ≤200 tok│ │ snapshot tail │ │ heartbeat + │
│ into context │ │ of transcript │ │ sessions line │
└───────▲────────┘ └──────────▲─────┘ └─────▲──────────┘
│ Claude Code hooks (installed by install.ps1/.sh)
└──────────────────────┬┴──────────────┬┘
│ │
┌──────────┴─────┐ ┌──────┴────────────────────┐
│ Claude Code │ │ AGENTS.md marker section │
│ (hook-driven) │ │ → CLAUDE.md / .cursor / │
└────────────────┘ │ copilot / windsurf / roo… │
│ (instruction-driven) │
└───────────────────────────┘
🤝 Supported AI Agents
| Agent | How |
|---|---|
| ✅ Claude Code | Native hooks (SessionStart / PreCompact / Stop) — inject, snapshot, re-anchor, all automatic |
| ✅ Cursor | .cursor/rules instruction hook + .cursor/hooks.json Stop heartbeat (sync --all) |
| ✅ GitHub Copilot | .github/copilot-instructions.md instruction hook |
| ✅ Windsurf | .windsurf/rules (trigger: always_on) |
| ✅ Cline / Roo | .clinerules / .roo/rules instruction hook |
| ✅ Gemini CLI | .gemini/settings.json loads AGENTS.md natively |
| ✅ Codex CLI | AGENTS.md (doctor warns past the ~32KiB read window) |
| ✅ Any MCP client | coderecall mcp — Claude Desktop / Cursor / VS Code… can call the memory tools directly |
Per-tool truth across the three layers (injection / write-back / compaction survival): see COMPATIBILITY.md.
📊 Market scarcity — who treats decision persistence as the core?
Plenty of tools record decisions; almost none make keeping stale decisions from misleading you while keeping current ones influential their core. Most cover only one or two cells:
| Capability | Memory Bank* | llm-wiki / Obsidian | mem0 / supermemory | ADR tools† | Code Recall |
|---|---|---|---|---|---|
| Easy / low-friction capture | ✅ | ❌ manual | ✅ auto | ❌ manual | ✅ CLI/MCP |
| Decision status lifecycle (accepted/superseded) | ❌ | ❌ | ❌ | ✅ | ✅ |
| Stale loses influence (rot governance) | ❌ append-only | ❌ | ⚠️ semantic | ❌ humans read | ✅ filter+weight |
| Surfacing across compaction | ❌ | ❌ | ❌ | ❌ | ✅ digest |
| Warn on re-litigation | ❌ | ❌ | ❌ | ❌ | ✅ |
| Local · zero-dep · no cloud | ✅ | ✅ | ❌ cloud/vector | ✅ | ✅ |
| AI-maintained | ⚠️ | ❌ | ✅ | ❌ human | ✅ |
* append-only memory banks like Cline / Roo / Cursor Memories † human ADR tools like adr-tools / log4brains
ADR tools have a status lifecycle but are human-authored and never surface to the agent or survive compaction. Memory banks auto-capture but have no decision-status lifecycle or influence governance (append-only → rot). Cloud memory (mem0 / supermemory) adds semantic recall but isn't local/zero-dep and has no ADR-style decision lifecycle. The combination — AI-maintained decision lifecycle + influence governance + compaction surfacing, all local and zero-dependency — is the uncontested gap Code Recall fills.
Honest positioning · We do not compete with mem0/supermemory on semantic recall or multi-modality (that's the cloud products' home turf), and we do not build a governance/approval engine. Code Recall's moat is "local, zero-dependency, decision lifecycle + surviving compaction." Per-tool reality in COMPATIBILITY.md; competitive assessment in ROADMAP.md.
🛠️ Advanced Usage
🔎 Search memory
node coderecall.js search "idempotency key" # 5 by default
node coderecall.js search redis retry --limit 3
Zero-dep BM25 lexical search across the ledger + archive/, paragraph/entry-level results with score and source.
📊 Working-state score
node coderecall.js score # human-readable
node coderecall.js score --json # for CI / agents
Answers "can an agent actually pick this ledger up?" — not whether the fields are filled, but a machine check of actionability: is GOAL specific, is NEXT a concrete next step (vague values like "continue"/"TBD" score low), does each [!] blocker have a reason, is the ledger fresh. Each dimension reports why and what to fix first. Deliberately a transparent heuristic, not a fake-precision ML score — the point is to catch false completeness ("looks filled, can't drive the next step"). status shows the one-line overall.
✅ Self-test / CI
node coderecall.js selftest # or doctor --selftest / npm test
Simulates compaction in a throwaway project and drives the real hook scripts (sessionstart / precompact), asserting the re-anchor digest contains the full TASK body and that a snapshot is written. GitHub Actions runs it on Linux + Windows × Node 18/20 on every push/PR — turning the headline claim into a reproducible regression test.
🧹 Temporal / supersede / expire (zero-dep)
DECISIONS/LESSONS support expires: (auto-forget on/after a date) and a supersede chain: writing an overlapping-title decision marks the old one status: superseded (kept, so evolution stays visible) by code, not a silent overwrite. consolidate retires superseded + expired entries to archive/retired-YYYY-MM.md. The links are code-maintained (not hand-written by the AI) and carry no traversal logic, so there are no orphans / cycles.
🔌 Optional: MCP server (write-back as tool calls)
// Claude Desktop / Cursor / any MCP client
{ "mcpServers": { "coderecall": { "command": "node", "args": ["<path>/code-recall/coderecall.js", "mcp"] } } }
Zero-dep stdio JSON-RPC exposing read_memory / update_task / write_decision / write_lesson / search_memory. Turns honor-system write-back into a tool call; files remain the storage layer, AGENTS.md still covers non-MCP tools.
♻️ Current truth & influence governance
The most dangerous thing about long-term memory isn't forgetting — it's wrongly remembering: stale/superseded decisions keep getting recalled and pollute context (influence rot). Code Recall treats decisions like Git, not a vector store: what matters is "which is HEAD (current)", not "which is most similar."
- Current/history split:
searchand MCPsearch_memoryreturn current decisions only by default; superseded/deprecated/archive don't appear. Add--historyto include them (clearly labeled[superseded]).decisionsgives the HEAD view. - Explicit supersede:
decision "new" --supersedes "old keyword"retires the old decision directly — independent of title similarity. - Weighted ranking: recall score =
BM25 × statusWeight (accepted 1.0 / proposed 0.5 / deprecated 0.2 / superseded 0.05) × confidence × recency. On an equal match, current/high-confidence/recent decisions rank first. - Surfacing: every session / after compaction, the digest surfaces the top-5 current decisions (titles only, newest-first, accepted only — proposed/superseded/expired excluded). Bounded curated attention, not the whole log.
- Anti-re-litigation: recording a decision that clearly overlaps an accepted one but is below the auto-supersede bar offers three resolutions:
--supersedes "X",--confirm-new, or revise the title.
Design philosophy: what an LLM lacks isn't storage, it's attention — the question isn't how many you can store, but "which few should this task see."
⚠️ Zero-dep boundary: detecting that code contradicts a decision needs semantic understanding (LLM/vector) and is out of scope. Code Recall instead surfaces current decisions and warns at authoring time — maximizing "seen, not re-decided," without semantic contradiction detection.
✍️ Reliable capture
A decision log is only worth anything if decisions actually get recorded. Code Recall uses two non-coercive levers:
node coderecall.js decision "Adopt hexagonal architecture" \
--context "billing tangled with HTTP" --decision "ports/adapters" --consequences "more boilerplate, easier to test"
- Lower the friction:
decisionrecords an ADR in one line (or MCPwrite_decision, called by the agent). - Nudge at the right checkpoint: the git pre-commit hook prints one advisory line when you commit source but record no decision (never blocks; not a per-turn Stop-hook nag).
- No coercive prompts — real enforcement is the commit gate + the human; a prompt is just a prompt.
🪝 Optional: git pre-commit gate (code maintains derived state)
node coderecall.js install-githook # advisory: lint issues warn, commit proceeds
node coderecall.js install-githook --strict # strict: malformed entries block the commit
node coderecall.js remove-githook
At commit time it regenerates the AGENTS.md digest from TASK.md + lints the ledger, and re-stages tracked AGENTS.md/CLAUDE.md. Cross-platform (node writes an sh hook), marker-merges without clobbering an existing hook, removed by deinit. Bypass once: git commit --no-verify.
🎓 Optional (experimental): graduate to ADR + cross-project lessons
node coderecall.js graduate # >90d, confidence high → docs/adr/NNNN-*.md (ADR files)
node coderecall.js graduate --global # also append to ~/.coderecall/GLOBAL-LESSONS.md (cross-project)
Non-destructive (entries stay in the ledger marked graduated:, exported once). Decisions become conventional numbered ADR files consumable by adr-tools/log4brains. To inject cross-project lessons into the digest (top-3): set CODE_RECALL_GLOBAL_LESSONS=1; relocate the global dir via CODE_RECALL_GLOBAL_DIR.
🔔 Optional: staleness reminder hook (off by default)
Off by default to honor token discipline. Enable by adding a UserPromptSubmit hook in ~/.claude/settings.json pointing at hooks/userpromptsubmit.js: when the ledger is >45 min stale it injects one ~15-token reminder, throttled.
🧹 Consolidation + 🤝 team collaboration
node coderecall.js consolidate # archive done items, retire expired entries, dedupe
Memory is plain-text Markdown — commit .ai/memory/ to git and your teammates and CI/CD share the same AI context.
❓ Troubleshooting
Hooks not firing — run node coderecall.js doctor; confirm the hook in ~/.claude/settings.json is an absolute path that exists (re-run the installer after moving the repo); restart the Claude Code session.
Installer says JSON parse failed — deliberate safety: a corrupt settings.json is never overwritten. Fix the JSON (find a settings.json.coderecall.bak.* backup) and re-run.
A project shouldn't have memory — do nothing: in projects without .ai/memory/, all hooks exit 0 immediately, zero cost.
Digest stale — a ledger unchanged for >2h is flagged STALE and the digest says "verify before trusting." Run node coderecall.js status and have the agent rewrite NOW/NEXT.
Ledger too big — run node coderecall.js consolidate; doctor warns past ~4KB/file.
Uninstall — global hooks: install.ps1 -Uninstall / install.sh --uninstall (removes only coderecall entries). Single project: node coderecall.js deinit (dry-run) → --yes (apply), preserving your content in shared files.
📄 License
MIT.