/recall

name: agent-deck-recall
description: Record and later find what an agent-deck session was for, across harnesses, and hand a past conversation to the current one. Use when the user says "remember what this session was for", "tag this session", "annotate", "mark the outcome", "ticket for this session", "find the session where we...", "what did we decide about", "which Codex/pi/Gemini session did X", "bring that conversation into this session", "search the other machine's sessions", or wants to search past conversations. Available: hints and tags (add/launch --hint, session annotate, remote annotate), the transcript index over Claude, Codex, pi, Gemini, OpenCode and Hermes (recall search/sessions/show/open/backfill/sweep/status/gc/rebuild, the TUI G key, hook-driven freshness), recall context --into current, the derived artifacts (recall enrich; lost_time, session_kind, outcome), federated remote search (--remote/--all-remotes), opt-in card sync (export/pull/import) and the MCP server (recall mcp); all behind [recall] enabled = true.
metadata:
  compatibility: "claude, codex, pi, gemini, opencode, hermes"

Recall

Recall is agent-deck's memory of what every session was for and what happened in it. Human intent (hints, tags) lives in the profile's state.db and survives everything; the transcript index (recall.db) is disposable: delete it, `recall rebuild`, nothing typed is lost. Full design: `docs/recall.md` in the repo.

Phase 1 (available now): hints and tags

Hints are single-valued per key (setting a key again replaces it). Tags are a set. Well-known keys: `purpose`, `ticket`, `why`, `decision`, `outcome`, `note`, `parent`; any identifier-shaped key works.

At creation (`add` and `launch`)

agent-deck add . -c claude --hint purpose="fix flaky auth test" --ticket SB-412 --tag auth --tag flaky --why "3rd regression"
agent-deck launch . -c claude --ticket SB-412 -m "Fix the flaky auth test"

• `launch` derives `purpose` from the first line of `-m` and both commands

derive `parent=<parent id>` for a child; an explicit `--hint purpose=` wins.

• `conductor setup <name>` records `purpose=conductor <name>`.
• `--json` echoes `hints` and `tags`.

Afterwards (`session annotate`)

agent-deck session annotate <id> --decision "root cause was clock skew" --outcome worked --tag clock-skew
agent-deck session annotate <id> --set-hint ticket=SB-413 --remove-tag flaky --unset why
agent-deck session annotate --self --outcome worked            # your own session (AGENTDECK_INSTANCE_ID)
agent-deck session annotate --self --note-stdin < summary.md   # free-text note, 8 KiB cap
agent-deck session annotate <id> --json                        # read: hints, tags, harness links

**End of task habit:** before the completion sentinel, run `agent-deck session annotate --self --outcome <worked|failed|partial> --decision "<one line>"` so the next agent can find what you concluded.

Remote sessions

agent-deck remote <host> session annotate <id> --outcome worked

Runs on the remote and writes the remote's own state.db. Remote hints are never copied locally; read them through the same forwarded command.

Config

[recall]
enabled = false   # reserved for the transcript index; hints work regardless

Phases 2 and 3 (available now): the transcript index, every harness

Needs `[recall] enabled = true` in config.toml (every command exits 2 with a clear message otherwise). One index for every profile on the machine and every harness: Claude (all profiles), Codex, pi, Gemini, OpenCode, Hermes. `--profile` narrows Claude to one account, `--harness` to one harness. Every interactive sweep runs inside the command that asked for it and ends with it; the Claude Stop hook, `session stop`, `worker_done` and the daemon's turn-end edge queue the transcript that just moved (the Stop hook only appends that line; the async SessionEnd hook also indexes its own file within 150 ms), and every search drains the queue first, so a conversation is searchable the moment you look for it. The one exception: `agent-deck notify-daemon` (the always-on daemon, every machine including remotes) runs a single background *initial backfill* the first time it sees recall enabled with an empty index or a never-finished pass (`[recall] backfill_on_enable = true`, the default) — see "Enabling recall for the first time" below.

Enabling recall for the first time

Turning `[recall] enabled = true` on no longer leaves the index empty: the notify-daemon runs one throttled background backfill on its own, the first time it sees an empty index or a marker saying the pass never finished (`[recall] backfill_on_enable = true`, default). It never refuses under load like the manual command below does — it shrinks its chunks and sleeps longer instead, so a machine sitting above `max_loadavg` still finishes, just slower. Progress: `agent-deck recall status --json`'s `initial_backfill` (`state`: `pending`/`running`/`done`, `done_at`, `sessions_done`, `sessions_pending`). Nothing to do if the daemon is not running (a machine that only ever uses the CLI interactively) — run `recall backfill` by hand there instead.

Find sessions

agent-deck recall backfill                     # once; resumable; refuses while a session is busy (--force)
agent-deck recall search "clock skew" --since 30d --profile work --json
agent-deck recall search "retry budget" --harness codex --json
agent-deck recall search SB-412 --hint ticket=SB-412 --phrase   # hint filters read state.db live
agent-deck recall sessions --tag auth --limit 10 --json
agent-deck recall sessions --harness hermes --json

• Search ranks sessions: a title, hint or tag hit always beats any number of

body mentions. Terms are AND-ed; `SB-412` and `handle_sess` stay whole; `--phrase` verifies the literal phrase in the hits' bodies and says how many bodies it read; a hit whose matching body is clipped (8 KiB tier) is `unverified (