@jeffober/thatch 0.1.5 → 0.1.6

package/docs/qa/use-cases/UC-006-cursor-hook-lifecycle.md

@@ -0,0 +1,31 @@
+# UC-006: Cursor hook lifecycle
+
+**Preconditions**
+- `thatch setup --cursor` has run; `.cursor/mcp.json` registers the thatch MCP server
+- A store with at least one memory (for the recall tier)
+
+**Steps**
+1. Start a Cursor agent session; the MCP server boots and opens its sideband socket.
+2. Have the agent run a non-thatch tool (e.g. read a file). The `postToolUse` hook runs
+   `thatch buffer-tool`, reading Cursor's stdin (`conversation_id`), and appends one
+   interaction to the session's queue file. Stdout is empty.
+3. Have the agent run a thatch tool (`mcp__thatch__memory_list`). The hook fires but filters
+   it out — nothing is appended.
+4. Submit a prompt. The `beforeSubmitPrompt` hook runs `thatch flush-tools --json`.
+5. Submit the next prompt with no fresh tool activity since step 4.
+
+**Expected**
+- `buffer-tool` normalizes `conversation_id` to a safe session file name and appends exactly one
+  interaction per call; thatch's own `mcp__thatch__*` tools never enter the queue (no self-echo).
+- `flush-tools` drains the queue first (extraction tier): prints the JSON payload wrapped for
+  Cursor as `additional_context`, and **deletes the queue file** so the next call carries no
+  repeat payload unless new tool activity happened.
+- With the queue empty and the sideband socket live, a semantically matching prompt yields a
+  recall nudge using the bare `memory_recall` tool name; below `THATCH_RECALL_THRESHOLD`
+  (default 0.55), no nudge.
+- `buffer-tool` and `flush-tools --json` output is the shape Cursor's `additional_context`
+  field consumes.
+
+_Automatable: partial — the `buffer-tool` and `flush-tools --json` CLI contracts are fully
+automatable; the live Cursor agent loop (booting the MCP server, the agent acting on a nudge)
+is manual._

package/docs/qa/use-cases/UC-007-recall-nudge.md

@@ -0,0 +1,31 @@
+# UC-007: Prompt-aware recall nudge
+
+**Preconditions**
+- A store with a memorable fact, e.g. "staging DB at staging-db.internal:5432"
+- An opencode session AND (separately) a Claude Code / Cursor session with the MCP server
+  running and the sideband socket live
+
+**Steps**
+
+**opencode path**
+1. Send a prompt matching the memory, e.g. "where does staging data live?"
+2. Send an unrelated prompt.
+3. Send a prompt shorter than 10 characters.
+
+**Claude Code / Cursor path**
+4. With the MCP server running and the sideband socket live, send a matching prompt (queue empty).
+5. Stop the MCP server; send a matching prompt.
+
+**Expected**
+- opencode: the `chat.message` hook embeds the prompt text (skipped when shorter than 10 chars),
+  searches `db.search([repo, global])`; a match at or above 0.55 pushes a synthetic nudge part
+  with labels and scores (singular wording for one match; up to two labels plus "etc." for more).
+- No match above threshold produces no nudge.
+- The nudge uses `db.search`, not `db.recall`, so **no recall telemetry is stamped** — usage
+  tracking fires only on explicit `thatch_memory_recall` / CLI `search`, not on nudges.
+- Claude Code / Cursor: `flush-tools` asks the warm MCP server via the sideband socket; the
+  returned labels become a nudge using the bare `memory_recall` name. With the MCP server down,
+  the recall nudge is absent (UC-009 covers the write-nudge fallback).
+
+_Automatable: partial — the sideband embed + search round-trip and threshold logic are
+unit-tested in `sideband.test.ts`; a live agent observing and acting on the nudge is manual._

package/docs/qa/use-cases/UC-008-hygiene-heartbeat.md

