@jeffober/thatch 0.1.5 → 0.1.8

package/README.md

@@ -2,12 +2,18 @@
 
 [![CI](https://github.com/sysread/thatch/actions/workflows/ci.yml/badge.svg)](https://github.com/sysread/thatch/actions/workflows/ci.yml)
 
-Persistent memory for AI coding agents — local embeddings, SQLite stores, zero config.
-
-Works with **OpenCode** (as a plugin) and **Claude Code** (as an MCP server).
-Your AI agent can remember information across sessions. Stores are per-repo
-with a shared `global` store. No API keys, no cloud services — everything runs
-on your machine.
+Persistent memory and operational methodology 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).
+Each session inherits the accumulated knowledge of every session before it —
+project architecture, conventions, gotchas, user preferences — so your agent
+starts with context instead of a blank slate. Stores are per-repo with a
+shared `global` store. On top of the memory layer, thatch ships a suite of
+skills that prime, maintain, and reflect on memory, plus a structured
+multi-agent code review framework. No API keys, no cloud services —
+everything runs on your machine.
 
 ## Quick start
 
@@ -51,7 +57,7 @@ thatch setup --claude
 1. Writes `.mcp.json` — registers the MCP server (Claude Code spawns `thatch mcp` as a stdio process)
 2. Appends instructions to `CLAUDE.md` — session startup, when to write, what to store
 3. Installs hooks in `.claude/settings.json` — `SessionStart` runs `thatch reminder` (recall nudge + hygiene), `UserPromptSubmit` reminds you to save new knowledge
-4. Installs skill files to `~/.claude/skills/` — `thatch-fact-extractor`, `thatch-dedup-classifier`, and `thatch-project-primer`
+4. Installs skill files to `~/.claude/skills/` — memory workflow skills (project primer, fact extractor, dedup classifier, session reflection) and code review skills (5 review specialists + synthesizer). See [Skills](#skills) below.
 
 Restart Claude Code and thatch's tools are available as `mcp__thatch__*`.
 
@@ -88,6 +94,38 @@ 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 |
 
+## Skills
+
+Thatch ships skills that encode operational methodology — practices your
+agent follows to maintain its own memory and review code systematically.
+
+### Memory workflows
+
+| Skill | What it does |
+|-------|-------------|
+| `thatch-project-primer` | Bootstrap a project's memory store by investigating the codebase and writing foundational memories |
+| `thatch-fact-extractor` | Extract durable facts from recent tool interactions and persist them to memory |
+| `thatch-dedup-classifier` | Classify and consolidate similar memories surfaced by `thatch_find_duplicates` |
+| `thatch-session-reflection` | Record what was learned during a session — project facts, user preferences, tool tips |
+
+### Code review
+
+| Skill | What it does |
+|-------|-------------|
+| `thatch-review-pedantic` | Mechanical correctness — spelling, naming, doc accuracy, specs, stale artifacts |
+| `thatch-review-acceptance` | Behavioral and product review — UX coherency, behavioral delta, integration effects |
+| `thatch-review-state-flow` | Data flow and contracts — module boundaries, implicit state machines, error propagation |
+| `thatch-review-no-slop` | AI writing anti-pattern detection — change narration, fourth wall breaks, hedging |
+| `thatch-review-breadcrumbs` | Comment narrative — do comments form a coherent outline of the code's behavior? |
+| `thatch-review-synthesizer` | Verify specialist findings against actual code, deduplicate, produce severity-grouped report |
+| `thatch-code-review` | Multi-agent review coordinator — triage, partition, dispatch specialists in parallel (opencode only) |
+
+The five review specialists run independently and can be used standalone. The
+synthesizer verifies their findings against the actual code — reading each
+cited location to confirm the evidence matches — before producing a final
+report. The coordinator (opencode only) orchestrates the full pipeline by
+dispatching specialist sub-agents in parallel.
+
 ## CLI
 
 The `thatch` CLI ships with the package (installed to your npm global bin by
@@ -141,6 +179,17 @@ Thatch auto-detects your repo identity from `git remote get-url origin`
 locally) and stored in `~/.config/thatch/thatch.db` (SQLite, WAL mode).
 Search is brute-force cosine similarity — fast enough for thousands of entries.
 
+### Memory capture
+
+Thatch doesn't call an LLM to extract facts. Instead, it buffers recent tool
+interactions and nudges the host agent to persist durable knowledge itself,
+using the `thatch-fact-extractor` skill. The agent's own model decides what's
+worth remembering — keeping thatch dependency-free and the agent in control.
+On OpenCode, the plugin hooks `tool.execute.after` and `chat.message` to
+buffer and flush. On Claude Code, `PostToolBatch` and `UserPromptSubmit`
+hooks drive a file-backed queue. Both paths produce the same payload for the
+fact-extractor skill.
+
 ## OpenCode vs Claude Code parity
 
 | Feature | OpenCode (plugin) | Claude Code (MCP + hooks) |
@@ -149,7 +198,7 @@ Search is brute-force cosine similarity — fast enough for thousands of entries
 | System prompt | Injected at runtime with repo name | Static CLAUDE.md (repo auto-detected by MCP server) |
 | Session-start reminder | `session.created` event | `SessionStart` hook → `thatch reminder` |
 | Compaction context | `experimental.session.compacting` hook | **Gap**: no equivalent (CLAUDE.md persists through compaction) |
-| Extraction nudge | `tool.execute.after` + `chat.message` | **Gap**: no cross-call buffering (hooks fire per-event) |
+| Extraction nudge | `tool.execute.after` + `chat.message` | `PostToolBatch` + `UserPromptSubmit` (file-backed queue) |
 | Skills | `$XDG_CONFIG_HOME/opencode/skills` | `~/.claude/skills/` |
 | Store detection | `worktree` param from plugin | `CLAUDE_PROJECT_DIR` env var |
 
@@ -174,10 +223,12 @@ and is cached. No data leaves your machine.
 bun install        # deps
 bun test           # full suite: zero network, zero external deps
 bun test --watch   # watch mode
+mise run check     # typecheck + bun test + markdownlint (the CI gate)
 ```
 
 Tests never reach outside the sandbox: temp-directory SQLite files, mock
-embeddings, no network.
+embeddings, no network. `mise run check` is the full quality gate; `mise run
+typecheck` or `mise run lint-md` run those alone.
 
 ## License
 

package/bin/release

@@ -22,9 +22,9 @@ echo "  bump:    $v"
 echo "  next:    $next"
 echo
 
-echo "▸ running tests..."
-bun test
-echo "  ✓ tests passed"
+echo "▸ running checks (typecheck + tests + markdown lint)..."
+mise run check
+echo "  ✓ checks passed"
 echo
 
 echo "▸ bumping version..."

package/bin/thatch

@@ -7,7 +7,7 @@ import { detectRepo } from "../src/git";
 import { BgeEmbeddingModel } from "../src/embeddings";
 import { hygieneReport } from "../src/hygiene";
 import { claudeSessionStartReminder } from "../src/prompts";
-import { setupClaudeCode } from "../src/setup";
+import { setupClaudeCode, setupCursor } from "../src/setup";
 
 const configHome = process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
 const dbPath = process.env.THATCH_DB_PATH ?? join(configHome, "thatch", "thatch.db");
@@ -22,13 +22,14 @@ function usage(): never {
   thatch show   <label> [store]    Display a memory by label
   thatch forget <label> [store]    Remove a memory by label
   thatch search <query> [store]    Semantic search (cosine similarity)
-  thatch mcp                       Start the stdio MCP server (for Claude Code)
-  thatch reminder                  Print session-start reminder (for SessionStart hook)
+  thatch mcp                       Start the stdio MCP server (for Claude Code, Cursor, etc.)
+  thatch reminder [--json]         Print session-start reminder (for SessionStart hook)
   thatch hygiene                   Print the hygiene report (standalone)
-  thatch prime                     Prime project memory (runs the primer skill via opencode or claude)
-  thatch buffer-batch              Append a PostToolBatch payload to the queue (hook only)
-  thatch flush-tools               Drain the queue + print an extraction nudge (hook only)
-  thatch setup [--claude] [--global] [--force]
+  thatch prime                     Prime project memory (runs the primer skill via opencode, cursor, or claude)
+  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]      Drain the queue + print an extraction nudge (hook only)
+  thatch setup --claude [--cursor] [--global]
                                    Install config + instructions + hooks + skills
 
 Stores default to the repo detected from git remote. Use "global" for the
@@ -44,6 +45,11 @@ async function defaultStore(): Promise<string> {
   }
 }
 
+/** Resolve the project directory from host-specific env vars or cwd. */
+function projectDir(): string {
+  return process.env.CURSOR_PROJECT_DIR ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+}
+
 switch (command) {
   case "stores":
     console.log(db.listStores().join("\n"));
@@ -138,21 +144,27 @@ switch (command) {
   }
 
   case "reminder": {
+    const isJson = args.includes("--json");
     const repo = await defaultStore();
-    const worktree = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+    const worktree = projectDir();
     let hygiene: string | null = null;
     try {
       hygiene = await hygieneReport(db, repo, worktree);
     } catch (err) {
       console.error(`[thatch] hygiene report failed: ${err}`);
     }
-    console.log(claudeSessionStartReminder(repo, hygiene));
+    const reminder = claudeSessionStartReminder(repo, hygiene);
+    if (isJson) {
+      console.log(JSON.stringify({ additional_context: reminder }));
+    } else {
+      console.log(reminder);
+    }
     break;
   }
 
   case "hygiene": {
     const repo = await defaultStore();
-    const worktree = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+    const worktree = projectDir();
     const hygiene = await hygieneReport(db, repo, worktree);
     console.log(hygiene ?? "Store is healthy.");
     break;
@@ -161,6 +173,7 @@ switch (command) {
   case "prime": {
     const primerPrompt = "Load the thatch-project-primer skill and follow its instructions to prime this project's memory store.";
     const opencodeBin = Bun.which("opencode");
+    const agentBin = Bun.which("agent");
     const claudeBin = Bun.which("claude");
 
     if (opencodeBin) {
@@ -170,6 +183,15 @@ switch (command) {
         stderr: "inherit",
       });
       process.exit(proc.exitCode ?? 1);
+    } else if (agentBin) {
+      // Cursor CLI: -p for non-interactive print mode, --approve-mcps to
+      // auto-approve the thatch MCP server (no interactive UI in -p mode).
+      console.error("Priming project memory via cursor agent...");
+      const proc = Bun.spawnSync([agentBin, "-p", primerPrompt, "--approve-mcps"], {
+        stdout: "inherit",
+        stderr: "inherit",
+      });
+      process.exit(proc.exitCode ?? 1);
     } else if (claudeBin) {
       console.error("Priming project memory via claude...");
       const proc = Bun.spawnSync([claudeBin, primerPrompt], {
@@ -178,7 +200,7 @@ switch (command) {
       });
       process.exit(proc.exitCode ?? 1);
     } else {
-      console.error("Error: neither 'opencode' nor 'claude' found on PATH.");
+      console.error("Error: none of 'opencode', 'agent', or 'claude' found on PATH.");
       console.error("Install one of them to use thatch prime.");
       process.exit(1);
     }
@@ -188,10 +210,11 @@ switch (command) {
   case "setup": {
     const isGlobal = args.includes("--global");
     const isClaude = args.includes("--claude");
+    const isCursor = args.includes("--cursor");
 
-    if (!isClaude) {
-      console.error("Currently only --claude is supported.");
-      console.error("Usage: thatch setup --claude [--global]");
+    if (!isClaude && !isCursor) {
+      console.error("Specify at least one host: --claude and/or --cursor.");
+      console.error("Usage: thatch setup --claude [--cursor] [--global]");
       process.exit(1);
     }
 
@@ -201,30 +224,47 @@ switch (command) {
     // If not on PATH (local dev checkout), use the absolute path to this script.
     const thatchOnPath = Bun.which("thatch");
     const thatchBin = thatchOnPath ?? resolve(process.argv[1] ?? process.execPath);
-    const projectDir = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+    const dir = projectDir();
 
-    const result = setupClaudeCode(thatchBin, isGlobal, projectDir);
+    if (isClaude) {
+      const result = setupClaudeCode(thatchBin, isGlobal, dir);
 
-    console.log(`Thatch setup complete (${isGlobal ? "global" : "project-local"}).`);
-    console.log();
-    if (result.mcpConfig) {
-      console.log(`  MCP config:    ${result.mcpConfig}`);
+      console.log(`Thatch setup complete for Claude Code (${isGlobal ? "global" : "project-local"}).`);
+      console.log();
+      if (result.mcpConfig) {
+        console.log(`  MCP config:    ${result.mcpConfig}`);
+      }
+      console.log(`  Instructions:  ${result.claudeMd}`);
+      console.log(`  Hooks:         ${result.settings}`);
+      const skillsDir = result.skills[0]?.path
+        ? result.skills[0].path.split("/").slice(0, -1).join("/")
+        : "(no skills installed)";
+      console.log(`  Skills:        ${skillsDir} (${result.skills.length} files)`);
+      console.log();
+      if (result.mcpAddCommand) {
+        console.log("To register the MCP server globally, run:");
+        console.log(`  ${result.mcpAddCommand}`);
+        console.log();
+      }
+      console.log("Restart Claude Code for the changes to take effect.");
     }
-    console.log(`  Instructions:  ${result.claudeMd}`);
-    console.log(`  Hooks:         ${result.settings}`);
-    // Skills dir is not currently surfaced on SetupResult — derive it from
-    // the skills file paths (they all share the same parent directory).
-    const skillsDir = result.skills[0]?.path
-      ? result.skills[0].path.split("/").slice(0, -1).join("/")
-      : "(no skills installed)";
-    console.log(`  Skills:        ${skillsDir} (${result.skills.length} files)`);
-    console.log();
-    if (result.mcpAddCommand) {
-      console.log("To register the MCP server globally, run:");
-      console.log(`  ${result.mcpAddCommand}`);
+
+    if (isCursor) {
+      const result = setupCursor(thatchBin, isGlobal, dir);
+
       console.log();
+      console.log(`Thatch setup complete for Cursor (${isGlobal ? "global" : "project-local"}).`);
+      console.log();
+      console.log(`  MCP config:    ${result.mcpConfig}`);
+      console.log(`  Instructions:  ${result.agentsMd}`);
+      console.log(`  Hooks:         ${result.hooks}`);
+      const skillsDir = result.skills[0]?.path
+        ? result.skills[0].path.split("/").slice(0, -1).join("/")
+        : "(no skills installed)";
+      console.log(`  Skills:        ${skillsDir} (${result.skills.length} files)`);
+      console.log();
+      console.log("Restart Cursor for the changes to take effect.");
     }
-    console.log("Restart Claude Code for the changes to take effect.");
     break;
   }
 
@@ -245,35 +285,116 @@ switch (command) {
     break;
   }
 
+  case "buffer-tool": {
+    // Cursor postToolUse hook: append a single tool interaction to the
+    // session's JSONL queue. Cursor fires postToolUse per-tool (no batch
+    // equivalent), so this receives one tool at a time. Silent on success.
+    // Session ID comes as `conversation_id` in Cursor (vs `session_id` in
+    // Claude Code). The tool result field name is not explicitly documented,
+    // so we try the most likely candidates.
+    try {
+      const raw = await Bun.stdin.text();
+      const data = JSON.parse(raw) as {
+        conversation_id?: string;
+        session_id?: string;
+        tool_name?: string;
+        tool_input?: Record<string, unknown>;
+        tool_use_id?: string;
+        tool_result?: string | unknown[];
+        tool_response?: string | unknown[];
+        result_json?: string;
+        result?: string | unknown[];
+        output?: string;
+      };
+      const sessionID = data.conversation_id ?? data.session_id;
+      if (sessionID && data.tool_name) {
+        const { appendBatch } = await import("../src/extract-queue");
+        const response = data.tool_result ?? data.tool_response ?? data.result_json ?? data.result ?? data.output ?? "";
+        appendBatch(sessionID, [{
+          tool_name: data.tool_name,
+          tool_input: data.tool_input ?? {},
+          tool_use_id: data.tool_use_id,
+          tool_response: response,
+        }]);
+      }
+    } catch (err) {
+      console.error(`[thatch buffer-tool] failed: ${err}`);
+    }
+    break;
+  }
+
   case "flush-tools": {
-    // UserPromptSubmit hook: drain the queue. With buffered interactions,
-    // print the extraction nudge carrying the payload so the agent can load
-    // the thatch-fact-extractor skill and persist durable facts. With an
-    // empty queue, fall back to the static write-nudge so the original
-    // workflow contract (a per-prompt "did you learn anything?" reminder)
-    // is preserved on conversational turns that did no tool use.
+    // UserPromptSubmit (Claude Code) / beforeSubmitPrompt (Cursor) hook.
+    // Three priority tiers:
+    //   1. Extraction nudge — buffered tool interactions are queued for fact
+    //      extraction (carries the JSON payload for thatch-fact-extractor).
+    //   2. Recall nudge — the user's prompt semantically matches existing
+    //      memories. Uses the sideband socket to ask the warm MCP server to
+    //      embed the prompt and search, avoiding a cold model load here.
+    //   3. Write nudge — static "did you learn anything?" fallback for
+    //      conversational turns with no tool use and no memory matches.
+    // --json wraps output as { additional_context: "..." } for Cursor hooks.
+    // Without --json, stdout is plain text (Claude Code style).
+    const isJson = args.includes("--json");
     try {
       const raw = await Bun.stdin.text();
-      const data = JSON.parse(raw) as { session_id?: string };
+      const data = JSON.parse(raw) as {
+        session_id?: string;
+        conversation_id?: string;
+        prompt?: string;
+        message?: string;
+        text?: string;
+        user_input?: string;
+        input?: string;
+      };
+      const sessionID = data.session_id ?? data.conversation_id;
 
       const { flushQueue } = await import("../src/extract-queue");
       const { buildExtractionPayload } = await import("../src/extraction");
-      const { claudeExtractionNudge, claudeWriteNudge } = await import("../src/prompts");
+      const { claudeExtractionNudge, claudeWriteNudge, claudeRecallNudge } = await import("../src/prompts");
 
       let repo = "unknown";
       try { repo = await detectRepo(); } catch {}
 
-      const interactions = data.session_id ? flushQueue(data.session_id) : [];
+      // Tier 1: extraction nudge.
+      const interactions = sessionID ? flushQueue(sessionID) : [];
       if (interactions.length > 0) {
-        console.log(claudeExtractionNudge(interactions.length, buildExtractionPayload(interactions, repo)));
-      } else {
-        console.log(claudeWriteNudge());
+        const output = claudeExtractionNudge(interactions.length, buildExtractionPayload(interactions, repo));
+        if (isJson) console.log(JSON.stringify({ additional_context: output }));
+        else console.log(output);
+        break;
       }
+
+      // Tier 2: recall nudge via sideband. The prompt text field name varies
+      // by host (Claude Code: "prompt", Cursor: undocumented). Try candidates.
+      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 sockPath = sidebandSocketPath(dbPath);
+        const threshold = parseFloat(process.env.THATCH_RECALL_THRESHOLD ?? "0.55");
+        const matches = await sidebandMatch(sockPath, promptText, [repo, "global"], threshold, 5);
+        if (matches && matches.length > 0) {
+          const output = claudeRecallNudge(matches);
+          if (isJson) console.log(JSON.stringify({ additional_context: output }));
+          else console.log(output);
+          break;
+        }
+      }
+
+      // Tier 3: static write nudge.
+      const output = claudeWriteNudge();
+      if (isJson) console.log(JSON.stringify({ additional_context: output }));
+      else console.log(output);
     } catch (err) {
       console.error(`[thatch flush-tools] failed: ${err}`);
       try {
         const { claudeWriteNudge } = await import("../src/prompts");
-        console.log(claudeWriteNudge());
+        const fallback = claudeWriteNudge();
+        if (isJson) {
+          console.log(JSON.stringify({ additional_context: fallback }));
+        } else {
+          console.log(fallback);
+        }
       } catch {
         // If even the fallback import fails, do nothing — silent failure is
         // preferable to blocking the user's prompt over an unrelated hook.

package/docs/dev/README.md

@@ -2,22 +2,30 @@
 
 ## Architecture
 
-Thatch has two integration paths sharing a common core:
+Thatch has three integration paths sharing a common core:
 
 1. **OpenCode plugin** — runs inside opencode's Bun runtime. Full access to
    plugin hooks: system prompt injection, session events, tool buffering,
    compaction context.
 2. **Claude Code MCP server** — runs as a stdio JSON-RPC process. Tools
    exposed via MCP; session behavior driven by Claude Code hooks.
+3. **Cursor MCP server** — same stdio MCP server as Claude Code; session
+   behavior driven by Cursor hooks in a flat `hooks.json` format.
 
-```
+For feature parity and gaps across the three, see [mcp-parity.md](mcp-parity.md).
+For the concrete files and hook events each host writes, see
+[setup-and-hooks.md](setup-and-hooks.md). For non-obvious invariants, see
+[gotchas.md](gotchas.md). For the skill system, see [skills.md](skills.md).
+
+```text
 Shared core
   ├── tool-defs.ts    → single source of truth: zod schemas + execute logic
-  ├── db.ts           → SQLite CRUD, cosine search, dedup verdicts
+  ├── db.ts           → SQLite CRUD, cosine search (recall + search), dedup verdicts
   ├── embeddings.ts   → embedding model via transformers.js
   ├── git.ts          → detect repo identity (store name)
   ├── hygiene.ts      → hygiene report (pending dedups, stale, orphaned branches)
-  ├── prompts.ts      → system prompt, compaction, reminders, CLAUDE.md instructions
+  ├── prompts.ts      → system prompt, compaction, reminders, recall nudge, CLAUDE.md instructions
+  ├── sideband.ts     → Unix socket server + client: warm-model semantic match for hook processes
   └── skills.ts       → SKILL.md content + installer (shared + opencode-only arrays)
 
 OpenCode plugin path
@@ -26,11 +34,15 @@ OpenCode plugin path
 
 MCP server path
   ├── mcp.ts          → stdio JSON-RPC server: z.toJSONSchema() for tools/list,
-  │                     z.object().parse() for validation, dispatches to tool-defs
-  └── setup.ts        → `thatch setup --claude`: writes .mcp.json, CLAUDE.md,
-                        settings.json hooks, installs skills
-
-bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygiene|setup
+  │                     z.object().parse() for validation, dispatches to tool-defs;
+  │                     opens sideband socket for warm-model match queries
+  ├── sideband.ts     → Unix socket: SidebandServer (embed + search via warm model)
+  │                     and sidebandMatch (thin client for hook processes)
+  └── setup.ts        → `thatch setup --claude` / `--cursor`: writes .mcp.json,
+                        CLAUDE.md / AGENTS.md, settings/hooks JSON, installs skills
+
+bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygiene|
+                        prime|buffer-batch|buffer-tool|flush-tools|setup
 ```
 
 ## Module responsibilities
@@ -44,10 +56,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, 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. |
 | `embeddings.ts` | Lazy-load the embedding model. Expose `queryEmbed`/`passageEmbed` and the model `name` (stored as an informational tag). `MockEmbeddingModel` for tests. |
 | `extraction.ts` | Buffers non-thatch tool interactions per session and serializes them into the JSON payload the extraction nudge carries. (opencode-only — no MCP equivalent.) |
-| `prompts.ts` | Text constants: opencode system prompt, compaction context, session-start reminder, Claude Code CLAUDE.md instructions, Claude Code hook text. |
+| `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. |
+| `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` (10 skills: fact-extractor, dedup-classifier, project-primer, 5 review specialists, review synthesizer, session reflection — 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]`. |
 
 ## Plugin hooks
@@ -57,9 +70,10 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 | Hook | What it does |
 |------|-------------|
 | `experimental.chat.system.transform` | Appends the thatch system prompt (store names, usage rules). |
-| `experimental.session.compacting` | Appends re-familiarization context so a compacted session still knows thatch exists. |
+| `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. |
 | `tool.execute.after` | Buffers every non-`thatch_*` tool call into the session's extraction buffer. 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` | If the session has buffered interactions, flushes them and injects a synthetic text part carrying the extraction nudge + JSON payload. |
+| `chat.message` | Two priority tiers: (a) if extraction buffer has interactions, flushes them as a synthetic text part carrying the extraction nudge + JSON payload; (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). |
 | `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. |
 
@@ -97,7 +111,7 @@ Two of these hooks were dead for weeks because failures were invisible.
 
 ## Data flow
 
-```
+```text
 thatch_memory_remember(label, content)
   → model.passageEmbed("# label\n\ncontent") → Float32Array
   → db.findSimilar(store, embedding) — write-time collision check (no telemetry)
@@ -129,6 +143,16 @@ extraction cycle (agent-driven)
   → next chat.message flushes the buffer into a nudge part with JSON payload
   → agent loads thatch-fact-extractor skill, saves facts via thatch_memory_remember
 
+prompt-aware recall nudge (both paths)
+  → opencode: chat.message hook embeds prompt text with warm in-process model,
+    searches db.search([repo, global]), pushes nudge part if matches ≥ threshold
+  → Claude Code/Cursor: flush-tools connects to MCP server's sideband socket,
+    warm server embeds + searches, returns labels; hook prints nudge or falls
+    back to write nudge if socket unavailable or no matches
+  → threshold: THATCH_RECALL_THRESHOLD env (default 0.55) — lower than
+    findDuplicates' 0.85 because "relates to" is a weaker signal than "duplicate"
+  → no telemetry stamped: uses db.search(), not db.recall()
+
 hygiene heartbeat (session start)
   → hygieneReport(db, repo, worktree): pending dedup pairs; entries neither
     updated nor recalled in 90+ days; memories scoped to branches that no
@@ -169,14 +193,43 @@ hygiene heartbeat (session start)
 ```bash
 bun install        # deps
 bun test           # full suite; no network, no real config dirs
+mise run check     # typecheck + bun test + markdownlint (the CI gate)
 opencode           # self-hosts via .opencode/plugins/thatch.ts
 ```
 
+The markdownlint gate lints `README.md` and `docs/` (excluding the historical
+`docs/plans/`) via `.markdownlint-cli2.jsonc`. It disables three rules that
+conflict with intentional house style (line length, table alignment, and the
+use-case template's bold-label + tight-list format). Run `mise run lint-md`
+alone to check docs without the test suite. Run `mise run typecheck` for
+`tsc` alone (uses `tsconfig.check.json`, which includes the test files that
+the build's `tsconfig.json` excludes).
+
 ## Release
 
 ```bash
 mise run release patch|minor|major
 ```
 
-Bumps version, tags, pushes; GitHub Actions publishes to npm via OIDC trusted
-publishing (no tokens — see `.github/workflows/publish.yml`).
+`bin/release` runs the full flow:
+
+1. Runs `bun test` (aborts on failure — no broken releases).
+2. `npm version <bump> --no-git-tag-version` bumps `package.json`.
+3. Prompts to commit, tag (`v<next>`), and push; declining reverts
+   `package.json` and exits cleanly.
+4. On confirm: commits, tags `v<next>`, pushes commits and the tag.
+
+Publishing is tag-driven and **passwordless**. Pushing a `v*` tag triggers
+`.github/workflows/publish.yml`, which publishes to npm via **OIDC trusted
+publishing** — no stored npm token. The `id-token: write` permission lets npm
+authenticate through GitHub's OIDC exchange instead. Prerequisites:
+
+- A Trusted Publisher configured on npmjs.com for `@jeffober/thatch` pointing at
+  the `sysread/thatch` repo and this workflow file.
+- npm >= 11.5.1 (the OIDC exchange needs it). `publish.yml` installs
+  `setup-node@v4` (node 24) and `npm install -g npm@latest`; it deliberately
+  sets **no `registry-url`**, which would write a token-expecting `.npmrc` that
+  preempts the OIDC exchange.
+
+CI (`.github/workflows/ci.yml`) runs `bun test` on every push/PR to `main` —
+the never-merge-broken guard before a release.