Skip to content

README.md

Latest commit

 

History

History
204 lines (162 loc) · 12.2 KB

README.md

File metadata and controls

204 lines (162 loc) · 12.2 KB

Recall — Persistent Memory for Claude Code

Recall — Persistent Memory for Claude Code

Every Claude Code session starts from zero. Recall fixes that — conversations are automatically extracted, indexed, and searchable across sessions.

Opencode and Pi π are very Alpha

Jump to the Docs

The Problem

Claude Code has no memory between sessions. Context is lost. You repeat yourself. Decisions made last week are forgotten today.

How Recall Fixes It

Install once, then forget about it. Recall runs silently in the background:

graph LR
    A[You Work] --> B[Session Ends]
    B --> C[Auto-Extract]
    C --> D[SQLite + FTS5]
    D --> E[Next Session]
    E -->|Memory Available| A

    style A fill:#3B82F6,color:#fff
    style C fill:#10B981,color:#fff
    style D fill:#F59E0B,color:#fff
Loading
  • Auto-extraction — sessions are parsed into structured summaries when they end
  • Full-text + semantic search — find anything from any past session
  • Zero friction — no workflow changes, no manual steps
  • MCP integration — Claude Code searches your memory automatically

Quick Start

git clone https://github.com/edheltzel/Recall.git
cd Recall
./install.sh

Verify it works:

mem stats        # Database overview
mem doctor       # Health check

Restart Claude Code to load the MCP server and hooks.

Full installation guide — prerequisites, platform support, session extraction setup

How Recall Works

Recall operates as three integrated layers — data flows in automatically, gets stored in a searchable database, and surfaces when you (or Claude) need it.

┌──────────────────────────────────────────────────────────────────────┐
│                        DATA ENTRY POINTS                             │
│                                                                      │
│  ┌────────────┐  ┌────────────┐  ┌──────────────┐  ┌────────────┐    │
│  │ CLI Direct │  │ MCP Server │  │  Stop Hook   │  │   Batch    │    │
│  │  mem add   │  │ (Claude    │  │ SessionExt-  │  │  Extract   │    │
│  │  mem dump  │  │  Code)     │  │  ract.ts     │  │  (cron)    │    │
│  └─────┬──────┘  └─────┬──────┘  └──────┬───────┘  └─────┬──────┘    │
└────────┼────────────────┼────────────────┼────────────────┼──────────┘
         │                │                │                │
         ▼                ▼                ▼                ▼
┌───────────────────────────────────────────────────────────────────────┐
│                      PROCESSING LAYER                                 │
│                                                                       │
│  Direct Inserts:              Session Extraction Pipeline:            │
│  mem add breadcrumb ──┐       Read JSONL                              │
│  mem add decision  ───┤         → Filter noise (tool results)         │
│  mem add learning  ───┤         → Dedup check (.extraction_tracker)   │
│  memory_add (MCP)  ───┤         → Acquire lock                        │
│                       │         → Claude Haiku extract                │
│                       │           (>120K? chunk → meta-extract)       │
│                       │           (fallback: Ollama)                  │
│                       │         → Quality gate                        │
│                       │           (requires SUMMARY + MAIN IDEAS)     │
│                       │              │                                │
└───────────────────────┼──────────────┼────────────────────────────────┘
                        │              │
                        ▼              ▼
┌──────────────────────────────────────────────────────────────────────┐
│                    STORAGE LAYER (Dual-Write)                        │
│                                                                      │
│  SQLite (~/.claude/memory.db)       Memory Files (~/.claude/MEMORY/) │
│  ┌────────────────────────────┐     ┌──────────────────────────────┐ │
│  │ sessions ←── messages      │     │ DISTILLED.md    (archive)    │ │
│  │ decisions    learnings     │     │ HOT_RECALL.md   (last 10)    │ │
│  │ breadcrumbs  loa_entries   │     │ SESSION_INDEX.json           │ │
│  │ embeddings (768-dim vecs)  │     │ DECISIONS.log                │ │
│  │                            │     │ REJECTIONS.log               │ │
│  │ FTS5 indexes (auto-sync)   │     │ ERROR_PATTERNS.json          │ │
│  │ WAL mode · 0600 perms      │     └──────────────────────────────┘ │
│  └────────────────────────────┘                                      │
└──────────────────────────────────────────────────────────────────────┘
                        │
                        ▼