@@ -0,0 +1,26 @@
+# UC-008: Hygiene heartbeat
+
+**Preconditions**
+- A store with: one memory not updated or recalled in 90+ days; one memory scoped to a git
+  branch that no longer exists; two near-duplicate memories (similarity > 0.85)
+- A second, clean store for the negative case
+
+**Steps**
+1. `thatch hygiene` (from the repo)
+2. `thatch reminder` (Claude Code hook shape) and `thatch reminder --json` (Cursor)
+3. Start an opencode session and a Claude Code / Cursor session (the session-start path)
+4. Run the same commands from a directory that is **not** a git repo
+
+**Expected**
+- The report names three signals — pending duplicate pairs, stale-memory count, orphaned-branch
+  memory count — and **only the non-zero ones**. A fully healthy store prints "Store is healthy."
+  (or `null`) and the reminder omits the hygiene block entirely.
+- Both `reminder` shapes fold the hygiene block into the session-start text only when it is non-null.
+- Outside a git repo, the orphaned-branch check is **skipped** — a missing branch list would
+  otherwise make everything look orphaned; stale and dup signals still report.
+- Signals are advisory: thatch never deletes or merges memories itself. The agent acts on the
+  nudge to fix the store, by the same `memory_forget` / `dedup_mark_checked` tools as UC-002.
+
+_Automatable: yes — `thatch hygiene` and `hygieneReport()` are pure functions over the DB and
+git state (`hygiene.test.ts` covers the unit contract); the live session-injection path is
+manual._

package/docs/qa/use-cases/UC-009-flush-tools-tiers.md

@@ -0,0 +1,31 @@
+# UC-009: flush-tools tier priority and sideband degradation
+
+**Preconditions**
+- A Claude Code / Cursor session; `.mcp.json` and hooks installed
+- At least one memory for the recall tier to match
+- For the failure modes: a way to stop the MCP server and to leave a stale socket file
+
+**Steps**
+1. Put buffered non-thatch tool interactions in the queue (via `buffer-tool` / `buffer-batch`),
+   then run `thatch flush-tools --json`.
+2. With the queue empty and the MCP server running, send a prompt matching a memory (recall tier),
+   then a prompt below threshold.
+3. Stop the MCP server; run `flush-tools` with an empty queue.
+4. Leave a stale socket file from a crashed MCP server; run `flush-tools`.
+5. Make the sideband server hang (> 2 s); run `flush-tools`.
+
+**Expected**
+- Tiers fire in strict priority — **extraction > recall > write** — at most one nudge per call:
+  - extraction: queue non-empty -> JSON payload, queue file deleted.
+  - recall: queue empty, socket live, match at or above `THATCH_RECALL_THRESHOLD` (default 0.55)
+    -> nudge with match labels; below threshold -> no nudge.
+  - write: socket unavailable, no matches, or socket error -> static
+    "did you learn anything worth persisting?" nudge.
+- Sideband failure **never blocks** the agent: server down, a stale socket file, and a > 2 s
+  timeout all degrade to the write nudge. A stale socket file left by a crash is cleaned up on
+  connection error.
+- `--json` wraps whichever nudge fires for Cursor's `additional_context`; plain stdout for Claude Code.
+
+_Automatable: yes — `flush-tools` is a deterministic CLI contract and sideband failure modes
+(server down, stale socket, timeout) plus tier ordering are filesystem/IPC only, with no LLM in
+the loop._

package/docs/qa/use-cases/UC-010-prime.md

@@ -0,0 +1,25 @@
+# UC-010: thatch prime
+
+**Preconditions**
+- Thatch installed and `bun` on PATH
+- At least one of: opencode (for `opencode run`), Cursor (`agent` CLI), or Claude Code
+  (`claude`) on PATH
+
+**Steps**
+1. From a project root, run `thatch prime`
+2. Let the selected child CLI run the `thatch-project-primer` skill to completion
+3. After it finishes, inspect the project store (`thatch list`)
+
+**Expected**
+- `prime` resolves the first available CLI in order — `opencode run`, then
+  `agent -p --approve-mcps` (Cursor), then `claude` — and spawns it with the project-primer
+  prompt.
+- The primer skill recalls existing memories first, investigates the codebase from multiple
+  angles, and writes foundational memories via `thatch_memory_remember` (project vs global
+  assignment per its own rules), then runs dedup afterward.
+- `prime` exits with the **child process's exit code** (0 on success).
+- If no supported CLI is on PATH, `prime` fails fast with a clear error rather than spawning
+  nothing.
+
+_Automatable: partial — the CLI dispatch selection (which child, which flags, exit-code
+pass-through) is automatable; the LLM's real investigation and memory writing are manual._

