recall

Zero-infrastructure memory for Claude Code
Captures session knowledge as markdown · Injects relevant context on startup · Survives compaction

---

Why recall?

Claude Code sessions are ephemeral. When a session ends or context compacts, everything you discussed — decisions, debugging steps, architectural choices — is gone. The next session starts blank.

recall fixes this with 4 lightweight hooks that automatically:

• Capture what happened (files changed, decisions made, work completed)
• Store it as plain markdown (human-readable, git-friendly, grep-able)
• Recall relevant context at the start of every new session
• Survive context compaction without losing your working state

No database. No daemon. No dependencies beyond bash + python3.

---

Installation

From the marketplace (recommended)

claude plugin add flight505/recall

From source

git clone https://github.com/flight505/recall.git
claude plugin add /path/to/recall

Verify installation

claude plugin list
# Should show: recall v1.2.0

After installation, recall works immediately — no configuration needed. End a session, start a new one, and you'll see [recall] context injected automatically.

---

How It Works

recall operates through Claude Code's hook system, intercepting 4 lifecycle events:

1. Session Ends → Capture

When you exit a session, the Stop hook (async, 30s) runs in the background:

Your session transcript (3.4 MB, ~1200 lines)
         │
         ▼  Anchored Compression (98.8% reduction)
         │  Strip: tool_result content, progress events, system metadata
         │  Filter: system-injected noise (task notifications, skill expansions)
         │  Keep: user text + assistant text + [ToolName: file_path] refs
         │
Compressed narrative (42 KB, ~330 lines)
         │
         ▼  Anchor extraction (parallel)
         │  Git commits, decision lines, edited files, tool names
         │
         ▼  Haiku summarization (single call, ~12K input tokens)
         │
Episodic entry:
  ### 14:30 — Implemented auth middleware with JWT validation
  - Goal: Add authentication to API routes
  - Outcome: JWT middleware, refresh token rotation, 12 tests passing
  - Key files: src/middleware/auth.ts, src/routes/api.ts, tests/auth.test.ts
  - Decisions: JWT over session cookies (stateless, CDN-compatible)
  - Open: Rate limiting not yet implemented

2. Next Session Starts → Recall

The SessionStart hook (sync, 5s) reads your stored memories and injects the most relevant ones:

SessionStart fires
         │
         ▼  Read episodic + semantic + working state
         │
         ▼  Priority-based assembly (4K char budget):
         │  1. Working state (only after compaction)
         │  2. Latest episodic entry
         │  3. Architecture semantic file (30-day staleness check)
         │  4. Branch-matching entries (last 7 days)
         │
         ▼  Inject via additionalContext
         │
Claude sees: "[recall] Last session: Implemented auth middleware..."

3. Context Compacts → Survive

When Claude Code runs out of context and compacts, recall protects your working state:

Context approaching limit
         │
         ▼  PreCompact hook (sync, 30s)
         │  Saves current task, progress, active files to working-state.md
         │
         ▼  Claude Code compacts (context is reset)
         │
         ▼  PostCompact hook (sync, 5s)
         │  Logs compaction event + captures Claude's compact_summary
         │
         ▼  SessionStart fires with source=compact
         │  Restores working-state.md into the fresh context
         │
You continue working as if nothing happened

---

Three-Tier Signal Hierarchy

recall uses three sources of truth, prioritized by reliability: