@jeffober/thatch 0.1.20 → 0.1.21

package/README.md

@@ -67,7 +67,7 @@ Include thatch's instructions in your agent's system prompt manually; see
 - **Prediction engine**: a statistical model of user decision-making
   preferences. When a prompt matches learned contexts, predictions fire
   alongside the recall nudge.
-- **Skills**: 20 skills for memory workflows, structured multi-specialist
+- **Skills**: 19 skills for memory workflows, structured multi-specialist
   code review, change walkthroughs, and writing tasks (PR descriptions,
   tickets, PR splitting).
 

package/artifacts/skills/pr-description.md

@@ -39,7 +39,7 @@ Sections, in order: SYNOPSIS, PURPOSE, DESCRIPTION, WALK-THROUGH (conditional),
 
 **SYNOPSIS, PURPOSE, and DESCRIPTION are mandatory** - even for a one-line, single-concern change. A tiny PR gets short sections, not fewer sections. WALK-THROUGH and NOTES appear only when warranted; omit them when empty. robots.txt appears only after an automated reviewer has produced a false positive worth heading off (see its section); it is always the final section.
 
-**Scale the body to the diff's conceptual size**, not its structure's capacity. A 2-file, single-concern change (add a flag, guard a branch, rename a symbol, bump a constant) is a few lines per section. SYNOPSIS one line, PURPOSE one to three, DESCRIPTION one short paragraph, NOTES if needed. The layered DESCRIPTION machinery below is for changes with real before/after mechanics to teach; when the diff is self-evident once you know the intent, collapse it. If your draft for a small change runs past ~15 lines of body, you are padding. Cut until each remaining line earns its place. Most of this skill's guidance exists to tame large PRs; applying it wholesale to a small one produces exactly the bloat the skill warns against.
+**Scale the body to the PR's complexity, not its size in files or lines.** Estimate complexity by how much new mental model the reviewer must build (see the point-based budgets in Length and style). A 1-point mechanical change gets short sections, not fewer sections. The layered DESCRIPTION machinery below is for changes with real before/after mechanics to teach; when the diff is self-evident once you know the intent, collapse it. Most of this skill's guidance exists to tame large PRs; applying it wholesale to a small one produces exactly the bloat the skill warns against.
 
 ### SYNOPSIS
 
@@ -77,7 +77,7 @@ When a ticket description is available, use its problem statement as the seed fo
 
 ### DESCRIPTION
 
-How much structure DESCRIPTION needs depends on the change's conceptual size.
+How much structure DESCRIPTION needs depends on the PR's complexity.
 
 **Small, self-evident change** (add a flag, guard a branch, rename a symbol, bump a constant): collapse to a sentence or two stating what the PR adds/changes. Do not manufacture a "how the code behaves today" paragraph for a change whose intent already makes the diff obvious. That is padding, not scaffolding.
 
@@ -240,13 +240,20 @@ These are hard rules, not suggestions.
 
 Target for most PRs: the reader can take in the whole description in under 60 seconds. Err on the shorter side.
 
-Scale the body to the diff's conceptual size:
-- Trivial 2-file change: ~15-line ceiling. SYNOPSIS one line, PURPOSE one to three, DESCRIPTION one short paragraph, NOTES if needed.
-- Moderate refactor: one tight paragraph or bullet set per section.
-- Large change with WALK-THROUGH: as long as the flow needs, but no longer. Aim for 3-6 steps; more means you are over-decomposing. Each step earns its place.
-- Enormous PR: accept that the reader may need more than 60 seconds. Keep the same rules, but spend the extra words on context, concrete behavior, and reviewer safety. Do not chase a tiny body by compressing meaning.
+Estimate the PR's **complexity** (how much new mental model the reviewer must build), not its size in files or lines. Complexity drives the word budget the way scrum points drive effort estimates:
 
