@jeffober/thatch 0.1.12 → 0.1.14

package/docs/dev/skills.md

@@ -1,7 +1,7 @@
 # Skills
 
 Thatch installs SKILL.md files that give the agent task-specific workflows. All
-skill content is defined in `src/skills.ts` and installed to a host-specific
+skill content lives in `artifacts/skills/*.md` and is loaded by `src/skills.ts` and installed to a host-specific
 directory. See `mcp-parity.md` for which skills each host gets.
 
 ## Skill file format
@@ -102,13 +102,10 @@ and `--cursor` pass only the shared set.
 
 ## Adding a skill
 
-1. Write the `SKILL.md` content as a template literal in `src/skills.ts`.
-   Interpolate `${REVIEW_COMMON}` if it's a review specialist.
-2. Add a `{ name, content }` entry to `SHARED_SKILLS` (or `OPENCODE_ONLY_SKILLS`
-   if it needs sub-agents).
-3. If the skill name appears in a tool's expected workflow (e.g. the extraction
-   nudge references `thatch-fact-extractor`), update that prompt in `src/prompts.ts`.
-4. The opencode plugin and `thatch setup` pick it up automatically on next init.
+1. Write `artifacts/skills/thatch-<name>.md` with YAML frontmatter. If it's a review specialist, include `${REVIEW_COMMON}` (interpolated from `artifacts/skills/common.md`).
+2. Add the skill name to the `names` array in `loadSharedSkills()` (or `loadOpencodeOnlySkills()` if sub-agents are needed). The loader in `src/skills.ts` reads `.md` files at init.
+3. If the skill name appears in a tool's workflow (e.g. `thatch-fact-extractor`), update `src/prompts.ts`.
+4. Run `mise run check` — tests verify counts; `installSkills` picks up new files on next init.
 
 ## Memory review skills in practice
 

package/docs/user/README.md

@@ -20,6 +20,17 @@ Publish to npm and add thatch to your opencode config:
 
 OpenCode installs the plugin and its dependencies automatically on next start.
 
