TL;DR

Recall is a retrieval-first memory layer: everything lands in one searchable database, the best of it is ranked and injected where a host supports session-start context, 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. MCP and skills span Claude Code, OpenCode, Pi, Codex, Grok, and JCode from one local database; lifecycle automation is host-specific.

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 OpenCode. Codex CLI has native MCP, skills, automatic capture, and session-start injection. Grok Build CLI has automatic capture but no automatic injection. JCode remains MCP and skills only after a bounded live probe. 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 ───────────────────────────────┘

• Automatic capture — supported lifecycle adapters preserve session progress without manual dumps; each host's exact capture and extraction behavior follows its verified lifecycle surface
• 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 on supported hosts
• 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. Claude Code, Pi, OpenCode, Codex, Grok, and JCode can share MCP memory. Automatic capture and injection depend on each host's supported lifecycle surfaces; see the capability matrix below.
• 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 installer-managed detected hosts. Codex uses the native plugin path below. 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, OpenCode, or Grok) to load the installed integration.

Codex uses its native plugin marketplace for MCP, skills, and lifecycle hooks; 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 supported session-start integrations inject a small identity file at the top of a 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 the resolved global identity file. On a new install this is ~/.agents/Recall/MEMORY/identity.md; an existing user-owned Claude identity remains authoritative. See the installation guide for the shared resolver's precedence. 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     # destroy runtime + DBs; preserve identity/distilled snapshots (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 where a host exposes a supported lifecycle surface; a READ path injects memory where a host supports session-start context. The diagram below shows the shared 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 — drop it onto excalidraw.com to edit.

Claude Code Session Lifecycle