-If your draft for a small change runs past ~15 lines of body, you are padding. Cut until each remaining line earns its place.
+- **1 point** (mechanical: rename, flag, guard, bump): the reviewer needs to know what changed, not why or how. ~50-100 words. SYNOPSIS one line, PURPOSE 1-2 sentences, DESCRIPTION 1-2 sentences.
+- **2-3 points** (new behavior, non-obvious mechanics): the reviewer needs to understand a before/after they cannot infer from the diff. ~100-250 words. SYNOPSIS 1-2 lines, PURPOSE 2-4 sentences, DESCRIPTION one tight paragraph or short three-layer.
+- **5 points** (new primitive, multi-workflow): the reviewer needs a mental model they do not have yet. ~250-400 words. Full sections as needed, WALK-THROUGH if there is a lifecycle.
+- **8 points** (architectural shift): the reviewer needs to re-orient their understanding of a subsystem. ~400-600 words. Accept the length, spend on context and reviewer safety.
+
+Estimate by: how many new concepts, how many decision points, whether the before/after is non-obvious, whether multiple workflows are affected. Not by files changed or lines added. A 200-line mechanical rename is 1 point. A 50-line new primitive with non-obvious semantics is 3-5 points.
+
+**When a section is too long, step up the abstraction ladder.** Do not compress terminology or cut connective tissue to hit a word count. Instead, replace a sequence of mechanism details with the principle that subsumes them. If you are explaining three mechanisms in sequence, find the one principle that makes all three obvious to someone who already knows the stack. The mechanism details belong in DESCRIPTION or the diff, not in PURPOSE or every section.
+
+Example: instead of six claims about how a connection pool reuses connections, how session locks are session-scoped, how a lock taken by one statement does not guard the next, and how nothing reports the mismatch, write: "Some Postgres features attach to the connection, not the statement. The pool freely reuses connections between statements, so state set by one statement may not be there for the next, and nothing reports the mismatch." Same understanding, fewer words, no compression.
+
+Brevity means fewer ideas, not compressed claims. If the section is still too long after stepping up, cut the lowest-value claim entirely. Do not cut the connective tissue that makes the remaining claims parse on first read.
 
 Inside sections, telegraphic bullet style is fine: lowercase start, abbreviations (`w/`, `1x`, `~`), parenthetical shorthand. Full sentences only when required for clarity. The section headers are the only formal structure.
 
@@ -401,7 +408,7 @@ That reading alone conveys the shape and scope of both changes. The prose is for
 11. **Verify links**: check ticket/PR links, repo file links, and external docs where tooling allows. Do not claim an unverified link was verified.
 12. **Verify prose style and core principle**: check each rule in Prose style. Cut design-narration, authoring-sequence, and buzzwordy abstractions. Verify plain ASCII. Verify first-use definitions for subsystem jargon. Verify project-private labels are translated before use. Verify plain English nouns (no code-domain nouns in prose). Verify conclusion-first in PURPOSE. Verify NOTES bullets are either short pointers or self-contained. Verify one-paragraph-one-physical-line for GitHub rendering. The robots.txt section is exempt from these prose rules below its human-warning line.
 13. **Clarity pass**: read the draft as a cold reviewer skimming the PR. Rewrite before returning it; do not tell the user you performed this pass. Check: does every project-specific term get plain-English meaning before or with the label? Are ambiguous terms qualified or replaced with concrete behavior? Did you replace code/comment shorthand with reader-facing behavior when the shorthand is less clear? Does every process word name object/action/effect? Does every contrast name old and new behavior? Does every causal sentence show the middle step? Did you preserve connective tissue instead of compressing meaning into noun stacks? If the draft got longer, cut a lower-value claim instead of compressing a high-value one.
-14. **Verify length**: if the body exceeds the ceiling for its conceptual size, cut until each line earns its place. For enormous PRs, accept extra length only when it buys context, concrete behavior, or reviewer safety.
+14. **Verify length**: estimate the PR's complexity (see the point-based budgets in Length and style). If the body exceeds the budget, step up the abstraction ladder first (replace mechanism sequences with the principle that subsumes them). If still over, cut the lowest-value claim entirely. Do not compress terminology or cut connective tissue to hit a word count.
 15. **Submit** via `gh pr create --body "$(cat <<'EOF' ... EOF)"` to preserve formatting.
 
 ## Anti-patterns

package/artifacts/skills/thatch-fact-extractor.md

@@ -15,7 +15,9 @@ You will be given a JSON payload with:
 1. Call thatch_memory_recall to check for existing memories related to the interactions.
 2. For each new fact, call thatch_memory_remember with the appropriate store.
 3. Do not save session-specific state, ephemeral debugging details, or info already in CLAUDE.md.
-4. Write for a future session with zero current context. No "we", "our session", "just now".
+4. Apply the durability test before saving: will this still be true and useful in a future session that knows nothing about this branch, commit, or session? If not, skip it. Do not store point-in-time values (migration indices, line numbers, file counts), commit hashes or branch history narratives (git is the source of truth), or anything re-derivable from the codebase faster than recalling it.
+5. Write for a future session with zero current context. No "we", "our session", "just now".
+6. Your final message must be exactly: "Extraction complete." — do not list or summarize what you saved. The memories are in the store; the parent session does not need a report.
 
 ## What to extract
 