+Set this environment variable so the extraction nudge can dispatch the
+fact-extractor as a **background** sub-agent instead of blocking your turn:
+
+```bash
+export OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true
+```
+
+Without it, opencode hides the task tool's `background` parameter and the
+extraction nudge runs synchronously. Put it in your shell rc, `mise.toml`
+`[env]`, or `.envrc`.
+
 For local development before publishing, use a file path:
 
 ```jsonc

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "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",
@@ -15,7 +15,8 @@
   "files": [
     "src",
     "docs",
-    "bin"
+    "bin",
+    "artifacts"
   ],
   "scripts": {
     "test": "bun test",

package/src/extract-queue.ts

@@ -37,11 +37,16 @@ function queuePath(sessionID: string): string {
 }
 
 /**
- * Buffer a batch of tool calls for later extraction. Filters out thatch's own
- * MCP tools (mcp__thatch__*) to avoid self-echo — extracting facts from memory
- * operations would just write the store back into the store. Each surviving
- * call is mapped to a ToolInteraction (title synthesized since Claude Code
- * doesn't supply one) and appended as one JSON line.
+ * Buffer a batch of tool calls for later extraction. Filters out:
+ * - thatch's own MCP tools (mcp__thatch__*) to avoid self-echo — extracting
+ *   facts from memory operations would just write the store back into itself.
+ * - skill/task/agent meta-tools — these orchestrate agent behavior (loading
+ *   skills, dispatching sub-agents) and buffering them creates a feedback
+ *   loop where the extraction nudge triggers a skill load, which gets
+ *   buffered, which triggers another nudge on the next turn.
+ * Memory writes reset the missed-nudge escalation counter.
+ * Each surviving call is mapped to a ToolInteraction (title synthesized since
+ * Claude Code doesn't supply one) and appended as one JSON line.
  */
 export function appendBatch(sessionID: string, toolCalls: BatchToolCall[]): void {
   const dir = queueDir();
@@ -50,7 +55,14 @@ export function appendBatch(sessionID: string, toolCalls: BatchToolCall[]): void
   const existing = readQueueFile(path);
   const additions: ToolInteraction[] = [];
   for (const tc of toolCalls) {
-    if (tc.tool_name.startsWith("mcp__thatch__")) continue;
+    const lower = tc.tool_name.toLowerCase();
+    if (lower === "mcp__thatch__memory_remember" || lower === "mcp__thatch__extraction_done") {
+      resetMissedCount(sessionID);
+      consumeQueue(sessionID);
+      existing.length = 0;
+    }
+    if (lower.startsWith("mcp__thatch__")) continue;
+    if (lower === "skill" || lower === "task" || lower === "agent") continue;
     const response = typeof tc.tool_response === "string"
       ? tc.tool_response
       : JSON.stringify(tc.tool_response).slice(0, 500);
@@ -70,8 +82,8 @@ export function appendBatch(sessionID: string, toolCalls: BatchToolCall[]): void
   writeFileSync(path, all.map((ix) => JSON.stringify(ix)).join("\n") + "\n");
 }
 
-/** Read and delete a session's queue. Returns the buffered interactions in order. */
-export function flushQueue(sessionID: string): ToolInteraction[] {
+/** Read a session's queued interactions without removing them. */
+export function peekQueue(sessionID: string): ToolInteraction[] {
   let path: string;
   try {
     path = queuePath(sessionID);
@@ -79,8 +91,18 @@ export function flushQueue(sessionID: string): ToolInteraction[] {
     return [];
   }
   if (!existsSync(path)) return [];
-  const interactions = readQueueFile(path);
-  unlinkSync(path);
+  return readQueueFile(path);
+}
+
+/** Delete a session's queue file. Called when the agent writes a memory. */
+export function consumeQueue(sessionID: string): void {
+  try { unlinkSync(queuePath(sessionID)); } catch { /* not present is fine */ }
+}
+
+/** Read and delete a session's queue. Returns the buffered interactions in order. */
+export function flushQueue(sessionID: string): ToolInteraction[] {
+  const interactions = peekQueue(sessionID);
+  consumeQueue(sessionID);
   return interactions;
 }
 
@@ -98,4 +120,33 @@ function readQueueFile(path: string): ToolInteraction[] {
       }
     })
     .filter((ix): ix is ToolInteraction => ix !== null);
+}
+
+// ---------------------------------------------------------------------------
+// Missed-nudge counter — file-backed per-session escalation state. Tracks
+// consecutive extraction nudges delivered without any memory_remember call.
+// Reset by appendBatch when the agent writes a memory. Read and incremented
+// by flush-tools when the nudge is delivered.
+// ---------------------------------------------------------------------------
+
+function countPath(sessionID: string): string {
+  return join(queueDir(), `${safeName(sessionID)}.count`);
+}
+
+export function resetMissedCount(sessionID: string): void {
+  try { unlinkSync(countPath(sessionID)); } catch { /* not present is fine */ }
+}
+
+export function getMissedCount(sessionID: string): number {
+  try {
+    return parseInt(readFileSync(countPath(sessionID), "utf8"), 10) || 0;
+  } catch {
+    return 0;
+  }
+}
+
+export function incrementMissedCount(sessionID: string): void {
+  const next = getMissedCount(sessionID) + 1;
+  mkdirSync(queueDir(), { recursive: true });
+  writeFileSync(countPath(sessionID), String(next));
 }

package/src/extraction.ts

@@ -100,10 +100,20 @@ export class ExtractionPipeline {
     this.#buffers.set(interaction.sessionID, buf.slice(-this.#maxBuffer));
   }
 
+  /** Returns the session's buffered interactions without clearing them. */
+  peek(sessionID: string): ToolInteraction[] {
+    return this.#buffers.get(sessionID) ?? [];
+  }
+
+  /** Clears the session's buffer. Called when the agent writes a memory. */
+  consume(sessionID: string): void {
+    this.#buffers.delete(sessionID);
+  }
+
   /** Returns the session's buffered interactions and clears them. */
   flush(sessionID: string): ToolInteraction[] {
-    const batch = this.#buffers.get(sessionID) ?? [];
-    this.#buffers.delete(sessionID);
+    const batch = this.peek(sessionID);
+    this.consume(sessionID);
     return batch;
   }
 

package/src/index.ts

@@ -9,6 +9,7 @@ import {
   compactionContext,
   sessionStartReminder,
   recallNudge,
+  extractionNudge,
   type NudgeMatch,
 } from "./prompts";
 import { ExtractionPipeline } from "./extraction";
@@ -49,6 +50,20 @@ export const server: Plugin = async ({ client, worktree }) => {
   // session, but no crash).
   const compacting = new Set<string>();
 
+  // Per-session count of consecutive extraction nudges delivered without any
+  // memory_remember call in between. Drives nudge escalation: the agent gets
+  // a couple of polite chances, then the tone shifts to directive, then to
+  // all-caps shouting. Reset to 0 whenever the agent writes a memory.
+  const missedNudges = new Map<string, number>();
+
+  // Parent-child session mapping for cross-session buffer drain. opencode
+  // creates real child sessions with their own IDs for sub-agents; without
+  // this map, a memory_remember call in a child (e.g. a background
+  // fact-extractor task) drains the child's empty buffer but leaves the
+  // parent's buffer untouched, causing the nudge to replay indefinitely.
+  // Populated from session.created events that carry a parentID.
+  const childToParent = new Map<string, string>();
+
   // Skills always install to the global opencode config — installing into the
   // worktree would mutate the user's repo (untracked files in git status).
   // A failed install degrades the nudge workflow but must not kill the plugin.
@@ -86,11 +101,49 @@ export const server: Plugin = async ({ client, worktree }) => {
       compacting.delete(input.sessionID);
     },
 
-    // 3. Tool buffering — feeds the extraction nudge. Thatch's own tools are
-    // excluded: extracting facts from memory operations would just echo the
-    // store back into itself.
+    // 3. Tool buffering — feeds the extraction nudge. Excluded tools:
+    //    - thatch_*: extracting facts from memory ops would echo the store
+    //    - skill/task: meta-tools that orchestrate agent behavior (loading
+    //      skills, dispatching sub-agents). Buffering them creates a feedback
+    //      loop — the nudge triggers a skill load, which gets buffered, which
+    //      triggers another nudge on the next turn.
+    //    Memory writes consume the buffer and reset the missed-nudge counter.
+    //    The buffer is NOT drained on nudge delivery — it persists until the
+    //    agent writes a memory, so ignored nudges accumulate and the payload
+    //    grows with each missed cycle.
+    //
+    //    Fix A: a memory_remember call in a child session (sub-agent) also
+    //    drains the parent's buffer. Without this, dispatching the
+    //    fact-extractor as a background task writes memories in the child
+    //    but never clears the parent's queue — the nudge replays every turn.
+    //
+    //    Fix C: thatch_extraction_done is an explicit acknowledgment tool the
+    //    model calls in the parent session after dispatching. Belt-and-
+    //    suspenders for fix A: covers the case where the sub-agent errors out
+    //    or the host doesn't expose parent-child session relationships.
     "tool.execute.after": async (input, output) => {
-      if (input.tool.startsWith("thatch_")) return;
+      if (input.tool === "thatch_memory_remember") {
+        extraction.consume(input.sessionID);
+        missedNudges.delete(input.sessionID);
+        // Fix A: if this is a child session, also drain the parent so the
+        // parent's extraction nudge stops replaying after a sub-agent writes
+        // memories on its behalf.
+        const parentID = childToParent.get(input.sessionID);
+        if (parentID) {
+          extraction.consume(parentID);
+          missedNudges.delete(parentID);
+        }
+        return;
+      }
+      // Fix C: explicit acknowledgment tool drains the buffer without
+      // requiring a memory write. The model calls this after dispatching
+      // the fact-extractor to a sub-agent.
+      if (input.tool === "thatch_extraction_done") {
+        extraction.consume(input.sessionID);
+        missedNudges.delete(input.sessionID);
+        return;
+      }
+      if (input.tool.startsWith("thatch_") || input.tool === "skill" || input.tool === "task") return;
       extraction.push({
         tool: input.tool,
         sessionID: input.sessionID,
@@ -113,12 +166,11 @@ export const server: Plugin = async ({ client, worktree }) => {
     "chat.message": async (input, output) => {
       if (compacting.has(input.sessionID)) return;
       if (extraction.pending(input.sessionID)) {
-        const batch = extraction.flush(input.sessionID);
+        const batch = extraction.peek(input.sessionID);
         const payload = extraction.buildPayload(batch, repo);
-        const text =
-          `[thatch] ${batch.length} recent tool interactions are queued for fact extraction. ` +
-          `Use the skill tool to load thatch-fact-extractor, then use thatch_memory_remember ` +
-          `to save any new durable facts from this payload:\n${payload}`;
+        const missed = missedNudges.get(input.sessionID) ?? 0;
+        const text = extractionNudge(batch.length, missed, "thatch_memory_remember", payload);
+        missedNudges.set(input.sessionID, missed + 1);
 
         output.parts.push({
           id: `prt_thatch_${Math.random().toString(36).slice(2)}`,
@@ -165,7 +217,22 @@ export const server: Plugin = async ({ client, worktree }) => {
 
     // 5. Session-start reminder, carrying the hygiene heartbeat. Hygiene is
     // best-effort: a failure there must not cost the reminder itself.
+    //
+    // Also tracks parent-child session relationships for fix A (cross-session
+    // buffer drain). session.created with a parentID records the mapping;
+    // session.deleted cleans it up to avoid unbounded growth.
     event: async ({ event }) => {
+      if (event.type === "session.created") {
+        const info = event.properties.info;
+        if (info.parentID) {
+          childToParent.set(info.id, info.parentID);
+        }
+      }
+      if (event.type === "session.deleted") {
+        childToParent.delete(event.properties.info.id);
+        return;
+      }
+
       if (event.type !== "session.created") return;
       const id = event.properties.info.id;
 

package/src/prompts.ts

@@ -136,7 +136,7 @@ Tools are prefixed in Claude Code: \`mcp__thatch__memory_remember\`,
 \`mcp__thatch__memory_recall\`, \`mcp__thatch__memory_list\`,
 \`mcp__thatch__memory_show\`, \`mcp__thatch__memory_forget\`,
 \`mcp__thatch__store_list\`, \`mcp__thatch__find_duplicates\`,
-\`mcp__thatch__dedup_mark_checked\`.
+\`mcp__thatch__dedup_mark_checked\`, \`mcp__thatch__extraction_done\`.
 Bare names used below for readability.
 
 ## Stores
@@ -255,16 +255,62 @@ export function claudeWriteNudge(): string {
 }
 
 /**
- * The UserPromptSubmit hook stdout when `thatch flush-tools` drained buffered
- * tool interactions. Mirrors the opencode plugin's in-process ExtractionPipeline
- * nudge (see src/index.ts) so the thatch-fact-extractor skill receives the same
- * JSON contract regardless of host. The skill picks the store from the
- * payload's `projectStore` field and calls `mcp__thatch__memory_remember`.
+ * Extraction nudge with escalation. Both the opencode plugin (src/index.ts)
+ * and the Claude Code/Cursor CLI (bin/thatch flush-tools) call this with
+ * 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.
+ */
+export function extractionNudge(
+  count: number,
+  missedCount: number,
+  toolName: string,
+  payload: string,
+): string {
+  const plural = count === 1 ? "" : "s";
+  // opencode's task tool has a `background` parameter (requires
+  // OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true) that launches the sub-agent
+  // asynchronously — the call returns immediately and the session is notified
+  // on completion. Naming the parameter gives the model a direct hit on the tool
+  // schema it sees. MCP hosts (Claude Code, Cursor) keep generic sub-agent
+  // wording because their background mechanisms differ and are not exposed as a
+  // per-call parameter in the same way.
+  const isOpencode = toolName.startsWith("thatch_");
+  const dispatch = isOpencode
+    ? "Dispatch a task with background: true"
+    : "Spawn a background sub-agent";
+  const drainTool = isOpencode ? "thatch_extraction_done" : "mcp__thatch__extraction_done";
+  const acknowledge = `After dispatching, call ${drainTool} to acknowledge.`;
+
+  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}`;
+  }
+  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}`;
+  }
+  return `[thatch] ${dispatch} to run the thatch-fact-extractor skill ` +
+    `on ${count} queued tool interaction${plural}. ` +
+    `${acknowledge} ` +
+    `Then answer the user. ` +
+    `Use ${toolName} to save durable facts from this payload:\n${payload}`;
+}
+
+/**
+ * Backwards-compatible wrapper for the Claude Code/Cursor CLI path.
+ * 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 `[thatch] ${count} recent tool interaction${count === 1 ? "" : "s"} queued for fact extraction. ` +
-    `Load the thatch-fact-extractor skill, then use mcp__thatch__memory_remember ` +
-    `to save any new durable facts from this payload:\n${payload}`;
+  return extractionNudge(count, 0, "mcp__thatch__memory_remember", payload);
 }
 
 /**
@@ -283,7 +329,7 @@ Tools are prefixed in Cursor: \`mcp__thatch__memory_remember\`,
 \`mcp__thatch__memory_recall\`, \`mcp__thatch__memory_list\`,
 \`mcp__thatch__memory_show\`, \`mcp__thatch__memory_forget\`,
 \`mcp__thatch__store_list\`, \`mcp__thatch__find_duplicates\`,
-\`mcp__thatch__dedup_mark_checked\`.
+\`mcp__thatch__dedup_mark_checked\`, \`mcp__thatch__extraction_done\`.
 Bare names used below for readability.
 
 ## Stores