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: