claude-recall

💡 The Problem

Claude Code has no memory between sessions. Every time you start a new conversation, Claude forgets your project's stack, architecture decisions, gotchas, and what you worked on yesterday.

You end up repeating the same context over and over.

✅ The Solution

claude-recall hooks into Claude Code and bridges it with your Obsidian vault — completely automatically.

	Hook	What happens
🔵	Before your first message	Loads your project context from Obsidian
🟠	When you exit	Saves a structured session note back to the vault

No manual invocation. No config beyond your vault path. No files created in your project directory.

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

---

🔁 How it works

🔵 On Session Start — UserPromptSubmit hook

1. Reads context.md from your vault
2. Loads the last 2 session notes
3. Injects everything into Claude's system context

Claude starts every session already knowing your project. Context is loaded once per terminal session — not on every prompt.

🟠 On Session End — Stop hook

1. Reads the session transcript (all messages)
2. LLM analyzes the full transcript → generates summary, decisions, next steps
3. Updates context.md auto-sections with session learnings
4. Writes a dated session note to the vault

Your work is automatically documented in Obsidian. Uses claude CLI under the hood — no API keys required.

Project slug is derived from your working directory:

Path	Slug
~/projects/setu	setu
~/client/acme/dashboard	acme-dashboard
~/Desktop/Dev/Innovation/setu	innovation-setu

---

📁 What gets created in Obsidian

your-vault/
└── claude-recall/
    ├── _index.md                         ← auto-updated project log
    └── projects/
        └── setu/
            ├── context.md                ← ✏️  you edit this in Obsidian
            └── sessions/
                ├── 2026-04-10_14-30.md   ← auto-written
                └── 2026-04-11_09-15.md   ← auto-written

context.md — auto-generated project memory

context.md is auto-generated from project scan + optionally AI-enhanced via claude CLI on first load and updated after each session. You can edit it in Obsidian — your content outside <!-- auto:* --> markers is never overwritten:

## What this is
<!-- auto:what_this_is:start -->
Project: setu — blood donation platform
<!-- auto:what_this_is:end -->

## Stack
<!-- auto:stack:start -->
Flutter · Express.js · MongoDB Atlas · Railway
<!-- auto:stack:end -->

## Key files
<!-- auto:key_files:start -->
- `lib/auth/jwt_handler.dart`
- `server/routes/auth.ts`
- `lib/screens/donor_screen.dart`
<!-- auto:key_files:end -->

## Architecture decisions
<!-- auto:architecture:start -->
- JWT auth with refresh tokens stored in secure storage
- Image uploads compressed client-side before S3
<!-- auto:architecture:end -->

## Gotchas
<!-- auto:gotchas:start -->
- Railway free tier has 500MB memory limit
- MongoDB Atlas M0 caps at 500 connections
<!-- auto:gotchas:end -->

Session notes — automatic breadcrumbs

Each session note includes YAML frontmatter, making them searchable with Obsidian Dataview:

---
date: 2026-04-11
project: setu
turns: 8
tags: [claude-recall, session]
---

# Session 2026-04-11 14:30

## Started with
> Add JWT auth to the Express routes

## Stats
8 user turns · 12 total messages · 5 tool calls

## Summary
Started with: Add JWT auth... · 3 file(s) modified · Tools used: Readx2, Editx2, Bashx1

## Files touched
- server/auth.js
- routes/api.js
- lib/screens/home_screen.dart

## Tools used
- `Read`: 2x
- `Edit`: 2x
- `Bash`: 1x

## Git changes

server/auth.js | 25 +++++++++ routes/api.js | 10 ++++ 2 files changed, 35 insertions(+)

## Next steps
- [ ] _(edit in Obsidian or ask Claude to summarise)_

---

📦 Install

Requirements: Python 3.8+ · Claude Code · Obsidian

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

What the installer does:

1. Asks for your Obsidian vault path (once)
2. Saves config to ~/.claude/claude-recall.json
3. Clones this repo to ~/.claude/skills/claude-recall/
4. Installs anthropic and fastmcp via pip
5. Registers hooks + MCP server in ~/.claude/settings.json
6. Creates the vault folder skeleton

