recall

🔁 Recall — fully-local project memory for Claude Code

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. See PRIVACY.md for the full policy.
• 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.

	CLAUDE.md / #	--continue / --resume	Recall
What it is	Hand-written notes & rules	Reloads a prior conversation	Auto-captured session log + local summary
Upkeep	Manual	None (you pick the session)	None — written as you work
Holds	Instructions to follow	The full prior transcript	Goal, files, commands, where you left off, next steps
Cost to resume	Small	Large (replays full transcript)	~1–2K tokens (compact digest)
Form	Markdown you edit	Local session state	Plaintext in .recall/ — diffable & shareable
How Claude treats it	As instructions	As the conversation	Fenced as untrusted reference data

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

Moment	What happens
During the session	The Stop / SessionEnd hooks append new activity to .recall/history.md. Capture is incremental (only new turns) and fully local.
At session start	The SessionStart hook surfaces context.md and has Claude ask you two things: resume from the saved context? and keep logging this session?
Before you wrap up	You run /recall:save. The local summarizer reads history.md and (over)writes context.md.
…or automatically	Set auto_save_context: "on_end" and context.md regenerates every time a session ends — no /recall:save needed.

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:

Key	Default	Purpose
output_dir	".recall"	Where history.md / context.md live.
capture_history	true	Append session activity to history.md.
auto_save_context	"off"	Regenerate `context.