@jeffober/thatch 0.1.17 → 0.1.19

package/README.md

@@ -7,8 +7,8 @@
 Persistent memory and useful dev skills for AI coding agents that requires zero
 manual config.
 
-Works with **OpenCode** (as a plugin), **Claude Code** (as an MCP server), and
-**Cursor** (as a local `stdio` MCP server).
+Works with **OpenCode** (as a plugin), **Claude Code** (as a local `stdio` MCP
+server), and **Cursor** (as a local `stdio` MCP server).
 
 Each session inherits the accumulated knowledge of every session before it —
 project architecture, conventions, gotchas, user preferences — so your agent
@@ -98,6 +98,28 @@ When `thatch` is not on PATH, setup uses the absolute path to `bin/thatch` in
 the hooks and MCP config. When it is on PATH (npm global install), setup uses
 the bare `thatch` command so the config survives updates.
 
+### Other MCP-compatible harnesses
+
+Thatch works as a `stdio` MCP server with any MCP client. Register it in your
+harness's MCP config by pointing to the `thatch` binary:
+
+```json
+{
+  "mcpServers": {
+    "thatch": {
+      "command": "thatch",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+No `setup` step is needed for bare MCP usage; `setup` installs hooks and
+instructions specific to Claude Code and Cursor. For other harnesses, add the
+MCP server config above and include thatch's tools/instructions in your agent's
+system prompt manually (see [docs/dev/mcp-parity.md](docs/dev/mcp-parity.md)
+for the prompt text). [Bun] must be on PATH.
+
 ## Tools
 
 | Tool (opencode) | Tool (MCP) | What it does |
@@ -111,6 +133,36 @@ the bare `thatch` command so the config survives updates.
 | `thatch_find_duplicates` | `mcp__thatch__find_duplicates` | Surface pairs of suspiciously similar memories |
 | `thatch_dedup_mark_checked` | `mcp__thatch__dedup_mark_checked` | Record a reviewed pair so it stops being re-reported |
 | `thatch_extraction_done` | `mcp__thatch__extraction_done` | Acknowledge extraction nudge was dispatched to a sub-agent; drains the buffer |
+| `thatch_prediction_query` | `mcp__thatch__prediction_query` | Query the user decision model for scored predictions matching a context |
+| `thatch_prediction_update` | `mcp__thatch__prediction_update` | Create, reinforce, or weaken a prediction about user preferences |
+| `thatch_prediction_list` | `mcp__thatch__prediction_list` | List all predictions with matchers, confidence, evidence, and provenance |
+| `thatch_prediction_delete` | `mcp__thatch__prediction_delete` | Delete a prediction created in error (cascades to edges and provenance) |
+
+## Prediction engine
+
+Thatch maintains a statistical model of the user's decision-making preferences.
+When the user sends a prompt, the engine embeds it (sharing the embedding
+already computed for memory recall) and searches for **matchers** — context
+patterns that describe situations where the user has expressed preferences.
+Matching matchers fire linked **predictions** (scored by cosine similarity,
+edge weight, and Bayesian confidence), and a nudge is injected alongside the
+recall nudge:
+
+```text
+[thatch] User decision model
+- [0.72 conf, 4 tests] When X: you tend to Y
+- [0.50 conf, 0 tests] When Z: you may prefer W
+```
+
+The nudge is descriptive, not directive. The system prompt instructions tell
+the agent to follow strong predictions, surface uncertainty when confidence is
+thin, and update the model when the user responds. Predictions use a Bayesian
+posterior with a Beta prior (K=5, P0=0.5); signals are `confirm`,
+`disconfirm`, `soft` (weak disconfirm, weight 0.25), and `create`.
+
+The MCP path (Claude Code, Cursor) fires predictions via the same sideband
+socket used for recall nudges. The `flush-predictions` CLI subcommand provides
+standalone prediction-only output for testing.
 
 ## Skills
 
@@ -181,6 +233,7 @@ thatch hygiene                   Print the hygiene report (standalone)
 thatch buffer-batch              Append Claude Code PostToolBatch output to extraction queue
 thatch buffer-tool               Append Cursor postToolUse output to extraction queue
 thatch flush-tools [--json]      Peek extraction queue; print extraction + recall nudges
+thatch flush-predictions [--json]  Query predictions for the prompt (hook or standalone)
 thatch setup --claude [--cursor] [--global] Install config + instructions + hooks + skills
 ```
 
