recall

Claude Code starts every session cold. Recall keeps a local log of your sessions and condenses it into a resume-ready summary — entirely on your machine. No API key, no external model, nothing sent anywhere. It's built for people running Claude Code locally on a subscription: the only AI in the loop is Claude Code itself; the summarization is done by a classical Python summarizer.

Why Recall

• Free on your subscription. It solves the cold-start problem — no more re-explaining the project each session — without a metered summarizer running up a bill. The summary is a local algorithm, not an LLM call, so persistent memory costs you nothing beyond the subscription you already pay for.
• Saves your usage credits. Two ways: (1) the summary is built locally, so capturing and updating your memory spends zero model tokens; and (2) resuming from a compact context.md (~1–2K tokens) instead of re-explaining the project from scratch each session means far fewer tokens spent per session — stretching your subscription's usage limits (or, on the API, lowering billed credits).
• Nothing leaves your machine. Your transcripts (code, paths, sometimes secrets) are never sent to any API. Most "memory" tools pipe your context to a model endpoint; Recall makes a privacy guarantee they can't.
• Zero-friction. No pip install, no local model to run, no key to configure, works offline. It starts working the moment the plugin loads.

Two files, written into your project under .recall/:

• history.md — the log. Append-only. Every session is captured here as it happens (your prompts, Claude's replies, the files touched and commands run).
• context.md — the summary. Overwritten by the local summarizer — the condensed "where are we right now" you load into the next session: goal, summary, next steps / open threads, files touched, and where you left off.

"Doesn't Claude Code already have memory?"

It does — and Recall is complementary, not a replacement. The built-in options solve different problems:

• CLAUDE.md (and the # shortcut) is hand-written memory: rules and notes you curate, loaded as instructions Claude follows. Great for "how I want you to work," but it's manual upkeep and it doesn't record what actually happened in a session.
• --continue / --resume replays a prior conversation — full fidelity, but it reloads the whole transcript (token-heavy) and is tied to your local session history on one machine, not a portable, readable digest.
• Context compaction condenses a conversation within a session; it isn't a durable record you reopen days later.

Recall fills the gap between these: an automatic, deterministic record of what each session did, condensed into a compact resume point.

In short: CLAUDE.md is how I want you to work; Recall is here's what we did last time and where we stopped — produced offline, with no model tokens spent.

How it works

There is no LLM call anywhere — the summary is produced by TF-IDF + TextRank (extractive summarization) running locally.

The summarizer

scripts/summarizer.py ranks the most central sentences of your session:

1. TF-IDF sentence vectors
2. a cosine-similarity graph between sentences
3. TextRank — PageRank power iteration over that graph — to score sentences
4. the top N are kept in original order

context.md wraps that summary with deterministic facts pulled straight from the transcript and git: the goal (your first ask), files touched, commands run, where you left off, and git diff --stat.

No installs required. The whole TF-IDF + TextRank implementation is vendored in summarizer.py. If numpy happens to be importable it's used to vectorize the math (faster on big sessions); if not, an identical pure-Python TextRank runs instead. Same algorithm, same result — numpy is an optional accelerator, never a requirement. The save output tells you which path ran.

Commands

• /recall:save — run the local summarizer → (over)write context.md.
• /recall:show — print context.md.
• /recall:log — tail history.md.

Configuration — recall.config.json

Drop this in your project root to override defaults:

Pause logging for a project without editing config: create .recall/.capture-paused. Delete it to resume.

Privacy & security

Recall makes no network calls, uses no API key, and loads no third-party model. The summarizer is local Python; the hooks are stdlib-only (numpy is an optional accelerator). It reads your session transcript and writes only under output_dir. Concretely:

• No credentials, ever. The plugin has zero references to API keys, auth, ANTHROPIC_*, or HTTP. If claude itself shows "Invalid API key", that's the CLI's own auth — usually a stale ANTHROPIC_API_KEY env var shadowing your subscription login. unset ANTHROPIC_API_KEY (or run env -u ANTHROPIC_API_KEY claude …). It has nothing to do with Recall.
• Redaction. A best-effort pass strips common secret shapes (API keys, tokens, .env assignments, PEM keys) before writing, since context.md / history.md may be committed. Best-effort, not a guarantee — review before committing.
• Hardened git. git diff/log are run with core.fsmonitor, diff.external, hooks, and the pager disabled, so an untrusted cloned repo can't use its own git config to execute code when Recall reads ground-truth. Set include_git: false to skip git entirely.
• Confined writes. output_dir is forced to stay inside the project; a project-shipped config can't redirect writes to an absolute path or ../...
• Scoped transcript. Recall only reads the transcript for the current project (matched by cwd); it never falls back to another project's sessions.
• Trust boundary for shared memory. context.md is injected into the model at session start. If you commit .recall/ as shared team memory, treat it like any other shared input: a teammate (or a bad actor with repo write access) could craft a context.md to attempt prompt-injection. SessionStart fences the content and labels it untrusted data, and Claude asks before relying on it — but if you don't fully trust who can write the repo, keep .recall/ git-ignored (the default).

Committing .recall/

Both are fine. Commit it for shared team memory, or git-ignore it for personal memory (.gitignore ships ignoring it by default — flip the comment to commit).

Install

From the marketplace (this repo is its own marketplace):

/plugin marketplace add raiyanyahya/recall
/plugin install recall@recall

Local dev (no install step):

claude --plugin-dir /path/to/recall

No pip install — the summarizer is vendored and stdlib-only (numpy used as an optional accelerator if present). Work a session, run /recall:save, and open a fresh session — Recall greets you with where you left off.

Development

python -m venv .venv && . .venv/bin/activate
pip install pytest ruff bandit numpy   # numpy optional