@jeffober/thatch 0.1.28 → 0.1.30

package/docs/dev/features/database.md

@@ -0,0 +1,244 @@
+# Database
+
+Thatch stores all data in a single SQLite file. The schema has 11 tables organized around three concerns: memory entries, the prediction engine, and the behavior engine.
+
+## Configuration
+
+- Default path: `$XDG_CONFIG_HOME/thatch/thatch.db` (override via `THATCH_DB_PATH`)
+- PRAGMAs: `journal_mode=WAL`, `busy_timeout=5000`, `foreign_keys=ON`
+- Single file, no external services
+
+## Schema overview
+
+11 tables in three groups:
+
+| Group | Tables | Purpose |
+|-------|--------|---------|
+| Memory | `stores`, `entries`, `dedup_pairs` | Core memory CRUD + dedup verdicts |
+| Prediction engine | `prediction_matchers`, `predictions`, `prediction_edges`, `prediction_provenance` | User decision model |
+| Behavior engine | `behavior_matchers`, `behaviors`, `behavior_edges`, `behavior_provenance` | LLM self-discipline rules |
+
+The prediction and behavior engines share the same four-table shape (matchers, items, edges, provenance) with different table names. They are separate because the semantics differ: predictions model what the user wants; behaviors model what the LLM should do.
+
+## Memory tables
+
+### stores
+
+Registry of all store names. The `global` store is inserted automatically at schema init.
+
+```sql
+stores(name TEXT PRIMARY KEY)
+```
+
+### entries
+
+The core table. Memory entries with embeddings, metadata, and usage telemetry.
+
+```sql
+entries(
+  slug TEXT NOT NULL,
+  store TEXT NOT NULL REFERENCES stores(name),
+  label TEXT NOT NULL,
+  content TEXT NOT NULL,
+  embedding BLOB,
+  model TEXT,
+  branch TEXT,
+  confidence INTEGER,
+  archived INTEGER NOT NULL DEFAULT 0,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  recall_count INTEGER NOT NULL DEFAULT 0,
+  last_recalled_at TEXT,
+  PRIMARY KEY (slug, store)
+)
+```
+
+- `slug`: derived from label via `slugify()`. Unicode letters/digits preserved. All-symbol labels fall back to hash.
+- `embedding`: raw Float32Array bytes. Null if not yet embedded.
+- `model`: embedding model tag (informational; dimension is the real discriminator).
+- `branch`: git branch scope. Null = project-wide.
+- `confidence`: 1-10 scale. Null = unset.
+- `archived`: 0 = live, 1 = archived. Search, dedup, and staleness queries all exclude archived by default.
+- `recall_count` / `last_recalled_at`: usage telemetry, stamped by `db.recall()` (not `db.search()`).
+
+### dedup_pairs
+
+Records which duplicate-candidate pairs have been reviewed.
+
+```sql
+dedup_pairs(
+  store TEXT NOT NULL,
+  slug_a TEXT NOT NULL,
+  slug_b TEXT NOT NULL,
+  status TEXT NOT NULL,
+  checked_at TEXT NOT NULL,
+  PRIMARY KEY (store, slug_a, slug_b)
+)
+```
+
+- Slugs stored sorted (a < b) for canonical matching.
+- `status`: "duplicate", "supplement", "contradiction", or "unrelated".
+- Overwriting or forgetting either memory clears the verdict (DELETE in `remember()` and `forgetEntry()`).
+
+## Prediction engine tables
+
+### prediction_matchers
+
+Situation descriptions that trigger predictions. Embedded, cosine-matched at `chat.message`.
+
+```sql
+prediction_matchers(
+  id TEXT PRIMARY KEY,
+  store TEXT NOT NULL REFERENCES stores(name),
+  description TEXT NOT NULL,
+  embedding BLOB,
+  model TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+)
+```
+
+### predictions
+
+User preference predictions with Bayesian confidence.
+
+```sql
+predictions(
+  id TEXT PRIMARY KEY,
+  store TEXT NOT NULL REFERENCES stores(name),
+  statement TEXT NOT NULL,
+  rationale TEXT,
+  embedding BLOB,
+  model TEXT,
+  confidence REAL NOT NULL DEFAULT 0.5,
+  confirm_count REAL NOT NULL DEFAULT 0,
+  disconfirm_count REAL NOT NULL DEFAULT 0,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+)
+```
+
+- `confidence`: Bayesian posterior. `p = (confirm + K*P0) / (confirm + disconfirm + K)`, K=5, P0=0.5.
+- `confirm_count` / `disconfirm_count`: REAL (fractional for soft signals, weight 0.25).
+
+### prediction_edges
+
+Many-to-many links between matchers and predictions.
+
+```sql
+prediction_edges(
+  matcher_id TEXT NOT NULL REFERENCES prediction_matchers(id) ON DELETE CASCADE,
+  prediction_id TEXT NOT NULL REFERENCES predictions(id) ON DELETE CASCADE,
+  weight REAL NOT NULL DEFAULT 1.0,
+  created_at TEXT NOT NULL,
+  PRIMARY KEY (matcher_id, prediction_id)
+)
+```
+
+### prediction_provenance
+
+Audit trail of every signal applied to a prediction.
+
+```sql
+prediction_provenance(
+  id TEXT PRIMARY KEY,
+  prediction_id TEXT NOT NULL REFERENCES predictions(id) ON DELETE CASCADE,
+  signal TEXT NOT NULL,
+  detail TEXT,
+  created_at TEXT NOT NULL
+)
+```
+
+- `signal`: "confirm", "disconfirm", "soft", or "create".
+
+## Behavior engine tables
+
+Same shape as prediction engine, with behavior-specific semantics.
+
+### behavior_matchers
+
+```sql
+behavior_matchers(
+  id TEXT PRIMARY KEY,
+  store TEXT NOT NULL REFERENCES stores(name),
+  description TEXT NOT NULL,
+  embedding BLOB,
+  model TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+)
+```
+
+### behaviors
+
+```sql
+behaviors(
+  id TEXT PRIMARY KEY,
+  store TEXT NOT NULL REFERENCES stores(name),
+  statement TEXT NOT NULL,
+  rationale TEXT,
+  embedding BLOB,
+  model TEXT,
+  confidence REAL NOT NULL DEFAULT 0.5,
+  confirm_count REAL NOT NULL DEFAULT 0,
+  disconfirm_count REAL NOT NULL DEFAULT 0,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+)
+```
+
+### behavior_edges
+
+```sql
+behavior_edges(
+  matcher_id TEXT NOT NULL REFERENCES behavior_matchers(id) ON DELETE CASCADE,
+  behavior_id TEXT NOT NULL REFERENCES behaviors(id) ON DELETE CASCADE,
+  weight REAL NOT NULL DEFAULT 1.0,
+  created_at TEXT NOT NULL,
+  PRIMARY KEY (matcher_id, behavior_id)
+)
+```
+
+### behavior_provenance
+
+```sql
+behavior_provenance(
+  id TEXT PRIMARY KEY,
+  behavior_id TEXT NOT NULL REFERENCES behaviors(id) ON DELETE CASCADE,
+  signal TEXT NOT NULL,
+  detail TEXT,
+  created_at TEXT NOT NULL
+)
+```
+
+- `signal`: "confirm" (ham), "disconfirm" (spam), or "codify".
+
+## Schema migration
+
+`recall_count`, `last_recalled_at`, and `archived` are added to pre-existing databases by an idempotent column migration at init. The migration uses `PRAGMA table_info` to check for the column's existence, then `ALTER TABLE ADD COLUMN` if missing. This handles databases created before these columns existed.
+
+## Embedding serialization
+
+Embeddings are raw Float32Array bytes stored as BLOBs. Serialization honors `byteOffset`/`byteLength` — transformers.js can return views into larger tensor buffers, and serializing the whole backing buffer corrupts vectors. Always serialize the view's own bytes, not the underlying buffer.
+
+## Key invariants
+
+- Single SQLite file, WAL mode, 5s busy timeout, foreign keys ON.
+- Embedding spaces are discriminated by vector dimension, not model tag.
+- Embedding serialization honors `byteOffset`/`byteLength` (views into larger buffers).
+- Slugs are slugified labels; slug + store = composite PK.
+- Dedup verdicts auto-clear when either memory is overwritten or forgotten.
+- Archived memories excluded from search, dedup, and staleness by default.
+- Column migration is idempotent (`PRAGMA table_info` + `ALTER TABLE`).
+
+## Interactions with other features
+
+- Memory store ([memory-store.md](memory-store.md)): `entries` table is the core; `stores` table is the registry
+- Deduplication ([deduplication.md](deduplication.md)): `dedup_pairs` table tracks reviewed pairs
+- Prediction engine ([prediction-engine.md](prediction-engine.md)): 4 prediction tables
+- Behavior engine ([behavior-engine.md](behavior-engine.md)): 4 behavior tables
+- Hygiene ([hygiene.md](hygiene.md)): `staleEntryCount` uses `recall_count` and `last_recalled_at`; `branchesInStore` uses `branch` column
+
+## Source files
+
+- `src/db.ts` — all schema, CRUD, search, scoring, migrations