┌──────────────────────────────────────────────────────────────────────┐
│                      RETRIEVAL LAYER                                 │
│                                                                      │
│  ┌───────────────┐  ┌────────────────┐  ┌─────────────────────────┐  │
│  │Keyword (FTS5) │  │Semantic (Embed)│  │  Hybrid (RRF Fusion)    │  │
│  │mem search     │  │mem semantic    │  │  mem hybrid (DEFAULT)   │  │
│  │memory_search  │  │embed → Ollama  │  │  FTS5 rank ─┐           │  │
│  │               │  │cosine sim      │  │  Embed rank ─┤→ merged  │  │
│  └───────────────┘  └────────────────┘  │  RRF(k=60) ◄┘           │  │
│                                         └─────────────────────────┘  │
│  Direct: mem recent · mem show · memory_recall · context_for_agent   │
└──────────────────────────────────────────────────────────────────────┘
                        │
                        ▼
┌──────────────────────────────────────────────────────────────────────┐
│  CONSUMERS:  Claude Code (MCP)  ·  CLI User (mem)  ·  Sub-agents     │
└──────────────────────────────────────────────────────────────────────┘

Session Lifecycle

  1. Session starts — A SessionStart hook loads recent decisions, breadcrumbs, and learnings from SQLite, giving Claude context from previous sessions immediately
  2. During the session — Claude searches memory via MCP tools (memory_search, memory_hybrid_search) before falling back to git history. Decisions and learnings are recorded in real-time with memory_add
  3. Session ends — A Stop hook fires SessionExtract.ts, which spawns a background process (non-blocking) to extract the conversation via Claude Haiku
  4. Extraction pipeline — The conversation JSONL is filtered, deduplicated, and sent to Claude Haiku (with chunking for large sessions >120K chars). A quality gate rejects low-quality extractions
  5. Dual-write storage — Results are written to both SQLite (structured, searchable) and markdown files (DISTILLED.md, HOT_RECALL.md, etc.)
  6. Batch catchup — A cron job (BatchExtract.ts) runs every 30 minutes to catch sessions missed during crashes or interruptions

Search Strategies

Strategy Command How it works
Keyword mem search "query" FTS5 full-text search across all tables
Semantic mem semantic "query" Ollama embeddings → cosine similarity (requires Ollama)
Hybrid (default) mem "query" Both keyword + semantic, merged with Reciprocal Rank Fusion (k=60). Falls back to keyword-only if Ollama is unavailable

Architecture deep-dive — database tables, FTS5 indexes, extraction pipeline details

What You Get

  • Session memory — auto-extracted on every session end via Claude Haiku
  • Full-text + semantic search — FTS5 keyword search, Ollama vector embeddings, or hybrid with Reciprocal Rank Fusion
  • Decision & learning tracking — record architectural decisions with reasoning, capture problems solved
  • Agent context — spawned agents inherit relevant memory via context_for_agent
  • Library of Alexandria — curated knowledge entries with Fabric extract_wisdom analysis
  • Breadcrumbs — quick context notes for future sessions

CLI at a Glance

mem "kubernetes auth"          # Search your memory
mem dump "Session Title"       # Save this session
mem add decision "Use X" ...   # Record a decision
mem stats                      # See what's stored
mem doctor                     # Health check
See it in action
Search Stats
mem search mem stats
Health Check Recent Memory
mem doctor mem recent

Full CLI reference

For AI Agents

If you're an AI agent reading this repository:

What you need Where to find it
Using Recall (MCP tools, CLI, core rules) FOR_CLAUDE.md
Developing Recall (build, test, conventions) CLAUDE.md

Documentation

Guide Description
Installation Prerequisites, install, verify, session extraction
CLI Reference All commands and options
MCP Tools Tools available to AI agents
Architecture Database, search, extraction pipeline
Slash Commands /recall:* commands for Claude Code
Upgrading Update, backup, migration system
Troubleshooting Common issues and fixes

License

MIT