@jeffober/thatch 0.1.5 → 0.1.8

package/src/index.ts

@@ -8,6 +8,8 @@ import {
   systemPrompt,
   compactionContext,
   sessionStartReminder,
+  recallNudge,
+  type NudgeMatch,
 } from "./prompts";
 import { ExtractionPipeline } from "./extraction";
 import { installSkills, SHARED_SKILLS, OPENCODE_ONLY_SKILLS } from "./skills";
@@ -17,6 +19,15 @@ import { hygieneReport } from "./hygiene";
 // V1 server export — tools, prompt injection, session hooks
 // ---------------------------------------------------------------------------
 
+// Minimum cosine score for the prompt-aware recall nudge. Lower than
+// findDuplicates' 0.85 (near-dupes) because "relates to" is a weaker signal
+// than "duplicate." Tunable via THATCH_RECALL_THRESHOLD.
+const RECALL_THRESHOLD = parseFloat(process.env.THATCH_RECALL_THRESHOLD ?? "0.55");
+
+// Prompts shorter than this skip the recall nudge — trivially short prompts
+// like "yes" or "ok" match too broadly to be useful.
+const MIN_PROMPT_LEN = 10;
+
 export const server: Plugin = async ({ client, worktree }) => {
   // The opencode server's cwd is wherever the server happened to start;
   // `worktree` is the project this plugin instance actually serves.
@@ -30,6 +41,14 @@ export const server: Plugin = async ({ client, worktree }) => {
   const model = new BgeEmbeddingModel(modelName);
   const extraction = new ExtractionPipeline();
 
+  // 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).
+  const compacting = new Set<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.
@@ -53,11 +72,20 @@ export const server: Plugin = async ({ client, worktree }) => {
       output.system.push(sys);
     },
 
-    // 2. Compaction context — re-familiarizes after compaction.
-    "experimental.session.compacting": async (_input, output) => {
+    // 2. Compaction context — re-familiarizes after compaction. The flag
+    //    suppresses chat.message nudges during summary generation (tool
+    //    calls are blocked there).
+    "experimental.session.compacting": async (input, output) => {
+      compacting.add(input.sessionID);
       output.context.push(compact);
     },
 
+    // 2b. Clear the compacting flag after compaction succeeds so chat.message
+    //     nudges resume for the synthetic auto-continue turn and beyond.
+    "experimental.compaction.autocontinue": async (input) => {
+      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.
@@ -72,27 +100,67 @@ export const server: Plugin = async ({ client, worktree }) => {
       });
     },
 
-    // 4. Per-message nudge — when interactions are queued, hand the agent the
-    // actual payload; the thatch-fact-extractor skill's contract is "you will
-    // be given a JSON payload", so the nudge must carry it.
+    // 4. Per-message nudge — two priority tiers:
+    //   a. Extraction nudge: prior tool interactions are queued for fact
+    //      extraction (carries the JSON payload for thatch-fact-extractor).
+    //   b. Recall nudge: the user's prompt semantically matches existing
+    //      memories — surface that prior knowledge exists before the agent
+    //      responds. Uses the in-process warm model (no sideband needed).
+    //
+    // Skipped during compaction: the agent can't call tools while generating
+    // a summary, so a nudge that says "use thatch_memory_recall" triggers a
+    // blocked-tool error.
     "chat.message": async (input, output) => {
-      if (!extraction.pending(input.sessionID)) return;
-
-      const batch = extraction.flush(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}`;
+      if (compacting.has(input.sessionID)) return;
+      if (extraction.pending(input.sessionID)) {
+        const batch = extraction.flush(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}`;
+
+        output.parts.push({
+          id: `prt_thatch_${Math.random().toString(36).slice(2)}`,
+          sessionID: input.sessionID,
+          messageID: input.messageID ?? output.message.id,
+          type: "text",
+          text,
+          synthetic: true,
+        });
+        return;
+      }
 
-      output.parts.push({
-        id: `prt_thatch_${Math.random().toString(36).slice(2)}`,
-        sessionID: input.sessionID,
-        messageID: input.messageID ?? output.message.id,
-        type: "text",
-        text,
-        synthetic: true,
-      });
+      // No extraction pending — try the prompt-aware recall nudge. Extract
+      // the user's prompt text from the message parts, embed it with the
+      // warm in-process model, and search for matches. Best-effort: any
+      // failure (no text, model not loaded, empty store) silently skips.
+      try {
+        const promptText = (output.parts as any[])
+          .filter((p) => p.type === "text" && !p.synthetic)
+          .map((p) => p.text)
+          .join(" ");
+        if (promptText.length < MIN_PROMPT_LEN) return;
+
+        const embedding = await model.queryEmbed(promptText);
+        const results = db.search([repo, "global"], embedding, { limit: 5 });
+        const matches: NudgeMatch[] = results
+          .filter((r) => r._score >= RECALL_THRESHOLD)
+          .map((r) => ({ label: r.label, score: Math.round(r._score * 1000) / 1000 }));
+
+        if (matches.length === 0) return;
+
+        output.parts.push({
+          id: `prt_thatch_${Math.random().toString(36).slice(2)}`,
+          sessionID: input.sessionID,
+          messageID: input.messageID ?? output.message.id,
+          type: "text",
+          text: recallNudge(matches),
+          synthetic: true,
+        });
+      } catch (err) {
+        console.error(`[thatch] recall nudge failed: ${err}`);
+      }
     },
 
     // 5. Session-start reminder, carrying the hygiene heartbeat. Hygiene is

package/src/mcp.ts

@@ -3,6 +3,7 @@ import { ThatchDB } from "./db";
 import { BgeEmbeddingModel } from "./embeddings";
 import { detectRepo } from "./git";
 import { TOOL_DEFS, type CoreContext, type ToolDef } from "./tool-defs";
+import { SidebandServer, sidebandSocketPath } from "./sideband";
 
 // ---------------------------------------------------------------------------
 // JSON-RPC 2.0 types
@@ -79,6 +80,10 @@ function compileTools(): Map<string, CompiledTool> {
  * model loads lazily on the first tool call that needs it, so the server
  * starts instantly and only pays the ~34 MB download cost when a memory is
  * actually written or recalled.
+ *
+ * A Unix domain socket sideband is opened at startup so that one-shot hook
+ * processes (thatch flush-tools) can ask the warm MCP server to embed a
+ * prompt and search for matches without loading the model themselves.
  */
 export async function runMcpServer(): Promise<void> {
   const projectDir = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
@@ -94,6 +99,19 @@ export async function runMcpServer(): Promise<void> {
   const ctx: CoreContext = { db, model, defaultStore: repo };
   const tools = compileTools();
 
+  // The sideband socket lets one-shot hook processes (flush-tools) ask the
+  // warm MCP server to embed a prompt and search for matches — without
+  // loading the ~34 MB model themselves. If the socket can't be opened
+  // (permissions, tmpdir issues), the MCP server still works; only the
+  // prompt-aware recall nudge degrades.
+  const sockPath = sidebandSocketPath(dbPath);
+  const sideband = new SidebandServer(sockPath, model, db);
+  try {
+    sideband.start();
+  } catch (err) {
+    console.error(`[thatch] sideband socket failed: ${err}`);
+  }
+
   // Read stdin line by line. Each line is a complete JSON-RPC message.
   const decoder = new TextDecoder();
   let buf = "";
@@ -123,6 +141,7 @@ export async function runMcpServer(): Promise<void> {
     }
   }
 
+  sideband.stop();
   db.close();
 }
 

package/src/prompts.ts

@@ -64,9 +64,9 @@ CLAUDE.md or OPENCODE.md, speculative conclusions.
 
 export function compactionContext(repo: string): string {
   return `Thatch persistent memory is active with stores "${repo}" and "global".
-Use thatch_memory_recall to retrieve prior knowledge, thatch_memory_remember
-to persist important decisions, patterns, and conventions encountered so far.
-Include context about what's been learned and decided when summarizing.`;
+When summarizing, preserve context about what's been learned and decided
+this session — conventions, architectural decisions, and prior knowledge
+retrieved from memory. This ensures continuity after compaction.`;
 }
 
 export function sessionStartReminder(repo: string, hygiene?: string | null): string {
@@ -202,3 +202,114 @@ export function claudeExtractionNudge(count: number, payload: string): string {
     `Load the thatch-fact-extractor skill, then use mcp__thatch__memory_remember ` +
     `to save any new durable facts from this payload:\n${payload}`;
 }
+
+/**
+ * Static instructions for Cursor's AGENTS.md. Same contract as
+ * claudeInstructions() — the host loads this at every session start, and the
+ * repo store name is auto-detected at runtime by the MCP server. Tool names
+ * use the same mcp__thatch__ prefix since Cursor discovers MCP tools via the
+ * same protocol.
+ */
+export function cursorInstructions(): string {
+  return `# Persistence
+
+Thatch provides persistent memory across Cursor sessions. Use it to persist
+knowledge so future sessions can build on what you've already learned.
+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\`.
+Bare names used below for readability.
+
+## Stores
+
+- \`global\`: user preferences, personality, system environment (shared across projects)
+- Per-project stores: project-specific knowledge (auto-detected from git remote)
+- Use \`mcp__thatch__store_list\` to see active stores
+
+Memories can be scoped to a git branch via the \`branch\` param (feature design,
+WIP, PR status). Unscoped memories are project-wide and always included in search.
+
+## Session Startup
+
+1. \`memory_recall\` "user preferences and personality" (global store)
+2. \`memory_recall\` "project architecture and conventions" (project store)
+3. If on a non-main branch, \`memory_recall\` with the branch name
+4. \`memory_list\` and \`store_list\` to see what's available
+
+Before diving into code, \`memory_recall\` with a query relevant to the area
+you're working in. Prior sessions may have already investigated it.
+
+## When to Write
+
+**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.
+
+## What to Store
+
+- **Global store**: user observations, agent personality, system environment
+- **Project store**: repo organization, infrastructure, languages/frameworks,
+  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.
+
+## How to Write
+
+- \`memory_recall\` first to check for duplicates. Use overwrite: true to
+  update rather than creating a new entry.
+- One topic per memory. Write for a future instance with zero current context.
+- Confidence 1-2: single signal. 5-6: moderate. 9: explicitly stated.
+  10: hard constraint.
+
+## What NOT to Store
+
+Session-specific context, incomplete/unverified info, anything already in
+AGENTS.md, speculative conclusions.
+
+## Explicit Requests
+
+"Remember X" — save immediately.
+"Forget X" — \`memory_recall\` to find it, then \`memory_forget\`.`;
+}
+
+// ---------------------------------------------------------------------------
+// Prompt-aware recall nudge — fires when the user's prompt semantically
+// matches existing memories. Injected via opencode's chat.message hook
+// (in-process, warm model) or via the sideband socket for Claude Code/Cursor
+// (flush-tools CLI subcommand).
+// ---------------------------------------------------------------------------
+
+export interface NudgeMatch {
+  label: string;
+  score: number;
+}
+
+/**
+ * The recall nudge for the opencode plugin path. Uses the thatch_ tool prefix
+ * since opencode discovers tools directly from the plugin registration.
+ */
+export function recallNudge(matches: NudgeMatch[]): string {
+  return formatRecallNudge(matches, "thatch_memory_recall");
+}
+
+/**
+ * The recall nudge for the Claude Code / Cursor hook path. Uses the bare tool
+ * name (memory_recall) since the mcp__thatch__ prefix is verbose and the
+ * CLAUDE.md / AGENTS.md instructions already establish the bare-name convention.
+ */
+export function claudeRecallNudge(matches: NudgeMatch[]): string {
+  return formatRecallNudge(matches, "memory_recall");
+}
+
+function formatRecallNudge(matches: NudgeMatch[], toolName: string): string {
+  const n = matches.length;
+  const word = n === 1 ? "memory" : "memories";
+  const verb = n === 1 ? "relates" : "relate";
+  const labels = matches.slice(0, 2).map((m) => `"${m.label}"`).join(", ");
+  const etc = n > 2 ? ", etc." : "";
+  return `[thatch] ${n} ${word} ${verb} to this prompt (${labels}${etc}). Use ${toolName} before responding.`;
+}

package/src/setup.ts

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { claudeInstructions } from "./prompts";
+import { claudeInstructions, cursorInstructions } from "./prompts";
 import { installSkills, type SkillFile } from "./skills";
 
 // ---------------------------------------------------------------------------
@@ -91,17 +91,26 @@ function writeMcpConfig(path: string, thatchBin: string): void {
 // ---------------------------------------------------------------------------
 
 const THATCH_MARKER = "# Persistence\n\nThatch provides persistent memory across Claude Code sessions.";
+const THATCH_END_MARKER = '"Forget X" — `memory_recall` to find it, then `memory_forget`.';
+const CURSOR_MARKER = "# Persistence\n\nThatch provides persistent memory across Cursor sessions.";
+const CURSOR_END_MARKER = THATCH_END_MARKER;
 
-function appendInstructions(path: string): void {
-  const instructions = claudeInstructions() + "\n";
-
+/**
+ * Idempotently append (or replace) a block of instructions in a markdown file.
+ * The block is delimited by startMarker and endMarker so re-running setup
+ * updates drifted content without clobbering surrounding text.
+ */
+function appendBlock(
+  path: string,
+  instructions: string,
+  startMarker: string,
+  endMarker: string,
+): void {
   if (existsSync(path)) {
     const existing = readFileSync(path, "utf8");
-    if (existing.includes(THATCH_MARKER)) {
-      // Already has thatch instructions — replace the block.
-      const startIdx = existing.indexOf("# Persistence\n\nThatch provides persistent memory across Claude Code sessions.");
+    if (existing.includes(startMarker)) {
+      const startIdx = existing.indexOf(startMarker);
       if (startIdx >= 0) {
-        const endMarker = '"Forget X" — `memory_recall` to find it, then `memory_forget`.';
         const endIdx = existing.indexOf(endMarker, startIdx);
         if (endIdx >= 0) {
           const afterEnd = endIdx + endMarker.length;
@@ -122,6 +131,14 @@ function appendInstructions(path: string): void {
   }
 }
 
+function appendInstructions(path: string): void {
+  appendBlock(path, claudeInstructions() + "\n", THATCH_MARKER, THATCH_END_MARKER);
+}
+
+function appendCursorInstructions(path: string): void {
+  appendBlock(path, cursorInstructions() + "\n", CURSOR_MARKER, CURSOR_END_MARKER);
+}
+
 // ---------------------------------------------------------------------------
 // settings.json — hook installation
 // ---------------------------------------------------------------------------
@@ -257,3 +274,149 @@ export function setupClaudeCode(
       : null,
   };
 }
+
+// ---------------------------------------------------------------------------
+// Cursor setup — .cursor/mcp.json, AGENTS.md, .cursor/hooks.json, skills
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the Cursor config directory. Cursor stores config under `~/.cursor`
+ * by default. No documented env override exists (unlike Claude Code's
+ * CLAUDE_CONFIG_DIR), but we honor a hypothetical CURSOR_CONFIG_DIR for
+ * symmetry and forward-compatibility.
+ */
+function cursorConfigDir(homeDir: string): string {
+  return process.env.CURSOR_CONFIG_DIR ?? join(homeDir, ".cursor");
+}
+
+interface CursorSetupPaths {
+  mcpConfigPath: string;
+  agentsMdPath: string;
+  hooksPath: string;
+  skillsDir: string;
+  global: boolean;
+}
+
+function resolveCursorPaths(global: boolean, projectDir: string, homeDir: string): CursorSetupPaths {
+  const configDir = cursorConfigDir(homeDir);
+  const skillsDir = join(configDir, "skills");
+
+  if (global) {
+    return {
+      // Cursor's global MCP config is a simple file — no equivalent of
+      // `claude mcp add --scope user`. Writing ~/.cursor/mcp.json is enough.
+      mcpConfigPath: join(configDir, "mcp.json"),
+      agentsMdPath: join(configDir, "AGENTS.md"),
+      hooksPath: join(configDir, "hooks.json"),
+      skillsDir,
+      global: true,
+    };
+  }
+
+  return {
+    mcpConfigPath: join(projectDir, ".cursor", "mcp.json"),
+    agentsMdPath: join(projectDir, "AGENTS.md"),
+    hooksPath: join(projectDir, ".cursor", "hooks.json"),
+    skillsDir,
+    global: false,
+  };
+}
+
+/**
+ * Cursor hooks use a flat format (no nesting, no `type` field):
+ * { "version": 1, "hooks": { "event": [{ "command": "..." }] } }
+ */
+interface CursorHooksJson {
+  version: number;
+  hooks: {
+    [event: string]: { command: string }[];
+  };
+  [key: string]: unknown;
+}
+
+function writeCursorHooks(path: string, thatchBin: string): void {
+  let config: CursorHooksJson = { version: 1, hooks: {} };
+  if (existsSync(path)) {
+    try {
+      config = JSON.parse(readFileSync(path, "utf8"));
+    } catch {
+      // Corrupt — start fresh.
+    }
+  }
+  if (!config.version) config.version = 1;
+  if (!config.hooks) config.hooks = {};
+
+  // --json makes reminder output { additional_context: "..." } which Cursor
+  // injects into the session. Without --json, stdout is plain text (Claude
+  // Code style) and Cursor would not parse it.
+  const sessionStartCmd = `${thatchBin} reminder --json`;
+  // postToolUse fires per-tool (Cursor has no PostToolBatch equivalent).
+  // Silent — no stdout — so the agent loop is not delayed.
+  const bufferCmd = `${thatchBin} buffer-tool`;
+  // beforeSubmitPrompt is Cursor's UserPromptSubmit equivalent. Drains the
+  // queue and prints the extraction nudge as JSON additional_context.
+  const flushCmd = `${thatchBin} flush-tools --json`;
+
+  config.hooks.sessionStart = replaceCursorThatchHooks(config.hooks.sessionStart ?? [], sessionStartCmd);
+  config.hooks.postToolUse = replaceCursorThatchHooks(config.hooks.postToolUse ?? [], bufferCmd);
+  config.hooks.beforeSubmitPrompt = replaceCursorThatchHooks(config.hooks.beforeSubmitPrompt ?? [], flushCmd);
+
+  mkdirSync(join(path, ".."), { recursive: true });
+  writeFileSync(path, JSON.stringify(config, null, 2) + "\n");
+}
+
+function replaceCursorThatchHooks(
+  entries: { command: string }[],
+  command: string,
+): { command: string }[] {
+  const filtered = entries.filter((e) => !e.command?.includes("thatch"));
+  filtered.push({ command });
+  return filtered;
+}
+
+export interface CursorSetupResult {
+  mcpConfig: string;
+  agentsMd: string;
+  hooks: string;
+  skills: SkillFile[];
+  global: boolean;
+}
+
+/**
+ * Installs thatch into Cursor. Writes .cursor/mcp.json (or ~/.cursor/mcp.json
+ * for global), appends instructions to AGENTS.md, installs sessionStart +
+ * postToolUse + beforeSubmitPrompt hooks in .cursor/hooks.json, and installs
+ * skill files. All operations are idempotent.
+ *
+ * Cursor's global MCP config is a simple file write (unlike Claude Code which
+ * needs `claude mcp add --scope user`). Skills install to ~/.cursor/skills/
+ * (auto-discovered by Cursor, which also reads ~/.claude/skills/ for compat).
+ *
+ * @param thatchBin Absolute path to the thatch binary
+ * @param global Whether to install globally or project-locally
+ * @param projectDir The project directory (used for project-local installs)
+ * @param homeDir Home directory (defaults to os.homedir())
+ */
+export function setupCursor(
+  thatchBin: string,
+  global: boolean,
+  projectDir: string,
+  homeDir?: string,
+): CursorSetupResult {
+  const { homedir } = require("node:os");
+  const home = homeDir ?? homedir();
+  const paths = resolveCursorPaths(global, projectDir, home);
+
+  writeMcpConfig(paths.mcpConfigPath, thatchBin);
+  appendCursorInstructions(paths.agentsMdPath);
+  writeCursorHooks(paths.hooksPath, thatchBin);
+  const skills = installClaudeSkills(paths.skillsDir);
+
+  return {
+    mcpConfig: paths.mcpConfigPath,
+    agentsMd: paths.agentsMdPath,
+    hooks: paths.hooksPath,
+    skills,
+    global,
+  };
+}