Recall: Fully-Local Project Memory for Claude Code

What is Recall?

Recall is a Claude Code plugin that solves the cold-start problem: every Claude Code session starts blank, forcing you to re-explain your project. Recall automatically logs sessions and condenses them into a compact context.md summary using a local TF-IDF + TextRank algorithm. No API key, no network calls, no external model.

Why It Matters

Claude Code's built-in memory options have gaps:

• CLAUDE.md is hand-written rules, not automatic session history.
• --continue replays full transcripts, costing many tokens.
• Context compaction works only within a session.

Recall fills the gap: it automatically captures what happened, then produces a ~1–2K token digest you load next session. The summarizer runs locally with zero token cost.

How It Works

Recall hooks into Claude Code session lifecycle events:

• During session: Stop and SessionEnd hooks append new activity to .recall/history.md.
• Session start: SessionStart hook surfaces context.md and asks if you want to resume.
• Manual save: Run /recall:save to run the local summarizer and overwrite context.md.
• Auto-save: Set auto_save_context: "on_end" to regenerate summary when a session ends.

No LLM calls anywhere. The summarizer uses TF-IDF sentence vectors, builds a cosine-similarity graph, then applies TextRank (PageRank on sentences) to extract the most central sentences.

Technical Details

The summarizer is in scripts/summarizer.py — a vendored implementation with no install required. If numpy is available, it accelerates vector math; otherwise, a pure-Python fallback runs identically. The output tells you which path executed.

Configuration is via recall.config.json in the project root. Key options:

• output_dir: default .recall
• capture_history: boolean (default true)
• auto_save_context: "off" or "on_end"
• summary_sentences: number of sentences to keep (default 8)
• redact: strips common secrets before writing (default true)
• include_git: adds git diff --stat and recent commits (default true)
• max_input_chars: cap on text fed to summarizer (default 200000)

Example config:

{
  "output_dir": ".recall",
  "capture_history": true,
  "auto_save_context": "on_end",
  "summary_sentences": 10,
  "redact": true,
  "include_git": true,
  "max_input_chars": 300000
}

Privacy & Security

Recall makes zero network calls, uses no API keys, and loads no third-party models. The summarizer is local Python; hooks use stdlib only (numpy optional).

Key design decisions:

• Redaction: Best-effort pass strips API keys, tokens, .env assignments, PEM keys before writing.
• Hardened git: Git commands run with core.fsmonitor, diff.external, hooks, and pager disabled to prevent untrusted repo config from executing code.
• Confined writes: output_dir forced inside the project; config can't redirect to absolute paths or ../...
• Scoped transcript: Only reads transcript for current project (matched by cwd).
• Trust boundary: context.md is injected at session start but fenced as untrusted reference data — Claude asks before relying on it. For shared team memory, consider the risk of prompt injection if .recall/ is committed.

Installation

From the Claude Code plugin marketplace:

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

Or for local development:

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

No pip install needed. The summarizer is vendored and stdlib-only.

Development & Quality

The repo includes a benchmark suite (benchmarks/bench.py) that scores summarizer quality against lead/tail/random baselines on a labeled fixture set. It also checks that numpy and pure-Python cores select the same sentences. CI runs lint, Bandit, tests across Python 3.9–3.13 (with and without numpy), CodeQL, and secret scanning.

Comparison with Built-in Options

Feature	CLAUDE.md	--continue	Recall
What it is	Hand-written notes	Reloads prior conversation	Auto-captured log + local summary
Upkeep	Manual	None	None
Holds	Instructions	Full transcript	Goal, files, commands, next steps
Cost to resume	Small	Large	~1–2K tokens
Form	Markdown	Session state	Plaintext in .recall/
Claude treats it as	Instructions	Conversation	Untrusted reference data

Summary

Recall is a practical, privacy-first solution for persistent session memory in Claude Code. It uses a deterministic local summarizer to produce compact digests, saving tokens and protecting your data. If you use Claude Code locally on a subscription, Recall is a no-brainer addition.