claude-recall

Persistent Obsidian memory for Claude Code
_{Install once · Works every session · Zero config · Zero project pollution}

💡 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.

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:

📁 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
}

🔄 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:

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

📄 File reference

🔧 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)')))
"

_{Built with 🧠 by senapati484}