recall

---

▾ TL;DR

▸ What — a Claude Code plugin that writes a structured log of each session to .claude/status.md and lets you resume on demand. ▸ Why — keep continuity across sessions without paying token cost on every start, without an opaque SQLite memory, without a background worker, and without competing with your existing task.md/output.md subagent files. ▸ How — install once, opt in per project with /recall:init, work normally, type /recall:resume when you want to pick up where you left off.

# install (once, from your shell — fully automated)
curl -fsSL https://raw.githubusercontent.com/tonimaxx/recall/main/install.sh | bash

# enable in a project (once per project, from inside Claude Code)
cd ~/my-project
/recall:init

That's it. SessionEnd writes .claude/status.md. SessionStart shows a one-line banner. Everything else is opt-in.

---

◇ Architecture

flowchart LR
    subgraph plugin["recall plugin · ~/code/recall (single source)"]
        man[".claude-plugin/plugin.json"]
        h["hooks/<br/>session-start-banner.sh<br/>session-end-write.sh<br/>stop-debounce.sh"]
        s["skills/<br/>init · resume · checkpoint"]
        l["lib/common.sh"]
    end

    subgraph proj["per project · opt-in"]
        marker[".claude/recall.json<br/>(presence ⇒ enabled)"]
        log[".claude/status.md<br/>(append-only)"]
        arc[".claude/status-archive.md<br/>(spillover)"]
        sub["task.md · output.md · status.md<br/>(your subagent files)"]
    end

    plugin -->|"installed via<br/>/plugin install"| reg["registered globally<br/>(but inert by default)"]
    reg -->|hook fires| chk{".claude/recall.json<br/>exists?"}
    chk -->|no| noop["exit 0<br/>(other projects unaffected)"]
    chk -->|yes| run["read transcript →<br/>redact secrets →<br/>fold subagent state →<br/>append entry"]
    run --> log
    log -->|"cap > max_entries"| arc
    sub -.-> run

    classDef inert fill:#e8e8e8,stroke:#999
    classDef active fill:#d6e8ff,stroke:#1f6feb
    class noop inert
    class run,log active

▸ Plugin lives in one place; updates propagate everywhere. ▸ Inert mode — without .claude/recall.json in a project, every hook short-circuits in microseconds. The plugin is invisible. ▸ Active mode — with the marker, hooks read the session transcript, redact configured patterns, fold tails of your subagent files, and append a structured entry.

---

◇ Lifecycle

sequenceDiagram
    autonumber
    participant U as User
    participant CC as Claude Code
    participant H as recall hooks
    participant S as .claude/status.md

    U->>CC: claude (in project with recall.json)
    CC->>H: SessionStart
    H->>S: read newest entry
    H-->>CC: additionalContext = "recall · last session: …"
    CC-->>U: banner shown (~50 tokens)

    Note over U,CC: …work happens…

    U->>CC: /recall:resume
    CC->>S: read last 1–3 entries
    CC-->>U: full context loaded on demand

    U->>CC: /recall:checkpoint "fixed migration race"
    CC->>S: append entry now

    U->>CC: exit
    CC->>H: SessionEnd
    H->>S: append entry (structured)
    Note over H: Stop debounce hook covers<br/>force-quit / network drop

---

◇ Why recall instead of …

Tool	Mechanism	Cost	Differentiator
recall (this)	shell hooks → .claude/status.md	$0, no runtime	deliberate, file-based, integrates with task.md / output.md
claude-mem	5 hooks + bg worker on :37777 + SQLite	API tokens for AI summaries on every Stop	global by default; opaque DB; auto-summarized
b17z/sage	MCP server + skills + plugin	API tokens; runtime	semantic / Obsidian-style, more academic-research shaped
sinzin91/claude-checkpoint	manual /checkpoint /restore	$0	manual only, stores in /tmp
Native /rewind	built-in	$0	rolls back file edits, not session memory

recall's pitch in one sentence: "What if my own deliberately-written status.md got auto-appended on every session end, and a one-line banner reminded me on session start, with zero LLM in the loop?"

---

◆ Install

Option A — one-line installer (recommended)

curl -fsSL https://raw.githubusercontent.com/tonimaxx/recall/main/install.sh | bash