package/docs/dev/README.md

@@ -58,11 +58,11 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 | `setup.ts` | `thatch setup --claude` installer. Writes .mcp.json, appends to CLAUDE.md (idempotent), installs hooks in settings.json, installs skills. |
 | `hygiene.ts` | Hygiene report: pending dedup pairs, stale count, orphaned branch memories. Shared by the plugin's session-start hook and the CLI's `thatch reminder` command. |
 | `git.ts` | Parse `owner/repo` from git remote. Worktree-safe fallback chain. |
-| `db.ts` | SQLite schema, CRUD for entries/stores, brute-force cosine search (`search` = pure scoring, `recall` = search + telemetry stamping), dedup-pair verdict tracking. |
+| `db.ts` | SQLite schema, CRUD for entries/stores, brute-force cosine search (`search` = pure scoring, `recall` = search + telemetry stamping), dedup-pair verdict tracking. Prediction tables: matchers, predictions, edges, provenance. `scorePredictionNudge` is the shared auto-fire entry point for both host paths. |
 | `embeddings.ts` | Lazy-load the embedding model. Expose `queryEmbed`/`passageEmbed` and the model `name` (stored as an informational tag). `MockEmbeddingModel` for tests. |
 | `extraction.ts` | Per-session in-memory ring buffer (cap 20) that buffers non-thatch tool interactions and serializes them into the JSON payload the extraction nudge carries. The in-memory pipeline is opencode-only, but the payload builders (`buildExtractionPayload`, `deriveTitle`) are shared by both paths — `extract-queue.ts` imports `deriveTitle`, `bin/thatch` imports `buildExtractionPayload`. `summarizeArgs` is used internally by `buildExtractionPayload`. |
 | `extract-queue.ts` | File-backed per-session JSONL queue (caps 20, oldest dropped). Shared by the Claude Code and Cursor hook paths, which fire one-shot per event with no cross-call state. This is the MCP-side equivalent of `extraction.ts`. |
-| `sideband.ts` | Unix domain socket server + client. The MCP server (long-lived, warm model) runs `SidebandServer` so one-shot hook processes can ask it to embed a prompt and search for matches without loading the model themselves. Socket path is a hash of the DB path — both processes compute it independently. |
+| `sideband.ts` | Unix domain socket server + client. The MCP server (long-lived, warm model) runs `SidebandServer` so one-shot hook processes can ask it to embed a prompt and search for matches without loading the model themselves. Handles two methods: `match` (recall nudge) and `predictions` (prediction auto-fire). Socket path is a hash of the DB path — both processes compute it independently. |
 | `prompts.ts` | Text constants: opencode system prompt, compaction context, session-start reminder, prompt-aware recall nudge (`recallNudge` / `claudeRecallNudge`), Claude Code CLAUDE.md instructions, Cursor AGENTS.md instructions, Claude Code hook text. |
 | `skills.ts` | `SKILL.md` content for all thatch skills, plus the installer. Skills are split into `SHARED_SKILLS` (18 skills: fact-extractor, dedup-classifier, project-primer, 6 review specialists, review synthesizer, review context, workflow research, change walkthrough, code walkthrough, session reflection, pr-description, ticket-description, split-overlarge-pr — work on both opencode and Claude Code) and `OPENCODE_ONLY_SKILLS` (1 skill: code-review coordinator — requires sub-agent support, not installed for Claude Code). `installSkills(dir, skills)` defaults to `SHARED_SKILLS`; the opencode plugin passes `[...SHARED_SKILLS, ...OPENCODE_ONLY_SKILLS]`. |
 
@@ -74,9 +74,9 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 |------|-------------|
 | `experimental.chat.system.transform` | Appends the thatch system prompt (store names, usage rules). |
 | `experimental.session.compacting` | Marks the session as compacting and appends re-familiarization context so a compacted session still knows thatch exists. |
