@jeffober/thatch 0.1.28 → 0.1.30

package/docs/dev/features/memory-store.md

@@ -0,0 +1,154 @@
+# Memory Store
+
+The memory store is thatch's core feature: a SQLite-backed store of memories with semantic search via local embeddings. Everything else thatch does — extraction, hygiene, nudges, predictions, behaviors — reads from or writes to this store.
+
+## What it does
+
+The store persists memories keyed by label, scoped to a project store or the shared "global" store. Each memory is a labeled chunk of text an agent writes for a future session of itself to read.
+
+- Stores memories keyed by label within a store. The store name is auto-detected from the git remote — the `owner/repo` slug — or falls back to `"global"` for cross-project knowledge.
+- Semantic search via cosine similarity over BGE-small-en-v1.5 embeddings (384 dimensions, ~34 MB). The model runs locally and is lazy-loaded.
+- Six tools: `memory_remember`, `memory_recall`, `memory_list`, `memory_show`, `memory_forget`, and `store_list`. All are defined in `src/tool-defs.ts`.
+- Branch scoping. Memories can be scoped to a git branch for work-in-progress context, or left unscoped for project-wide knowledge. Branch-scoped memories are recalled alongside project-wide ones when the branch matches.
+- Confidence grading on a 1–10 scale, stored per memory.
+- Archived flag. Archived memories are long-term records excluded from search and hygiene by default. Pass `includeArchived: true` to surface them.
+- Write-time duplicate detection. When a new memory is similar to existing ones (cosine ≥ 0.85), the save returns a warning listing the near-duplicates. The save always proceeds — the warning asks the agent to reconcile, never blocks.
+- Asymmetric search. Query text gets a BGE-specific prefix for retrieval; stored passages get no prefix. This follows the BGE training convention for asymmetric search.
+- Multi-model dimension check. Entries embedded by a model with a different vector dimension are silently skipped during search, not ranked. The `model` column is informational — dimension is the discriminator.
+- Recall tracking. Each memory carries `recall_count` and `last_recalled_at`, stamped when an agent-initiated search returns it. The hygiene system uses these to detect stale memories.
+
+## How it works
+
+### Store detection
+
+`src/git.ts` parses `owner/repo` from the git remote URL. The resolution chain is worktree-safe:
+
+1. Parse `owner/repo` from `git remote get-url origin`.
+2. Fall back to the basename of the git common dir (worktree-safe).
+3. Fall back to the directory basename.
+4. Falls back to `"unknown"` if none of the above yield a result.
+
+The "global" store always exists — it is inserted at schema init (`INSERT OR IGNORE INTO stores (name) VALUES ('global')`). Store creation is implicit: the first `memory_remember` to a new store calls `ensureStore`, which creates it via `INSERT OR IGNORE`.
+
+### Embedding model
+
+`src/embeddings.ts` defines the `BgeEmbeddingModel` class.
+
+- Model: `Xenova/bge-small-en-v1.5` — 384 dimensions, ~34 MB.
+- Lazy-loaded via the `@huggingface/transformers` `pipeline("feature-extraction")` API. The first load downloads from Hugging Face Hub; subsequent loads use the cached model.
+- Query prefix: `"Represent this sentence for searching relevant passages: "` — the BGE asymmetric search convention. Queries get the prefix; passages do not.
+- Mean pooling and L2 normalization are applied via pipeline options.
+- Output is a `Float32Array`.
+- `MockEmbeddingModel` is available for tests.
+- The model can be overridden via the `THATCH_MODEL` environment variable.
+
+### Write path (memory_remember)
+
+```text
+agent calls memory_remember(label, content, opts)
+  → model.passageEmbed("# label\n\ncontent")  →  Float32Array
+  → db.findSimilar(store, embedding, { excludeSlug })  →  write-time collision check
+  → db.remember(store, label, content, embedding, model.name, opts)
+      overwrite:false  →  atomic INSERT (PK constraint rejects duplicates)
+      overwrite:true   →  upsert + clear stale dedup verdicts for that slug
+  → return confirmation + warning if similar memories found
+```
+
+The tool prepends `# ${label}\n\n` to the content before embedding. The stored `content` column holds this full formatted text — it is the exact input that was embedded, so a future re-embed requires no reconstruction.
+
+The `findSimilar` call is a write-time collision check with no telemetry. It excludes the slug being written (self-exclusion on overwrite). If it finds entries with cosine ≥ 0.85, the return value includes a warning listing them.
+
+The save always proceeds. The warning asks the agent to reconcile — merge into one entry (overwrite + forget the other) or record that they are genuinely distinct via `dedup_mark_checked`.
+
+On overwrite, the upsert clears stale dedup verdicts: any `dedup_pairs` rows referencing that slug are deleted, since the content change may resolve or create duplicates.
+
+### Read path (memory_recall)
+
+```text
+agent calls memory_recall(query, opts)
+  → model.queryEmbed(query)  →  Float32Array
+  → db.recall([repo, "global"], queryEmbedding, { branch?, limit })
+      → db.search()  →  cosine scoring, sort desc, top-N
+      → stamp recall_count + last_recalled_at on returned rows
+  → return formatted results with scores
+```
+
+The tool layer hardcodes `[repo, "global"]` as the default search scope. Omitting the `store` parameter searches both. Passing a specific store searches only that store.
+
+Entries with a mismatched embedding dimension are skipped during search — the `emb.length !== queryEmbedding.length` guard in `db.search()`. This handles the case where a different embedding model was used for older entries.
+
+### Search vs. recall
+
+Two methods, one scoring engine, different telemetry policy:
+
+| Method | Telemetry | Used by |
+|--------|-----------|---------|
+| `db.search()` | None | Prompt-aware recall nudge (see [nudge-pipeline.md](nudge-pipeline.md)) |
+| `db.recall()` | Stamps `recall_count` / `last_recalled_at` | `thatch_memory_recall` tool, CLI `thatch search` |
+
+The distinction is deliberate. The recall nudge checks whether memories relate to a prompt — the plugin is looking, not the agent. Stamping telemetry on a nudge would inflate the "used recently" signal that hygiene reporting depends on. Only explicit agent-initiated recall stamps telemetry.
+
+### Default recall scope
+
+The tool layer hardcodes `[repo, "global"]` as the default search scope. This means a `memory_recall` call with no `store` argument searches both the project store and the global store. There is no way to search only the project store without the global store via the tool — pass an explicit `store` argument to scope to one.
+
+### Archived memories
+
+The `archived` column is an integer flag: `0` (default) is live, `1` is archived.
+
+- `search()`, `findDuplicates()`, and the stale-entry count in hygiene all filter `WHERE archived = 0`.
+- To search archived memories: pass `includeArchived: true` to `memory_recall`.
+- To archive: write with `archived: true`. To unarchive: write with `archived: false`.
+- Updating an already-archived memory requires an explicit `archived` parameter. The guard prevents accidental unarchival — the caller must consciously pass `archived: true` to keep it archived or `archived: false` to unarchive it.
+
+### Slug generation
+
+`slugify()` converts a label to a slug: lowercase, whitespace to hyphen, Unicode letters and digits preserved. All-symbol labels fall back to a hash so no label ever maps to an empty slug. ASCII labels produce the same slugs as earlier releases.
+
+The slug plus store name form the composite primary key: `PRIMARY KEY (slug, store)`.
+
+### CLI access
+
+The `bin/thatch` CLI provides read-only access to the store:
+
+| Command | Description |
+|---------|-------------|
+| `thatch stores` | List all stores |
+| `thatch list [store]` | List memory labels in a store |
+| `thatch show <label> [store]` | Display one memory |
+| `thatch forget <label> [store]` | Delete one memory |
+| `thatch search <query> [store]` | Semantic cosine search (limit 10; `"all"` searches project + global) |
+
+## Interactions with other features
+
+- **Extraction pipeline** ([extraction.md](extraction.md)): the extraction sub-agent writes memories via `memory_remember`. The extraction buffer drains on any `memory_remember` call.
+- **Deduplication** ([deduplication.md](deduplication.md)): `find_duplicates` scans stored memories for cosine-similar pairs. `dedup_mark_checked` records verdicts in the `dedup_pairs` table. Overwriting or forgetting a memory clears its dedup verdicts.
+- **Hygiene** ([hygiene.md](hygiene.md)): staleness checks use `recall_count` and `last_recalled_at` to find memories nobody has read recently. Duplicate checks use cosine search. Orphaned-branch detection finds branch-scoped memories whose branch no longer exists.
+- **Nudge pipeline** ([nudge-pipeline.md](nudge-pipeline.md)): the recall nudge uses `db.search()` — not `db.recall()` — to avoid inflating telemetry. The nudge fires when search results exceed the similarity threshold (default 0.55).
+- **Prediction engine** ([prediction-engine.md](prediction-engine.md)) and **behavior engine** ([behavior-engine.md](behavior-engine.md)): these share the same embedding model but store vectors in separate tables (`prediction_matchers`, `prediction_predictions`, `behavior_matchers`, `behavior_behaviors`). They do not read from or write to the `entries` table.
+
+## Source files
+
+| File | Responsibility |
+|------|---------------|
+| `src/db.ts` | SQLite schema, CRUD for entries and stores, brute-force cosine search (`search` vs. `recall`), dedup verdict tracking, prediction and behavior tables |
+| `src/embeddings.ts` | `BgeEmbeddingModel` (lazy-load, query/passage embed, mean pooling, L2 normalization) and `MockEmbeddingModel` for tests |
+| `src/git.ts` | Detect repo identity (store name) from git remote; worktree-safe fallback chain |
+| `src/tool-defs.ts` | Tool definitions — single source of truth for all tools, including the six memory tools |
+| `bin/thatch` | CLI subcommands: `stores`, `list`, `show`, `forget`, `search` |
+
+## Key invariants
+
+1. **No global mutable state.** Every module accepts dependencies explicitly. `ThatchDB` takes a path; `BgeEmbeddingModel` takes an optional pipeline factory; tools receive a `ctx` with `db` and `model`.
+
+2. **Embedding is a separate concern.** `db.ts` stores and retrieves BLOBs and compares vectors handed to it. It knows nothing about embedding models — it never calls `passageEmbed` or `queryEmbed`. The tool layer is the bridge: it embeds, then hands the vector to the DB.
+
+3. **Embedding spaces are discriminated by vector dimension, not model tag.** The `model` column is written on every save and returned on every read, but no code path filters or branches on it. Dimension mismatch is the only guard. This means a same-dimension model switch produces silently wrong cosine scores, while a different-dimension switch produces silently skipped entries.
+
+4. **Store creation is implicit.** The first `memory_remember` to a new store creates it. There is no explicit "create store" operation.
+
+5. **Default recall scope is repo + global.** The tool layer hardcodes `[ctx.defaultStore, "global"]` when no `store` argument is provided. This is intentional — cross-project knowledge in the global store is always searched alongside project-specific memories.
+
+6. **The write-time similarity warning never blocks the save.** `findSimilar` returns a warning, `remember` proceeds regardless. The warning asks the agent to reconcile after the fact.
+
+7. **`search()` records no usage. `recall()` stamps telemetry. This is deliberate.** The recall nudge (plugin checking relevance) must not inflate the "used recently" signal. Only agent-initiated recall counts as actual usage.

