claude-recall

Obsidian-backed persistent memory for Claude Code. Install once, works on every session. All context is auto-generated using a local LLM — no manual Obsidian editing required.

Session Model

A session = one terminal session (open terminal → close terminal or /exit). This is NOT per-prompt. The session marker at ~/.claude/.recall_<session_id> prevents context re-injection after the first prompt of a session.

Terminal session opens → UserPromptSubmit fires → context loaded ONCE
Terminal session continues → UserPromptSubmit fires → SKIPPED (marker exists)
Terminal session closes → Stop hook fires → session note written, context updated

How It Works

Session start   →  load_context.py    →  keyword match  →  inject 2-3 relevant nodes
Tool use       →  post_tool_use.py   →  mark_files_stale() on Edit/Write/Create
Session end    →  save_context.py    →  claude CLI → update mindmap.json nodes
/recall query  →  MCP server recall_get() → return relevant context nodes

Both hooks run via Claude Code hooks in ~/.claude/settings.json. No invocation needed. The /recall command is invoked directly by the user during a Claude session. MCP tools are available for Claude to call mid-session for deeper context.

Hook Events

• UserPromptSubmit: Injects relevant context nodes based on current prompt keywords
• PostToolUse: Marks mindmap nodes stale when files are edited (Edit, Write, MultiEdit, Create)
• Stop: Analyzes full transcript via claude CLI, updates mindmap.json, writes session note

LLM Model

LLM Model

claude-recall natively uses claude CLI — meaning it inherits your Claude Code auth. API keys are only used as fallback.

• Backend 1 (Primary): claude CLI backend
• Backend 2: ANTHROPIC_API_KEY (haiku-4-5)
• Backend 3: NVIDIA NIM
• If missing all: gracefully falls back to regex-based context extraction
• LLM is used for:
• Session summarization (what was done, decisions, next steps, files_and_roles)
• Project context generation (via /recall update)
• Re-summarizing stale nodes after file edits
• MCP tool responses for deeper context queries

/recall Command

To manually refresh project context during a session, type the full command:

/Users/sayansenapati/.claude/skills/claude-recall/scripts/recall_update.py update

Or from any project directory, run:

python3 ~/.claude/skills/claude-recall/scripts/recall_update.py update

Available actions:

• update — Scan project with LLM and regenerate context.md
• status — Show current context.md content
• reset — Delete context.md and regenerate from scratch

Note: /recall is not a native Claude Code command. You must use the full path above. The hint shown in Claude's context will remind you of this each session.

Quick Reference

Auto-Context Generation

Claude automatically generates and updates context.md content:

• On first session load: Analyzes transcript + scans project files to auto-populate context
• On every session end: LLM analyzes full transcript → merges new learnings into context.md
• On `/recall update`: LLM scans filesystem for stack, structure, and README → updates context.md

Auto-marker system

Auto-generated content is wrapped in markers:

## Stack
<!-- auto:stack:start -->
Next.js 16 · Tailwind CSS · TypeScript
<!-- auto:stack:end -->

• Inside markers: Managed by claude-recall, updated automatically
• Outside markers: User-owned, NEVER modified by auto-updates

Install

curl -fsSL https://raw.githubusercontent.com/senapati484/claude-recall/main/install.sh | bash

The installer:

1. Checks Python 3 + Claude Code are present
2. Asks for your Obsidian vault path (once — saved to ~/.claude/claude-recall.json)
3. Clones the repo to ~/.claude/skills/claude-recall/
4. Installs anthropic and fastmcp via pip
5. Checks for claude CLI and optional API keys
6. Registers UserPromptSubmit, Stop, and PostToolUse hooks + MCP server in ~/.claude/settings.json
7. Creates <vault>/claude-recall/ folder structure

Then restart Claude Code.

Obsidian Vault Structure

<your-vault>/
└── claude-recall/
    ├── _index.md                    ← deduplicated project table (auto-updated)
    └── projects/
        └── <project-slug>/
            ├── context.md           ← auto-populated + user can edit
            └── sessions/
                └── YYYY-MM-DD_HH-MM.md   ← auto-written on exit

`context.md` is the permanent memory file — auto-populated with project stack, architecture decisions, gotchas, and current state. Users can add their own notes outside the auto-markers. Claude reads it before your first message every session.

`_index.md` shows each project ONCE with accumulated stats:

| Project | Directory | Sessions | Total Turns | Last Active |
|---------|-----------|----------|-------------|-------------|
| setu    | `/home/.../setu` | 5 | 127 | 2025-01-16 14:07 |

Project slug is derived from the directory you launched claude in: /home/sayan/projects/setu → setu, /home/sayan/client/acme → client-acme

Scripts

• scripts/load_context.py — UserPromptSubmit hook. Fires on every prompt.
• Injects 2-3 relevant context nodes based on keyword matching
• Auto-generates mindmap.json on first load if missing
• Loads relevant nodes + last session summary → stdout for Claude
• Starts MCP server process for recall tools
• scripts/save_context.py — Stop hook. Fires on exit.
• Parses full transcript (all messages, tool calls, errors, file ops)
• Generates structured summary (summary, decisions, files_and_roles, keywords) via LLM
• Updates mindmap.json nodes with session learnings
• Writes context.md (Obsidian-readable) from mindmap
• Writes session note to sessions/YYYY-MM-DD_HH-MM.md
• Updates _index.md
• scripts/summarize.py — LLM summarizer.
• Automatically routes to claude CLI or Anthropic/NIM APIs
• Returns structured JSON: summary, decisions, files_and_roles, next_steps, keywords
• Falls back to regex if LLMs unavailable
• scripts/mindmap.py — Mindmap storage + retrieval.
• load_mindmap(), save_mindmap(), get_relevant_nodes()
• upsert_node(), mark_files_stale(), build_initial_mindmap_from_stack()
• mindmap_to_context_md() for Obsidian viewing
• scripts/mcp_server.py — FastMCP server.
• Exposes recall_get(), recall_update_node(), recall_session_history(), recall_mindmap()
• Claude can call these mid-session for deeper context
• scripts/post_tool_use.py — PostToolUse hook.
• Marks mindmap nodes stale when files are edited (Edit, Write, MultiEdit, Create)
• scripts/recall_update.py — /recall command.
• update: Build initial mindmap from filesystem + README
• status: Show mindmap as tree with stale indicators
• query: Search mindmap for relevant nodes
• reset: Delete and regenerate mindmap.json
• scripts/utils.py — shared helpers:
• llm_available() — checks for claude CLI or API keys
• get_anthropic_client() — cached Anthropic client
• merge_auto_section() — preserves user content outside auto-markers
• detect_project_stack() — scans package.json, requirements.txt, etc.

Config (~/.claude/claude-recall.json)

{
  "vault_path": "/path/to/your/vault",
  "vault_folder": "claude-recall",
  "max_context_tokens": 400,
  "include_recent_sessions": 2,
  "save_sessions": true,
  "load_on_every_prompt": true,
  "use_claude_api": true
}

Troubleshooting

When Helping the User

• First-time setup: walk through install → vault path → restart → test with a prompt
• Context not appearing: check hook registration → run load script manually → open vault
• Editing context: guide to <vault>/claude-recall/projects/<slug>/context.md in Obsidian
• Auto-generated sections are inside <!-- auto:*:start/end --> markers
• User can add their own content anywhere outside markers
• LLM model missing: explain auto-download or manual download from HuggingFace
• Token savings: explain that pre-loaded context avoids repeated codebase discovery
• /recall commands: run recall_update.py when user asks for context refresh