crispy-recall 0.3.0 → 0.4.0

package/README.md

@@ -1,37 +1,103 @@
 # crispy-recall
 
-**Save every session. Recall any conversation. Continue where you left off.**
+**Let your agents search your past conversations.**
 
-Each conversation with your agent lands in a transcript on disk, waiting for Claude Code's [startup cleanup (30 days by default)](https://code.claude.com/docs/en/settings) to delete it. recall indexes user and assistant turns as they end — verbatim, on your machine — so your agent can search, read, and continue the conversation even after its transcript is gone.
+Recall lets Claude Code and Codex look up your past conversations, so you can start a new session whenever you want. Close a long chat to save tokens without writing a handoff or worrying about losing what you worked through. Your next session can retrieve just what it needs.
 
-**Local session memory for Claude Code, with Codex support.** Hybrid text and semantic search. Verbatim conversation history.
+Just ask: “Recall where we left off,” “Recall why we chose this approach,” or even “Recall \<session ID\> and continue.” Your conversations are saved automatically, so your agent can find the relevant discussion or pick up a specific session. Continuing an old, uncached session this way can also save tokens: Recall brings back the conversation without all the background activity that filled the original chat.
 
-No daemon, no cron, no cloud. A Stop hook and a SQLite file.
+Under the hood, Recall indexes the JSONL conversation logs that Claude Code and Codex already generate in a local SQLite database, with vector embeddings generated by the open-source Nomic Embed Text v1.5 model running on your machine. A small skill teaches your agent to retrieve relevant passages using hybrid keyword and semantic search—local RAG over your conversation history, guided by what your agent needs right now.
 
