<p align="center"> <img src="assets/banner.png" alt="Recall — Persistent Memory for Coding Agents" width="100%"> </p>

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 where a host lifecycle adapter exists, MCP tools expose them mid-session, hybrid search (FTS5 + embeddings) retrieves them, and a tiered L0/L1 recall block injects identity + top-ranked records on supported hosts. Works across Claude Code, OpenCode, Pi, and Codex 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 Beta for OpenCode (capture is verified against a live server; compaction injection is not). Codex CLI uses a native plugin for MCP and skills; lifecycle auto-capture is not yet supported. Gemini CLI remains on the roadmap. See Roadmap.

---

Jump to the Docs

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, OpenCode, and Codex connect through MCP. 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, agent skills, 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).

<details> <summary>Install from source instead</summary>

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

</details>

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.

Codex uses its native plugin marketplace instead of the lifecycle installer; see Codex Integration.

Claude Code can additionally install Recall as a native plugin, which takes over the nine recall-* skills and the recall-memory MCP server while the installer keeps owning the lifecycle hooks. Existing installs need one reconciliation step — see Claude Integration.

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 — 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).

<p align="center"> <img src="assets/how-recall-works.png" alt="How Recall Works — write path captures sessions into SQLite, read path injects them back into the agent on next session" width="100%"> </p> <details> <summary>Text-only architecture diagram (for terminal viewers)</summary>

┌──────────────────────────────────────────────────────────────────────┐
│                        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   │
└──────────────────────────────────────────────────────────────────────┘

</details>

The source `.excalid