@@ -239,6 +292,7 @@ payload for the fact-extractor skill.
 | Session-start reminder | `session.created` event | `SessionStart` hook → `thatch reminder` | `sessionStart` hook → `thatch reminder --json` |
 | Compaction context | `experimental.session.compacting` hook | **Gap**: no equivalent (CLAUDE.md persists) | **Gap**: no equivalent |
 | Extraction nudge | `tool.execute.after` + `chat.message` | `PostToolBatch` + `UserPromptSubmit` (file-backed queue) | `postToolUse` + `beforeSubmitPrompt` (file-backed queue) |
+| Prediction auto-fire | `chat.message` hook, separate try/catch from recall | `flush-tools` tier 2 (sideband socket) | `flush-tools` tier 2 (sideband socket) |
 | Setup detection at startup | n/a (plugin auto-installs) | `checkSetup` in MCP server: detects missing/broken instructions | Same as Claude Code |
 | Skills | 19 (18 shared + coordinator) | 18 (shared only) | 18 (shared only) |
 | Store detection | `worktree` param from plugin | `CLAUDE_PROJECT_DIR` env var | `CURSOR_PROJECT_DIR` then `CLAUDE_PROJECT_DIR` |

package/bin/thatch

@@ -29,6 +29,7 @@ function usage(): never {
   thatch buffer-batch              Append a PostToolBatch payload to the queue (Claude Code hook only)
   thatch buffer-tool               Append a single postToolUse interaction to the queue (Cursor hook only)
   thatch flush-tools [--json]      Peek the queue + print an extraction nudge (hook only)
+  thatch flush-predictions [--json] Query predictions for the prompt (hook only)
   thatch setup --claude [--cursor] [--global]
                                    Install config + instructions + hooks + skills
 
@@ -351,7 +352,7 @@ switch (command) {
 
       const { peekQueue, getMissedCount, incrementMissedCount } = await import("../src/extract-queue");
       const { buildExtractionPayload } = await import("../src/extraction");
-      const { extractionNudge, claudeWriteNudge, claudeRecallNudge } = await import("../src/prompts");
+      const { extractionNudge, claudeWriteNudge, claudeRecallNudge, predictionNudge } = await import("../src/prompts");
 
       let repo = "unknown";
       try { repo = await detectRepo(); } catch {}
@@ -369,16 +370,31 @@ switch (command) {
         break;
       }
 
-      // Tier 2: recall nudge via sideband. The prompt text field name varies
-      // by host (Claude Code: "prompt", Cursor: undocumented). Try candidates.
+      // Tier 2: recall nudge + prediction fire via sideband. The prompt text
+      // field name varies by host (Claude Code: "prompt", Cursor: undocumented).
+      // Both recall and predictions share the same sideband round-trip.
       const promptText = data.prompt ?? data.message ?? data.text ?? data.user_input ?? data.input;
       if (promptText && promptText.length >= 10) {
-        const { sidebandMatch, sidebandSocketPath } = await import("../src/sideband");
+        const { sidebandMatch, sidebandPredictions, sidebandSocketPath } = await import("../src/sideband");
         const sockPath = sidebandSocketPath(dbPath);
-        const threshold = parseFloat(process.env.THATCH_RECALL_THRESHOLD ?? "0.55");
-        const matches = await sidebandMatch(sockPath, promptText, [repo, "global"], threshold, 5);
+        const recallThreshold = parseFloat(process.env.THATCH_RECALL_THRESHOLD ?? "0.55");
+        const predThreshold = parseFloat(process.env.THATCH_PREDICTION_THRESHOLD ?? "0.45");
+
+        const [matches, predictions] = await Promise.all([
+          sidebandMatch(sockPath, promptText, [repo, "global"], recallThreshold, 5),
+          sidebandPredictions(sockPath, promptText, [repo, "global"], predThreshold, 5),
+        ]);
+
+        const parts: string[] = [];
         if (matches && matches.length > 0) {
-          const output = claudeRecallNudge(matches);
+          parts.push(claudeRecallNudge(matches));
+        }
+        if (predictions && predictions.length > 0) {
+          parts.push(predictionNudge(predictions));
+        }
+
+        if (parts.length > 0) {
+          const output = parts.join("\n\n");
           if (isJson) console.log(JSON.stringify({ additional_context: output }));
           else console.log(output);
           break;
@@ -407,6 +423,56 @@ switch (command) {
     break;
   }
 
+  case "flush-predictions": {
+    // UserPromptSubmit (Claude Code) / beforeSubmitPrompt (Cursor) hook.
+    // Standalone prediction fire: queries the sideband for scored
+    // predictions matching the prompt text, prints the prediction nudge
+    // if any matchers fire. --json wraps as { additional_context: "..." }
+    // for Cursor hooks. Without --json, stdout is plain text.
+    //
+    // NOTE: flush-tools already fires predictions alongside the recall
+    // nudge in its tier 2 block. This subcommand exists for testing and
+    // for hosts that want prediction-only output without the recall or
+    // extraction nudges.
+    const isJson = args.includes("--json");
+    try {
+      const raw = await Bun.stdin.text();
+      const data = JSON.parse(raw) as {
+        prompt?: string;
+        message?: string;
+        text?: string;
+        user_input?: string;
+        input?: string;
+      };
+
+      const promptText = data.prompt ?? data.message ?? data.text ?? data.user_input ?? data.input;
+      if (!promptText || promptText.length < 10) {
+        if (isJson) console.log(JSON.stringify({ additional_context: "" }));
+        break;
+      }
+
+      let repo = "unknown";
+      try { repo = await detectRepo(); } catch {}
+
+      const { sidebandPredictions, sidebandSocketPath } = await import("../src/sideband");
+      const { predictionNudge } = await import("../src/prompts");
+      const sockPath = sidebandSocketPath(dbPath);
+      const threshold = parseFloat(process.env.THATCH_PREDICTION_THRESHOLD ?? "0.45");
+      const predictions = await sidebandPredictions(sockPath, promptText, [repo, "global"], threshold, 5);
+
+      if (predictions && predictions.length > 0) {
+        const output = predictionNudge(predictions);
+        if (isJson) console.log(JSON.stringify({ additional_context: output }));
+        else console.log(output);
+      } else {
+        if (isJson) console.log(JSON.stringify({ additional_context: "" }));
+      }
+    } catch (err) {
+      console.error(`[thatch flush-predictions] failed: ${err}`);
+    }
+    break;
+  }
+
   default:
     usage();
 }

package/docs/in-progress/prediction-engine.md

@@ -0,0 +1,404 @@
+# Prediction engine (in progress)
+
+> **Status: implementation complete across both host paths.** The
+> schema, tools, auto-fire (opencode), sideband prediction fire (MCP),
+> prompt instructions, and tests are shipped and passing the quality
+> gate. The feature is ready for field testing. This doc is the live
+> ledger; when the work closes, graduate durable parts into a permanent
+> `docs/dev/prediction-engine.md` and retire this file.
+
+## Purpose
+
+A **user decision model** that learns the user's preferences for
+judgment calls the coding agent faces every session: scope (how much to
+do), appropriateness (is this the right thing), methodology (the right
+way). The agent gets a "guess what the user would want in this
+situation" system -- inspired by nak's samskara predictive model, but
+different mechanism and domain.
+
+The delta over flat thatch memory is three things flat memory cannot do:
+
+1. **Graded confidence** -- memory is binary (stored or not).
+   Predictions have a Bayesian posterior that is reinforced or weakened
+   by user feedback. This enables ambiguity-surfacing: when confidence
+   is thin or predictions conflict, the agent asks the user instead of
+   guessing.
+2. **Context-disambiguation** -- matchers separate "when" from "what."
+   The same topic (tech debt in a PR) can produce opposite predictions
+   in different situations (flaky test blocking CI = fix it; unrelated
+   to change = skip it). Flat memory encodes this in prose the LLM must
+   re-reason about every time; the prediction engine encodes it as
+   structure.
+3. **Agent-driven feedback loop** -- the LLM itself decides to
+   strengthen or weaken a prediction based on user feedback, creating a
+   loop that flat memory lacks.
+
+## Design decisions (settled)
+
+These came out of design discussion with Jeff, July 2026. They are
+constraints, not open questions.
+
+1. **Auto-fire at chat.message.** The hook already embeds the user's
+   text for the recall nudge. The prediction fire shares that embedding
+   and does a second cosine search against the matchers table. When
+   matchers clear a relevance floor, scored predictions are injected as
+   a synthetic nudge part. No matchers fire = nothing injected (zero
+   tokens, zero latency). No "if appropriate" hedging -- the block's
+   presence is the appropriateness signal.
+
+2. **Tool-based update, agent-driven.** No local LLM classifier. Prompt
+   instructions tell the agent: when the user corrects you, answers a
+   question, or provides a clear signal, use prediction_update to
+   create/reinforce/weaken a prediction. The LLM decides with
+   appropriately nuanced prompt instructions; the tool is the trusted
+   boundary that handles embedding, dedup, and confidence math.
+
+3. **Statistical model query, not AI.** The query (embed + cosine +
+   weighted edges) is mechanical -- same as thatch_memory_recall but
+   against different tables. No model call. The agent can also call
+   prediction_query explicitly when it wants to check the model before a
+   judgment call.
+
+4. **No local LLM.** Considered and declined. The host LLM is already
+   reading the message and classifying "was this a correction?" as part
+   of understanding it. Adding a second classifier pays twice for the
+   same answer. The cost of not having a classifier is wasted nudge text
+   on turns with no signal -- not wasted model calls.
+
+5. **Descriptive context, not directive.** The injected block reads
+   "[0.72 conf, 4 tests] When X: you tend to Y" -- same shape as
+   samskara's compound summary. The system prompt instructions govern
+   how to act on it (follow strong silently, surface weak/competing,
+   update on user response). No "if appropriate" or "consider" hedging
+   in the injection itself.
+
+6. **Confidence mirrors samskara health.** A Bayesian posterior with
+   population-prior shrinkage: `confidence = (confirm + k*p0) /
+   (confirm + disconfirm + k)`. No wall-clock decay -- relevance-gated,
+   like samskara. Being tested (user gives feedback) is what moves
+   confidence. Untested predictions stay at p0.
+
+7. **LLM is the conflict detector.** The auto-fire returns all
+   predictions from matching matchers, not just the top one. The LLM
+   reads competing predictions and decides whether they conflict. No
+   mechanical conflict heuristic -- the LLM is better at semantic
+   conflict detection than any rule.
+
+## The normative asymmetry (carried from samskara)
+
+Samskara's intents doc identifies a normative asymmetry: the descriptive
+layer (samskara predictions) is ethically free to surface, but the
+normative layer (intents -- "what the model is working toward") carries
+weight because it shapes behavior. The prediction engine is descriptive
+("you tend to prefer X"), not normative ("I'm working toward X with
+you"). It reads user behavior, it does not pursue an agenda. The
+firewall from samskara's efficacy model carries over: the model that
+uses predictions cannot grade its own predictions -- the user's
+feedback is the only signal that moves confidence.
+
+## Data model
+
+Four new tables in the same SQLite DB, same conventions as the existing
+`entries`/`dedup_pairs` tables (idempotent CREATE TABLE IF NOT EXISTS,
+BLOB embeddings, store column, crypto.randomUUID PKs).
+
+### `prediction_matchers`
+
+Context patterns describing situations. The "when."
+
+- `id TEXT PRIMARY KEY` (crypto.randomUUID).
+- `store TEXT NOT NULL`.
+- `description TEXT NOT NULL` -- "reviewing a PR with pre-existing tech
+  debt."
+- `embedding BLOB` -- 384-dim Float32Array, passageEmbed (no query
+  prefix; matchers are passages, not queries).
+- `model TEXT`.
+- `created_at`, `updated_at` -- ISO timestamps.
+
+### `predictions`
+
+User preference statements. The "what."
+
+- `id TEXT PRIMARY KEY`.
+- `store TEXT NOT NULL`.
+- `statement TEXT NOT NULL` -- "skip it unless it's blocking this
+  change."
+- `rationale TEXT` -- why this prediction exists (inspector context).
+- `embedding BLOB` -- for dedup at creation time.
+- `model TEXT`.
+- `confidence REAL NOT NULL DEFAULT 0.5` -- Bayesian posterior [0,1].
+- `confirm_count REAL NOT NULL DEFAULT 0` -- fractional (soft signals
+  are sub-unit).
+- `disconfirm_count REAL NOT NULL DEFAULT 0` -- same.
+- `created_at`, `updated_at`.
+
+### `prediction_edges`
+
+Weighted matcher-to-prediction links. The "context-dependence."
+
+- `matcher_id TEXT NOT NULL` (FK to prediction_matchers, CASCADE).
+- `prediction_id TEXT NOT NULL` (FK to predictions, CASCADE).
+- `weight REAL NOT NULL DEFAULT 1.0`.
+- `created_at`.
+- `PRIMARY KEY (matcher_id, prediction_id)`.
+
+### `prediction_provenance`
+
+Audit trail. Gives the inspector context and the agent "plenty of
+context" for nuance.
+
+- `id TEXT PRIMARY KEY`.
+- `prediction_id TEXT NOT NULL` (FK to predictions, CASCADE).
+- `signal TEXT NOT NULL` -- 'confirm' | 'disconfirm' | 'soft' |
+  'create'.
+- `detail TEXT` -- what the user said or did.
+- `created_at`.
+
+## Confidence model
+
+Mirrors samskara's health posterior with population-prior shrinkage.
+
+```
+confidence = (confirm_count + k * p0) / (confirm_count + disconfirm_count + k)
+
+k      = 5     (prior strength, pseudo-count)
+p0     = 0.5   (population baseline; make population-derived later)
+W_SOFT = 0.25  (soft miss weight, same as samskara)
+```
+
+- `confirm` signal: confirm_count += 1.
+- `disconfirm` signal: disconfirm_count += 1.
+- `soft` signal: disconfirm_count += W_SOFT (0.25).
+- `create` signal: no confidence adjustment, just seeds at p0.
+- No wall-clock decay. Relevance-gated: being tested (user gives
+  feedback) is what moves confidence. Untested = stays at p0.
+- confirm_count / disconfirm_count are REAL (fractional). An integer
+  column would truncate soft signals to 0 (samskara's bug).
+- p0 starts at 0.5 for v1. Later: `populationP0(store)` = sum(confirm) /
+  sum(confirm + disconfirm), with a 0.5 fallback under 20 evidence.
+
+## Scoring at query time
+
+```
+score = cosine(user_text, matcher.embedding) * edge.weight * prediction.confidence
+```
+
+The auto-fire returns all predictions from matching matchers (not just
+the top scoring one), so the LLM can read conflicts. The score is for
+ranking and display, not for a mechanical "follow if above X" gate --
+the LLM decides whether to follow, surface, or ignore, informed by the
+confidence and evidence count shown alongside.
+
+## Ambiguity-surfacing (the killer feature)
+
+- **Strong prediction** (high confidence, sufficient evidence) -> agent
+  follows silently, does not interrupt.
+- **No prediction** -> agent asks the user (same as today).
+- **Ambiguous or competing predictions** -> agent surfaces naturally:
+  "I think you usually prefer X here, but I'm not sure -- what do you
+  want?"
+- **User responds to a surfaced prediction** -> agent calls
+  prediction_update to reinforce or weaken.
+
+Value = fewer interruptions, not more. High-confidence predictions
+suppress questions the agent would otherwise ask.
+
+## Tool surface
+
+Four tools, following the existing ToolDef pattern in tool-defs.ts.
+
+### `prediction_query`
+
+Mechanical search. Returns scored predictions with matcher
+description, confidence, and evidence count.
+
+Args: `context` (string), `store` (optional).
+
+### `prediction_update`
+
+The trusted boundary. The agent says "here's the situation, here's the
+preference, here's what happened." The tool handles: embed matcher,
+find/create by cosine dedup, embed prediction, find/create by cosine
+dedup, adjust confidence, record provenance.
+
+Args: `matcher` (string), `prediction` (string), `signal` (confirm |
+disconfirm | soft | create), `rationale` (string), `store` (optional).
+
+### `prediction_list`
+
+Inspector. Lists all predictions with confidence, evidence, matchers,
+and rationale.
+
+Args: `store` (optional).
+
+## Auto-fire in chat.message hook
+
+Slots into the existing recall-nudge path in index.ts, sharing the
+embedding call. After the recall nudge block, before the catch:
+
+```
+embedding = await model.queryEmbed(promptText)  // already computed
+
+// recall nudge (existing)
+results = db.search([repo, "global"], embedding, { limit: 5 })
+if matches >= RECALL_THRESHOLD -> inject recallNudge
+
+// prediction fire (new)
+predItems = db.scorePredictionNudge([repo, "global"], embedding, PREDICTION_THRESHOLD)
+if predItems.length > 0:
+    output.parts.push(predictionNudge(predItems))  // synthetic: true
+```
+
+One more cosine scan against a separate table. Same brute-force
+pattern, same cost profile. No extra embedding call.
+
+## System prompt instructions
+
+New section in all three prompt variants (systemPrompt,
+claudeInstructions, cursorInstructions), after "Before Responding."
+
+New tools registered in the tool list line:
+`thatch_prediction_query`, `thatch_prediction_update`,
+`thatch_prediction_list` (opencode); bare names for MCP.
+
+The injected block format:
+
+```
+## User decision model
+- [0.72 conf, 4 tests] When reviewing a PR with pre-existing tech debt: you tend to skip it unless it's blocking the change
+- [0.61 conf, 2 tests] When the tech debt is a flaky test: you've preferred fixing it
+```
+
+Prompt instructions:
+- Follow strong predictions silently.
+- Surface weak or competing predictions to the user naturally.
+- When the user responds to a surfaced prediction, use
+  prediction_update to reinforce or weaken.
+- When the user corrects you, answers a question, or provides a clear
+  signal, use prediction_query then prediction_update.
+
+## Constants
+
+```
+PREDICTION_THRESHOLD   = 0.45  // lower than RECALL_THRESHOLD (0.55)
+MATCHER_DEDUP_COSINE   = 0.85  // near-duplicate check at creation
+PREDICTION_DEDUP_COSINE = 0.85
+P0                     = 0.5   // prior (population-derived later)
+K                      = 5     // prior strength
+W_SOFT                 = 0.25  // soft miss weight
+```
+
+## Hook integration
+
+The `tool.execute.after` hook (index.ts) already skips
+`thatch_*`-prefixed tools from the extraction buffer.
+`thatch_prediction_*` is caught by that check -- no special handling
+needed. MCP path same: `mcp__thatch__prediction_*` caught by the
+`mcp__thatch__*` filter in extract-queue.ts.
+
+Prediction calls do NOT drain the extraction buffer -- they are a
+separate system. The agent may do both in the same turn (save a memory
+AND update a prediction).
+
+## Build status
+
+Landed so far:
+
+1. DB schema + methods (db.ts) -- four new tables (prediction_matchers,
+   predictions, prediction_edges, prediction_provenance) in #initSchema,
+   plus findMatchers, scorePredictions, findNearestMatcher,
+   findNearestPrediction, createMatcher, createPrediction, createEdge,
+   adjustConfidence, addProvenance, listPredictions, populationP0,
+   getPrediction, getProvenance, deletePrediction, scorePredictionNudge.
+   Confidence uses Bayesian posterior with k=5, p0=0.5, W_SOFT=0.25.
+2. Tool definitions (tool-defs.ts) -- prediction_query,
+   prediction_update, prediction_list, prediction_delete. Added to
+   TOOL_DEFS array (9 -> 13).
+3. Auto-fire (index.ts) -- prediction fire in chat.message hook,
+   sharing embedding with recall nudge. Prediction blocks injected
+   when matchers clear PREDICTION_THRESHOLD (0.45). predictionNudge
+   formatter in prompts.ts.
+4. System prompt (prompts.ts) -- "User Decision Model" section in all
+   three variants (systemPrompt, claudeInstructions,
+   cursorInstructions). New tools in all three tool lists.
+5. Tools wiring (tools.ts + mcp.ts) -- automatic via TOOL_DEFS
+   iteration. No manual changes needed.
+6. Tests -- tests/prediction.test.ts (schema, confidence math, dedup,
+   scoring, provenance, listPredictions, populationP0). Updated
+   tool-defs.test.ts and plugin.test.ts tool count assertions (9 -> 13).
+7. MCP path (sideband.ts + bin/thatch) -- the sideband server now
+   handles `method: "predictions"` alongside `method: "match"`, so
+   the warm MCP server can query matchers and score predictions for
+   one-shot hook processes. The `flush-tools` CLI subcommand (already
+   wired into UserPromptSubmit hooks for Claude Code and Cursor) now
+   fires predictions alongside the recall nudge in its tier 2 block,
+   sharing one sideband round-trip via `Promise.all`. A standalone
+   `flush-predictions` subcommand is also available for testing.
+   No new hook installation needed -- the existing `flush-tools` hook
+   covers it.
+
+Future enhancements:
+
+1. **p0 population derivation** -- v1 uses flat 0.5. Once enough
+   predictions accumulate, switch to population-derived p0 per store.
+2. **Auto-fire block separation** -- separate synthetic part from the
+   recall nudge, or combined? Starting with separate (simpler).
+3. **Inspector UI** -- `thatch prediction list` CLI subcommand for
+   terminal inspection. No Svelte UI (thatch has no UI).
+4. **Score formula tuning** -- v1 is `cosine * weight * confidence`.
+   If confidence dominates (high confidence on weak cosine swamps low
+   confidence on strong cosine), add samskara's `cosine^1.3` power.
+   Start simple; let data drive.
+5. **Edge weight tuning** -- v1 is flat 1.0 for all edges. The weight
+   encodes context-dependence but we have no signal to set it yet.
+   Could later set it from the matcher's cosine at creation time
+   (stronger match = higher weight) or from co-occurrence statistics.
+
+## Interactions
+
+- **Memory** (existing) -- distinct system. Memory is facts the
+  agent/user committed; predictions are learned preferences with graded
+  confidence. No data flows between them. The agent may write a memory
+  about a preference AND update a prediction about the same preference;
+  the memory is the "what" (durable fact), the prediction is the "how
+  confident" (graded, updated by feedback).
+- **Extraction pipeline** (existing) -- prediction tools are excluded
+  from the extraction buffer by the thatch_* prefix filter. No
+  feedback loop.
+- **Recall nudge** (existing) -- the prediction fire shares the
+  embedding call and runs in the same chat.message hook path (opencode)
+  or the same sideband round-trip (MCP). The two nudges are separate
+  synthetic parts (opencode) or combined in one output block (MCP);
+  either can be absent.
+- **Sideband** (existing, MCP path) -- the sideband server now handles
+  a `predictions` method alongside `match`. The `flush-tools` CLI
+  subcommand queries both in parallel via `Promise.all`.
+- **Compaction guard** (existing) -- the compacting set check at the
+  top of chat.message suppresses ALL nudges, including prediction fire.
+  No change needed.
+
+## Gotchas
+
+- **Matcher embeddings use passageEmbed, not queryEmbed.** Matchers
+  are passages (stored content matched against), not queries. The query
+  prefix applies to the user's text at fire time. Same pattern as
+  remember() which uses passageEmbed for content.
+- **confirm_count / disconfirm_count MUST be REAL.** An integer column
+  truncates soft signals (W_SOFT = 0.25) to 0 and freezes confidence at
+  p0. This is the same bug samskara had.
+- **Cold start is free.** Empty matchers table, findMatchers returns
+  [], nothing injected. The feature is inert until the first
+  prediction_update call. No migration, no config.
+- **Prediction calls do not drain the extraction buffer.** They are a
+  separate system. The agent may do both in the same turn.
+
+## Reference
+
+- nak samskara: `docs/dev/samskara.md` in the nak repo (the predictive
+  model of the user this feature is inspired by).
+- nak intents: `docs/dev/in-progress/intents.md` in the nak repo (the
+  normative layer atop samskara; the C efficacy model and firewall
+  between employment and efficacy informed the confidence model here).
+- thatch memory: this doc's "Interactions" section.
+- thatch extraction pipeline: `docs/dev/README.md` + `docs/dev/mcp-parity.md`.
+- thatch hook surface: `docs/dev/setup-and-hooks.md`, `docs/dev/gotchas.md`.

package/docs/qa/README.md

@@ -91,7 +91,7 @@ correctness on `README.md` and `docs/` excluding `docs/plans/`; see
 
 ### `tests/plugin.test.ts`
 
-- `server` export shape: all nine tools, every hook present, tools carry
+- `server` export shape: all thirteen tools, every hook present, tools carry
   description/args/execute
 - System transform and compaction hooks append their text
 - `tool.execute.after` → `chat.message` extraction round-trip: nudge carries
@@ -101,6 +101,38 @@ correctness on `README.md` and `docs/` excluding `docs/plans/`; see
 - `event` handler: calls `client.session.prompt` on `session.created` with
   correct session ID and nudge text; ignores non-`session.created` events
 - `sessionStartReminder`: includes store name and recall instructions
+- Recall nudge via `chat.message`: surfaces when prompt matches a stored
+  memory, no nudge for unrelated or short prompts, extraction priority
+- Prediction auto-fire via `chat.message`: surfaces when prompt matches a
+  stored matcher, no nudge for unrelated prompts, prediction and recall
+  nudges fire independently as separate synthetic parts
+
+### `tests/tool-defs.test.ts`
+
+- Tool count (13) and name list
+- Zod schema validation for each tool's args
+- Execute functions: `memory_remember` save/duplicate/overwrite/archived,
+  `memory_recall` default/empty/archived, `memory_list`/`show`/`forget`,
+  `store_list`, `find_duplicates` clean store
+- Prediction execute functions: `prediction_update` create/confirm/disconfirm/
+  create-on-existing (dedup links without disconfirming), `prediction_query`
+  matching/unrelated, `prediction_list` with provenance, `prediction_delete`
+  found/not-found
+
+### `tests/prediction.test.ts`
+
+- Schema: tables exist, `populationP0` fallback on empty store
+- Matcher creation and lookup: `findMatchers` ranking, `findNearestMatcher`
+  threshold/dedup
+- Prediction creation: `createPrediction` seeds at p0, `adjustConfidence`
+  confirm/disconfirm/soft/multiple, non-existent ID no-op
+- Edges and scoring: `createEdge` links, `scorePredictions` empty/dedup/
+  weight-preservation, `scorePredictionNudge` threshold filtering + dedup
+- `findNearestPrediction`: store-wide search, threshold, cross-matcher
+- Provenance: `addProvenance` + `getProvenance` read-back, `deletePrediction`
+  cascade to edges and provenance
+- `listPredictions`: sorted by confidence, matchers included
+- `populationP0`: under-20 fallback, population hit rate with sufficient evidence
 
 ### `tests/hygiene.test.ts`
 

package/docs/qa/use-cases/README.md

@@ -29,6 +29,10 @@ file/IPC/CLI contracts ready to graduate into `bun:test` integration tests.
 | [UC-018](UC-018-mcp-startup-setup-detection.md) | MCP startup detects missing/broken setup instructions and warns the agent |
 | [UC-019](UC-019-archived-memory-lifecycle.md) | Archive, search exclusion, update guard, unarchive |
 | [UC-020](UC-020-extraction-escalation.md) | Nudge escalation (polite → insistent → ALL-CAPS), buffer persistence, `extraction_done` drain |
+| [UC-021](UC-021-prediction-autofire.md) | Prediction auto-fire: matcher scores prompt, prediction nudge injected alongside recall |
+| [UC-022](UC-022-prediction-dedup.md) | Prediction create-on-existing: dedup finds match, links edge without disconfirming |
+| [UC-023](UC-023-prediction-confidence-model.md) | Bayesian confidence math: create, confirm, soft (weak disconfirm), disconfirm signals |
+| [UC-024](UC-024-prediction-delete.md) | Prediction delete with cascade, provenance inspection, not-found handling |
 
 ## Template