cap'n hook Review 2026: Persistent memory for coding agents that cache-busts on file change

If you’ve ever watched a coding agent grind through the same codebase mysteries session after session — re-reading files you already explained, re-tracing call chains you already mapped — you know the pain. AI coding assistants are brilliant, but their amnesia is expensive: every new session means burning thousands of tokens re-discovering what was already known. cap’n hook tackles this problem head-on with a disarmingly simple idea: let the agent save what it learned, and automatically invalidate that memory when the files change.

Built as a lightweight SessionStart hook for Claude Code and Codex, cap’n hook requires no wrapper, no middleware, and no server. It stores human-readable Markdown entries in a local .capn/ directory that you can browse, edit, or even use as a project knowledge base. When the agent figures something out — say, which module owns authentication logic or how the database migration pipeline works — it saves the key files as a named memory. Next session, a single CLI command recalls that context, skipping the re-exploration entirely.

What cap’n hook Does

cap’n hook is a local-first memory tool that gives coding agents persistent recall across sessions. Its killer feature is cache-busting: every saved memory is fingerprinted with the SHA-256 hash of its backing files. The moment a file changes or disappears, the corresponding memory is automatically deleted — you never act on stale information. The tool works agent-agnostically through its CLI, supporting both QMD hybrid search and BM25, and installs as a zero-friction SessionStart hook.

Use Cases

• Onboarding a new agent to a large codebase: Instead of letting the agent spend 20 minutes exploring the repo structure, recall a pre-saved memory that maps out the architecture, key modules, and entry points — cutting setup time dramatically.
• Deep-dive debugging sessions: When debugging a complex issue across multiple files, save the discovered relationships and call chains. If the bug resurfaces next sprint, the agent picks up exactly where you left off.
• Code review assistance: Save the reasoning behind past review decisions — why a certain pattern was rejected, which edge cases were considered — so future reviews stay consistent without re-litigation.
• Multi-session feature development: Building a feature across several days? Each session, the agent recalls the design decisions, file layouts, and dependencies from the previous session, maintaining momentum.

Key Features

Persistent Recall with Zero Overhead

Save answer files once with capn save <name> <files...>, then recall them next session with capn recall <query>. The agent gets the exact context it needs without re-exploring the codebase, saving tokens and time.

Auto Cache-Bust via SHA-256 Fingerprints

This is where cap’n hook stands apart from simple note-taking. Each memory entry is hashed against its source files. Change auth.ts and any memory that depended on it evaporates. No stale answers, ever.

Agent-Agnostic CLI with Dual Search Modes

The core CLI works with any coding agent, not just Claude Code or Codex. It offers QMD (Query-based Memory Discovery) for semantic search and traditional BM25 for keyword matching. The official hooks simply wire the CLI into the agent’s session lifecycle.

Human-Readable Memory Graph

All memories live as plain Markdown files in .capn/entries/. You can read them yourself, edit them, version-control the ones you want, and .gitignore the rest. No black-box database, no proprietary format.

Lightweight Hook Architecture

Installation is a single line in your Claude Code or Codex config. No wrapper scripts, no middleware servers, no additional processes running in the background. The hook fires at session start and injects a system prompt that teaches the agent how to use capn.

Pricing

cap’n hook is completely free and open-source under the MIT license. There are no paid tiers, no API keys to buy, and no usage limits. The only cost is the one-time download of an embedding model (300MB–2GB depending on configuration) on first run, and the disk space for your .capn/ directory. Everything runs locally on your machine.

Common Questions

Does cap’n hook work with other coding agents besides Claude Code and Codex? Yes, the core CLI is agent-agnostic. While official SessionStart hooks are only available for Claude Code and Codex, you can use the CLI directly with any agent — just tell the agent the capn recall and capn save commands are available. Community hooks for other agents may emerge as adoption grows.

Is my code ever sent to a cloud service? No. cap’n hook is entirely local-first. Embeddings are computed on your machine, memories are stored in a local .capn/ directory, and nothing leaves your filesystem. The tool is designed for developers who care about code confidentiality.

What happens if I rename or move a file that’s part of a memory? The SHA-256 fingerprinting detects the change immediately. If a file in a memory entry no longer exists at its recorded path, that memory is automatically deleted on the next recall attempt. This keeps your memory graph clean but means you may need to re-save memories after significant refactors.

Verdict

cap’n hook earns an 8.4/10. It solves a real, expensive problem — agent amnesia across sessions — with an elegant, local-first approach that respects developer privacy. The auto cache-bust mechanism is genuinely clever and solves the “stale answer” problem that plagues simpler note-taking approaches. In benchmarks across 5 production codebases, it delivered 77% token savings at equal correctness, which translates directly to faster sessions and lower API costs.

The trade-offs are reasonable: you need to download an embedding model, memories don’t sync across machines, and the agent has to actually follow the hint to use the tool. But for any developer who regularly works with AI coding assistants on non-trivial codebases, cap’n hook is a straightforward win.