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

What you type	What happens
Full path above	Runs /recall update — LLM regenerates context.md
(context loads automatically)	Happens on first prompt of every session

---

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
}

Key	Default	Description
vault_path	required	Absolute path to your Obsidian vault
vault_folder	claude-recall	Folder name created inside the vault
max_context_tokens	400	Token budget for injected context (~1.6K chars)
include_recent_sessions	2	How many past session notes to load
load_on_every_prompt	true	Reload relevant context on every prompt
use_claude_api	true	Use Claude API for summarization

---

Troubleshooting

Symptom	Fix
Context not loading	Check hooks in ~/.claude/settings.json; restart Claude Code
"Vault not found" error	Check vault_path in config; verify drive is mounted
Sessions not saving	Verify vault is writable; check save_sessions: true in config
Wrong project loaded	Launch claude from the correct project directory
Mindmap is empty	Run /recall update to populate from filesystem
"claude CLI: not found"	Install Claude Code and ensure it's in your PATH
Hook errors	Run echo '{"cwd":"'$(pwd)'","session_id":"t"}' | python3 ~/.claude/skills/claude-recall/scripts/load_context.py
Re-install / update	Re-run the curl install command — detects existing install

---

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