package/docs/dev/features/multi-host.md

@@ -0,0 +1,228 @@
+# Multi-Host Support
+
+Thatch runs as both an opencode plugin and an MCP server for Claude Code and
+Cursor. Three integration paths share a common core---the tool definitions in
+`src/tool-defs.ts`---but differ in how they deliver system prompts, prefix tool
+names, and handle session lifecycle events.
+
+## What it does
+
+Thatch supports three host agents from a single codebase:
+
+- **opencode plugin**---in-process, direct event hooks, warm embedding model,
+  `thatch_` tool prefix
+- **Claude Code MCP**---stdio MCP server, external CLI hooks,
+  `mcp__thatch__` tool prefix, system prompt in CLAUDE.md
+- **Cursor MCP**---same stdio MCP server, `--json` hook output format,
+  `mcp__thatch__` tool prefix, system prompt in AGENTS.md
+
+All three paths expose the same 18 tool definitions from `src/tool-defs.ts`.
+The tools are host-agnostic: each takes args and a `CoreContext`
+(`{ db, model, defaultStore }`) and returns a string. The host-specific
+wrapping---prefixing, transport, session hooks---lives outside the core.
+
+## The three paths
+
+### opencode plugin (`src/index.ts`)
+
+Runs inside opencode's Bun runtime as a loaded plugin. No setup command is
+needed---opencode discovers the plugin from `opencode.json` and loads it at
+startup.
+
+**System prompt**: injected at runtime via the
+`experimental.chat.system.transform` hook. The hook calls `systemPrompt(repo)`
+and pushes the result into `output.system` every turn. No files are written.
+The repo name is baked in at runtime, so the prompt always reflects the current
+worktree.
+
+**Tools**: registered through opencode's `tool()` wrapper in `src/tools.ts`,
+which adds the `thatch_` prefix. The agent sees `thatch_memory_remember`,
+`thatch_memory_recall`, etc.
+
+**Skills**: installed to `$XDG_CONFIG_HOME/opencode/skills` at plugin init.
+Both the shared skill array and the opencode-only skill array are installed.
+See [../skills.md](../skills.md) for the skill system.
+
+**Capabilities unique to this path**:
+
+- Full access to plugin hooks: system prompt injection, session events, tool
+  buffering, compaction context
+- TUI toast notifications---best-effort, silently ignored in headless mode
+- Direct extraction via child sessions (see [session-lifecycle.md](session-lifecycle.md))
+- Compaction recovery (see [compaction-recovery.md](compaction-recovery.md))
+- Background sub-agents (experimental)---the code-review coordinator dispatches
+  specialist sub-agents through opencode's agent infrastructure
+
+### Claude Code MCP server (`src/mcp.ts`)
+
+Runs as a stdio JSON-RPC 2.0 process spawned by Claude Code. The MCP server
+exposes tools via `tools/list` and `tools/call`. It is long-lived for the
+session duration, keeping the embedding model warm in memory.
+
+**System prompt**: static text appended to `CLAUDE.md` by
+`thatch setup --claude`. The text is written between marker constants
+(`THATCH_MARKER` / `THATCH_END_MARKER`) using the `appendBlock` helper in
+`src/setup.ts`. The block is idempotent---re-running setup replaces the content
+between the markers rather than duplicating it. Claude Code loads `CLAUDE.md`
+at session start.
+
+**Tools**: the MCP server exposes bare names (`memory_remember`,
+`memory_recall`). Claude Code's MCP client applies the `mcp__thatch__` prefix,
+so the agent sees `mcp__thatch__memory_remember`. Thatch itself does not apply
+this prefix.
+
+**Skills**: installed to `$CLAUDE_CONFIG_DIR/skills/`---shared skills only.
+The code-review coordinator skill is opencode-only because it requires
+sub-agent dispatch, which Claude Code does not support.
+
+**Session behavior**: driven by external CLI hook processes (`bin/thatch`).
+The hooks are registered in `.claude/settings.json` during setup. Each hook
+spawns a short-lived `thatch` process that communicates with the long-lived MCP
+server via the sideband socket (see [sideband.md](sideband.md)) for warm-model
+access. This avoids loading the ~34 MB embedding model in every one-shot hook
+process.
+
+**Setup**: `thatch setup --claude` writes `.mcp.json` (server config),
+`CLAUDE.md` (instructions block), `.claude/settings.json` (hooks), and
+installs skills. See [setup.md](setup.md) for the setup system.
+
+### Cursor MCP server (same `src/mcp.ts`)
+
+The same stdio MCP server as Claude Code. The differences are in hook format,
+system prompt file, and tool batching granularity.
+
+**System prompt**: static text appended to `AGENTS.md` by
+`thatch setup --cursor`, using the same `appendBlock` helper and marker pair.
+Cursor loads `AGENTS.md` at session start.
+
+**Tools**: same bare names over MCP, same `mcp__thatch__` prefix applied by
+Cursor's MCP client.
+
+**Skills**: installed to `$CURSOR_CONFIG_DIR/skills/`---shared skills only.
+
+**Session behavior**: driven by Cursor hooks in flat `hooks.json` format
+(`.cursor/hooks.json`). Hook output uses the `--json` flag, producing
+`{ additional_context: "..." }` objects that Cursor injects into the agent's
+context. The `postToolUse` hook fires per-tool---there is no batch equivalent
+of Claude Code's `PostToolBatch`. Tool buffering uses `thatch buffer-tool` on
+each individual tool call. Cursor uses `conversation_id` instead of
+`session_id` for session tracking.
+
+**Setup**: `thatch setup --cursor` writes `.cursor/mcp.json`, `AGENTS.md`,
+`.cursor/hooks.json`, and installs skills.
+
+## System prompt delivery
+
+Three mechanisms, one per host. The prompt functions all live in
+`src/prompts.ts`.
+
+1. **opencode**: the `experimental.chat.system.transform` hook calls
+   `systemPrompt(repo)` and pushes the result into `output.system` at runtime.
+   No files are written. The prompt is generated fresh every turn.
+
+2. **Claude Code**: `claudeInstructions()` produces the text that
+   `thatch setup --claude` appends to `CLAUDE.md` between
+   `THATCH_MARKER` / `THATCH_END_MARKER`. The file is loaded once at session
+   start by Claude Code.
+
+3. **Cursor**: `cursorInstructions()` produces the text that
+   `thatch setup --cursor` appends to `AGENTS.md` between the same markers.
+   Loaded once at session start by Cursor.
+
+The three prompt functions are near-identical. They differ only in host name
+string, config file reference (`OPENCODE.md` / `CLAUDE.md` / `AGENTS.md`), and
+tool name prefix in the tool list line. Their shared prose sections---"When to
+Write", "What NOT to Store", "Before Responding", "Stores", "Skills"---are
+verbatim copies with these token substitutions.
+
+There is no single-source-of-truth template that generates all three. Each
+variant is an independent string constant in `src/prompts.ts`. Editing shared
+prose in one variant requires mirroring the edit in the other two, or the
+variants silently drift.
+
+The tool list line in all three prompts must be kept in sync with
+`TOOL_DEFS` in `src/tool-defs.ts`. The historical failure mode: a tool is added
+to `TOOL_DEFS` but only two of the three prompt functions are updated, creating
+an asymmetry a reviewer can catch by diffing the tool lines.
+
+## Tool name prefixing
+
+The 18 tool definitions in `src/tool-defs.ts` use bare names:
+`memory_remember`, `memory_recall`, `memory_list`, etc. Each host applies its
+own prefix.
+
+| Host | Prefix | Applied by | Example |
+|------|--------|------------|---------|
+| opencode | `thatch_` | `tool()` wrapper in `src/tools.ts` | `thatch_memory_remember` |
+| Claude Code | `mcp__thatch__` | Claude Code's MCP client | `mcp__thatch__memory_remember` |
+| Cursor | `mcp__thatch__` | Cursor's MCP client | `mcp__thatch__memory_remember` |
+
+The MCP server (`src/mcp.ts`) always exposes bare names. The
+`mcp__thatch__` prefix is a convention of the MCP client, not of thatch.
+The opencode prefix is applied in-process by the `tool()` wrapper.
+
+## Feature availability differences
+
+Not all features are available on all hosts. The opencode plugin has direct
+access to session events, child sessions, and compaction hooks. The MCP hosts
+rely on external hook processes and the sideband socket for equivalent
+behavior, with some features having no MCP counterpart.
+
+| Feature | opencode | Claude Code | Cursor |
+|---------|----------|-------------|--------|
+| Direct extraction (child sessions) | Yes | No | No |
+| Compaction recovery | Yes | No | No |
+| TUI toast notifications | Yes | No | No |
+| Sideband socket | No (in-process) | Yes | Yes |
+| code-review coordinator skill | Yes | No | No |
+| Background sub-agents | Yes (experimental) | No | No |
+| Tool batching | N/A (in-process) | PostToolBatch (batch) | postToolUse (per-tool) |
+
+For the full parity matrix, see [../mcp-parity.md](../mcp-parity.md).
+
+## Interactions with other features
+
+All 18 tools are shared across all hosts via the single source of truth in
+`src/tool-defs.ts`. Individual tool behavior is documented in
+[memory-store.md](memory-store.md), [extraction.md](extraction.md),
+[prediction-engine.md](prediction-engine.md),
+[behavior-engine.md](behavior-engine.md), and
+[deduplication.md](deduplication.md).
+
+The **nudge pipeline** (see [nudge-pipeline.md](nudge-pipeline.md)) runs
+in-process for opencode. For MCP hosts, it runs via the sideband socket---hook
+processes query the long-lived MCP server for memory matches, predictions, and
+behavior nudges through a Unix domain socket. See [sideband.md](sideband.md)
+for the socket protocol.
+
+The **extraction pipeline** (see [extraction.md](extraction.md)) uses an
+in-memory ring buffer for opencode. For MCP hosts, it uses a file-backed JSONL
+queue that hook processes append to and the MCP server drains.
+
+The **setup system** (see [setup.md](setup.md)) handles Claude Code and Cursor
+installation. opencode auto-installs skills and injects the system prompt at
+plugin init---no setup command is needed.
+
+**Skills** (see [../skills.md](../skills.md)) install both the shared and
+opencode-only arrays for opencode. MCP hosts receive shared skills only, since
+the opencode-only skills require sub-agent dispatch or in-process hooks.
+
+## Source files
+
+| File | Role |
+|------|------|
+| `src/index.ts` | opencode plugin entry---hooks, system prompt injection, session events |
+| `src/mcp.ts` | MCP server (shared by Claude Code and Cursor)---stdio JSON-RPC, tool dispatch |
+| `src/setup.ts` | Setup installer for Claude Code and Cursor---markers, hooks, skills |
+| `src/prompts.ts` | All three system prompt variants---`systemPrompt()`, `claudeInstructions()`, `cursorInstructions()` |
+| `src/tools.ts` | Thin opencode tool wrappers---imports tool-defs, adds `thatch_` prefix via `tool()` |
+| `src/tool-defs.ts` | Single source of truth for all 18 tool definitions---name, description, zod schema, execute |
+| `bin/thatch` | CLI hook commands for MCP hosts---`reminder`, `buffer-tool`, `flush-tools`, `setup` |
+
+## Key invariants
+
+- All three hosts share the same 18 tool definitions from `src/tool-defs.ts`. Adding a tool requires updating `TOOL_DEFS` and all three prompt functions.
+- The MCP server always exposes bare names. The `mcp__thatch__` prefix is applied by the MCP client, not thatch.
+- The three system prompt variants are independent string constants in `src/prompts.ts` with no shared template. Editing shared prose in one requires mirroring in the other two, or they drift.
+- The tool list line in all three prompts must match `TOOL_DEFS` in `src/tool-defs.ts`. The historical failure mode: a tool is added to `TOOL_DEFS` but only two of three prompts are updated.
+- opencode-only features (direct extraction, compaction recovery, code-review coordinator, background sub-agents, TUI toasts) have no MCP counterpart.