-| `experimental.compaction.autocontinue` | Clears the compacting flag so `chat.message` nudges resume. Without this, nudges that instruct tool calls would fire during summary generation where tools are blocked. |
+| `experimental.compaction.autocontinue` | Clears the compacting flag so `chat.message` nudges resume. Without this, nudges that instruct tool calls would fire during summary generation where tools are blocked. The `chat.message` hook also clears the flag if it fires for a session still in the compacting set but the incoming message has no compaction-type part — this handles compaction failure, where the session would otherwise be stuck with nudges off forever. |
 | `tool.execute.after` | Buffers every non-`thatch_*`, non-`skill`, non-`task` tool call into the session's extraction buffer. (Skill/task are excluded — buffering them creates a feedback loop where the nudge triggers a skill load, which gets buffered, which triggers another nudge.) Memory writes (`thatch_memory_remember`) and `thatch_extraction_done` drain the buffer and reset the missed-nudge counter. This is a plugin hook, NOT a bus event — do not move it into the `event` handler; the event bus has no such event and it will silently never fire. |
-| `chat.message` | Two priority tiers: (a) if extraction buffer has interactions, **peeks** the buffer (does NOT drain it) and injects a synthetic text part carrying the extraction nudge + JSON payload — the buffer persists until the agent writes a memory or calls `thatch_extraction_done`, so ignored nudges repeat and escalate (polite → insistent → ALL-CAPS) via the `missedNudges` counter; (b) otherwise, embeds the user's prompt text with the in-process warm model, searches `db.search()` across repo + global, and pushes a recall nudge if matches exceed the threshold (default 0.55). Skipped entirely while the session is compacting (tool calls are blocked during summary generation). |
+| `chat.message` | Two priority tiers: (a) if extraction buffer has interactions, **peeks** the buffer (does NOT drain it) and injects a synthetic text part carrying the extraction nudge + JSON payload — the buffer persists until the agent writes a memory or calls `thatch_extraction_done`, so ignored nudges repeat and escalate (polite → insistent → ALL-CAPS) via the `missedNudges` counter; (b) otherwise, embeds the user's prompt text with the in-process warm model, searches `db.search()` across repo + global, and pushes a recall nudge if matches exceed the threshold (default 0.55). The same embedding also feeds the prediction auto-fire: `db.scorePredictionNudge` scores the prompt against prediction matchers and injects a separate `[thatch] User decision model` nudge if any matchers clear the 0.45 threshold. Recall and prediction nudges fire independently (separate try/catch blocks, separate synthetic parts). Skipped entirely while the session is compacting (tool calls are blocked during summary generation). |
 | `event` (`session.created`) | Sends the session-start reminder via `client.session.prompt`, carrying the hygiene heartbeat (pending dedup pairs, stale count, orphaned branch memories) when any signal is non-zero. The session id is at `event.properties.info.id`. |
 | `dispose` | Closes the DB. |
 
@@ -121,6 +121,23 @@ Two of these hooks were dead for weeks because failures were invisible.
    case (agent forgot to save, next user turn arrives with buffer still
    pending). This is an experiment — model reliability on meta-instructions
    is uncertain.
+10. **Background completion narration is suppressed, not prevented.** When a
+    background sub-agent completes, opencode injects a `<task_result>` block
+    into the parent session and triggers a full model generation. Thatch
+    cannot cancel this turn (no pre-response hook). Two mitigations: the
+    fact-extractor skill's return value is constrained to the literal
+    "Extraction complete." so the injected block has no narratable content,
+    and the system prompt's "Background Task Completions" section instructs
+    the model not to narrate completions or treat them as approval to act.
+11. **Prediction engine is a statistical model, not an LLM call.** The query
+    (embed prompt, cosine-match against matchers, score linked predictions)
+    is mechanical — same shape as `thatch_memory_recall` but against different
+    tables. The agent drives formation and evaluation via tools
+    (`thatch_prediction_update` with confirm/disconfirm/soft/create signals)
+    guided by system prompt instructions. No wall-clock decay; confidence is
+    relevance-gated (being tested moves it, not being ignored). See the
+    prediction DB tables, auto-fire in `chat.message`, and the sideband
+    `predictions` method for the MCP path.
 
 ## Data flow
 
