@jeffober/thatch 0.1.27 → 0.1.28

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

@@ -5,7 +5,7 @@ description: Extract durable project facts, user preferences, and environment kn
 
 You are the Thatch Fact Extractor. Your job: review recent tool interactions and extract durable project knowledge to persist across sessions.
 
-You will be given a JSON payload with:
+The extraction nudge or dispatch prompt will give you a session ID. Call `get_extraction_payload` (or `thatch_get_extraction_payload` / `mcp__thatch__get_extraction_payload` depending on host) with that session ID to retrieve a JSON payload containing:
   - "interactions": recent tool calls and their results (tool name, args, truncated output)
   - "projectStore": the current project's store name (e.g., "sysread/thatch")
   - "globalStore": "global"
@@ -17,7 +17,7 @@ You will be given a JSON payload with:
 3. Do not save session-specific state, ephemeral debugging details, or info already in CLAUDE.md.
 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. Call thatch_extraction_done to mark the run complete. Do this even when nothing was worth saving: the parent session holds the buffered interactions until a completion signal arrives, and a memory write is not one on a no-save run.
+6. Call `extraction_done` (with `session_id` set to the parent session's ID from the nudge) to mark the run complete. Do this even when nothing was worth saving: the parent session holds the buffered interactions until a completion signal arrives, and a memory write is not one on a no-save run.
 7. 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/bin/thatch

@@ -351,7 +351,6 @@ switch (command) {
       const sessionID = data.session_id ?? data.conversation_id;
 
       const { peekQueue, getMissedCount, incrementMissedCount } = await import("../src/extract-queue");
-      const { buildExtractionPayload } = await import("../src/extraction");
       const { extractionNudge, claudeWriteNudge, claudeRecallNudge, predictionNudge } = await import("../src/prompts");
 
       let repo = "unknown";
@@ -360,11 +359,13 @@ switch (command) {
       // Tier 1: extraction nudge. Peek (don't drain) - the queue persists
       // until the agent calls memory_remember, which triggers consumeQueue.
       // If the agent ignores the nudge, the payload grows on the next flush.
+      // The nudge carries the session ID, not the full payload — the
+      // sub-agent fetches it via get_extraction_payload.
       const interactions = sessionID ? peekQueue(sessionID) : [];
       if (interactions.length > 0) {
         const missed = sessionID ? getMissedCount(sessionID) : 0;
         if (sessionID) incrementMissedCount(sessionID);
-        const output = extractionNudge(interactions.length, missed, "mcp__thatch__memory_remember", buildExtractionPayload(interactions, repo));
+        const output = extractionNudge(interactions.length, missed, "mcp__thatch__memory_remember", sessionID ?? "");
         if (isJson) console.log(JSON.stringify({ additional_context: output }));
         else console.log(output);
         break;

package/docs/dev/README.md

@@ -60,7 +60,7 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 | `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. 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`. |
+| `extraction.ts` | Per-session in-memory ring buffer (cap 20) that buffers non-thatch tool interactions and serializes them into the JSON payload the `get_extraction_payload` tool returns. The in-memory pipeline is opencode-only, but the payload builders (`buildExtractionPayload`, `deriveTitle`) are shared by both paths — `extract-queue.ts` imports `deriveTitle`, `mcp.ts` imports `buildExtractionPayload` for the extraction payload provider. `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. 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. |
@@ -76,7 +76,7 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 | `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. 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. For child sessions (`childToParent.has(sessionID)`), also tracks metrics: `remember` with `overwrite:false` → new++, `overwrite:true` → updated++, `forget` → deleted++. 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 and the session is NOT in the `extracting` set (direct extraction in progress), **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). |
+| `chat.message` | Two priority tiers: (a) if extraction buffer has interactions and the session is NOT in the `extracting` set (direct extraction in progress), **peeks** the buffer (does NOT drain it) and injects a synthetic text part carrying the extraction nudge with the session ID and fetch tool name (not the full payload) — the sub-agent calls `thatch_get_extraction_payload` to retrieve the interactions as a tool response, keeping the full payload out of the main session's context window. 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` | Subscribes to all session bus events. `session.created`: records `childToParent` + `parentSnapshots` (shallow copy of the parent's buffer for snapshot-aware drain), then 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. `session.status` (idle): if the session is a child, drains its snapshot, fires a toast with `childMetrics`, and deletes the child session; if the session is a parent with pending tool interactions and not already extracting, calls `triggerExtraction` to create a direct-extraction child. `session.error`: requeues the parent's buffer (child died without draining). `session.deleted`: cleans up `childToParent`, `parentSnapshots`, `childMetrics`, and `extracting`. `session.compacted`: clears the compacting flag so `chat.message` nudges resume. |
 | `dispose` | Closes the DB. |
 
@@ -186,12 +186,13 @@ extraction cycle
   → nudge path (fallback): if triggerExtraction throws (create or prompt
     fails), the `extracting` set clears and the next chat.message sees
     pending entries with no extracting flag → peeks the buffer and injects
-    a nudge part with JSON payload; missed nudges escalate (polite →
+    a nudge part with session ID and fetch tool name; missed nudges escalate (polite →
     insistent → ALL-CAPS) via the missedNudges counter
     → drain: thatch_memory_remember (or thatch_extraction_done) clears the
       buffer and resets the missed-nudge counter
-    → agent loads thatch-fact-extractor skill, saves facts via
-      thatch_memory_remember
+    → agent dispatches a sub-agent that calls thatch_get_extraction_payload
+      to fetch the queued interactions, loads thatch-fact-extractor skill,
+      saves facts via thatch_memory_remember
   → MCP path (Claude Code/Cursor): unchanged — no SDK client, no child
     sessions; extract-queue.ts + flush-tools drives the nudge via hooks
 

package/docs/dev/mcp-parity.md

@@ -22,7 +22,7 @@ This document maps the feature parity and documents the remaining gaps.
 | **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** (buffer tool calls, extract durable facts) | `tool.execute.after` buffers non-thatch, non-skill, non-task tool calls in-process; **direct extraction** is the primary path — when the parent session goes idle with pending buffer entries, the plugin creates a child session via the SDK (`client.session.create` with `parentID`) and prompts it with the extraction payload (nudge suppressed via the `extracting` set); the `chat.message` nudge path is a **fallback** used when direct extraction throws | `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` | **Partial** — opencode uses direct extraction (parent idle → child session) as the primary path, with the nudge as fallback; MCP hosts are nudge-only. Both paths produce the same JSON shape via `buildExtractionPayload()`. Nudge timing differs: the nudge arrives at the **start** of the next turn in Claude Code/Cursor; opencode's direct extraction fires at **end of turn** (session idle), and the nudge fallback fires at the start of the next turn like MCP |
+| **Extraction** (buffer tool calls, extract durable facts) | `tool.execute.after` buffers non-thatch, non-skill, non-task tool calls in-process; **direct extraction** is the primary path — when the parent session goes idle with pending buffer entries, the plugin creates a child session via the SDK (`client.session.create` with `parentID`) and prompts it to call `get_extraction_payload` (nudge suppressed via the `extracting` set); the `chat.message` nudge path is a **fallback** used when direct extraction throws | `PostToolBatch` → `thatch buffer-batch` (file-backed JSONL queue); `UserPromptSubmit` → `thatch flush-tools` peeks the queue and prints the nudge with session ID + fetch tool name (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` | **Partial** — opencode uses direct extraction (parent idle → child session) as the primary path, with the nudge as fallback; MCP hosts are nudge-only. Both paths use `get_extraction_payload` to fetch the queued interactions as a tool response, keeping the full payload out of the main session's context window. Nudge timing differs: the nudge arrives at the **start** of the next turn in Claude Code/Cursor; opencode's direct extraction fires at **end of turn** (session idle), and the nudge fallback fires at the start of the next turn like MCP |
 | **Extraction feedback** (toast notifications) | `client.tui.showToast` fires when the extraction child goes idle — shows `[thatch] new: N, updated: M, deleted: K` (success) or `extraction complete — nothing to save` (info); best-effort, silently ignored in headless mode | No TUI connection — MCP hosts have no equivalent | No TUI connection | **Gapped** — MCP hosts cannot show toast notifications |
 | **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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.1.27",
+  "version": "0.1.28",
   "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

@@ -141,8 +141,7 @@ export const server: Plugin = async ({ client, worktree }) => {
     extracting.add(parentID);
 
     const batch = extraction.peek(parentID);
-    const payload = extraction.buildPayload(batch, repo);
-    const promptText = extractionDirectPrompt(batch.length, payload);
+    const promptText = extractionDirectPrompt(batch.length, parentID);
 
     const result = await client.session.create({
       body: { parentID, title: "thatch-extraction" },
@@ -201,7 +200,15 @@ export const server: Plugin = async ({ client, worktree }) => {
   }
 
   return {
-    tool: createTools(db, model, repo),
+    tool: createTools(db, model, repo, {
+      extractionPayloadProvider: (sessionID: string): string | null => {
+        const interactions = extraction.peek(sessionID);
+        const accepted = extraction.peekAccepted(sessionID);
+        const all = [...accepted, ...interactions];
+        if (all.length === 0) return null;
+        return extraction.buildPayload(all, repo);
+      },
+    }),
 
     // 1. System prompt - always in context.
     "experimental.chat.system.transform": async (_input, output) => {
@@ -352,9 +359,8 @@ export const server: Plugin = async ({ client, worktree }) => {
       // here only when direct extraction was never triggered or threw.
       if (!extracting.has(input.sessionID) && extraction.pending(input.sessionID)) {
         const batch = extraction.peek(input.sessionID);
-        const payload = extraction.buildPayload(batch, repo);
         const missed = missedNudges.get(input.sessionID) ?? 0;
-        const text = extractionNudge(batch.length, missed, "thatch_memory_remember", payload);
+        const text = extractionNudge(batch.length, missed, "thatch_memory_remember", input.sessionID);
         missedNudges.set(input.sessionID, missed + 1);
 
         output.parts.push({

package/src/mcp.ts

@@ -5,6 +5,8 @@ import { detectRepo } from "./git";
 import { checkSetup } from "./setup";
 import { TOOL_DEFS, type CoreContext, type ToolDef } from "./tool-defs";
 import { SidebandServer, sidebandSocketPath } from "./sideband";
+import { peekQueue, consumeQueue, resetMissedCount } from "./extract-queue";
+import { buildExtractionPayload } from "./extraction";
 import pkg from "../package.json";
 
 // ---------------------------------------------------------------------------
@@ -98,7 +100,33 @@ export async function runMcpServer(): Promise<void> {
 
   const db = new ThatchDB(dbPath);
   const model = new BgeEmbeddingModel(modelName);
-  const ctx: CoreContext = { db, model, defaultStore: repo };
+
+  // Extraction payload provider: peeks the file-backed queue and returns the
+  // serialized JSON payload. Called by the get_extraction_payload tool when a
+  // sub-agent needs to fetch the parent's queued interactions. Returns null
+  // when no interactions are queued.
+  const extractionPayloadProvider = (sessionID: string): string | null => {
+    const interactions = peekQueue(sessionID);
+    if (interactions.length === 0) return null;
+    return buildExtractionPayload(interactions, repo);
+  };
+
+  // Drain a session's file-backed queue and reset its missed-nudge counter.
+  // Called by extraction_done when a sub-agent passes the parent's session_id.
+  // Without this, the MCP path's appendBatch self-detection would drain the
+  // sub-agent's (empty) queue instead of the parent's.
+  const drainExtractionQueue = (sessionID: string): void => {
+    resetMissedCount(sessionID);
+    consumeQueue(sessionID);
+  };
+
+  const ctx: CoreContext = {
+    db,
+    model,
+    defaultStore: repo,
+    extractionPayloadProvider,
+    drainExtractionQueue,
+  };
   const tools = compileTools();
 
   // Check whether `thatch setup` was run for the current host. If not, or if

package/src/prompts.ts

@@ -9,7 +9,7 @@ knowledge so future sessions can build on what you've already learned.
 Tools: thatch_memory_remember, thatch_memory_recall, thatch_memory_list,
        thatch_memory_show, thatch_memory_forget, thatch_store_list,
        thatch_find_duplicates, thatch_dedup_mark_checked,
-       thatch_extraction_done,
+       thatch_extraction_done, thatch_get_extraction_payload,
        thatch_prediction_query, thatch_prediction_update, thatch_prediction_list,
        thatch_prediction_delete
 
@@ -214,6 +214,7 @@ Tools are prefixed in Claude Code: \`mcp__thatch__memory_remember\`,
 \`mcp__thatch__memory_show\`, \`mcp__thatch__memory_forget\`,
 \`mcp__thatch__store_list\`, \`mcp__thatch__find_duplicates\`,
 \`mcp__thatch__dedup_mark_checked\`, \`mcp__thatch__extraction_done\`,
+\`mcp__thatch__get_extraction_payload\`,
 \`mcp__thatch__prediction_query\`, \`mcp__thatch__prediction_update\`,
 \`mcp__thatch__prediction_list\`, \`mcp__thatch__prediction_delete\`. Bare names used below for readability.
 
@@ -395,12 +396,17 @@ export function claudeWriteNudge(): string {
  * their respective tool name prefix. The missedCount parameter tracks
  * consecutive nudges delivered without any memory_remember call in between,
  * escalating the tone from polite to insistent to shouting.
+ *
+ * The sessionID replaces the inline payload: the nudge tells the model to
+ * dispatch a sub-agent that calls get_extraction_payload to fetch the queued
+ * interactions as a tool response. This keeps the full payload out of the
+ * main session's context window.
  */
 export function extractionNudge(
   count: number,
   missedCount: number,
   toolName: string,
-  payload: string,
+  sessionID: string,
 ): string {
   const plural = count === 1 ? "" : "s";
   // opencode's task tool has a `background` parameter (requires
@@ -415,47 +421,48 @@ export function extractionNudge(
     ? "Dispatch a task with background: true"
     : "Spawn a background sub-agent";
   const drainTool = isOpencode ? "thatch_extraction_done" : "mcp__thatch__extraction_done";
+  const fetchTool = isOpencode
+    ? "thatch_get_extraction_payload"
+    : "mcp__thatch__get_extraction_payload";
   const acknowledge = `After dispatching, call ${drainTool} to acknowledge.`;
+  const subAgentPrompt = `Call ${fetchTool} with session_id "${sessionID}" to retrieve the queued tool interactions, then run the thatch-fact-extractor skill to extract durable facts. Call ${drainTool} with session_id "${sessionID}" when finished, even if nothing was worth saving.`;
 
   if (missedCount >= 3) {
     return `[thatch] YOU ARE IGNORING EXTRACTION INSTRUCTIONS. ` +
       `${count} TOOL INTERACTION${plural.toUpperCase()} ARE QUEUED AND YOU HAVE NOT PROCESSED ANY OF THEM. ` +
       `THE USER INSTALLED THIS PLUGIN FOR A REASON. ` +
-      `${dispatch.toUpperCase()} NOW TO RUN THE thatch-fact-extractor SKILL. ` +
-      `${acknowledge.toUpperCase()} ` +
-      `USE ${toolName.toUpperCase()} TO SAVE DURABLE FACTS FROM THIS PAYLOAD:\n${payload}`;
+      `${dispatch.toUpperCase()} NOW WITH THIS PROMPT: "${subAgentPrompt.toUpperCase()}" ` +
+      `${acknowledge.toUpperCase()}`;
   }
   if (missedCount >= 2) {
     return `[thatch] YOU HAVE NOT PROCESSED YOUR PREVIOUS EXTRACTION PAYLOAD${plural.toUpperCase()}. ` +
       `${count} more tool interaction${plural} are now queued. ` +
-      `${dispatch} to run the thatch-fact-extractor skill on this payload. ` +
-      `${acknowledge} ` +
-      `Use ${toolName} to save durable facts from this payload:\n${payload}`;
+      `${dispatch} with this prompt: "${subAgentPrompt}" ` +
+      `${acknowledge}`;
   }
   return `[thatch] ${dispatch} to run the thatch-fact-extractor skill ` +
     `on ${count} queued tool interaction${plural}. ` +
+    `Sub-agent prompt: "${subAgentPrompt}" ` +
     `${acknowledge} ` +
     `This is a system nudge, not user input. After dispatching and acknowledging, ` +
     `stop: do not advance pending work on this nudge's account. If you are ` +
-    `waiting for the user to respond, continue waiting. ` +
-    `Use ${toolName} to save durable facts from this payload:\n${payload}`;
+    `waiting for the user to respond, continue waiting.`;
 }
 
 /**
  * Prompt text sent directly to a child session the plugin created for
  * extraction. Unlike extractionNudge (which tells the model to dispatch a
  * sub-agent and call extraction_done), this prompt is already inside the
- * child - the model just runs the fact-extractor skill and saves facts.
- * The payload format is identical to the nudge path so the skill receives
- * the same contract either way.
+ * child - the model calls get_extraction_payload to fetch the queued
+ * interactions, runs the fact-extractor skill, and saves facts.
  */
-export function extractionDirectPrompt(count: number, payload: string): string {
+export function extractionDirectPrompt(count: number, sessionID: string): string {
   const plural = count === 1 ? "" : "s";
   return `Run the thatch-fact-extractor skill to extract durable facts from ` +
     `${count} queued tool interaction${plural}. ` +
+    `Call thatch_get_extraction_payload with session_id "${sessionID}" to retrieve the interactions. ` +
     `Use thatch_memory_remember to save any durable facts you find. ` +
-    `Call thatch_extraction_done when finished, even if nothing was worth saving.\n` +
-    `Payload:\n${payload}`;
+    `Call thatch_extraction_done with session_id "${sessionID}" when finished, even if nothing was worth saving.`;
 }
 
 /**
@@ -463,8 +470,8 @@ export function extractionDirectPrompt(count: number, payload: string): string {
  * Maintained for any external callers; bin/thatch should use extractionNudge
  * directly with a missedCount from extract-queue.ts.
  */
-export function claudeExtractionNudge(count: number, payload: string): string {
-  return extractionNudge(count, 0, "mcp__thatch__memory_remember", payload);
+export function claudeExtractionNudge(count: number, sessionID: string): string {
+  return extractionNudge(count, 0, "mcp__thatch__memory_remember", sessionID);
 }
 
 /**
@@ -484,6 +491,7 @@ Tools are prefixed in Cursor: \`mcp__thatch__memory_remember\`,
 \`mcp__thatch__memory_show\`, \`mcp__thatch__memory_forget\`,
 \`mcp__thatch__store_list\`, \`mcp__thatch__find_duplicates\`,
 \`mcp__thatch__dedup_mark_checked\`, \`mcp__thatch__extraction_done\`,
+\`mcp__thatch__get_extraction_payload\`,
 \`mcp__thatch__prediction_query\`, \`mcp__thatch__prediction_update\`,
 \`mcp__thatch__prediction_list\`, \`mcp__thatch__prediction_delete\`. Bare names used below for readability.
 

package/src/tool-defs.ts

@@ -22,6 +22,18 @@ export interface CoreContext {
   db: ThatchDB;
   model: EmbeddingModel;
   defaultStore: string;
+  /** Peeks the extraction buffer for a session and returns the serialized
+   *  JSON payload (same shape as buildExtractionPayload). Returns null when
+   *  no interactions are queued. Used by the get_extraction_payload tool so
+   *  the sub-agent fetches the payload as a tool response instead of
+   *  receiving it inline in the nudge text. */
+  extractionPayloadProvider?: (sessionID: string) => string | null;
+  /** Drains a session's extraction queue. On the MCP path this deletes the
+   *  file-backed queue and resets the missed-nudge counter. On the opencode
+   *  path this is unused (the tool.execute.after hook handles drain via
+   *  childToParent). Called by extraction_done when the sub-agent passes
+   *  the parent's session_id. */
+  drainExtractionQueue?: (sessionID: string) => void;
 }
 
 /**
@@ -370,6 +382,61 @@ const markCheckedDef: ToolDef = {
  * which is durable across interruption because the queue persists on disk
  * until then.
  */
+/**
+ * Fetches the queued extraction payload for a session. The sub-agent calls
+ * this with the parent's session ID to retrieve the tool interactions that
+ * need fact extraction, instead of receiving them inline in the nudge text.
+ * This keeps the full payload out of the main session's context window.
+ */
+const getExtractionPayloadDef: ToolDef = {
+  name: "get_extraction_payload",
+  description:
+    "Retrieve the queued tool interactions for extraction. Call this with " +
+    "the session_id from the extraction nudge to get the JSON payload " +
+    "(interactions, projectStore, globalStore). Then run the " +
+    "thatch-fact-extractor skill on the returned payload.",
+  args: {
+    session_id: z.string().describe(
+      "The session ID from the extraction nudge. This is the parent session " +
+      "whose tool interactions are queued for extraction.",
+    ),
+  },
+  async execute(args, ctx) {
+    if (!ctx.extractionPayloadProvider) {
+      return "Extraction payload retrieval is not available in this host.";
+    }
+    const payload = ctx.extractionPayloadProvider(args.session_id as string);
+    if (!payload) {
+      return "No queued tool interactions found for this session.";
+    }
+    return payload;
+  },
+};
+
+/**
+ * Extraction-buffer acknowledgment, with AMQP-style accept/complete roles.
+ *
+ * Called in a PARENT session after dispatching the fact-extractor, it accepts
+ * the buffer: entries move to a holding area and the nudge quiets, but they
+ * are not dropped until the extractor completes. Called in a CHILD extractor
+ * at the end of its run, it completes the parent's accepted entries -
+ * including no-save runs that write no memory. If the child errors or is
+ * deleted before either signal, the host requeues the entries so the facts
+ * are not lost.
+ *
+ * The actual state changes happen in the host's post-tool hook
+ * (tool.execute.after for opencode, PostToolBatch/appendBatch for MCP) -
+ * this tool's execute function is a no-op confirmation. The tool exists so
+ * the model has a recognizable tool name to key on. In the MCP path the
+ * file-backed queue is consumed on this call (or on any memory_remember),
+ * which is durable across interruption because the queue persists on disk
+ * until then.
+ *
+ * The optional session_id parameter lets a sub-agent drain the PARENT's
+ * file-backed queue on the MCP path, where the sub-agent's session ID
+ * differs from the parent's and appendBatch's self-detection would drain
+ * the wrong (empty) queue.
+ */
 const extractionDoneDef: ToolDef = {
   name: "extraction_done",
   description:
@@ -377,9 +444,20 @@ const extractionDoneDef: ToolDef = {
     "dispatching the fact-extractor to a sub-agent: accepts the buffer " +
     "(quiets the nudge) while keeping entries until the extractor completes. " +
     "In the fact-extractor sub-agent, call at the end of the run to mark the " +
-    "entries complete, even when nothing was worth saving.",
-  args: {},
-  async execute() {
+    "entries complete, even when nothing was worth saving. Pass session_id " +
+    "when running as a sub-agent to drain the parent session's queue.",
+  args: {
+    session_id: z.string().optional().describe(
+      "The parent session's ID, when called from a sub-agent on the MCP " +
+      "path. Drains the parent's file-backed queue. Omit when called from " +
+      "the parent session itself (opencode path handles drain via hooks).",
+    ),
+  },
+  async execute(args, ctx) {
+    const sessionID = args.session_id as string | undefined;
+    if (sessionID && ctx.drainExtractionQueue) {
+      ctx.drainExtractionQueue(sessionID);
+    }
     return "[acknowledged]";
   },
 };
@@ -587,6 +665,7 @@ export const TOOL_DEFS: ToolDef[] = [
   findDuplicatesDef,
   markCheckedDef,
   extractionDoneDef,
+  getExtractionPayloadDef,
   predictionQueryDef,
   predictionUpdateDef,
   predictionListDef,

package/src/tools.ts

@@ -13,8 +13,18 @@ export function createTools(
   db: ThatchDB,
   model: EmbeddingModel,
   defaultStore: string,
+  extensions?: {
+    extractionPayloadProvider?: CoreContext["extractionPayloadProvider"];
+    drainExtractionQueue?: CoreContext["drainExtractionQueue"];
+  },
 ): Record<string, ReturnType<typeof tool>> {
-  const ctx: CoreContext = { db, model, defaultStore };
+  const ctx: CoreContext = {
+    db,
+    model,
+    defaultStore,
+    extractionPayloadProvider: extensions?.extractionPayloadProvider,
+    drainExtractionQueue: extensions?.drainExtractionQueue,
+  };
 
   const tools: Record<string, ReturnType<typeof tool>> = {};
   for (const def of TOOL_DEFS) {