chat-recall

# chat-recall

> One memory across every AI coding tool you use. Claude Code, Gemini CLI, Codex, OpenCode and Antigravity share a single searchable history — and the agent can search it itself.

Your coding agents each keep their own transcripts, in their own format, in their own directory, and none of them can read another's. `chat-recall` indexes all of them into one place, redacts secrets on the way, and exposes the result to your agent through **53 MCP tools** so it can recall its own past work instead of you re-explaining it.

That cross-tool part is the point. A single tool's built-in history stops at its own boundary; this does not.

## Install

```bash
npx chat-recall init
```

That indexes the transcripts already on your disk, detects which AI tools you have, and registers the MCP server in `~/.mcp.json`. Then:

```bash
chat-recall search "that auth bug"      # search everything you have ever done
chat-recall recent                      # what was I working on
```

By default this syncs to the hosted server at [chatrecall.dev](https://chatrecall.dev), which starts with a 14-day trial that needs no card and is a paid subscription after that — see [pricing](https://chatrecall.dev/pricing/). To keep everything on your own machine instead, run the server yourself: that is **free for one person, forever**, with every feature and no licence key, and a licence only buys collaboration — a second member, shared history, the team board. See [Self-host](#self-host-the-server-docker-compose) below. Either way the CLI is the same binary and the same commands; only the server URL differs.

No API keys are required. Postgres full-text search is the default backend; vector search and AI summaries are upgrades, not prerequisites.

## Four things it actually does

1. **Cross-tool unified memory.** One index, one search, one UI over Claude Code (`~/.claude/projects/`), Gemini CLI (`~/.gemini/tmp/`), Codex (`~/.codex/`), OpenCode (`~/.local/share/opencode/`) and Antigravity. Sessions, plans, tasks, CLAUDE.md files, paste cache, shell history and agent diaries all share one pluggable `MemorySource` interface.
2. **The agent recalls itself.** 53 MCP tools, so Claude Code can `recall_smart_resume`, `recall_search` (with `like_session` to find similar work), `recall_edits_timeline`, `recall_subagent_search` and `recall_redundant_files` rather than asking you what happened last time. It writes back too, via `recall_decision_record`, `recall_kg_add` and `recall_set`.
3. **Warns before you redo work.** A `UserPromptSubmit` hook searches for similar past sessions on every prompt and injects a short "you have done this before, in session X" note into the agent's context.
4. **Temporal knowledge graph.** Decisions and tool mentions become entity-relationship triples with `valid_from`/`valid_to` windows, so you can ask what was decided in March and whether it still holds.

## Add your own AI tool

A new backend is one file and one line — no changes to the engine. See [`docs/ADDING_A_TOOL.md`](docs/ADDING_A_TOOL.md). If a tool you use writes transcripts to disk, it can be indexed here, and a pull request is the fastest way to make that happen.

### Optional: vector search

```bash
ollama pull nomic-embed-text
chat-recall sync --full       # re-ships; the server embeds chunks into pgvector
```

…or set `EMBEDDING_PROVIDER=gemini` with `GEMINI_API_KEY` if you'd rather use a hosted embedder. Without either, search falls back to Postgres FTS — same results surface, slightly less semantic.

### Optional: web dashboard

The React dashboard is part of the **server** (SaaS or self-host docker
compose) — the CLI itself has no UI. For dashboard development:

```bash
npm run web:install                 # install web deps
npm run web:dev                     # API on :5000, UI on :5174
```

### Self-host the server (docker compose)

Everything on your own machine, no account, nothing sent anywhere:

```bash
git clone https://github.com/munhq/chat-recall && cd chat-recall
echo "ADMIN_KEY=$(openssl rand -hex 24)"         >> .env
echo "POSTGRES_PASSWORD=$(openssl rand -hex 24)" >> .env
docker compose up -d --build          # FIRST RUN BUILDS FROM SOURCE (minutes)
```

Then mint a device token and connect a machine — the full sequence, with
troubleshooting, is in **[docs/SELF_HOSTING.md](docs/SELF_HOSTING.md)**.

Two containers: the server plus a bundled `pgvector/pgvector` Postgres, so a
plain `docker compose up` is self-contained. Bring-your-own-Postgres is
supported too (it is how the hosted service runs): set `DATABASE_URL` to an
external Postgres 16+. The `pgvector` extension is needed only for semantic
search — everything degrades to full-text without it.

### Keep the index live (+ optional server sync)

You do not need a daemon. Claude Code spawns the MCP server, and that process
syncs every 3 minutes on its own — the binary is the daemon. For a headless box
with no assistant running, opt in to a background service:

```bash
chat-recall watch                    # foreground daemon: watches every tool, summaries, precompute
chat-recall watch --install-service  # systemd user unit (Linux) · launchd (macOS) · Scheduled Task (Windows)
```

`init` does not install it, on purpose. Both paths push through the same
`syncIncremental()` under the same cross-platform index lock, so one writer
touches the ledger at a time — see [docs/SYNC.md](docs/SYNC.md) before changing
any of it. Secrets are masked client-side before anything leaves the machine.
`chat-recall sync` does the same push once, on demand.

## Hook it up to Claude Code

`chat-recall init` does this for you. Manual equivalent in `~/.mcp.json`:

```json
{
  "mcpServers": {
    "chat-recall": {
      "command": "chat-recall-mcp"
    }
  }
}
```

Then install the hooks (one command sets up auto-save, pre-compact backup, and the resume-hint that warns when you're about to redo work):

```bash
chat-recall install-hooks                 # registers all five events, in every Claude profile
chat-recall install-hooks --no-resume-hint  # skip the resume warning
chat-recall install-hooks --no-wakeup       # skip the session-start wake-up bundle
chat-recall install-hooks --no-escalate     # skip the session-end escalation
chat-recall install-hooks --uninstall     # remove all of ours, leave third-party hooks alone
```

| Hook | When it fires | What it does |
|---|---|---|
| `SessionStart` | New session (`startup` / `clear`) | Injects the project-scoped wake-up bundle |
| `UserPromptSubmit` | When you type a prompt | Searches past sessions; if a similar one exists, injects "you've worked on this before" into the agent's context |
| `Stop` | After every assistant turn | Auto-saves topics, decisions, and tools to `~/.chat-recall/memory/` |
| `PreCompact` | Before Claude Code compacts context | Emergency save so nothing is lost to compaction |
| `SessionEnd` | When the session closes | Escalates the session's learnings in the background, so nothing is delayed |

## Companion: codeindex (auto-detected)

There's a separate MCP server called **codeindex** (Zig binary, ~56 MB) by [munhq](https://github.com/munhq/codeindex) that gives the agent code-level lookup. The two compose:

- **chat-recall** = session memory. *What have I worked on? What did we decide?*
- **codeindex** = code memory. *Where is this symbol? Who calls it? What breaks if I change it?*

Together the agent can answer "have I built this before?" *and* "does it already exist in this codebase?" before redoing work.

**How chat-recall handles it:** `chat-recall init` detects whether `codeindex` is on your PATH (or at `~/.local/bin/codeindex`). If yes, it registers it as an MCP server in `~/.mcp.json` automatically — no download, no surprise. If no, it prints a one-line hint about how to get it.

```bash
chat-recall init                       # default — detect and register if installed
chat-recall init --with-codeindex      # additionally force-download the binary
chat-recall init --skip-codeindex      # don't even check
chat-recall companions install         # download manually (after init)
chat-recall companions status          # show what was detected
chat-recall companions uninstall       # remove the binary + MCP registration
```

codeindex is open source (MIT) at [github.com/munhq/codeindex](https://github.com/munhq/codeindex). The install is optional — chat-recall works entirely without it; you just don't get the code-level tools.

## What gets indexed

| Source | Origin | Notes |
|--------|--------|-------|
| **Sessions (Claude)** | `~/.claude/projects/<hash>/<uuid>.jsonl` | Full transcripts, tokens, cost, files touched, models used |
| **Sessions (Gemini CLI)** | `~/.gemini/tmp/*/chats/*.json` | Tokens and tool usage extracted where present |
| **Sessions (OpenCode)** | `~/.local/share/opencode/opencode.db` (SQLite) | Cost, tokens, todos |
| **Subagent transcripts** | `<session-dir>/<id>/subagents/*.jsonl` | Explore, aside, **and `acompact-*`** (orphaned compacted history) |
| **Plans** | `~/.claude/plans/*.md` | Agent planning docs, split by `##` |
| **Tasks** | `~/.claude/tasks/<session>/*.json` | Linked to parent session |
| **CLAUDE.md** | Auto-discovered from project hashes | Linked to sessions in same project |
| **History** | `~/.claude/history.jsonl` | Shell history, optionally tied to a session |
| **Paste** | `~/.claude/paste-cache/*.txt` | Large pasted blobs |
| **Diary** | `~/.chat-recall/index/diary/<agent>/*.json` | What the agent told its future self via `recall_diary_write` |

## MCP tools (53, including 4 code-intelligence tools that register when the codeindex companion is installed)

**Search & retrieve** — `recall_search`, `recall_memory_search`, `recall_recent`, `recall_show`, `recall_context`, `recall_summary`, `recall_smart_resume`, `recall_project_context`, `recall_weekly_digest`, `recall_analytics_summary`, `recall_wake_up`.

**Pattern detection** — `recall_search` with `like_session: <id>` (find work similar to a