⚠️ Restart Claude Code after install.

git clone https://github.com/senapati484/claude-recall ~/.claude/skills/claude-recall
bash ~/.claude/skills/claude-recall/install.sh

---

⚙️ Config

Edit ~/.claude/claude-recall.json to override defaults:

{
  "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	What it does
vault_path	(required)	Absolute path to your Obsidian vault
vault_folder	claude-recall	Folder inside the vault for all notes
max_context_tokens	400	Token budget for injected context (~1.6K chars)
include_recent_sessions	2	How many past session notes to load
save_sessions	true	Write session notes on exit
load_on_every_prompt	true	Reload relevant context on every prompt
use_claude_api	true	Use Claude API for summarization

🤖 LLM Fallback Providers

claude-recall supports multiple AI backends for session summarization and context generation. It checks them in a specific fallback order and defaults to a zero-config local regex fallback if no backend is configured or available.

Fallback Priority Order

1. Claude CLI (Primary)

   • When used: Whenever the claude executable is found in your system's PATH.
   • How it works: Uses Claude Code's own active authentication context under the hood via claude -p.
   • Dependencies: No extra configuration or API keys are required.

2. Anthropic API (Fallback 1)

   • When used: If the claude CLI is not found or fails to run, and the ANTHROPIC_API_KEY environment variable is defined.
   • How it works: Directly calls Anthropic's API using the claude-haiku-4-5-20251001 (or haiku-4-5) model.
   • Dependencies: Requires the anthropic Python package (pip install anthropic).

3. NVIDIA NIM / OpenAI-Compatible API (Fallback 2)

   • When used: If both the claude CLI and ANTHROPIC_API_KEY are unavailable, and the OPENAI_API_KEY and NVIDIA_NIM_BASE_URL environment variables are defined.
   • How it works: Calls an OpenAI-compatible endpoint with the claude-3-5-haiku-20241022 model name (mapped appropriately by the target provider).
   • Dependencies: Requires the openai Python package (pip install openai).

4. Regex-based Fallback (Fallback 3)

   • When used: If all of the above options are unavailable or fail.
   • How it works: Parses the transcript using fast heuristic regex pattern matching to extract touched files, session metrics, and basic summaries.

Example Environment Configuration

An example configuration file is provided in the project root as .env.example. You can copy this file to .env in your project folder or export these variables directly in your terminal profile:

# Copy example env file
cp .env.example .env

Example NVIDIA NIM Setup

To use NVIDIA NIM (or another OpenAI-compatible inference endpoint) as your fallback provider, configure your .env as follows:

# Use build.nvidia.com or your local/private NIM endpoint
NVIDIA_NIM_BASE_URL="https://integrate.api.nvidia.com/v1"
OPENAI_API_KEY="nvapi-your-nvidia-api-key-here"

---

🔄 Update

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

Re-running the installer detects an existing install and runs git pull.

---

🗑️ Uninstall

# 1. Remove hooks from settings
#    Edit ~/.claude/settings.json — delete the two "claude-recall" entries

# 2. Remove skill files
rm -rf ~/.claude/skills/claude-recall

# 3. Remove config
rm ~/.claude/claude-recall.json

Your Obsidian notes under <vault>/claude-recall/ are never touched by uninstall.

---

🏗️ Architecture

┌──────────────┐       ┌──────────────────┐       ┌────────────────┐
│  Claude Code │       │  claude-recall   │       │ Obsidian Vault │
│              │       │                  │       │                │
│  Prompt      ├──────►│ load_context.py  │◄──────┤ mindmap.json   │
│  (every msg) │       │ + get_relevant() │       │ context.md     │
│              │       │                  │       │ sessions/*.md  │
│  Exit        ├──────►│ save_context.py  ├──────►│                │
│  (stop hook) │       │ + update_mindmap │       └────────────────┘
│              │       │                  │
│  Tool use    ├──────►│ post_tool_use.py │       ┌────────────────┐
│  (edit)      │       │ + mark_stale()   │       │  MCP Server    │
└──────────────┘       └────────┬─────────┘       │ recall_get()   │
                                │                 │ recall_update()│
                   ┌────────────┴────────────┐    │ recall_session_│
                   │   claude CLI (primary)  │    │ recall_mindmap │
                   │   or API key (fallback) │    └────────────────┘
                   └─────────────────────────┘
~/.claude/claude-recall.json
~/.claude/claude-recall-slug.env

---

🗺️ Mindmap Storage

claude-recall stores project context as a JSON graph at <vault>/claude-recall/projects/<slug>/mindmap.json:

{
  "_meta": {"version": 2, "updated": "2026-04-18"},
  "nodes": {
    "project_overview": {
      "content": "Blood donation platform with donor/recipient matching",
      "keywords": ["flutter", "express", "mongodb", "setu"],
      "parent": null,
      "files": [],
      "created": "2026-04-10",
      "last_updated": "2026-04-18",
      "stale": false
    },
    "stack": {
      "content": "Tech stack: Flutter, Express.js, MongoDB Atlas, Railway",
      "keywords": ["flutter", "express", "mongodb", "railway"],
      "parent": "project_overview",
      "files": ["package.json", "pubspec.yaml"],
      "stale": false
    },
    "auth_system": {
      "content": "JWT auth with refresh tokens stored in secure storage",
      "keywords": ["jwt", "auth", "security"],
      "parent": "project_overview",
      "files": ["lib/auth/jwt_handler.dart"],
      "stale": true
    }
  },
  "file_node_map": {
    "lib/auth/jwt_handler.dart": ["auth_system"]
  },
  "sessions": [
    {"date": "2026-04-18", "summary": "Added JWT auth...", "nodes_updated": ["auth_system"]}
  ]
}

Why JSON? Enables fast keyword lookups, parent/child relationships, and file→node mapping. The context.md in your vault is auto-generated from this JSON for Obsidian viewing.

---

🔌 MCP Tools

claude-recall registers an MCP server that exposes 4 tools Claude can call during a session:

Tool	When used	What it returns
recall_get(query)	You ask about past decisions/architecture	Relevant context nodes
recall_update_node(node_id, content, keywords)	You explicitly update context	Confirmation
recall_session_history(count)	You ask "what did I work on before?"	Last N session summaries
recall_mindmap()	You ask for full project overview	Full mindmap tree

These tools let Claude fetch deeper context mid-session — not just what was injected at prompt time.

---

📄 File reference

File	Purpose
install.sh	One-command GitHub installer
SKILL.md	Claude skill metadata and instructions
scripts/load_context.py	UserPromptSubmit hook — injects relevant context nodes
scripts/save_context.py	Stop hook — writes session note, updates mindmap
scripts/summarize.py	LLM summarizer using claude CLI or fallback API
scripts/mindmap.py	Mindmap storage + keyword search + node management
scripts/mcp_server.py	FastMCP server exposing recall tools to Claude
scripts/post_tool_use.py	PostToolUse hook — marks nodes stale on file edits
scripts/recall_update.py	/recall command for manual context updates
scripts/utils.py	Shared helpers (config, slugs, truncation, stack detection)
references/hook-api.md	Claude Code hook I/O specification
references/context-structure.md	Vault note formats and examples

---

🔧 Troubleshooting

Test the load hook manually:

echo '{"cwd":"'$(pwd)'","session_id":"test"}' | python3 ~/.claude/skills/claude-recall/scripts/load_context.py

If output is empty, check:

• Does context.md exist in your vault for this project?
• Is vault_path correct in ~/.claude/claude-recall.json?

Check that save_sessions is true in ~/.claude/claude-recall.json and that Claude Code is passing a transcript_path to the Stop hook.

The slug strips noise segments (projects, repos, code, src, workspace, dev, work, home) and keeps the last 2 meaningful parts. Verify with:

python3 -c "
from pathlib import Path
import sys; sys.path.insert(0, '\$HOME/.claude/skills/claude-recall/scripts')
from utils import cwd_to_slug
print(cwd_to_slug(Path('\$(pwd)')))
"

---