recall

recall

Your AI chat history, searchable. Across Cursor, Claude Code, Codex, and pi. Really fast. Read-only. No copies.

recall indexes the conversations you've already had with Cursor, Claude Code, OpenAI Codex CLI, and pi — straight from their native storage. It does not move, copy, or modify your data. It builds a tiny searchable index over excerpts and metadata, and lets you grep the lot from your terminal.

Above: the pi extension lets an agent call recall_search to find a past conversation and read it back — no copy-paste.

$ recall doctor
recall 0.1.0

sources:
  ✓ cursor  ~/Library/Application Support/Cursor/User/globalStorage/state.vscdb
  ✓ claude  ~/.claude/projects
  ✓ codex   ~/.codex/sessions

index: ~/.recall/index.sqlite (69.5 MiB)
  cursor  1514 sessions
  claude    25 sessions
  codex   1058 sessions
  total   2597 sessions

$ recall "import cycle" --limit 3
2025-09-02 18:36  cursor  ~/code/acme-api    Fix import cycle in proto files
    id=cursor:94dc8775-5fd3-41e9-93d7-43d7dff795b6  msg=1  role=assistant
    I'll help you fix the «import» «cycle» in the request logging…

$ recall last --repo ~/code/acme-api | claude -p "continue this"

Install

# Homebrew
brew install pratikgajjar/tap/recall

# one-line installer (downloads the right prebuilt binary)
curl -fsSL https://raw.githubusercontent.com/pratikgajjar/recall/main/install.sh | sh

# …or with Go
go install github.com/pratikgajjar/recall@latest

# …or grab a binary from https://github.com/pratikgajjar/recall/releases

Then build the index once:

recall index           # one-time, ~1 minute on real data
recall doctor
recall <query>

Pure Go, no CGO. Builds a single static binary.

Use it in your agent (MCP)

recall mcp is a Model Context Protocol server over stdio, so any MCP-capable harness can search your past chats. It exposes recall_search, recall_transcript, recall_sessions, recall_related, and recall_tag/recall_untag/recall_tags, and keeps the index warm in the background.

Claude Code

claude mcp add recall -- recall mcp

Codex — add to ~/.codex/config.toml:

[mcp_servers.recall]
command = "recall"
args = ["mcp"]

Cursor / Cline / Windsurf — add to the client's mcp.json (e.g. ~/.cursor/mcp.json):

{
  "mcpServers": {
    "recall": { "command": "recall", "args": ["mcp"] }
  }
}

pi — use the native extension instead (no MCP needed): pi install npm:@pratikgajjar/pi-recall (packages/pi-recall).

As a skill — for any agent with a skills system + shell access (Claude Code Agent Skills, pi skills), install the recall skill instead of a server. It teaches the agent to shell out to the CLI directly:

npx skills add pratikgajjar/recall          # via the skills CLI (skills.sh)
# or manually:  cp -r skills/recall ~/.claude/skills/recall

Once connected, ask the agent things like "use recall to find how we fixed the import cycle" and it will search and read the relevant past session.

For huge sessions, every integration takes range (Python-style slice like "305:315" or "-50:") and outline (one line per message), so an LLM can navigate and read slices instead of dumping a 25 MB transcript into context. Sessions over 200 messages default to outline when no slice is requested.

Commands

recall index (re)build the index from all sources recall search; prints ranked hits recall find [--repo P] same, with filters recall last [--repo P] dump the most recent session as transcript recall show dump one session as transcript recall sessions [--repo P] list recent sessions recall related sessions on the same topic recall tag list all tags + counts (git-tag style) recall tag … attach durable tags (survive reindex) recall tag -d … remove tags recall tag -l [session-id] list all tags, or one session's tags recall mcp run an MCP server (Claude Code, Codex, Cursor, …) recall plugin list show bundled + installed Lua plugins recall plugin install install a bundled plugin into ~/.recall/plugins recall plugin test dry-run a plugin: print the records it produces recall doctor health check

Flags can appear anywhere on the line:

--repo PATH restrict to a project folder --since DURATION e.g. 24h, 7d, 30d --limit N default 30 --tag SELECTOR filter, repeatable (AND). A user tag, or a reserved facet: source:cursor|claude|codex|pi --json machine-readable output

### Tags

Tag any session to find it again later — tags are **durable**: they live in a
separate table the indexer never rebuilds, so they survive `recall index --full`.

```bash
recall tag cursor:94dc8775-… deploy-rca auth-design   # remember this session
recall sessions --tag deploy-rca                      # find tagged sessions
recall sessions --tag deploy-rca --tag source:cursor  # tag + facet, AND

source is exposed as a reserved facet through the same --tag selector (--tag source:cursor) rather than a separate flag — one filter vocabulary, k8s-label style. Reserved facets are derived from the session, so you can filter by them but can't author them as tags. Agents can tag via the recall_tag MCP tool to bookmark sessions worth remembering.

What it reads

The index lives at ~/.recall/index.sqlite. It contains:

• sessions(id, source, source_id, project, title, started_at, msg_count, …)
• messages_fts(session_pk, idx, role, ts, text) — SQLite FTS5 over excerpts (trimmed to ~1.5 KB per message)

Nuke ~/.recall/ and re-run recall index any time. The index is disposable.

Index anything: Lua plugins

The sources above are built in. Anything else — a notes vault, another agent's history, any JSONL or SQLite-backed log — is indexable by a small Lua plugin, no recompile. A plugin is a sandboxed pure transform (no os/io/net): recall owns all I/O, the plugin just maps bytes to records.

recall plugin list                 # bundled + installed
recall plugin install obsidian     # → ~/.recall/plugins/obsidian.lua
recall index                       # now indexes your vault too

Bundled plugins install on demand (nothing auto-runs until you ask); anything in ~/.recall/plugins/*.lua is auto-discovered on the next index, and a broken plugin is skipped without blocking the others. Kinds: line (JSONL), file (whole document), kv (SQLite, incremental via a watermark).

See plugins/ for examples and architecture.md for the full contract.

• Read-only. Sources stay the source of truth.
• No materialization. No markdown copies, no canonical schema migrations.
• One binary. Single Go executable, ~10 MB, no CGO.
• SQLite + FTS5 for search. bm25 ranking with a small recency lift.
• Adapter trait. Add a new tool = implement one interface (Adapter in types.go).

Inspired by fff's pattern: thin index, live source reads, MCP-as-peer.

Status

v0.1. Incremental indexing (append-only), an MCP server, and the pi extension all work. A filesystem watcher and a TUI are next.

Licence

MIT.