@@ -178,6 +195,33 @@ hygiene heartbeat (session start)
     longer exist (skipped when worktree isn't a git repo)
   → non-zero signals appended to the session-start reminder; the agent tends
     the store when convenient — the plugin never deletes memories itself
+
+prediction cycle (agent-driven, statistical model)
+  → formation: agent calls thatch_prediction_update(matcher, prediction, signal)
+    with signal = create|confirm|disconfirm|soft. The tool embeds the matcher
+    text (raw, no header prepend — unlike memory_remember), finds or creates
+    a matcher (0.85 dedup), finds or creates a prediction (0.85 store-wide
+    dedup), links them via an edge, and adjusts confidence via a Bayesian
+    posterior: (confirm + K*P0) / (confirm + disconfirm + K), K=5, P0=0.5.
+    Soft signals count as 0.25 of a full signal. No wall-clock decay;
+    confidence is relevance-gated (being tested moves it, not being ignored).
+  → auto-fire (opencode): chat.message reuses the prompt embedding already
+    computed for the recall nudge. db.scorePredictionNudge([repo, global],
+    embedding, 0.45) finds matchers above threshold, follows edges to
+    predictions, scores by cosine * weight * confidence, dedups by
+    prediction_id, and returns top 5. Injects a separate synthetic part
+    with a [thatch] User decision model block. 0-evidence predictions use
+    "you may prefer"; predictions with evidence use "you tend to".
+  → auto-fire (Claude Code/Cursor): flush-tools fires the prediction query
+    via the sideband socket's `predictions` method in parallel with the
+    recall nudge. Same scorePredictionNudge entry point prevents scoring
+    drift between host paths.
+  → consumption: agent follows strong predictions silently, surfaces
+    ambiguous/competing predictions to the user, and calls
+    thatch_prediction_update to reinforce or weaken after the user responds.
+    thatch_prediction_list inspects the model with provenance;
+    thatch_prediction_delete removes bad predictions (cascade clears edges
+    and provenance).
 ```
 
 ## Database
@@ -188,7 +232,11 @@ hygiene heartbeat (session start)
   `entries(slug, store, label, content, embedding BLOB, model, branch,
   confidence, archived, created_at, updated_at, recall_count,
   last_recalled_at, PK(slug, store))`,
-  `dedup_pairs(store, slug_a, slug_b, status, checked_at, PK(store, slug_a, slug_b))`.
+  `dedup_pairs(store, slug_a, slug_b, status, checked_at, PK(store, slug_a, slug_b))`,
+  `prediction_matchers(id PK, store, description, embedding BLOB, model, created_at, updated_at)`,
+  `predictions(id PK, store, statement, rationale, embedding BLOB, model, confidence REAL, confirm_count REAL, disconfirm_count REAL, created_at, updated_at)`,
+  `prediction_edges(matcher_id, prediction_id, weight REAL, PK(matcher_id, prediction_id), FK CASCADE)`,
+  `prediction_provenance(id PK, prediction_id, signal, detail, created_at, FK CASCADE)`.
 - `recall_count`, `last_recalled_at`, and `archived` are added to pre-existing
   databases by an idempotent column migration at init (`PRAGMA table_info` +
   `ALTER TABLE`). The `archived` column is `INTEGER NOT NULL DEFAULT 0` (0 =

package/docs/dev/mcp-parity.md

@@ -18,12 +18,13 @@ This document maps the feature parity and documents the remaining gaps.
 
 | Feature | OpenCode plugin | Claude Code MCP + hooks | Cursor MCP + hooks | Parity |
 |---------|----------------|------------------------|---------------------|--------|
-| **Tools** (9, single source of truth) | Plugin tool registration, `thatch_` prefix | MCP `tools/list` + `tools/call`, `mcp__thatch__` prefix | MCP `tools/list` + `tools/call`, `mcp__thatch__` prefix | **Full** |
+| **Tools** (13, single source of truth) | Plugin tool registration, `thatch_` prefix | MCP `tools/list` + `tools/call`, `mcp__thatch__` prefix | MCP `tools/list` + `tools/call`, `mcp__thatch__` prefix | **Full** |
 | **System prompt** (store names, usage rules) | `experimental.chat.system.transform` — dynamic, repo baked in at runtime | CLAUDE.md static text appended by `thatch setup`; repo auto-detected by the MCP server at startup | AGENTS.md static text appended by `thatch setup`; repo auto-detected at startup | **Approximate** — static text persists through compaction, so the agent retains the usage instructions, but the dynamic per-turn refresh is lost |
 | **Session-start reminder** (recall nudge + hygiene heartbeat) | `session.created` event → `client.session.prompt` injects a synthetic message | `SessionStart` hook → `thatch reminder`; stdout becomes context | `sessionStart` hook → `thatch reminder --json`; output is `additional_context` JSON | **Full** |
 | **Compaction context** (re-familiarize after compaction) | `experimental.session.compacting` hook appends context to the compaction output | `PostCompact` hook — side-effects only, **cannot inject context** | No equivalent hook | **Gapped** — see below |
 | **Extraction nudge** (buffer tool calls, inject JSON payload) | `tool.execute.after` buffers non-thatch, non-skill, non-task tool calls in-process; `chat.message` peeks the buffer (does not drain it) and injects a synthetic text part | `PostToolBatch` → `thatch buffer-batch` (file-backed JSONL queue); `UserPromptSubmit` → `thatch flush-tools` peeks the queue and prints the nudge (does not drain — the queue persists until a memory write or `extraction_done`) | `postToolUse` → `thatch buffer-tool` (single-tool, file-backed queue); `beforeSubmitPrompt` → `thatch flush-tools --json` | **Full** (file-backed) — timing differs: the nudge arrives at the **start** of the next turn in Claude Code/Cursor, not at the end of the current one like opencode's `chat.message` |
 | **Prompt-aware recall nudge** | `chat.message` hook embeds the prompt with the in-process warm model, searches `db.search()`, pushes a nudge part if matches ≥ threshold | `UserPromptSubmit` hook → `thatch flush-tools` connects to the MCP server's sideband socket; the warm server embeds + searches; hook prints the nudge or falls back to the write nudge | `beforeSubmitPrompt` hook → `thatch flush-tools --json` (same sideband path) | **Full** — sideband socket gives cold hook processes access to the warm MCP server's model |
+| **Prediction auto-fire** (user decision model) | `chat.message` hook scores the prompt embedding against prediction matchers; injects a `[thatch] User decision model` nudge alongside the recall nudge (separate synthetic part, same embedding call) | `UserPromptSubmit` hook → `thatch flush-tools` fires prediction query via the sideband socket's `predictions` method in parallel with the recall nudge | `beforeSubmitPrompt` hook → `thatch flush-tools --json` (same sideband path) | **Full** — same `scorePredictionNudge` entry point in both paths |
 | **Skills** | Installed to `$XDG_CONFIG_HOME/opencode/skills` at plugin init (shared **+** opencode-only) | Installed to `$CLAUDE_CONFIG_DIR/skills/` by `thatch setup` (shared only) | Installed to `~/.cursor/skills/` by `thatch setup` (shared only) | **Full** — same SKILL.md format; the code-review coordinator is opencode-only (needs sub-agents) |
 | **Store detection** (repo identity from git remote) | `worktree` parameter from the opencode plugin | `CLAUDE_PROJECT_DIR` env (set by Claude Code for stdio MCP servers) | `CURSOR_PROJECT_DIR` then `CLAUDE_PROJECT_DIR` then cwd | **Full** |
 | **Setup detection at startup** | n/a — plugin auto-installs at init | `checkSetup` in MCP server: detects missing or broken instructions in CLAUDE.md | Same as Claude Code (checks AGENTS.md) | **Full** — warns the agent to tell the user to run `thatch setup` |

package/docs/user/README.md

@@ -108,6 +108,15 @@ Stores are created automatically — no setup required.
 |------|-------------|
 | `thatch_extraction_done` | Acknowledge that the extraction nudge was dispatched to a sub-agent. Drains the buffer so the nudge does not replay. Called after dispatching a background task to run the fact-extractor skill. |
 
+### Prediction tools
+
+| Tool | What it does |
+|------|-------------|
+| `thatch_prediction_query` | Query the user decision model for scored predictions matching a context. Returns predictions with confidence and evidence count. |
+| `thatch_prediction_update` | Create, reinforce, or weaken a prediction. Takes a matcher (context description), a prediction (preference statement), and a signal (confirm/disconfirm/soft/create). |
+| `thatch_prediction_list` | List all predictions in a store with matchers, confidence, and provenance. |
+| `thatch_prediction_delete` | Delete a prediction by semantic match. Edges and provenance are cascade-deleted. |
+
 ## Automatic behaviors
 
 Beyond the tools, thatch hooks into opencode itself:
@@ -133,6 +142,12 @@ Beyond the tools, thatch hooks into opencode itself:
   thatch never saves memories on its own.
 - **Compaction context.** When opencode compacts a long session, thatch injects
   a reminder so the summarized session still knows memory tools exist.
+- **Prediction auto-fire.** When a prompt matches learned contexts, thatch
+  injects a `User decision model` block alongside the recall nudge. The block
+  lists scored predictions (confidence, evidence count) that the agent can
+  follow silently (strong prediction), surface to the user (ambiguous), or
+  use to update the model after the user responds. No extra model call —
+  the prediction search reuses the same prompt embedding as the recall nudge.
 
 ### Setup detection (Claude Code and Cursor)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.1.20",
+  "version": "0.1.21",
   "description": "Persistent memory for AI coding agents — local embeddings, SQLite stores, zero config. Works with OpenCode (as a plugin), Claude Code (as an MCP server), and Cursor (as an MCP server).",
   "type": "module",
   "main": "src/index.ts",

package/src/index.ts

@@ -51,9 +51,12 @@ export const server: Plugin = async ({ client, worktree }) => {
   // Sessions currently being compacted. chat.message nudges are skipped while
   // a session is in this set — the agent can't call tools during summary
   // generation, so a recall or extraction nudge would cause a blocked-tool
-  // error. Cleared by experimental.compaction.autocontinue. If compaction
-  // fails, the entry leaks (graceful degradation: nudges stay off for that
-  // session, but no crash).
+  // error. Cleared by experimental.compaction.autocontinue (success), the
+  // session.compacted event (redundant belt-and-suspenders), or chat.message
+  // itself when a non-compaction message arrives (compaction failure fallback
+  // — autocontinue never fired, so the next real user message clears the
+  // stale flag). If all three somehow miss, the flag leaks (graceful
+  // degradation: nudges stay off for that session, but no crash).
   const compacting = new Set<string>();
 
   // Per-session count of consecutive extraction nudges delivered without any
@@ -192,7 +195,18 @@ export const server: Plugin = async ({ client, worktree }) => {
     // a summary, so a nudge that says "use thatch_memory_recall" triggers a
     // blocked-tool error.
     "chat.message": async (input, output) => {
-      if (compacting.has(input.sessionID)) return;
+      if (compacting.has(input.sessionID)) {
+        // The session is marked as compacting. If this message is the
+        // compaction summary generation itself (has a compaction-type part),
+        // suppress nudges — tools are blocked during summary generation and a
+        // nudge would cause a blocked-tool error. If it is NOT a compaction
+        // message, compaction has already failed (autocontinue never fired)
+        // and the user is sending a new message. Clear the stale flag and
+        // proceed normally — tools are available again.
+        const isCompactionMsg = (output.parts as any[]).some((p) => p.type === "compaction");
+        if (isCompactionMsg) return;
+        compacting.delete(input.sessionID);
+      }
       if (extraction.pending(input.sessionID)) {
         const batch = extraction.peek(input.sessionID);
         const payload = extraction.buildPayload(batch, repo);
@@ -291,6 +305,15 @@ export const server: Plugin = async ({ client, worktree }) => {
         return;
       }
 
+      // session.compacted fires on successful compaction. Redundant with
+      // experimental.compaction.autocontinue, but belt-and-suspenders: if
+      // autocontinue didn't fire or wasn't installed, the event still clears
+      // the compacting flag so nudges resume.
+      if (event.type === "session.compacted") {
+        compacting.delete(event.properties.sessionID);
+        return;
+      }
+
       if (event.type !== "session.created") return;
       const id = event.properties.info.id;
 

package/src/prompts.ts

@@ -54,7 +54,9 @@ workflows. The host auto-discovers them, but reach for them proactively:
 
 **One signal is enough.** Do not wait for confirmation.
 Save immediately on: feedback, preferences, corrections, emotional signals,
-new project knowledge, conventions, architectural decisions, investigation results.
+new project knowledge, conventions, architectural decisions, investigation
+results that produced durable knowledge (not point-in-time facts about the
+current state of the code).
 
 ## Before Responding
 
@@ -64,6 +66,16 @@ whether you've discovered knowledge worth persisting. Use thatch_memory_recall
 to check for duplicates, then thatch_memory_remember for new findings. Then
 deliver your response.
 
+## Background Task Completions
+
+When a background task completes and its result is injected into the session,
+the completion is informational — it is not user input and not approval to
+proceed with anything you were discussing. Do not narrate what the task did or
+summarize its output. If you were mid-conversation with the user, continue
+that thread. If the user's last message has been fully addressed, stop and
+wait. Do not treat the completion as a trigger to advance work the user has
+not greenlit.
+
 ## User Decision Model
 
 A statistical model of the user's decision-making preferences is maintained by
@@ -100,8 +112,9 @@ reinforce or adjust it when possible.
   component relationships, conventions, operational playbooks
 - **Branch-scoped**: branch purpose, feature design decisions, PR status,
   temporary workarounds
-- **Insights**: ALWAYS save non-obvious gotchas, patterns, and architectural
-  lessons discovered during implementation. Never prompt the user; just do it.
+- **Insights**: Save non-obvious gotchas, patterns, and architectural
+  lessons discovered during implementation, but only if they remain true
+  across sessions. Never prompt the user; just do it.
 
 ## How to Write
 
@@ -116,6 +129,16 @@ reinforce or adjust it when possible.
 Session-specific context, incomplete/unverified info, anything already in
 CLAUDE.md or OPENCODE.md, speculative conclusions.
 
+Apply the durability test: will this still be true and useful in a future
+session that knows nothing about this branch, commit, or session? If not,
+do not save it. Do not store:
+- Point-in-time values (migration indices, line numbers, file counts) that
+  will be stale by next session
+- Commit hashes and branch-specific history narratives. Git is the source
+  of truth for this; do not duplicate it in memory
+- Anything re-derivable from the codebase faster than recalling it (current
+  file locations, type signatures, function names)
+
 ## Archived Memories
 
 Memories can be marked \`archived\` — a flag for stable, long-term historical
@@ -228,7 +251,9 @@ workflows. The host auto-discovers them, but reach for them proactively:
 
 **One signal is enough.** Do not wait for confirmation.
 Save immediately on: feedback, preferences, corrections, emotional signals,
-new project knowledge, conventions, architectural decisions, investigation results.
+new project knowledge, conventions, architectural decisions, investigation
+results that produced durable knowledge (not point-in-time facts about the
+current state of the code).
 
 ## Before Responding
 
@@ -274,8 +299,9 @@ reinforce or adjust it when possible.
   component relationships, conventions, operational playbooks
 - **Branch-scoped**: branch purpose, feature design decisions, PR status,
   temporary workarounds
-- **Insights**: ALWAYS save non-obvious gotchas, patterns, and architectural
-  lessons discovered during implementation. Never prompt the user; just do it.
+- **Insights**: Save non-obvious gotchas, patterns, and architectural
+  lessons discovered during implementation, but only if they remain true
+  across sessions. Never prompt the user; just do it.
 
 ## How to Write
 
@@ -290,6 +316,16 @@ reinforce or adjust it when possible.
 Session-specific context, incomplete/unverified info, anything already in
 CLAUDE.md, speculative conclusions.
 
+Apply the durability test: will this still be true and useful in a future
+session that knows nothing about this branch, commit, or session? If not,
+do not save it. Do not store:
+- Point-in-time values (migration indices, line numbers, file counts) that
+  will be stale by next session
+- Commit hashes and branch-specific history narratives. Git is the source
+  of truth for this; do not duplicate it in memory
+- Anything re-derivable from the codebase faster than recalling it (current
+  file locations, type signatures, function names)
+
 ## Archived Memories
 
 Memories can be marked \`archived\` — a flag for stable, long-term historical
@@ -464,7 +500,9 @@ workflows. The host auto-discovers them, but reach for them proactively:
 
 **One signal is enough.** Do not wait for confirmation.
 Save immediately on: feedback, preferences, corrections, emotional signals,
-new project knowledge, conventions, architectural decisions, investigation results.
+new project knowledge, conventions, architectural decisions, investigation
+results that produced durable knowledge (not point-in-time facts about the
+current state of the code).
 
 ## Before Responding
 
@@ -510,8 +548,9 @@ reinforce or adjust it when possible.
   component relationships, conventions, operational playbooks
 - **Branch-scoped**: branch purpose, feature design decisions, PR status,
   temporary workarounds
-- **Insights**: ALWAYS save non-obvious gotchas, patterns, and architectural
-  lessons discovered during implementation. Never prompt the user; just do it.
+- **Insights**: Save non-obvious gotchas, patterns, and architectural
+  lessons discovered during implementation, but only if they remain true
+  across sessions. Never prompt the user; just do it.
 
 ## How to Write
 
@@ -526,6 +565,16 @@ reinforce or adjust it when possible.
 Session-specific context, incomplete/unverified info, anything already in
 AGENTS.md, speculative conclusions.
 
+Apply the durability test: will this still be true and useful in a future
+session that knows nothing about this branch, commit, or session? If not,
+do not save it. Do not store:
+- Point-in-time values (migration indices, line numbers, file counts) that
+  will be stale by next session
+- Commit hashes and branch-specific history narratives. Git is the source
+  of truth for this; do not duplicate it in memory
+- Anything re-derivable from the codebase faster than recalling it (current
+  file locations, type signatures, function names)
+
 ## Archived Memories
 
 Memories can be marked \`archived\` — a flag for stable, long-term historical