package/docs/dev/features/deduplication.md

@@ -0,0 +1,102 @@
+# Deduplication System
+
+Agent-driven detection and resolution of duplicate memories. The system
+surfaces candidates; the agent decides what to do.
+
+## What it does
+
+- `find_duplicates` tool: cosine similarity pairs, grouped into
+  connected-component clusters
+- `dedup_mark_checked` tool: records a pairwise verdict so `find_duplicates`
+  stops re-reporting
+- Automatic verdict clearing: overwriting either memory clears the verdict
+- `thatch-dedup-classifier` skill: classifies the relationship and reconciles
+  pairs
+
+## How it works
+
+### find_duplicates (tool)
+
+- Parameters: `store` (optional, default project store), `threshold`
+  (optional, default 0.85)
+- Finds memory pairs whose embeddings exceed the cosine similarity threshold
+- Groups related pairs into connected-component clusters: a cluster of 3+
+  labels usually means one topic fragmented across entries that should be
+  consolidated
+- Pairs already resolved via `dedup_mark_checked` are skipped
+- Output: clustered rendering — "Cluster of N:" then
+  `[score:N] labelA <-> labelB` lines
+- Read-only
+
+### dedup_mark_checked (tool)
+
+- Parameters: `label_a`, `label_b` (both required), `status` (one of
+  `duplicate`, `supplement`, `contradiction`, `unrelated`), `store` (optional)
+- Records a pairwise verdict so `find_duplicates` stops re-reporting that pair
+- Labels are slugified internally
+- Overwriting either memory later clears the verdict automatically
+  (DB-level: the `remember()` and `forgetEntry()` functions `DELETE` from
+  `dedup_pairs` for the affected slug)
+- Returns `[checked] store :: a <-> b -> status`
+
+### Verdict lifecycle
+
+1. `find_duplicates` surfaces a pair above threshold
+2. Agent loads the `thatch-dedup-classifier` skill
+3. Agent classifies the pair: `duplicate` (merge), `supplement` (keep both),
+   `contradiction` (resolve), `unrelated` (mark and ignore)
+4. For duplicates: agent merges via `memory_remember(overwrite: true)` +
+   `memory_forget` the other entry
+5. Agent calls `dedup_mark_checked` for the surviving pair
+6. Overwriting either memory clears the verdict → the pair can re-flag if the
+   merge created a new similarity
+
+### The dedup_pairs table
+
+- PK: `(store, slug_a, slug_b)` — slugs stored sorted (`a < b`) for canonical
+  matching
+- No FK to entries (slugs are compared by string, not by FK constraint)
+- Overwriting or forgetting an entry clears all verdicts involving that slug
+  (`DELETE` in `remember()` and `forgetEntry()`)
+
+### thatch-dedup-classifier skill
+
+- Shared skill (`artifacts/skills/thatch-dedup-classifier.md`)
+- Classifies the relationship between two similar memory entries
+- Provides a structured process: read both entries, compare content, decide
+  verdict, reconcile
+- Can be dispatched as a sub-agent by the extraction pipeline or loaded
+  directly by the agent
+
+## Interactions with other features
+
+- [Memory store](memory-store.md): `find_duplicates` searches stored memories;
+  merging uses `memory_remember(overwrite)` + `memory_forget`.
+- [Hygiene](hygiene.md): hygiene report counts pending dedup pairs (same
+  underlying `db.findDuplicates`).
+- Skills: `thatch-dedup-classifier` is the skill that guides the
+  reconciliation process.
+- [Extraction](extraction.md): extraction can trigger the dedup cycle when
+  write-time duplicate detection fires.
+
+## Source files
+
+- `src/db.ts` — `findDuplicates`, `markChecked`, `dedup_pairs` table
+- `src/tool-defs.ts` — 2 dedup tools (`find_duplicates`, `dedup_mark_checked`)
+- `artifacts/skills/thatch-dedup-classifier.md` — classifier skill
+
+## Database tables
+
+- `dedup_pairs(store, slug_a, slug_b, status, checked_at, PK(store, slug_a, slug_b))`
+
+## Key invariants
+
+- `find_duplicates` groups pairs into clusters (connected components). A
+  cluster of 3+ should be consolidated into one memory.
+- Verdicts are automatically cleared when either memory is overwritten or
+  forgotten. This is intended — a merge can create a new similarity that
+  should re-flag.
+- The threshold (0.85) is higher than the recall nudge threshold (0.55) because
+  "duplicate" is a stronger claim than "relates to".
+- Slugs in `dedup_pairs` are stored sorted (`a < b`) for canonical matching
+  regardless of argument order.