package/docs/qa/use-cases/UC-011-write-time-similarity-warning.md

@@ -0,0 +1,24 @@
+# UC-011: Write-time similarity warning
+
+**Preconditions**
+- A store with a memory, e.g. `API rate limit` -> "the API rate limit is 100 req/min"
+- A second, similar memory not yet saved
+
+**Steps**
+1. Save the second memory under a different label with similar content, without
+   `overwrite: true`.
+2. Read the tool's response.
+
+**Expected**
+- The save **succeeds** (`[saved] ...`) — the warning never blocks. The response
+  also carries a warning listing the existing memory with a similarity score and
+  instructions to reconcile.
+- Two reconciliation paths both work:
+  - Merge: `memory_remember` the merged content with `overwrite: true` on the
+    better label, then `memory_forget` the other. The survivor has the combined
+    content; the deleted label is gone.
+  - Mark distinct: `dedup_mark_checked` the pair as `unrelated`. A subsequent
+    `find_duplicates` no longer reports the pair.
+
+_Automatable: yes — the "save proceeds + warning lists similar entries" contract
+and both reconciliation paths are pure tool/DB calls with no LLM in the loop._

package/docs/qa/use-cases/UC-012-model-migration.md

@@ -0,0 +1,28 @@
+# UC-012: THATCH_MODEL migration (mixed embedding dimensions)
+
+**Preconditions**
+- A store with memories embedded by a model of dimension A (e.g. the default
+  384-dim `bge-small-en-v1.5`)
+- A second model available whose vectors have a **different** dimension
+
+**Steps**
+1. `export THATCH_MODEL=<other-model>` (different vector dimension).
+2. Start a fresh session. `memory_list` and `memory_show` an old memory by label.
+3. `memory_recall` for a topic that matches an old memory.
+4. Save a new memory with the new model; `memory_recall` for it.
+5. `memory_show` an old memory and inspect its `model` tag.
+
+**Expected**
+- `list` and `show` still return the old memories — the data is intact, **not
+  corrupted and not deleted**.
+- `recall` returns **no matches** for the old memories: entries whose vector
+  dimension differs from the query are skipped, not scored. This is a silent
+  skip, not an error.
+- The new memory embeds at the new dimension and is recallable.
+- `show` reveals the old memories carry the old model tag while new ones carry
+  the new tag. There is **no automatic re-embedding** — old memories stay
+  invisible to search until re-saved.
+
+_Automatable: yes — dimension-skip and data-intact assertions are pure DB calls;
+use two `MockEmbeddingModel` instances with different dimensions (no network, no
+real model download)._

package/docs/qa/use-cases/UC-013-compaction-context.md

@@ -0,0 +1,25 @@
+# UC-013: Compaction context (opencode-only)
+
+**Preconditions**
+- An opencode session that grows long enough to trigger context compaction
+- Several memories already stored in the repo's store
+
+**Steps**
+1. Work in the session until opencode compacts the context window.
+2. Inspect the compaction output.
+3. After compaction, ask the agent something that should use a memory tool.
+
+**Expected**
+- The compaction output includes the thatch re-familiarization context block
+  pushed by `experimental.session.compacting` — it reminds the agent that
+  `thatch_memory_recall` exists and that memories persist.
+- After compaction, the agent still knows the memory tools exist and uses them
+  (it does not "forget" thatch just because the window was summarized).
+- This behavior is **opencode-only**. Claude Code's `PostCompact` hook is
+  side-effects only and cannot inject context; Cursor has no equivalent hook.
+  See `docs/dev/mcp-parity.md` for the gap and its mitigation (CLAUDE.md /
+  AGENTS.md persists through compaction; the `SessionStart` recall reminder
+  runs again after compaction in Claude Code).
+
+_Automatable: no — requires a live opencode compaction event. The hook's string
+content is unit-tested, but actual compaction injection is manual._

package/docs/qa/use-cases/UC-014-skill-install-drift.md

