/claude-recall

name: claude-recall
description: >
  Always-on Claude Code skill that bridges Claude with an Obsidian vault for persistent
  project memory. Automatically loads relevant context nodes from mindmap.json before every
  prompt (UserPromptSubmit hook) and saves structured session notes to the vault on exit
  (Stop hook). Zero manual invocation — hooks fire automatically.

  Context is AUTO-GENERATED using the claude CLI. Claude analyzes
  transcripts and project files to populate mindmap.json with stack, architecture decisions,
  gotchas, and current state. Users never need to manually edit.

  The /recall command lets users trigger on-demand context updates from the terminal.
  MCP tools (recall_get, recall_update_node, recall_session_history, recall_mindmap) let
  Claude fetch deeper context mid-session.

  Storage: <vault>/claude-recall/projects/<project-slug>/mindmap.json (JSON graph)
  and sessions/YYYY-MM-DD_HH-MM.md (session notes). Project slug is derived from
  the directory Claude Code was launched in.

  Install from GitHub (one command):
    curl -fsSL https://raw.githubusercontent.com/senapati484/claude-recall/main/install.sh | bash

  Requires: Python 3.8+, Obsidian, Claude Code CLI in PATH. API keys are optional fallbacks.

  Consult this skill for: install help, Obsidian vault path issues, hooks not firing,
  context not loading, sessions not saving, editing context.md, vault folder structure,
  slug mapping questions, config options, uninstalling, /recall commands.

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