package/docs/dev/features/extraction.md

@@ -0,0 +1,253 @@
+# Extraction Pipeline
+
+Automated capture of durable facts from tool interactions. The agent does not
+need to remember to save — the system buffers tool calls and nudges the agent
+to extract memories from them.
+
+The facts most worth remembering overwhelmingly surface in tool call results
+(file contents, command output, API responses, git state) rather than in
+conversation prose. So tool calls serve as both the **trigger** and the
+**queue**. A fact that exists only in conversation never enters the buffer;
+the system prompt instructs the agent to call `thatch_memory_remember`
+directly for conversation-derived knowledge.
+
+## What it does
+
+- Buffers every non-`thatch_*`, non-`skill`, non-`task` tool call for later
+  extraction
+- Two paths: **direct extraction** via a child session (opencode, primary) and
+  **nudge-based extraction** (all hosts, fallback for opencode, primary for
+  MCP)
+- The extraction nudge escalates: polite (0–1 missed), insistent (2),
+  all-caps shouting (3+)
+- `thatch_get_extraction_payload` fetches queued interactions as JSON,
+  keeping the full payload out of the main session's context window
+- `thatch_extraction_done` acknowledges and quiets the nudge
+- AMQP-style buffer lifecycle for opencode: pending → accepted → completed,
+  with requeue on failure
+- File-backed JSONL queue for MCP hosts (no cross-call state)
+- Parent-child session drain: the child drains the parent's snapshot,
+  preserving interleaved-turn entries added after the snapshot was taken
+
+## How it works
+
+### Tool interaction buffering
+
+After every tool execution, non-`thatch_*`, non-`skill`, non-`task` tool
+calls are buffered for later extraction.
+
+**opencode** — `tool.execute.after` hook in `src/index.ts`:
+
+- In-memory ring buffer per session (`ExtractionPipeline` in
+  `src/extraction.ts`)
+- Max 20 interactions per session
+- For child sessions, also tracks new/updated/deleted metrics via
+  `childMetrics`
+- `tool.execute.after` is a **plugin hook, not a bus event**. Moving it into
+  the `event` handler silently never fires it — the event bus has no such
+  event
+- Filtering rationale: `thatch_*` tools would echo the store back into
+  itself; `skill`/`task` meta-tools would create a feedback loop (extraction
+  triggers a skill load, which gets buffered, which triggers another
+  extraction)
+
+**MCP hosts** — `bin/thatch`, `src/extract-queue.ts`:
+
+- Claude Code: `PostToolBatch` hook → `thatch buffer-batch` (reads JSON from
+  stdin: `{ session_id, tool_calls }`)
+- Cursor: `postToolUse` hook → `thatch buffer-tool` (reads JSON from stdin,
+  single tool, uses `conversation_id`)
+- File-backed JSONL queue under
+  `$XDG_CACHE_HOME/thatch/queue/<session>.jsonl` (max 20, oldest dropped)
+- Silent on success (no stdout) so the agent loop is not delayed
+- Filters the same tools as opencode (`mcp__thatch__memory_remember`,
+  `mcp__thatch__extraction_done`, `mcp__thatch__*`, `skill`, `task`, `agent`)
+
+### Direct extraction (opencode, primary path)
+
+When a parent session goes idle (`session.status` idle event) with pending
+buffer interactions:
+
+1. `triggerExtraction` adds the parent ID to the `extracting` set — this
+   suppresses the nudge in `chat.message`
+2. Peeks the buffer to count pending interactions
+3. Creates a child session via
+   `client.session.create({ parentID, title: "thatch-extraction" })`
+4. The `session.created` event fires, populating `childToParent` and
+   `parentSnapshots` (a snapshot of the full pending buffer at dispatch time)
+5. Adds the child ID to the `extractionChildren` set
+6. Prompts the child with `extractionDirectPrompt(count, sessionID)`
+7. If background sub-agents are enabled
+   (`OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS`): `promptAsync`. Otherwise:
+   fire-and-forget `prompt`
+8. On prompt failure: `cleanupChild` removes the child from all maps and
+   deletes the child session
+
+The child session then:
+
+- Calls `thatch_get_extraction_payload` to fetch the queued interactions
+- Runs the [thatch-fact-extractor](../skills.md) skill
+- Writes memories via `thatch_memory_remember`
+- Goes idle
+
+On child idle (`session.status` idle event, extraction child):
+
+1. Drains the parent's snapshot from the pending buffer via
+   `consumeSnapshot` — removes only entries captured at dispatch time by
+   reference identity, preserving interleaved-turn entries
+2. Fires a toast with extraction metrics (only if memories were actually
+   written)
+3. `completeAccepted(parentID)`, resets `missedNudges`
+4. Cleans up all maps
+5. `consume(childID)` — drains the child's own buffer
+6. Deletes the child session
+
+### Nudge-based extraction (fallback for opencode, primary for MCP)
+
+If direct extraction was never triggered or threw an error (session not in
+the `extracting` set) **and** the buffer has pending interactions:
+
+- The next user message (`chat.message` for opencode,
+  `UserPromptSubmit`/`beforeSubmitPrompt` for MCP) gets an extraction nudge
+- The nudge carries the session ID and fetch tool name — not the full
+  payload — so the sub-agent calls `thatch_get_extraction_payload` to
+  retrieve the interactions as a tool response
+
+**Nudge escalation** (via the `missedNudges` counter):
+
+| Missed count | Tone |
+|--------------|------|
+| 0–1 | Polite |
+| 2 | Insistent |
+| 3+ | All-caps shouting |
+
+The buffer persists until the agent writes a memory or calls
+`thatch_extraction_done`. Ignored nudges repeat and escalate.
+
+- **opencode**: in-memory `missedNudges` map
+- **MCP hosts**: file-backed `.count` file per session
+
+### Buffer lifecycle (opencode, AMQP-style)
+
+Buffered interactions move through four states in `ExtractionPipeline`
+(`src/extraction.ts`):
+
+- **pending** — interactions in the ring buffer. The nudge fires on
+  `chat.message`.
+- **accepted** — moved from pending by `accept()`. The nudge quiets, but
+  entries are not dropped yet.
+- **completed** — dropped by `completeAccepted()`. Triggered by a
+  `memory_remember` or `extraction_done` call in the child, or the child
+  going idle.
+- **requeued** — moved back to pending by `requeueAccepted()`. Triggered by
+  the child session erroring or being deleted before completing.
+
+Key methods:
+
+| Method | Action |
+|--------|--------|
+| `push()` | Add interaction to pending buffer (capped at 20) |
+| `peek()` | Read without clearing |
+| `consume()` | Delete the session's pending buffer (called on memory write) |
+| `accept()` | Move pending to accepted — quiet the nudge, hold entries |
+| `completeAccepted()` | Drop accepted entries — extractor finished |
+| `requeueAccepted()` | Move accepted back to pending — extractor died |
+| `consumeSnapshot()` | Remove only entries that were in the snapshot (by reference identity). Used for child-parent drain. |
+
+### Parent-child session drain
+
+When a child session writes a memory via `thatch_memory_remember`:
+
+1. `tool.execute.after` detects the memory write
+2. If in a child session (`childToParent.has(sessionID)`): track metrics,
+   `completeAccepted(parentID)`, drain the parent's snapshot via
+   `consumeSnapshot`, reset the parent's `missedNudges`
+3. `consume(sessionID)` — drains the child's own buffer
+
+`consumeSnapshot` is **snapshot-aware**: it removes only entries that were
+in the parent's buffer at dispatch time (by reference identity).
+Interleaved-turn entries — added after the snapshot was taken, while the
+child was extracting — survive. This prevents data loss when the parent
+continues working while the child extracts.
+
+### MCP file-backed queue drain
+
+- `drainExtractionQueue(sessionID)` calls `resetMissedCount` +
+  `consumeQueue` (deletes the JSONL file)
+- Triggered by: `thatch_extraction_done` called with the parent's
+  `session_id`, or `thatch_memory_remember` called
+- `appendBatch` in `extract-queue.ts` self-detects
+  `memory_remember`/`extraction_done` calls and resets the counter +
+  consumes the queue inline
+
+### The `extraction_done` tool
+
+- No-op confirmation (`[acknowledged]`) unless `session_id` is passed and
+  `drainExtractionQueue` is wired
+- On the MCP path with `session_id`: resets the missed-nudge count +
+  consumes (deletes) the file-backed queue
+- The real state transitions happen in the host's post-tool hook
+  (`tool.execute.after` for opencode, `PostToolBatch`/`appendBatch` for MCP)
+- The tool exists primarily so the model has a recognizable name to key on
+
+### The `get_extraction_payload` tool
+
+- Fetches the queued tool interactions for extraction as serialized JSON
+  (`interactions`, `projectStore`, `globalStore`)
+- **opencode**: peeks accepted + pending interactions, builds JSON via
+  `buildExtractionPayload`
+- **MCP**: peeks the file-backed queue, builds the same JSON payload
+- Returns `null` when no interactions are queued
+- Read-only — it peeks the queue; it does not consume it. Consumption is
+  `extraction_done`'s job
+
+### Background sub-agent support (opencode)
+
+- Experimental flag: `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS` (set in
+  `mise.toml`)
+- When enabled: `promptAsync` for child session creation (async extraction)
+- When disabled: fire-and-forget `prompt` (synchronous but unawaited)
+
+## Interactions with other features
+
+- [Memory store](memory-store.md) — extraction writes memories via
+  `thatch_memory_remember`
+- [Nudge pipeline](nudge-pipeline.md) — the extraction nudge is tier 1
+  (highest priority, returns early)
+- [Session lifecycle](session-lifecycle.md) — direct extraction is triggered
+  by `session.status` idle; child lifecycle is managed by the event handler
+- [Skills](../skills.md) — the thatch-fact-extractor skill is dispatched to
+  child sessions
+- [Multi-host](multi-host.md) — in-memory ring buffer for opencode,
+  file-backed queue for MCP hosts
+- [Compaction recovery](compaction-recovery.md) — extraction nudge is
+  suppressed during compaction (tools are blocked)
+
+## Source files
+
+| File | Responsibility |
+|------|----------------|
+| `src/extraction.ts` | In-memory ring buffer (`ExtractionPipeline`), shared payload builders (`buildExtractionPayload`, `deriveTitle`, `summarizeArgs`) |
+| `src/extract-queue.ts` | File-backed JSONL queue for MCP hosts |
+| `src/index.ts` | opencode hooks: `tool.execute.after`, `session.status` idle, `session.created`, `session.error`, `session.deleted`, `chat.message` (nudge tier 1) |
+| `bin/thatch` | `buffer-batch`, `buffer-tool`, `flush-tools` subcommands |
+| `src/prompts.ts` | `extractionNudge` (with escalation), `extractionDirectPrompt` |
+
+## Key invariants
+
+1. **Tool filtering is absolute.** `thatch_*`, `skill`, and `task` tools are
+   never buffered. Buffering them would echo the store into itself or create
+   a feedback loop.
+2. **The nudge peeks, never flushes.** The buffer persists until a memory
+   write or `extraction_done`. Ignored nudges repeat and escalate.
+3. **`consumeSnapshot` is snapshot-aware.** It removes only entries captured
+   at dispatch time (by reference identity), preserving interleaved-turn
+   entries added while the child was extracting.
+4. **`tool.execute.after` is a plugin hook, not a bus event.** The event bus
+   has no such event. Moving the buffering logic into the `event` handler
+   silently never fires it.
+5. **MCP host hooks must be silent.** `PostToolBatch`/`postToolUse` produce
+   no stdout — only `flush-tools` prints. Any stdout delays the agent loop.
+6. **The no-save drain runs unconditionally.** The child-idle handler drains
+   the remaining snapshot regardless of whether the child wrote memories,
+   covering no-save extraction runs.

