Recall: Local Project Memory for Claude Code

Recall: Local Project Memory for Claude Code

Recall is a fully-local project memory plugin for Claude Code designed to eliminate the "cold-start" problem where users must re-explain project context in every new session. By maintaining a local log of activity and condensing it into a resume-ready summary, Recall allows developers to resume work without wasting model tokens or compromising privacy.

Local Summarization and Token Efficiency

Recall provides durable memory without requiring an external LLM or API key for summarization. It uses a classical Python-based extractive summarization algorithm—combining TF-IDF and TextRank—to identify the most central sentences of a session. This approach ensures that updating project memory costs zero model tokens.

When resuming a session, Recall loads a compact context.md file (typically 1–2K tokens) rather than replaying a full conversation transcript. This significantly reduces token consumption, stretching subscription usage limits or lowering API costs.

How Recall Manages Project Memory

Recall operates using two primary files stored within a .recall/ directory in the project root:

  • history.md: An append-only log that captures every session, including prompts, AI replies, files touched, and commands executed.
  • context.md: A condensed summary that includes the project goal, a summary of progress, next steps, open threads, and a git diff --stat of recent changes.

Operational Workflow

Phase Action
During Session Stop and SessionEnd hooks incrementally append new activity to history.md.
Session Start The SessionStart hook surfaces context.md and asks the user if they wish to resume from the saved context and continue logging.
Session Wrap-up The user runs /recall:save to trigger the local summarizer, or the process happens automatically if auto_save_context is set to "on_end".

Comparison with Built-in Claude Code Memory

Recall is complementary to existing Claude Code features rather than a replacement. It fills the gap between manual instructions and full transcript replays.

Feature CLAUDE.md / # --continue / --resume Recall
Nature Hand-written rules/notes Full conversation replay Auto-captured log + local summary
Upkeep Manual None Automatic
Content Instructions to follow Full prior transcript Goals, files, commands, next steps
Resume Cost Small Large (token-heavy) Small (~1–2K tokens)
Format Editable Markdown Local session state Plaintext in .recall/
Claude's Treatment As instructions As the conversation As untrusted reference data

Privacy and Security Architecture

Recall is designed with a "zero-network" architecture. It makes no network calls, requires no API keys, and loads no third-party models. All processing occurs locally on the user's machine.

Security Measures

  • Secret Redaction: A best-effort pass strips common secret shapes (API keys, PEM keys, .env assignments) before writing to disk.
  • Hardened Git Integration: To prevent malicious repositories from executing code via git config, git diff and log are run with core.fsmonitor, diff.external, and hooks disabled.
  • Confined Writes: The output_dir is restricted to the project directory to prevent unauthorized writes to absolute paths or parent directories.
  • Trust Boundary: Because context.md can be committed to a repository, it is treated as untrusted data. Claude is notified of this boundary, and the user is asked for confirmation before relying on the saved context.

Installation and Configuration

Recall can be installed via the Claude Code marketplace:

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

Key Configuration Options (recall.config.json)

  • auto_save_context: Set to "on_end" to regenerate the summary automatically when a session ends.
  • summary_sentences: Controls how many sentences the extractive summarizer retains (default is 8).
  • include_git: Toggles the inclusion of git diff --stat and recent commits in the context.md file.
  • redact: Enables or disables the stripping of secrets from logs.

Sources