-## Quick start
+[Website](https://recall.thesylvester.ca) · [GitHub](https://github.com/TheSylvester/crispy-recall)
 
-Requires Claude Code and either Node.js 22 LTS (`>=22.16`) or Node.js 24+. Install recall in the same environment where you run Claude Code:
+## Quick start (single machine)
+
+Use Node.js 24 (or Node.js 22.16+) and install in the environment where you run
+Claude Code. This installs the stable single-machine release:
 
 ```bash
 npm install -g crispy-recall
 recall install
 ```
 
-recall downloads a local embedding runtime and model, sets up a `Stop` hook in Claude Code, installs the recall Agent Skill, and starts indexing the session history still on disk. If Codex is detected, recall sets up the same integration there.
+It picks up the conversation history already on your machine, so you can ask it to recall something straight away. The installer sets up the local embedding model, lifecycle hooks, and recall skill for Claude Code, with the same integration for Codex when detected.
 
-## How to use recall
+### More than one machine (experimental)
 
-### Ask your agent
+Keep your coding history on one **hub**. Each **satellite** uploads its transcripts
+and searches the hub, without running its own database or embedding model.
+Install Recall under the same account and in the same environment as your coding
+agent. WSL is optional; install separately in Windows and WSL if you use both.
+
+Use Node.js 24 and a private network, such as your LAN or Tailscale. Recall does
+not configure Tailscale or SSH; remote access is separate from shared memory.
+
+Satellite mode is experimental. On every machine (the hub and each satellite),
+install Recall first:
+
+```bash
+npm install -g crispy-recall
+```
+
+**On the hub**, initialize Recall, create a token for one satellite, and start
+listening on the hub's private IP:
+
+```bash
+recall install
+recall hub token --host laptop
+recall hub serve --bind <hub-private-ip> --port 7877 --detach
+```
+
+Save the token shown. Use your hub's private IP below even if the generated
+example shows `127.0.0.1`. Give each satellite a different host name; issuing a
+new token for the same name replaces its old token.
+
+**On the satellite**, enter that token and connect to the hub. These commands
+read it interactively and pass it through stdin, keeping it out of shell history.
+
+Bash:
+
+```bash
+read -r -s -p 'Hub token: ' recall_token; printf '\n'
+printf '%s\n' "$recall_token" | recall install --hub http://<hub-private-ip>:7877 --token -
+unset recall_token
+```
+
+PowerShell:
 
-**Your agent starts every session from zero — until you say the word.**
+```powershell
+$recallToken = Read-Host 'Hub token'
+$recallToken | recall install --hub http://<hub-private-ip>:7877 --token -
+Remove-Variable recallToken
+```
+
+Installation starts uploading existing transcripts; new turns follow automatically.
+Check the connection and search shared history:
+
+```bash
+recall doctor
+recall --all "a conversation from another machine"
+```
 
-The word is `recall`. Say it in a prompt and your agent goes and gets exactly what it needs: a top-level conversation by UUID, messages by keyword or meaning, or the Claude Code session that wrote the code behind a commit.
+Keep the hub running and reachable. `--detach` does not configure startup after
+reboot. On Linux, stop the detached hub before running `recall hub install-service`,
+which starts and enables the systemd service; follow any printed linger instructions.
+Windows and macOS need their own startup configuration. Live platform and reboot
+acceptance for this prerelease is still pending.
 
-Use it naturally:
+Only connect trusted users: satellites upload raw transcripts, and every hub
+token can search the entire hub history. See [Privacy and data](#privacy-and-data).
+
+## How to use recall
+
+### Ask your agent
+
+Ask about what you worked through, or give your agent a session ID and continue from there:
 
 | Say this | What your agent can recover |
 |---|---|
 | `Recall where we left off.` | The decisions, unfinished work, and next step from prior sessions. |
+| `Recall why we chose this approach.` | The reasoning and alternatives discussed before the decision. |
 | `Recall — we solved this before.` | The earlier fix, even when your new wording doesn't match the transcript. |
 | `Recall <session-uuid> and continue.` | A UUID-backed conversation in a fresh session, centered on the relevant part. |
 | `Recall why this line exists.` | The session behind a commit or line, including alternatives discussed at the time. |
@@ -52,7 +118,7 @@ Every result includes a session id and the matched message id. For UUID-based Cl
 recall <session-uuid> <message-uuid>
 ```
 
-Search defaults to the current project's sessions. Expand only when needed:
+Search defaults to the current project's sessions. In 0.4.0, matching repositories share a search scope across clones and worktrees. Expand only when needed:
 
 ```bash
 recall --all "the decision may have happened in another repo"
@@ -78,11 +144,9 @@ recall keeps the user and assistant conversation word-for-word. It doesn't repla
 
 That distinction matters when you need the exact constraint, command, promise, rejected idea, or one-line fix that a summary would reasonably discard.
 
-**`/compact` summarizes. recall quotes.**
-
 Auto-memory saves what you knew to keep. recall finds what you didn't know you'd need. They complement each other: one keeps selected facts close; the other searches the verbatim conversation record on demand.
 
-Tool calls, tool output, and hidden thinking are intentionally excluded from the searchable conversation. Tool output is re-runnable; the conversation that interpreted it isn't.
+Tool calls, tool output, hidden thinking, and images are intentionally excluded from the searchable conversation. Tool output is re-runnable; the conversation that interpreted it isn't.
 
 ### Continue without replaying the session
 
@@ -94,7 +158,7 @@ Recall fe6cc221-2e63-4928-8417-65ec1587d062 and continue the release.
 
 recall reads the indexed conversation instead of replaying an entire raw transcript. Reads can open on the matched message, paginate forward, and combine context from several past sessions. That means your agent can recover the few facts that matter without pouring every old tool result back into its context window.
 
-`/resume` dies with the transcript; recall doesn't. recall reads the relevant indexed turns instead of replaying one whole session, and it can combine facts from other sessions.
+The indexed conversation stays available even after its original transcript is deleted. Your agent can also look up related discussions from other sessions as it works.
 
 ### From a line of code back to the conversation
 
@@ -108,7 +172,7 @@ recall --blame src/foo.ts:42 src/bar.ts:10-20 --limit 20
 
 Matching is structural: recall compares edits recorded in sessions with commit diffs instead of guessing from timestamps. A commit message summarizes intent; the conversation holds the reasoning, tradeoffs, and rejected alternatives.
 
-Commit and blame attribution currently scans Claude Code transcripts. Codex sessions remain searchable by text and meaning, but aren't yet attributed to commits.
+Commit and blame attribution scans local Claude Code edits and Codex `apply_patch` records. It compares recorded changes with git diffs; edits made by arbitrary shell commands may not carry enough structured evidence for attribution.
 
 **`git blame` tells you who. `recall --blame` tells you why.**
 
@@ -143,15 +207,15 @@ Claude Code deletes transcripts after 30 days by default. The recall index doesn
 
 ## How it works
 
-Under the hood, recall is deliberately boring:
+On a single machine:
 
 1. Stop and SubagentStop hooks index conversation text as turns finish.
-2. A local llama.cpp embedding model vectorizes it on your machine.
+2. Nomic Embed Text v1.5 generates embeddings locally through llama.cpp.
 3. SQLite stores the text, FTS5 index, vectors, and session metadata in `~/.recall/`.
 4. A small skill teaches your agent to search first when prior work is likely to matter.
 5. Search results enter the context only when the agent asks for them.
 
-There's no resident daemon, and recall makes no LLM calls of its own. Indexing and search don't consume model tokens; retrieved text costs context tokens only when your agent reads it, like any other local file.
+On a single machine there's no resident daemon (the optional hub daemon runs only in satellite mode), and recall makes no LLM calls of its own. Indexing and search don't consume model tokens; retrieved text costs context tokens only when your agent reads it, like any other local file.
 
 Install-time backfill indexes the Claude Code and Codex sessions still present on disk, so recall is useful on day one rather than only after day one.
 
@@ -159,13 +223,14 @@ Install-time backfill indexes the Claude Code and Codex sessions still present o
 
 ### Requirements
 
-- Node.js 22 LTS (`>=22.16`) or Node.js 24+
-- Claude Code (required); Codex session indexing and search are also configured when Codex is detected
-- Linux x64/arm64, macOS x64/arm64, or Windows x64
-- macOS 14+ on Apple Silicon or macOS 13.7+ on Intel
-- 500 MB free recommended for installation; upgrading also needs free space for retained rollback snapshots — roughly the database size when upgrading from 0.2.x, and roughly twice that from 0.1.x (which keeps two snapshots)
+- Node.js 24 recommended; Node.js 22.16+ is also supported for a local install or hub.
+- Claude Code; Codex integration is added when detected.
+- Linux x64/arm64, macOS x64/arm64, or Windows x64.
+- macOS 14+ on Apple Silicon or macOS 13.7+ on Intel.
+- 500 MB free for installation, plus space for database backups when upgrading.
 
-Node 23 is unsupported because no prebuilt SQLite binding is available for it.
+Satellites also support Node.js 20, but installing on Node 20 requires Python,
+make and a C/C++ compiler. Node.js 21 and 23 are unsupported.
 
 ```bash
 npm install -g crispy-recall
@@ -188,21 +253,43 @@ Use `recall doctor` if setup reports a problem. Use `recall install --offline` w
 
 ### Upgrading
 
-Close active Claude Code and Codex sessions, then make `recall install` the first recall command you run after upgrading — it applies any pending one-time database migrations attended, before your agent reopens the database:
+Close active coding-agent sessions, upgrade the package, then run `recall install`
+before using Recall again. For a stable release:
 
 ```bash
 npm install -g crispy-recall
 recall install
 ```
 
-- **From 0.1.x**, the installer migrates the wasm database to native SQLite/WAL (writing a `~/.recall/recall.db.pre-upgrade-<stamp>` snapshot) and checks integrity, then runs the retrieval-class migration below.
-- **From 0.2.x**, the installer runs the retrieval-class migration: it reclassifies any subagent (agent-leaf) messages as durable-but-excluded-from-default-search, rebuilds the FTS index, and re-embeds affected rows in the background.
+On an existing satellite, upgrade the package and re-run the satellite installer.
+It reuses the saved token for that hub:
 
-Before it changes anything, the retrieval-class migration writes a `~/.recall/recall.db.pre-retrieval-<stamp>` snapshot; a 0.1.x upgrade therefore keeps two retained snapshots (pre-upgrade and pre-retrieval). Keep free disk roughly equal to the current database size — twice that when upgrading from 0.1.x — and delete the snapshots only after you're satisfied.
+```bash
+npm install -g crispy-recall
+recall install --hub http://<hub-private-ip>:7877
+```
+
+The installer applies required migrations and keeps rollback snapshots. Allow up
+to three database-sized backups when upgrading from 0.1.x, or two from 0.2.x.
+If the database is busy, close the process using it and retry. Complete migrations
+before searching; semantic results may be incomplete while background embedding
+catches up. Check progress with `recall status` and `recall doctor`.
+
+The 0.4.0 upgrade rebuilds Codex message identities from available transcripts.
+Keep the default backfill enabled to recover sessions previously missed by the
+index. Deleted source transcripts cannot be recovered.
 
-If a live session or a running backfill holds the database, the installer aborts cleanly so you can exit it and rerun `recall install`. Search remains available during migration; use `recall status` to watch progress, and the background re-embed resumes after interruption or reboot.
+If an earlier build missed messages or misordered turns, run this on the local
+installation or hub after upgrading:
 
-Migration works from `recall.db`, not the source transcripts, so indexed history is preserved even when the original JSONL has already been cleaned up. Your database is the store of record; if old transcripts are gone, `recall repair --full` cannot recreate them. Don't downgrade to `<=0.1.6` after converting the database.
+```bash
+recall repair --messages
+recall backfill --auto-embed
+```
+
+This repairs known transcripts without clearing retained history. Avoid
+`recall repair --full` unless you intend to rebuild the index from the transcripts
+still on disk. Do not downgrade to 0.1.6 or earlier after database conversion.
 
 ## Command reference
 
@@ -213,16 +300,29 @@ Migration works from `recall.db`, not the source transcripts, so indexed history
 | `recall <session-id> [<message-id>]` | Read a session, optionally centered on a match. IDs are opaque — full stored IDs or literal prefixes (UUIDs, `agent-<hex>` leaves, `codex-jsonl-*` messages) all resolve. |
 | `recall read <session-ref> [<message-ref>]` | Explicit read for any stored ID shape; a failed read exits nonzero and never falls back to search. |
 | `recall search <terms…>` | Force a search when a term would otherwise look like a session/message ID. |
-| `recall --commit <hash>` | Find Claude Code sessions that produced a commit. |
-| `recall --blame <path>[:line[-line]]` | Trace current code back to its producing Claude Code conversations. |
+| `recall --commit <hash>` | Find local Claude Code or Codex sessions that produced a commit. |
+| `recall --blame <path>[:line[-line]]` | Trace current code back to its producing local conversations. |
 | `recall install` | Install or upgrade the hooks, skills, local assets, and history index. |
 | `recall backfill [--auto-embed] [--vendor <v>] [--detach]` | Index session transcripts currently on disk, optionally for one vendor or as a detached job. |
+| `recall backfill --purge-meta [--dry-run]` | Delete machine boilerplate rows indexed before the ingest filter existed; `--dry-run` opens the database read-only and only reports. |
 | `recall status` | Show database size, message counts, embedding gap/migration progress, and active backfill state. |
 | `recall doctor [--integrity]` | Run read-only install and database checks. |
 | `recall repair --fts \| --vectors \| --full` | Rebuild FTS5, clear vectors for re-embedding, or fully reingest on-disk transcripts. |
+| `recall repair --messages` | Re-read known transcripts to recover missed turns, fork history and ordering without clearing the index (hub only). |
+| `recall repair --rekey-codex` | Run the one-time Codex message-id migration to full session UUIDs (hub only). |
+| `recall repair --rekey-projects [--force]` | Fill `project_key` on existing rows; `--force` also re-keys already-keyed rows (hub only). |
+| `recall "<query>" --project-key K` | Scope by an already-derived repo key (`git:`/`origin:`/`path:`), skipping derivation. |
+| `recall hub serve [--bind <addr>] [--port <n>] [--detach]` | Run the hub daemon: mirror satellite transcripts and answer their queries (hub only). |
+| `recall hub token --host <name> \| --revoke <name>` | Issue (or rotate) a satellite's bearer token, or revoke one without a restart (hub only). |
+| `recall hub status [--json]` | Show the daemon, the resolved address, and per-host mirror and push/query state (hub only). |
+| `recall hub install-service` | Register the systemd user unit so the daemon starts at login (hub only). |
+| `recall install --hub <url> --token <t>\|-` | Register this machine as a satellite of that hub; `-` reads the token from stdin (satellite only). |
+| `recall push [--full]` | Push pending transcripts to the hub now; `--full` re-offers every transcript (satellite only). |
 | `recall statusline [--suggest]` | Print the session-id chip or integration guidance. |
 | `recall uninstall [--purge]` | Remove the integration; `--purge` also deletes recall's data. |
 
+Date-only `--since` and `--until` bounds cover UTC calendar days; explicit timestamps retain their stated offset. Both text and semantic searches apply these bounds before selecting candidates.
+
 Run `recall --help` for the full search and read flag set. Add `--json` to `install`, `uninstall`, `status`, or `doctor` for machine-readable output. Installer options include `--offline`, `--no-backfill`, `--auto-backfill`, `--statusline`, and `--no-statusline`.
 
 ### Optional statusline
@@ -235,20 +335,25 @@ It is off by default: accepting the installer defaults, using `--yes` or a non-i
 
 The installed statusline never opens the database. Its only I/O is one guarded `git status` call with a 400 ms timeout; failure simply drops the git segment, and any segment whose input is missing is omitted. For composition with your own statusline, `recall statusline` prints only the bare, uncolored session-id chip. Uninstall removes the line only if recall still owns it, and doctor reports statusline problems as warnings.
 
-> **Warning:** `recall repair --full` is destructive: it replaces the index contents from the transcripts still on disk. If older source transcripts have already been cleaned up, their indexed history cannot be rebuilt. Prefer `--fts` or `--vectors` unless a full reingest is truly necessary.
+> **Warning:** `recall repair --full` is destructive: it replaces the index contents from the transcripts still on disk. If older source transcripts have already been cleaned up, their indexed history cannot be rebuilt. Prefer `--fts` or `--vectors` unless a full reingest is truly necessary. On a hub it also re-ingests the satellite mirror under `~/.recall/remote/`, and it refuses to run when that directory exists but enumerates no hosts — a satellite's history would otherwise be deleted and not rebuilt.
 
 ## Privacy and data
 
 - Your index lives in `~/.recall/recall.db`.
-- Search and indexing stay on your machine.
+- On a single machine, search and indexing stay on that machine. In satellite mode the satellite forwards its query text and cwd to your hub and the hub does all indexing (see below).
 - While a query is being embedded, its text is written to a transient file under `~/.recall/run/query-embed/` (mode 0600) and deleted as soon as the embedding completes.
 - There is no telemetry.
 - The database is plain SQLite and inspectable with ordinary SQLite tools.
-- Network access is limited to downloading the embedding runtime and model when missing, plus host reachability probes during install and doctor checks.
+- On a single machine, network access is limited to downloading the embedding runtime and model when missing, plus host reachability probes during install and doctor checks. A satellite additionally talks only to the hub URL you configured.
 - `recall uninstall --purge` removes the local store completely.
 
 The installed integration is inspectable too: Claude's skill and hook live under `~/.claude/skills/recall/` and `~/.claude/settings.json`. When Codex is detected, recall also uses `~/.codex/skills/recall/` and `~/.codex/hooks.json`.
 
+Satellites send raw transcripts and queries to your hub. Recall uses plain HTTP
+without built-in TLS, so keep it on a private network. Each token can search the
+whole hub index and upload only to its named satellite's mirror. Revoke a token
+with `recall hub token --revoke <name>`; no restart is needed.
+
 The index deliberately outlives source-transcript cleanup. recall doesn't encrypt `recall.db`; treat `~/.recall/` with the same care as your original Claude Code and Codex histories.
 
 ## Limitations
@@ -256,9 +361,11 @@ The index deliberately outlives source-transcript cleanup. recall doesn't encryp
 - It isn't automatic fact injection into every prompt. Retrieval is pull-based.
 - It isn't a replacement for documentation, tests, or git.
 - It doesn't claim recalled context is still correct.
-- It doesn't preserve tool output or hidden thinking in the searchable conversation.
+- It doesn't preserve tool output, hidden thinking, or images in the searchable conversation.
 - It doesn't yet offer per-session deletion; forgetting is database-level today.
 - Subagent transcripts (Claude Task leaves, Codex child rollouts) are stored durable and readable by explicit ID, but are excluded from default search, lists, and semantic vectors — the parent thread's narration is the canonical memory. There is no search mode that includes them yet.
+- On a satellite, `recall --commit` and `recall --blame` see local sessions only. They read local git and local transcripts, never the hub index.
+- A repo that is keyed `git:<root-commit>` on one machine and `origin:<url>` on another — a shallow clone, for instance — does not unify until both machines agree on the key. Run `git fetch --unshallow`, then `recall repair --rekey-projects --force` on the hub.
 
 ## Project status
 

package/dist/SKILL.md.template

@@ -10,244 +10,35 @@ when_to_use: >-
   Trigger for phrases like "remind me about", "pick up where we left off",
   "continue from last time", or when starting complex work in an area with
   obvious prior sessions. Skip for simple lookups and trivial questions.
-allowed-tools: Bash, Agent, Read
 ---
 
 # Recall
 
-Unified tool for session transcript memory — search, read, and browse.
-
-## The two-step pattern
-
-**Step 1: Search.** Every search result includes a matched message ID.
-
-```bash
-$RECALL_BIN "your query here"
-```
-
-**Step 2: Read the matched message.** Do NOT read the session from the top.
-
-```bash
-$RECALL_BIN <session-id> <message-id>
-```
-
-This auto-centers on the match with ~30% context before and ~70% after,
-filling up to the output budget. The footer tells you the exact `--offset`
-to continue reading forward.
-
-**NEVER start a session read from the top after searching.** The search
-already found the relevant message — go directly to it. Only use
-`$RECALL_BIN <id>` (no message-id) when you genuinely need to start
-from the beginning of a session.
-
-## Confidence tags
-
-Search results are tagged by how they were found:
-- `[FTS5+SEMANTIC]` — Both keyword and meaning matched. High confidence.
-- `[SEMANTIC-ONLY]` — Found by meaning, not exact words. Vocabulary mismatch discovery.
-- `[FTS5-ONLY]` — Exact keyword match only. May be coincidental.
-
-## Sub-agent pattern (recommended for deep research)
-
-For questions requiring multiple searches or reading session content, launch a sub-agent.
-The agent prompt **must** include full CLI instructions — sub-agents don't see this skill file.
-
-```
-Agent(prompt: "You have a recall CLI for searching and reading past session transcripts.
-Use ONLY `$RECALL_BIN` for all transcript access — do NOT read .jsonl files directly,
-do NOT use Grep/Glob/find to locate transcripts.
-
-CLI usage:
-  $RECALL_BIN \"query\"                    Search (returns session IDs + matched message IDs)
-  $RECALL_BIN <session-id> <message-id>   Read centered on matched message (use this after search)
-  $RECALL_BIN <session-id>                Read from beginning (only when you need full arc)
-  $RECALL_BIN <session-id> --offset N     Continue reading from offset N (shown in output footer)
-  $RECALL_BIN read <session-ref> [<message-ref>]  Explicit read for any stored ID (opaque; exits
-                                          nonzero on failure — never falls back to search)
-  $RECALL_BIN search <terms...>           Force a search when a term looks like an ID
-  $RECALL_BIN --list --since YYYY-MM-DD   List recent sessions
-  $RECALL_BIN --help                      Full flag reference
-
-Session/message IDs are OPAQUE strings (UUIDs, agent-<hex> subagent leaves,
-codex-jsonl-* message ids). Paste them back exactly as displayed — full ID or
-a literal prefix both resolve.
-
-DATE HANDLING: Any date the user mentions MUST become a flag — never search text:
-  --since YYYY-MM-DD   Only sessions on or after this date
-  --until YYYY-MM-DD   Only sessions on or before this date (inclusive)
-  --recent             Boost recent sessions (use when user says 'recently', 'latest')
-  Example: \"what happened April 10\" → $RECALL_BIN --list --since 2026-04-10 --until 2026-04-10
-
-PROJECT SCOPING: search and list default to the CURRENT directory's project.
-  --all                Search across ALL projects (use when the answer may live
-                       in another repo, or when a scoped search returns little)
-  --project PATH       Scope to a specific project path instead of the CWD
-  If results look thin or empty, retry with --all before concluding nothing exists.
-
-CRITICAL READING RULE: After searching, ALWAYS read the matched message:
-  $RECALL_BIN <session-id> <message-id>
-This auto-centers on the match and shows surrounding turns. The output
-footer shows the --offset to continue reading forward. NEVER read sessions
-from the beginning after a search — the match is already found for you.
-
-Task: [describe what to find]. Run these searches: [list queries].
-Search EXHAUSTIVELY — do not stop after the first promising result. Run all
-listed queries, read into multiple results, and only report findings after
-you have checked every search path. Cross-reference results and summarize.",
-mode: "auto")
-```
-
-## Other reading modes
-
-| Mode | Command | When to use |
-|------|---------|-------------|
-| **Matched message** | `$RECALL_BIN <id> <msg-id>` | **Always use this after search** — auto-centers on match |
-| Full session | `$RECALL_BIN <id>` | Only when you need the overall arc, not a specific answer |
-| Continue | `$RECALL_BIN <id> --offset N` | Continue from where the last read left off |
-| Newest first | `$RECALL_BIN <id> --reverse` | Looking for recent content in a long session |
-
-## Commit attribution (`--commit` / `--blame`)
-
-Find the session(s) that produced a given commit, or the session(s)
-responsible for specific code in a file. Matches by structurally comparing
-session Edit/Write/MultiEdit tool calls against the commit's diff (tri-gram
-intersection), not by clock proximity. Results include both top-level
-sessions and Task-tool subagent leaves (`agent-<hash>`) with
-`parent_session_id` set.
-
-```bash
-# Sessions that produced one commit
-$RECALL_BIN --commit 864f569
-$RECALL_BIN --commit 864f569 --raw                     # full JSON
-
-# Sessions responsible for a file (HEAD-relative blame)
-$RECALL_BIN --blame src/webview/components/FlexAppLayout.tsx
-
-# Sessions responsible for one line — narrowest, most precise lookup
-$RECALL_BIN --blame src/foo.ts:42
-
-# Sessions responsible for a line range
-$RECALL_BIN --blame src/foo.ts:42-100
-
-# Multiple specs in one query (unioned)
-$RECALL_BIN --blame src/foo.ts:42 src/bar.ts:10-20 --limit 20
-```
-
-`--blame` is HEAD-relative: it runs `git blame` to find the commits
-responsible for the current state of the file (or line range) and
-attributes each. Sessions whose work was overwritten by a later commit
-won't appear — for the full historical iteration set, use `git log` and
-pass each commit to `--commit` separately.
-
-### When to use
-
-- **"Who produced this commit?"** — `--commit <hash>`. Returns the session(s)
-  that typed the edits. Multiple matches mean nested/sequential work.
-- **"Why is this line / block of code here?"** — `--blame <path>:<line>`
-  or `--blame <path>:<L1>-<L2>`. The narrowest, most precise lookup —
-  go straight to the session that authored the line you're staring at.
-- **"What sessions are responsible for this file's current state?"** —
-  `--blame <path>` (no line). Returns one row per (commit, session) for
-  every commit whose lines still live in HEAD.
-- **"Why is this code shaped this way?"** — When refactoring, debugging a
-  regression, or reviewing a legacy pattern, look up the originating session
-  before reasoning from the code alone. The session usually has rejected
-  approaches and constraints that the final code does not.
-
-### Reading the results
-
-Sessions are listed chronologically (oldest first). **The most recent is
-usually the load-bearing one for current code; earlier sessions show
-evolution.** Each row exposes:
-
-- `session` — top-level UUID or `agent-<hash>` subagent leaf
-- `parent_session_id` — set when the match is a subagent; follow this to
-  reach the parent's rationale conversation
-- `content_hits` — tri-gram intersections with the commit's added lines
-- `surviving_in_commit` / `surviving_ratio` — how much of the session's
-  work made it into the commit's final state (low ratio = iterated heavily
-  or was partly overwritten by a later session)
-- `matched_files` — commit-touched files this session edited in window
-- `last_edit_at` — ISO timestamp used for chronological sort
-
-Once you have a session ID, pass it back into recall to read the conversation:
-
-```bash
-$RECALL_BIN <session-id>                        # full session, oldest first
-$RECALL_BIN <session-id> --reverse              # newest first (faster for recent context)
-$RECALL_BIN "rationale keyword" --since DATE    # search within window
-```
-
-**For in-progress sessions**, the Stop hook that indexes a session hasn't
-fired yet — wait a few seconds after the turn finishes, then search again.
-
-## Date handling
-
-**Any date or time indication from the user MUST be translated into date flags.**
-Do NOT put dates into the search query text — dates in FTS5 produce false matches.
-
-```bash
-# Single day — use --since and --until together
-$RECALL_BIN --list --since 2026-04-10 --until 2026-04-10
-$RECALL_BIN "scroll bug" --since 2026-04-10 --until 2026-04-10
-
-# Open range — just one flag
-$RECALL_BIN "recall improvements" --since 2026-04-01
-$RECALL_BIN "old bug" --until 2026-03-15
-```
-
-- `--since DATE` — only sessions on or after this date
-- `--until DATE` — only sessions on or before this date (inclusive of the day)
-- Both accept ISO-8601 dates (YYYY-MM-DD)
-- Both work in search and list modes
-
-**Example:** "What did we work on April 10?" →
-`$RECALL_BIN --list --since 2026-04-10 --until 2026-04-10` to find all sessions,
-then search with topic keywords + date flags if needed.
-
-## Project scope
-
-**Search and list default to the current working directory's project.** Recall
-filters results to the project whose path is your CWD — so from inside one repo
-you only see that repo's sessions. This keeps everyday recall focused, but it
-silently hides history when the answer lives elsewhere.
-
-```bash
-# Default — scoped to the CWD's project
-$RECALL_BIN "auth refactor"
-
-# Search every project (cross-repo questions, or when a scoped search is thin)
-$RECALL_BIN "auth refactor" --all
-
-# Scope to a specific project regardless of CWD
-$RECALL_BIN "auth refactor" --project /home/me/dev/other-repo
-```
-
-- `--all` — disable scoping; search across all indexed projects
-- `--project PATH` — scope to an explicit project path instead of the CWD
-- Both work in search and list modes
-
-**When to reach for `--all`:** the user asks about work that may span repos, the
-question isn't tied to the current repo, or a default (scoped) search returns
-few/zero results. A thin scoped result is often just the scope — retry with
-`--all` before concluding the history doesn't exist.
-
-## Recency boost
-
-When the user says "recently", "latest", "last few days", or otherwise indicates
-they want recent results, add `--recent` to strongly boost newer sessions:
-
-```bash
-$RECALL_BIN "scroll bug fix" --recent
-```
-
-This increases the recency decay from ~50% penalty at 50 days to ~50% at 10 days,
-pushing recent sessions to the top of results. Combine with `--since` for best results.
-
-## Tips
-
-- **Search is cheap, reading is expensive.** Run 3-5 varied queries before committing to reading sessions.
-- **Message IDs are stable.** You can reference them across searches.
-- **Use `--since` / `--until` to scope.** Both search and list modes accept date flags.
-- **Search is scoped to the CWD's project by default.** Add `--all` for cross-repo questions or when a scoped search comes back thin.
-- **Raw JSON output** (`--raw`) is available for programmatic processing.
+Search + read past Claude Code / Codex session transcripts. Command: `recall`
+(fallback: `$RECALL_BIN`).
+
+**Pattern: search → read the match.** `recall "query"` returns rows with session ID +
+matched message ID; then `recall <session-id> <message-id>` reads centered on that match
+(footer shows `--offset` to continue). Don't re-read sessions from the top.
+
+- Dates go in flags, never query text: `--since`/`--until YYYY-MM-DD`; `--recent` for "lately".
+- Search is scoped to this repo (any clone or worktree); thin or off-target results → retry with `--all`
+  (or `--project PATH`). Semantic fill returns plausible rows for ANY query — judge
+  relevance yourself.
+- A read's header says `Session:`. If it says `Query:`, the ref fell back to search
+  and the rows are noise — fix the ID; `recall read <ref>` exits nonzero instead of
+  falling back.
+- Transcripts record what was believed, not what is — verify claimed state against
+  git/disk before repeating it.
+- `recall --commit <hash>` / `recall --blame path:line` → the sessions that produced a
+  commit / the code at HEAD (structural match, includes rationale + rejected approaches) (local sessions only on a satellite).
+- `recall --list --since D --until D` browses a day. IDs are opaque; paste back exactly.
+- Just-finished sessions index a few seconds after the turn ends; on a
+  satellite, after the push lands (seconds).
+- `recall --help` for everything else.
+
+**Deep research → sub-agent.** For multi-search timelines, delegate. The sub-agent can't
+see this file, so its prompt must say: use only the `recall` CLI (never Grep/Read .jsonl
+transcripts); run `recall --help` first; search then read matched messages
+(`recall <session-id> <message-id>`); dates as `--since`/`--until` flags; `--all` if
+results are thin; search exhaustively and cross-reference before reporting.