@@ -0,0 +1,28 @@
+# UC-014: Skill install and drift recovery
+
+**Preconditions**
+- Thatch installed; the host's skills directory empty
+- `bun` on PATH
+
+**Steps**
+1. `thatch setup --claude` (and/or start an opencode session, and/or
+   `thatch setup --cursor`).
+2. List the skills directory.
+3. Edit one `SKILL.md` file locally to introduce drift.
+4. Re-run `setup` (or restart opencode).
+5. Check whether the `thatch-code-review` coordinator skill is present.
+
+**Expected**
+- Claude Code and Cursor install exactly **10 shared skills** to the skills
+  dir — the coordinator (`thatch-code-review`) is **absent** (it needs
+  sub-agents, which those hosts lack).
+- opencode installs **11** — the 10 shared plus the coordinator.
+- The locally edited `SKILL.md` is **overwritten** with the canonical content
+  on the next `setup`/init (drift detection: a file is only rewritten when its
+  content differs from the definition). Unrelated skill files are untouched.
+- Skills never land in the worktree — always under the user-scoped config dir
+  (`~/.claude/skills`, `~/.cursor/skills`, `$XDG_CONFIG_HOME/opencode/skills`).
+
+_Automatable: yes — file presence, count (10 vs 11), content-diff-overwrite, and
+coordinator host-gating are all file assertions (`setup.test.ts` already covers
+the unit contract)._

package/docs/qa/use-cases/UC-015-env-override-matrix.md

@@ -0,0 +1,28 @@
+# UC-015: Environment variable override matrix
+
+**Preconditions**
+- Writable temp directories; `bun` on PATH
+
+**Steps**
+Set each variable and confirm the effect at the documented resolution point.
+
+| Variable | Set to | Expected effect |
+|----------|--------|------------------|
+| `THATCH_DB_PATH` | a temp file path | the SQLite DB is created there (CLI + plugin + MCP) |
+| `XDG_CONFIG_HOME` | a temp dir | the default DB (`$XDG_CONFIG_HOME/thatch/thatch.db`) and opencode skill dir move there; the real `~/.config` is untouched |
+| `CLAUDE_CONFIG_DIR` | a temp dir | `thatch setup --claude --global` writes CLAUDE.md, settings.json, and skills under that dir; project-local keeps project paths but skills under the custom dir |
+| `THATCH_QUEUE_DIR` | a temp dir | extraction-queue JSONL files land there instead of `$XDG_CACHE_HOME/thatch/queue` |
+| `THATCH_RECALL_THRESHOLD` | a low value (e.g. `0.2`) | the prompt-aware recall nudge fires for weaker matches (a prompt that matched nothing at 0.55 now surfaces results) |
+| `THATCH_MODEL` | a different model name | new memories carry the new model tag and vector dimension; old memories become invisible to search (see UC-012) |
+
+**Expected**
+- Each override takes effect at the point the docs describe (see
+  `docs/dev/setup-and-hooks.md` and the dev README config section). None require
+  a restart beyond the process that reads them.
+- `THATCH_DB_PATH` and `XDG_CONFIG_HOME` change the **same** sideband socket
+  path (it is a hash of the resolved DB path) — so a hook process and the MCP
+  server must both resolve the same DB path or they miss each other.
+
+_Automatable: yes — env resolution is deterministic and side-effect-free;
+`setup.test.ts` already covers `CLAUDE_CONFIG_DIR`; the rest follow the same
+shape._

package/docs/qa/use-cases/UC-016-concurrent-session-isolation.md

@@ -0,0 +1,36 @@
+# UC-016: Concurrent session isolation
+
+**Preconditions**
+- Two opencode sessions in the same repo (A and B)
+- (Separately) two Claude Code / Cursor hook processes with different session IDs
+
+**Steps**
+
+**opencode (in-memory buffer)**
+1. In session A, run a non-thatch tool (the extraction ring buffer records it).
+2. In session B, send a message — `chat.message` runs.
+3. In session A, send a message — `chat.message` runs.
+
+**Claude Code / Cursor (file-backed queue)**
+4. Hook process for session A calls `buffer-tool`/`buffer-batch`.
+5. Hook process for session B calls `buffer-tool`/`buffer-batch`.
+6. `flush-tools` is invoked for session A, then for session B.
+
+**Sideband (shared warm model)**
+7. Both sessions' `flush-tools` connect to the same sideband socket.
+
+**Expected**
+- **No cross-session bleed** in either path: session B's `chat.message` produces
+  no nudge from session A's buffered interaction; session B's message only sees
+  its own buffer. The in-memory `ExtractionPipeline` and the file-backed queue are
+  both keyed by session ID.
+- `flush-tools` for session A drains only A's queue file and deletes it; a second
+  flush for A is empty. Session B's queue file is untouched and drains on its own
+  flush.
+- The sideband socket is **shared** (one warm MCP server) but **stateless per
+  query**: each request embeds a fresh prompt and returns its own matches. Two
+  concurrent match requests do not interfere.
+
+_Automatable: yes — `extraction.test.ts` (in-memory per-session) and
+`extract-queue.test.ts` (file-backed per-session) already cover isolation; the
+sideband is a stateless request/response so concurrency is trivially safe._