1. Session starts — A SessionStart hook injects two tiers of context: L0 identity (your global or project-local 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 ~/.agents/Recall/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 — database tables, FTS5 indexes, extraction pipeline details

What You Get

• Auto-captured session memory — Claude Code extracts incrementally; Codex and Grok write supported transcript content directly to SQLite; Pi and OpenCode use their documented host adapters
• MCP server (recall-mcp) — memory_search, memory_hybrid_search, memory_recall, memory_add, memory_dump, context_for_agent exposed to your agent mid-session. memory_search supports table hard filters and bias_type soft boosts.
• Hybrid search — FTS5 keyword search + optional Ollama embeddings, fused via Reciprocal Rank Fusion. Lose Ollama, lose nothing — keyword path keeps working. Type targeting (table / bias_type) is a keyword-path feature — see Search Strategies.
• Tiered RecallStart (v0.7.0+) — resolved L0 identity + L1 top 12 records ranked by importance, with 4 reserved slots for curated Library of Alexandria entries. L2/L3 fetched on demand
• Importance scoring (1–10) — every record carries an importance score that drives what surfaces in L1. Manage with recall pin / recall unpin / recall importance backfill
• PreCompact flush — RecallPreCompact.ts writes in-flight messages to SQLite before Claude compacts its context window, so the squashed chunk is never lost
• Decision lifecycle — recall decision supersede/revert tracks when a decision was replaced or rolled back; confidence scoring (high/medium/low) on every decision and learning
• Cross-host ingestion — Codex and Grok lifecycle hooks write immediately through one scrubbed, deduplicated SQLite ingest seam. OpenCode and Pi keep their existing drop-and-batch paths. One database remains searchable from every connected host
• Library of Alexandria — curated knowledge entries (session distillations, imported docs, telos goals, quotes) with Fabric extract_wisdom analysis. Default importance 8 — these get reserved L1 slots
• TELOS integration (PAI users) — RecallTelosSync.ts auto-imports your TELOS framework files (goals, mission, projects, strategies) from PAI's USER/TELOS/ directory on every session start. Changes are detected by mtime; unchanged files are skipped. Manual import: recall telos import --yes
• Breadcrumbs, decisions, learnings — three structured record types for non-session memory, addable from CLI (recall add), MCP (memory_add), or the recall-add agent skill
• Codebase scouting — /recall-scout [focus] produces a memory-first scout report (repo map, key paths, tests, risks, next steps) for orienting in an unfamiliar repo, with a strict no-secrets boundary and chat-only-by-default output
• Benchmark harness — recall benchmark run B measures wake-up context efficiency against locked baselines so regressions are visible
• Onboarding — recall onboard runs a 7-question interview that writes your L0 identity file

Measured wake-up efficiency

Suite B measures the byte cost of session-start memory injection. Latest tracked run (2026-04-18, scope atlas-recall):

Variant	Chars	Tokens (est, 4 ch/tok)
v2 tiered RecallStart (L0 + L1 top 12)	5,306	~1,327
v1 flat-blob RecallStart (simulated)	8,020	~2,005
CLAUDE.md static baseline	8,760	~2,190

v2 is 51% smaller than v1 on this corpus. CLAUDE.md is hand-written static context; Recall is auto-extracted dynamic memory — the two are complementary, not competitors. Numbers scale with your own DB and L0 identity; reproduce with recall benchmark run B. Methodology and caveats live in benchmarks/README.md.

CLI at a Glance

recall "kubernetes auth"          # Search your memory
recall onboard                    # Seed your L0 identity tier (one-time)
recall dump "Session Title"       # Save this session
recall add decision "Use X" ...   # Record a decision
recall decision list              # List decisions with status and confidence
recall pin decisions 42           # Pin a record to high importance
recall benchmark run B            # Measure wake-up context efficiency
recall prune                      # Preview stale records for removal
recall stats                      # See what's stored
recall doctor                     # Health check

See it in action

Search	Stats

Health Check	Recent Memory

Full CLI reference

For AI Agents

If you're an AI agent reading this repository:

What you need	Where to find it
Using Recall from Claude Code (MCP tools, CLI, core rules)	FOR_CLAUDE.md
Installing the Claude Code plugin	docs/CLAUDE_INTEGRATION.md
Using Recall from OpenCode	FOR_OPENCODE.md
Using Recall from Pi	FOR_PI.md
Using Recall from Codex	docs/CODEX_INTEGRATION.md
Using Recall from Grok	docs/GROK_INTEGRATION.md
Using Recall from JCode	docs/JCODE_INTEGRATION.md
Developing Recall (build, test, conventions)	CLAUDE.md

Roadmap

Recall separates MCP and skills, automatic capture, and automatic injection. A host can support one without supporting the others.

Agent	MCP + skills	Automatic capture	Automatic injection	Status
Claude Code	✅	✅ Stop and PreCompact extraction	✅ SessionStart L0/L1	Stable reference implementation
Pi	✅	⚠ Beta shutdown capture	⚠ Beta before-agent context	Native package plus separate MCP adapter/config
OpenCode	✅	⚠ Beta session.idle capture	❌ Compaction injection not verified	Runtime verified against OpenCode 1.18.5
Codex CLI	✅	✅ Supplied rollout hooks	✅ Supported additionalContext	Native plugin; verified lifecycle contract
Grok Build CLI	✅	✅ Export-based lifecycle hook	❌ No prompt-mutation hook	Installer-managed capture; verified lifecycle contract
JCode	✅	❌ Probe did not prove safe ordering/composition	❌ Probe did not prove deterministic injection	MCP and skills only
Gemini CLI	❌	❌	❌	Coming soon

Unattended lifecycle writes pass the scrub gate from #50. Agent Skill bodies remain canonical under #228. Installer-owned files follow surgical ownership from #236, while broader atomic config-write parity remains tracked in #124.

Candidate — Cursor: both .cursor/hooks.json and MCP are first-class; the integration model maps cleanly onto Recall's existing hook architecture. Tracked but not started.

Have an agent you'd like to see supported? Open an issue — Recall is designed to be agent-agnostic, and any host that speaks MCP is a candidate.

Documentation

Guide	Description
Installation	Prerequisites, install, verify, session extraction
Managing Recall	Which command when: install, update, uninstall, custom DB, recovery
CLI Reference	All commands and options
MCP Tools	Tools available to AI agents
Architecture	Database, search, extraction pipeline
Codebase Map (local)	Interactive visual map at .agents/atlas/artifacts/2026-06-10-recall-codebase-map.html — generated from the codegraph index, not committed (.agents/ is gitignored)
Agent Skills	Canonical recall-* workflows and host-specific packaging
Codex Integration	Native plugin MCP, skills, automatic capture, and session-start injection
Claude Integration	Native plugin install, plugin/installer ownership split, migration
Pi Integration	Native package, separate MCP setup, lifecycle coverage, and host limits
Grok Integration	Installer-owned automatic capture and explicit injection boundary
JCode Integration	Live-probe evidence and current MCP/skills-only boundary
Upgrading	Update, backup, migration system
Troubleshooting	Common issues and fixes
Changelog	Release notes and breaking changes

Acknowledgments

Graciously borrowing and features inspired by:

• MemPalace — tiered session-start context, PreCompact hook, importance scoring
• Personal AI Infrastructure (PAI) — TELOS framework integration

License

MIT