Recall: Local Project Memory for Claude Code

Recall provides durable, offline memory for Claude Code

Recall is a local-first plugin designed to solve the "cold-start" problem in Claude Code sessions. It automatically captures session activity and condenses it into a compact, resume-ready summary stored entirely on the user's machine. By using a classical Python summarizer instead of an LLM, Recall allows developers to resume work with project context without spending additional model tokens or sending sensitive session transcripts to an external API.

Core Functionality and Memory Architecture

Recall manages project memory through two primary files stored in a .recall/ directory within the project root:

  • history.md: An append-only log that captures every session, including prompts, Claude's replies, files touched, and commands executed.
  • context.md: A condensed summary of the project's current state, including the goal, a summary of progress, next steps, open threads, and a list of files touched.

The Local Summarization Process

Unlike most memory tools that rely on LLM calls, Recall uses a deterministic, local algorithm to generate context.md. The summarizer (scripts/summarizer.py) employs TF-IDF (Term Frequency-Inverse Document Frequency) and TextRank (a PageRank-based power iteration over a cosine-similarity graph of sentence vectors).

This extractive summarization approach ensures that:

  1. Zero Token Cost: Updating memory costs nothing beyond the existing Claude Code subscription.
  2. Privacy: Transcripts and secrets never leave the local machine.
  3. No Dependencies: The implementation is vendored in pure Python; while numpy is used as an optional accelerator for larger sessions, it is not required for the tool to function.

Integration with Claude Code

Recall complements existing Claude Code memory features rather than replacing them. It fills a specific 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) ~1–2K tokens (compact digest)
Format Editable Markdown Local session state Plaintext in .recall/

Workflow and Commands

  • Session Start: The SessionStart hook surfaces context.md and asks the user if they wish to resume from the saved context and continue logging the session.
  • During Session: Stop and SessionEnd hooks incrementally append activity to history.md.
  • Saving Context: Users can run /recall:save to trigger the local summarizer or enable auto_save_context: "on_end" in recall.config.json to automate the process.
  • Utility Commands: /recall:show prints the current context, and /recall:log tails the history log.

Privacy, Security, and Configuration

Recall is designed with a strict trust boundary to prevent data leakage and code execution:

  • Network Isolation: The plugin makes no network calls and requires no API keys.
  • Secret Redaction: A best-effort pass strips common secret shapes (API keys, PEM keys, .env assignments) before writing to disk.
  • Hardened Git Integration: When pulling git diff or log for the context summary, Recall disables core.fsmonitor, diff.external, and hooks to prevent untrusted repositories from executing code.
  • Path Confinement: The output_dir is forced to remain within the project directory to prevent directory traversal attacks.

Community Perspectives and Alternatives

Discussion among developers reveals varying approaches to managing agent memory. While some find Recall's automation valuable for auditing and retrieving "transversal context," others rely on manual alternatives:

  • Manual Status Docs: Some users maintain a status_docs/ folder with dated markdown files, acting as a project diary for both the human and the LLM.
  • Manual State Management: Others use a state.md file, updated at milestones and manually edited to remove "blind alleys" or failed debugging attempts.
  • Skepticism of Automation: Some developers argue that starting fresh sessions is often preferable to avoid "poisoning" the agent with stale plans or failed guesses that may persist in an automated summary.

"The hard part with project memory isn’t saving more stuff, it’s deciding what not to trust later. Stale plans and failed debugging guesses can quietly poison an agent pretty fast."

Related Tools

Developers have noted other local-first indexing tools, such as ccrider, which indexes session transcripts into a local SQLite FTS database for searchable history via TUI, CLI, or MCP server.

Sources