package/docs/qa/use-cases/UC-017-buffer-tool-vs-buffer-batch.md

@@ -0,0 +1,27 @@
+# UC-017: buffer-tool vs buffer-batch contract
+
+**Preconditions**
+- A Claude Code setup (`PostToolBatch` -> `buffer-batch`) and a Cursor setup
+  (`postToolUse` -> `buffer-tool`)
+
+**Steps**
+1. **Claude Code**: a `PostToolBatch` fires with a `tool_calls` array (several
+   tools, one a `mcp__thatch__*` call) and a `session_id`.
+2. **Cursor**: a `postToolUse` fires for a single tool with a `conversation_id`.
+3. Run `flush-tools` for both.
+
+**Expected**
+- `buffer-batch` (Claude Code) reads the `tool_calls` array and `session_id`,
+  appends all interactions to the session's JSONL queue, filters out
+  `mcp__thatch__*` calls, and caps at 20 (oldest dropped). It is **silent**.
+- `buffer-tool` (Cursor) reads **one** tool call, normalizes `conversation_id`
+  to a safe filename (unsafe chars -> underscore), appends that single
+  interaction, filters `mcp__thatch__*`, same 20 cap. Also silent.
+- Both write the same `ToolInteraction` shape to the same JSONL format, so
+  `flush-tools` drains them identically and `buildExtractionPayload` produces an
+  identical contract for the fact-extractor skill.
+- Thatch's own tools never appear in either queue (no self-echo feedback loop).
+
+_Automatable: yes — `extract-queue.test.ts` covers both shapes (batch with
+`tool_calls` and single-tool), the `mcp__thatch__*` filter, the 20 cap, and
+back-compat with `buildExtractionPayload`._

package/docs/user/README.md

@@ -1,10 +1,14 @@
 # Thatch
 
-Persistent memory for opencode. Thatch gives your AI agent the ability to
-remember information across sessions using local embeddings and SQLite.
+Persistent memory for AI coding agents. Thatch gives your agent the ability to
+remember information across sessions using local embeddings and SQLite. It
+works with **OpenCode** (as a plugin), **Claude Code** (as an MCP server), and
+**Cursor** (as an MCP server).
 
 ## Installation
 
+### OpenCode
+
 Publish to npm and add thatch to your opencode config:
 
 ```jsonc
@@ -24,6 +28,36 @@ For local development before publishing, use a file path:
 
 Or place the thatch repo in `.opencode/plugins/` for auto-loading.
 
+### Claude Code
+
+Install the MCP server, hooks, instructions, and skills into Claude Code:
+
+```bash
+thatch setup --claude            # project-local (writes .mcp.json, CLAUDE.md, .claude/)
+thatch setup --claude --global   # user-scoped (~/.claude/)
+```
+
+`bun` must be on PATH (the thatch binary runs under bun). `setup` is idempotent
+— re-running it updates drifted content without clobbering unrelated config.
+For a global install, `setup` prints the `claude mcp add --scope user` command
+to run instead of writing a project `.mcp.json`.
+
+### Cursor
+
+```bash
+thatch setup --cursor            # project-local (.cursor/mcp.json, AGENTS.md, .cursor/hooks.json)
+thatch setup --cursor --global   # user-scoped (~/.cursor/)
+```
+
+Cursor has no `claude mcp add` equivalent — `setup` writes `~/.cursor/mcp.json`
+directly. Hook output is JSON-wrapped (`--json`) so Cursor injects it as
+`additional_context`.
+
+### Before running setup
+
+The `thatch` binary must resolve `bun` on PATH. Install from npm (`npm i -g
+@jeffober/thatch`) or from a checkout (`bun run bin/thatch`).
+
 ## How it works
 
 ### Stores
@@ -84,8 +118,9 @@ Beyond the tools, thatch hooks into opencode itself:
 
 On startup thatch installs [skills] into your global opencode config
 (`~/.config/opencode/skills/`, or `$XDG_CONFIG_HOME/opencode/skills`).
-When using `thatch setup --claude`, skills are installed to `~/.claude/skills/`
-(or `$CLAUDE_CONFIG_DIR/skills/`).
+With `thatch setup --claude`, skills install to `~/.claude/skills/` (or
+`$CLAUDE_CONFIG_DIR/skills/`); with `thatch setup --cursor`, to
+`~/.cursor/skills/`.
 
 ### Memory skills
 
@@ -129,13 +164,13 @@ Five specialist review lenses, each a self-contained static-analysis pass:
 For a **quick single-lens review**, load any specialist skill directly and
 point it at a branch or commit range:
 
-```
+```text
 Load thatch-review-pedantic and review the changes on this branch.
 ```
 
 For a **full multi-specialist review on opencode**, load the coordinator:
 