package/docs/dev/features/nudge-pipeline.md

@@ -0,0 +1,282 @@
+# Per-Message Nudge Pipeline
+
+Runs on every user message. Four priority tiers share one embedding
+computation. The pipeline injects *synthetic parts*---text the model sees in
+the conversation but the user does not see in the TUI. This is the inverse of
+toast notifications, which are TUI-visible but model-invisible.
+
+The nudge pipeline is thatch's core innovation. It is not a passive
+store-and-retrieve system. It is a nudge layer that changes agent behavior by
+injecting context at the right moment. See [extraction.md](extraction.md) for
+the extraction nudge, [prediction-engine.md](prediction-engine.md) for the
+prediction auto-fire, and [behavior-engine.md](behavior-engine.md) for the
+behavior auto-fire.
+
+## What it does
+
+On every user message, thatch runs through four priority tiers:
+
+1. **Extraction nudge**---if tool interactions are buffered, tell the agent to
+   extract memories.
+2. **Recall nudge**---semantically search stored memories for context
+   relevant to the user's prompt.
+3. **Prediction nudge**---surface user decision-model predictions relevant to
+   the current situation.
+4. **Behavior nudge**---surface LLM self-discipline rules relevant to the
+   current situation.
+
+Tiers 2--4 fire independently and share one embedding computation. Tier 1
+returns early, skipping tiers 2--4.
+
+## How it works
+
+Two host paths deliver the same four tiers through different mechanisms. The
+opencode path runs in-process with direct event hooks. The MCP path runs via
+external CLI hook processes that communicate with the long-lived MCP server
+through the sideband socket.
+
+### opencode path (`src/index.ts`, `chat.message` hook)
+
+#### Compaction guard
+
+If the session is in the `compacting` set, thatch checks whether the incoming
+message is a compaction summary. If it is, all nudges are suppressed---tools
+are blocked during summary generation, so a nudge that says "call
+`thatch_memory_recall`" would trigger a blocked-tool error. If the message is
+not a compaction summary, compaction has already failed (the auto-continue
+never fired). Thatch clears the stale `compacting` flag and proceeds normally.
+See [compaction-recovery.md](compaction-recovery.md).
+
+#### Tier 1---Extraction nudge (fallback path)
+
+Fires only when direct extraction was never triggered or threw (the session is
+not in the `extracting` set) **and** the in-memory buffer has pending
+interactions.
+
+- Injects `extractionNudge(count, missed, "thatch_memory_remember", sessionID)`
+  as a synthetic text part.
+- Increments the `missedNudges` counter for escalation: polite at 0, insistent
+  at 2, ALL-CAPS shouting at 3+.
+- Returns early. Tiers 2--4 are skipped.
+
+See [extraction.md](extraction.md) for the full extraction pipeline, including
+the accept/complete/requeue lifecycle and the `extracting` set.
+
+#### Tier 2---Recall nudge
+
+- Extracts user prompt text from non-synthetic text parts. Skips if the text
+  is shorter than `MIN_PROMPT_LEN` (10 characters, hardcoded). Trivially short
+  prompts like "yes" or "ok" match too broadly to be useful.
+- Embeds the prompt with the warm in-process model: `model.queryEmbed(text)`.
+- Searches memories via `db.search([repo, "global"], embedding, { limit: 5 })`.
+  This uses `db.search`, not `db.recall`, to avoid inflating recall telemetry.
+  The agent has not actually read the memories yet---the nudge only checks
+  whether they relate to the prompt.
+- Filters results to `_score >= RECALL_THRESHOLD` (0.55, env:
+  `THATCH_RECALL_THRESHOLD`).
+- If matches survive: injects `recallNudge(matches)` as a synthetic text part
+  and fires a toast notification via `client.tui.showToast`.
+- Wrapped in its own try/catch. A recall failure does not block prediction or
+  behavior tiers.
+
+#### Tier 3---Prediction auto-fire
+
+- Reuses the same embedding from tier 2. No extra model call.
+- Scores prediction matchers via
+  `db.scorePredictionNudge([repo, "global"], embedding, PREDICTION_THRESHOLD)`.
+  This is a mechanical query: cosine-match against matchers, then score linked
+  predictions by Bayesian confidence.
+- Threshold: 0.60 (env: `THATCH_PREDICTION_THRESHOLD`). Higher than recall
+  because surfacing a preference nudge is more disruptive---the agent may act
+  on it or surface it to the user.
+- If matches: injects `predictionNudge(items)` as a synthetic text part and
+  fires a toast.
+- Independent try/catch.
+
+See [prediction-engine.md](prediction-engine.md) for the confidence model,
+matcher/prediction/edge data model, and the ambiguity-surfacing behavior.
+
+#### Tier 4---Behavior auto-fire
+
+- Reuses the same embedding. One more cosine scan, this time against
+  `behavior_matchers`.
+- Scores via
+  `db.scoreBehaviorNudge([repo, "global"], embedding, BEHAVIOR_THRESHOLD)`.
+- Threshold: 0.60 (env: `THATCH_BEHAVIOR_THRESHOLD`).
+- If matches: injects `behaviorNudge(items)` as a synthetic text part and
+  fires a toast.
+- Independent try/catch.
+
+See [behavior-engine.md](behavior-engine.md) for the ham/spam feedback loop
+and the self-discipline rule data model.
+
+#### Tier independence
+
+Tiers 2, 3, and 4 all fire independently. Any subset may inject. All share
+one embedding computation. The embedding is computed once, after the
+extraction tier returns early, and is reused across three cosine scans against
+different tables.
+
+### MCP path (`bin/thatch`, `flush-tools` subcommand)
+
+The `flush-tools` subcommand fires on `UserPromptSubmit` (Claude Code) or
+`beforeSubmitPrompt` (Cursor). It reads JSON from stdin:
+
+```json
+{
+  "session_id": "...",
+  "conversation_id": "...",
+  "prompt": "...",
+  "message": "...",
+  "text": "...",
+  "user_input": "...",
+  "input": "..."
+}
+```
+
+Session ID is `session_id ?? conversation_id`. Prompt text is the first
+present field from `prompt`, `message`, `text`, `user_input`, `input`.
+
+Three priority tiers, first match wins:
+
+#### Tier 1---Extraction nudge
+
+- `peekQueue(sessionID)` peeks the file-backed JSONL queue without draining
+  it. The queue persists until the agent calls `memory_remember`, which
+  triggers `consumeQueue`.
+- If interactions are pending: increments the missed count, prints
+  `extractionNudge(count, missed, "mcp__thatch__memory_remember", sessionID)`.
+- Breaks. Tiers 2--3 are skipped.
+
+See [extraction.md](extraction.md) for the file-backed queue and the
+`buffer-batch` subcommand that populates it.
+
+#### Tier 2---Recall + prediction + behavior via sideband
+
+- Extracts prompt text. Skips if shorter than 10 characters.
+- Connects to the sideband socket and fetches all three in parallel:
+  `sidebandMatch`, `sidebandPredictions`, `sidebandBehaviors`.
+- Same thresholds as opencode: 0.55 recall, 0.60 prediction, 0.60 behavior.
+- Concatenates any non-empty results: `claudeRecallNudge`,
+  `predictionNudge`, `behaviorNudge`.
+- Prints to stdout. Breaks.
+
+The sideband socket lets short-lived hook processes use the warm embedding
+model in the long-lived MCP server, avoiding a cold ~34 MB model load on every
+prompt. See [sideband.md](sideband.md) for the socket protocol.
+
+#### Tier 3---Static write nudge
+
+Fallback for conversational turns with no tool use and no memory matches.
+Prints `claudeWriteNudge()`:
+
+> After responding, check: did you learn new project knowledge, user
+> preferences, or corrections worth persisting? If so, save to thatch.
+
+On any error, falls back to the static write nudge. If that import also fails,
+silent failure---the hook never blocks the user's prompt over an unrelated
+error.
+
+### `flush-predictions` subcommand
+
+Standalone prediction fire---queries the sideband for scored predictions
+only. Not installed as a hook. Exists for testing and for hosts that want
+prediction-only output. `flush-tools` already fires predictions in tier 2.
+
+### Output format
+
+- **Claude Code**: plain text to stdout. Claude Code feeds hook stdout into
+  the agent's context.
+- **Cursor**: `--json` flag wraps output as `{ additional_context: "..." }`.
+  Cursor injects `additional_context` into the session.
+
+## Thresholds
+
+All thresholds are env-overridable.
+
+| Threshold | Default | Env var |
+|-----------|---------|---------|
+| Recall nudge | 0.55 | `THATCH_RECALL_THRESHOLD` |
+| Prediction auto-fire | 0.60 | `THATCH_PREDICTION_THRESHOLD` |
+| Behavior auto-fire | 0.60 | `THATCH_BEHAVIOR_THRESHOLD` |
+| Min prompt length | 10 chars | hardcoded (`MIN_PROMPT_LEN`) |
+
+The recall threshold (0.55) is lower than `findDuplicates`'s 0.85 because
+"relates to" is a weaker signal than "duplicate." The prediction and behavior
+thresholds (0.60) are higher than recall because surfacing a preference or
+self-discipline rule is more disruptive than surfacing a memory---the agent
+may act on it or interrupt the user.
+
+## Toast notifications (opencode only)
+
+`client.tui.showToast` is best-effort. If the TUI is not connected (headless
+mode), the call is silently ignored. Toasts are model-invisible: they go to
+the user only, not into the conversation history.
+
+| Trigger | Message | Variant | Duration |
+|---------|---------|---------|----------|
+| Recall matches | recalled N memories | info | 3s |
+| Prediction matches | N predictions surfaced | info | 3s |
+| Behavior matches | N behaviors surfaced | info | 3s |
+| Extraction child goes idle | new: N, updated: M, deleted: K | success | 4s |
+
+The extraction metrics toast fires only when memories were actually written.
+No-save runs produce no toast to avoid notification fatigue.
+
+## Synthetic nudge parts (opencode only)
+
+Nudges are injected via `client.session.prompt` with `noReply: true` and
+`synthetic: true`. The `synthetic` flag is a TUI-visibility marker, not a
+model-routing flag. The model sees the nudge text in the conversation. The
+user does not see it in the TUI transcript. This asymmetry is what makes the
+nudge-injection pattern work: the model can act on the nudge without
+cluttering the user's view.
+
+Do not confuse `synthetic` with `ignored`. A part marked `ignored` is dropped
+from the LLM-bound message. A part marked `synthetic` is only hidden from the
+TUI display. The opencode framework's history serializer filters on
+`!part.ignored`, not `!part.synthetic`.
+
+## Interactions with other features
+
+- **Extraction pipeline** ([extraction.md](extraction.md)): tier 1 is the
+  extraction nudge. The `extracting` set suppresses tier 1 when direct
+  extraction is active.
+- **Memory store** ([memory-store.md](memory-store.md)): tier 2 searches
+  stored memories via `db.search()`. This path records no telemetry---the
+  agent has not read the memories yet.
+- **Prediction engine** ([prediction-engine.md](prediction-engine.md)): tier
+  3 scores prediction matchers by cosine, then scores linked predictions by
+  Bayesian confidence.
+- **Behavior engine** ([behavior-engine.md](behavior-engine.md)): tier 4
+  scores behavior matchers by cosine, then scores linked behaviors by
+  ham/spam confidence.
+- **Sideband IPC** ([sideband.md](sideband.md)): MCP hosts use the sideband
+  socket for warm-model access. The hook process sends the prompt text; the
+  MCP server embeds it and runs the cosine scans.
+- **Compaction recovery** ([compaction-recovery.md](compaction-recovery.md)):
+  the nudge pipeline is suppressed during compaction. The compaction guard
+  clears stale flags when compaction fails.
+- **Session lifecycle** ([session-lifecycle.md](session-lifecycle.md)):
+  direct extraction (`triggerExtraction`) suppresses tier 1 by adding the
+  session to the `extracting` set.
+
+## Source files
+
+| File | Role |
+|------|------|
+| `src/index.ts` | opencode: `chat.message` hook (all 4 tiers), compaction guard, extraction fallback |
+| `bin/thatch` | MCP: `flush-tools` and `flush-predictions` subcommands |
+| `src/sideband.ts` | MCP: sideband client helpers (`sidebandMatch`, `sidebandPredictions`, `sidebandBehaviors`) |
+| `src/prompts.ts` | All nudge formatting functions (`recallNudge`, `claudeRecallNudge`, `predictionNudge`, `behaviorNudge`, `extractionNudge`, `claudeWriteNudge`) |
+
+## Key invariants
+
+- Tier 1 (extraction) returns early. Tiers 2-4 are skipped when tier 1 fires.
+- Tiers 2-4 share one embedding computation. One embed, three cosine scans against different tables.
+- Each tier is wrapped in its own try/catch. A failure in one tier does not block the others.
+- The recall nudge uses `db.search()`, not `db.recall()`, to avoid inflating telemetry. The agent has not read the memories yet.
+- The recall threshold (0.55) is lower than prediction/behavior (0.60) because "relates to" is weaker than "should surface to user."
+- Nudges are suppressed during compaction. Tools are blocked during summary generation, so a nudge saying "call `memory_recall`" would trigger a blocked-tool error.
+- `synthetic` means TUI-invisible, not model-invisible. The model sees the nudge text; the user does not. Do not confuse with `ignored`, which drops the part from the LLM-bound message.
+- MCP host hooks must be silent on success. Only `flush-tools` prints. Any stdout from other hooks delays the agent loop.