package/docs/dev/features/hygiene.md

@@ -0,0 +1,81 @@
+# Hygiene System
+
+Store maintenance signals surfaced at session start. The plugin never deletes
+memories itself — it surfaces problems and lets the agent tend the store.
+
+## What it does
+
+- Three signals: duplicate candidates, stale entries, orphaned branch memories
+- Runs at session start on all three hosts
+- Only non-zero signals are reported (healthy stores stay silent)
+- Standalone `thatch hygiene` CLI command for manual inspection
+
+## How it works
+
+### Three signals
+
+1. **Duplicate candidates** — `db.findDuplicates(repo)`: near-duplicate memory
+   pairs via cosine >= 0.85 pending review. These are the same pairs that
+   `find_duplicates` surfaces, but the hygiene report is a count-only summary,
+   not the full pair list.
+
+2. **Stale entries** — `db.staleEntryCount(repo, cutoff)`: memories neither
+   updated nor recalled in 90+ days (`STALE_DAYS = 90`). Uses `recall_count`
+   and `last_recalled_at` columns. Archived memories are excluded
+   (`WHERE archived = 0`).
+
+3. **Orphaned branch memories** — `db.branchesInStore(repo)` cross-references
+   against `git.listBranches(worktree)`. Memories scoped to branches that no
+   longer exist. Skipped when the worktree is not a git repo
+   (`listBranches` returns `[]`) to avoid false positives — without a git
+   repo, every branch-scoped memory would look orphaned.
+
+### When it runs
+
+- **opencode**: `session.created` event for top-level sessions (no `parentID`).
+  The hygiene report is appended to the session-start reminder sent via
+  `client.session.prompt`.
+- **Claude Code**: `SessionStart` hook → `thatch reminder` (runs
+  `hygieneReport`, appends to reminder text, prints to stdout).
+- **Cursor**: `sessionStart` hook → `thatch reminder --json` (same, wrapped as
+  `additional_context` JSON).
+- **Standalone**: `thatch hygiene` CLI command (prints report or
+  "Store is healthy." to stdout).
+
+### Report format
+
+Only non-zero signals are reported. A healthy store produces no output
+(silent). The report is appended to the session-start reminder with
+instructions for the agent to tend the store when convenient.
+
+### Shared implementation
+
+`hygieneReport(db, repo, worktree)` in `src/hygiene.ts` is shared by:
+
+- The opencode plugin's session-start hook (`src/index.ts`)
+- The CLI's `thatch reminder` and `thatch hygiene` subcommands (`bin/thatch`)
+
+## Interactions with other features
+
+- [Deduplication](deduplication.md): hygiene reports the count of pending dedup
+  pairs; the agent uses `find_duplicates` to see the actual pairs.
+- [Memory store](memory-store.md): staleness uses `recall_count` and
+  `last_recalled_at`; orphan check uses the `branch` column.
+- Session lifecycle: hygiene runs at `session.created` for top-level sessions.
+- Nudge pipeline: hygiene is part of the session-start reminder, not the
+  per-message nudge pipeline.
+
+## Source files
+
+- `src/hygiene.ts` — `hygieneReport` function
+- `src/db.ts` — `findDuplicates`, `staleEntryCount`, `branchesInStore`
+- `src/git.ts` — `listBranches`
+- `bin/thatch` — `hygiene` and `reminder` subcommands
+
+## Key invariants
+
+- The plugin never deletes memories. It surfaces problems; the agent tends the
+  store.
+- Only non-zero signals are reported.
+- Orphan check is skipped outside a git repo.
+- Archived memories are excluded from staleness and duplicate checks.