-```
+```text
 Load thatch-code-review and review branch feature-x.
 ```
 
@@ -145,7 +180,7 @@ specialist lens), and synthesize a final report.
 For a **full review on Claude Code** (or without the coordinator), run each
 specialist in sequence, then synthesize:
 
-```
+```text
 1. Load thatch-review-pedantic, review branch feature-x, report findings.
 2. Load thatch-review-acceptance, review the same branch.
 3. ... repeat for state-flow, no-slop, breadcrumbs ...

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.1.5",
-  "description": "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).",
+  "version": "0.1.6",
+  "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",
   "types": "src/index.ts",
@@ -28,6 +28,7 @@
   "devDependencies": {
     "@opencode-ai/plugin": "^1.17.13",
     "@types/bun": "latest",
+    "markdownlint-cli2": "^0.23.0",
     "typescript": "^5.7.0"
   },
   "peerDependencies": {

package/src/db.ts

@@ -234,9 +234,12 @@ export class ThatchDB {
   /**
    * Brute-force cosine similarity search across the given stores.
    * When branch is specified, includes project-wide (branch IS NULL) plus
-   * branch-specific entries.
+   * branch-specific entries. Does NOT stamp recall telemetry — the prompt-aware
+   * nudge uses this to check whether memories relate to a prompt without
+   * polluting recall_count/last_recalled_at (the agent hasn't actually read
+   * them yet, only the plugin has checked for relevance).
    */
-  recall(
+  search(
     stores: string[],
     queryEmbedding: Float32Array,
     opts?: { branch?: string; limit?: number },
@@ -281,10 +284,21 @@ export class ThatchDB {
     });
 
     scored.sort((a, b) => b._score - a._score);
-    const top = scored.slice(0, limit);
+    return scored.slice(0, limit);
+  }
+
+  /**
+   * Semantic recall for agent-initiated searches. Delegates to search() for
+   * cosine scoring, then stamps recall telemetry — retrieval is the "used
+   * recently" signal hygiene reporting keys on.
+   */
+  recall(
+    stores: string[],
+    queryEmbedding: Float32Array,
+    opts?: { branch?: string; limit?: number },
+  ): (MemoryRow & { _score: number })[] {
+    const top = this.search(stores, queryEmbedding, opts);
 
-    // Recall telemetry: retrieval is the "used recently" signal hygiene
-    // reporting keys on, so returned rows get stamped here.
     if (top.length > 0) {
       const now = new Date().toISOString();
       const rowKeys = top.map(() => "(?, ?)").join(", ");

package/src/git.ts

@@ -54,7 +54,7 @@ const URL_PATTERNS: UrlPattern[] = [
  * 3. Fall back to the directory basename
  */
 export async function detectRepo(cwd?: string): Promise<string> {
-  const dir = cwd ?? process.cwd();
+  const dir = cwd ?? process.env.CURSOR_PROJECT_DIR ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
 
   try {
     const remote = await $`git remote get-url origin`.cwd(dir).quiet();

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.
@@ -72,27 +83,62 @@ 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).
     "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 (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