Recall

TL;DR

Recall is a retrieval-first memory layer: everything lands in one searchable database, the best of it is ranked and injected at session start, and decisions carry confidence, importance, and a lifecycle across any coding agent/harness.

> A SQLite-backed persistent memory layer for coding agents. Stop-hook extraction captures sessions as you work, MCP tools expose them mid-session, hybrid search (FTS5 + embeddings) retrieves them, and a tiered L0/L1 recall block injects identity + top-ranked records at every session start. Works across Claude Code, OpenCode, and Pi from one local database.

Got questions about the project? I'd suggest using DeepWiki from Devin/Cognition to ask questions about the project.

Recall — Persistent Memory for Any Agent Harness

All coding agents forget when a session ends. Recall doesn't — it extracts, indexes, and recalls what matters across every session, across every agent you use.

Built on the Model Context Protocol. One SQLite file. No phone-home. No vendor lock-in.

> Stable on Claude Code. Beta on Pi and Alpha for OpenCode (MCP works; lifecycle extensions are early). Codex CLI and Gemini CLI on the roadmap. See [Roadmap](#roadmap).

---

[Jump to the Docs](#documentation)

The Problem

AI agents have no memory between sessions. Context is lost. You repeat yourself. Decisions made last week are forgotten today. Every new session re-learns the basics.

How Recall Fixes It

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

┌──────────┐    ┌────────────────┐    ┌──────────────┐    ┌───────────────┐    ┌──────────────┐
│ You Work │───▶│ Stop hook fires│───▶│ Auto-Extract │───▶│ SQLite + FTS5 │───▶│ Next Session │
└─────▲────┘    │ (end of turn)  │    └──────────────┘    └───────────────┘    └──────┬───────┘
      │         └────────────────┘                                                    │
      └───────────────────────────── Memory Available ───────────────────────────────┘

• Auto-extraction — sessions are parsed into structured summaries incrementally as you work (Stop hook fires at the end of every turn, not only when you exit)
• Full-text + semantic search — find anything from any past session
• Tiered session-start context — L0 identity (who you are) + L1 importance-ranked top records load automatically
• Zero friction — no workflow changes, no manual steps
• MCP integration — your agent searches memory automatically through standard MCP tools

Why Recall

Four things that set Recall apart from cloud-hosted memory layers and from agent-specific scratch files:

• Local-first, zero infrastructure. One SQLite file at ~/.agents/Recall/recall.db (override via RECALL_DB_PATH). WAL mode, 0600 perms. No vector database, no graph database, no agent server, no API keys for retrieval. Nothing leaves your machine — no telemetry, no phone-home. Optional Ollama for embeddings (also local).
• Multi-agent native. One memory layer across the agents you actually use. Stable on Claude Code today; Pi and OpenCode connect via MCP; Codex CLI and Gemini CLI on the way. Memories captured by one agent are searchable from any other agent on the same machine.
• Structured taxonomy, not a flat blob. Decisions (with supersede/revert lifecycle and confidence scoring), learnings, breadcrumbs, and curated Library of Alexandria entries — each has a purpose and a query path. Importance scoring (1–10) surfaces what matters first.
• Hybrid search that works offline. FTS5 keyword search ships with SQLite — no embedding infrastructure required to find anything. Optional Ollama embeddings layer on top for semantic queries. Both are merged via Reciprocal Rank Fusion. Lose Ollama, lose nothing — the keyword path keeps working.

Quick Start

Recall requires Bun (it uses bun:sqlite and Bun-native hooks).

# Primary — install from npm with Bun, then configure
bun install -g recall-memory
recall install

# Secondary — one-shot via npx (Bun must be on PATH)
npx --package=recall-memory recall install

recall install runs the canonical setup (MCP server, hooks, slash commands, guides) for all detected agents. Prefer bun install -g: with npm install -g, the #!/usr/bin/env bun shebang depends on Bun being on PATH (nvm/fnm shells can hide it).

Install from source instead

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

Verify it works:

recall stats        # Database overview
recall doctor       # Health check

Restart your agent (Claude Code, Pi, or OpenCode) to load the MCP server and hooks.

First run: set your identity

Recall's tiered RecallStart injects a small identity file at the top of every session (the L0 tier — your role, projects, tools, and working preferences). Without it, L0 is empty and every new session has to re-learn the basics.

recall onboard

A 7-question interview that writes ~/.claude/MEMORY/identity.md. Run it once. Re-run whenever your role, active projects, or working preferences change. Use | (not ,) to separate values so a phrase like no force-push, ever survives as a single entry.

Updating

From inside Claude Code, /Recall:update prints the current vs. latest release and the exact command to run. From a shell:

./update.sh --check   # version check only
./update.sh           # full update: pull, build, migrate, re-register hooks

Installed from npm? Use recall update (same flags) — or bun install -g recall-memory@latest && recall install to bump the binary.

Uninstalling

./uninstall.sh --dry-run   # preview, touch nothing
./uninstall.sh             # surgical remove; preserves ~/.agents/Recall/ (DB + backups)
./uninstall.sh --purge     # also destroy ~/.agents/Recall/ and any legacy DB (confirmed)

Installed from npm? Use recall uninstall (same flags, e.g. --dry-run / --purge).

> [Full installation guide](docs/installation.md) — prerequisites, platform support, session extraction setup, uninstalling

How Recall Works

Recall sits between your agent and a single SQLite database. A WRITE path captures sessions as you work; a READ path injects memory back into every new session. The diagram below shows both flows side-by-side, with the line styles in the legend distinguishing capture (solid), recall (dashed purple), and the write-only markdown mirror (dashed gray).

Text-only architecture diagram (for terminal viewers)

┌──────────────────────────────────────────────────────────────────────┐
│                        DATA ENTRY POINTS                             │
│                                                                      │
│  ┌────────────┐  ┌────────────┐  ┌──────────────┐  ┌────────────┐    │
│  │ CLI Direct │  │ MCP Server │  │  Stop Hook   │  │   Batch    │    │
│  │  recall add   │  │ (Claude    │  │ SessionExt-  │  │  Extract   │    │
│  │  recall dump  │  │  Code)     │  │  ract.ts     │  │  (cron)    │    │
│  └─────┬──────┘  └─────┬──────┘  └──────┬───────┘  └─────┬──────┘    │
└────────┼────────────────┼────────────────┼────────────────┼──────────┘
         │                │                │                │
         ▼                ▼                ▼                ▼
┌───────────────────────────────────────────────────────────────────────┐
│                      PROCESSING LAYER                                 │
│                                                                       │
│  Direct Inserts:              Session Extraction Pipeline:            │
│  recall add breadcrumb ──┐       Read JSONL                              │
│  recall add decision  ───┤         → Filter noise (tool results)         │
│  recall 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 (~/.agents/Recall/recall.db)  Memory Files (~/.agents/Recall/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)    │  │
│  │recall search     │  │recall semantic    │  │  recall hybrid (DEFAULT)   │  │
│  │memory_search  │  │embed → Ollama  │  │  FTS5 rank ─┐           │  │
│  │               │  │cosine sim      │  │  Embed rank ─┤→ merged  │  │
│  └───────────────┘  └────────────────┘  │  RRF(k=60) ◄┘           │  │
│                                         └─────────────────────────┘  │
│  Direct: recall recent · recall show · memory_recall · context_for_agent   │
└──────────────────────────────────────────────────────────────────────┘
                        │
                        ▼
┌──────────────────────────────────────────────────────────────────────┐
│  CONSUMERS:  Coding agents (MCP)  ·  CLI user (recall)  ·  Sub-agents   │
└──────────────────────────────────────────────────────────────────────┘

The source .excalidraw file lives at [assets/how-recall-works.excalidraw](assets/how-recall-works.excalidraw) — drop it onto excalidraw.com to edit.

Session Lifecycle

1. Session starts — A SessionStart hook injects two tiers of context: L0 identity (your ~/.claude/MEMORY/identity.md, always on) and L1 top records (top 12 by importance score, with 4 slots reserved for curated Library of Alexandria entries). L2/L3 stay on disk and are pulled on demand via MCP search.
2. During the session — your agent searches memory via MCP tools (memory_search, memory_hybrid_search, memory_recall, context_for_agent) before falling back to git history. Decisions, learnings, and breadcrumbs are recorded in real-time with memory_add.
3. End of every turn — A Stop hook fires RecallExtract.ts, which self-spawns a background process (non-blocking). It checks .extraction_tracker.json and only re-extracts if the conversation has grown meaningfully since last time — so capture is incremental, not just an "on exit" event.
4. Extraction pipeline — The conversation JSONL is filtered, deduplicated, and sent to the claude CLI running Haiku (with chunking for large sessions >120K chars). Optional Ollama fallback if the CLI fails. A quality gate rejects low-quality extractions before they're stored.
5. PreCompact flush — When Claude Code is about to compact its context, a PreCompact hook (RecallPreCompact.ts) flushes the in-flight messages first, so the squashed window is never lost.
6. Dual-write storage — Results are written to SQLite (the only query surface — every CLI/MCP read hits this) and to markdown artifacts (DISTILLED.md, HOT_RECALL.md, etc., write-only, human-readable).
7. Batch catchup (optional) — A cron job (RecallBatchExtract.ts) sweeps any sessions the Stop hook missed during crashes or interruptions, and ingests sessions dropped by the OpenCode plugin and Pi extension into ~/.claude/MEMORY/{opencode,pi}-sessions/. install.sh prints the registration command at the end — opt in by running it once; nothing is auto-scheduled.
8. TELOS auto-sync (PAI users) — If you use Personal AI Infrastructure (PAI), Recall ships a RecallTelosSync.ts SessionStart hook that watches ~/.claude/skills/PAI/USER/TELOS/ for changes and silently runs recall telos import --update when any file is newer than the last import. This is automatic — no action required once Recall is installed and PAI's TELOS directory exists. You can also import manually at any time with recall telos import --yes. If you don't use PAI, the hook checks for the directory, finds nothing, and exits in under 1ms.

Search Strategies

| Strategy | Command | How it works | | -------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | Keyword | recall search "query" | FTS5 full-text search across all tables. Use -t decisions to hard-filter, or --bias-type decisions to prefer decisions while keeping other matches. | | Semantic | recall embed semantic "query" | Ollama embeddings → cosine similarity (requires Ollama) | | Hybrid (default) | recall "query" | Both keyword + semantic, merged with Reciprocal Rank Fusion (k=60). Falls back to keyword-only if Ollama is unavailable |

Narrowing by record type — table vs bias_type. Both let you steer results toward decisions, learnings, breadcrumbs, LoA entries, or raw messages, but they differ in strength:

• -t / table is a hard filter — only the named record type comes back.
• --bias-type / bias_type is a soft boost — matching records of that type rank higher, but every other type can still appear when it's relevant.

Where it's available: table and bias_type act on FTS5 ranking, so they exist only on the keyword path — recall search, recall "query" -k, and the MCP memory_search tool. They are silently ignored elsewhere: plain recall "query" (default hybrid), recall "query" -v (semantic), and memory_hybrid_search rank by embedding distance and have no bias_type. Valid types: messages, decisions, learnings, breadcrumbs, loa.

> [Architecture deep-dive](docs/architecture.md) — database tables, FTS5 indexes, extraction pipeline details

What You Get

• Auto-captured session memory — extracted incrementally (Stop hook on every turn) via Claude Haiku, with RecallBatchExtract.ts cron sweeper as a crash-recovery safety net
• MCP server (recall-mcp) — memory_search, `memory_hybr

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: edheltzel
• Source: edheltzel/Recall
• License: MIT

Install and usage instructions live in the source repository linked above.