@jeffober/thatch 0.1.27 → 0.1.29

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.

package/docs/dev/features/memory-store.md

@@ -0,0 +1,154 @@
+# Memory Store
+
+The memory store is thatch's core feature: a SQLite-backed store of memories with semantic search via local embeddings. Everything else thatch does — extraction, hygiene, nudges, predictions, behaviors — reads from or writes to this store.
+
+## What it does
+
+The store persists memories keyed by label, scoped to a project store or the shared "global" store. Each memory is a labeled chunk of text an agent writes for a future session of itself to read.
+
+- Stores memories keyed by label within a store. The store name is auto-detected from the git remote — the `owner/repo` slug — or falls back to `"global"` for cross-project knowledge.
+- Semantic search via cosine similarity over BGE-small-en-v1.5 embeddings (384 dimensions, ~34 MB). The model runs locally and is lazy-loaded.
+- Six tools: `memory_remember`, `memory_recall`, `memory_list`, `memory_show`, `memory_forget`, and `store_list`. All are defined in `src/tool-defs.ts`.
+- Branch scoping. Memories can be scoped to a git branch for work-in-progress context, or left unscoped for project-wide knowledge. Branch-scoped memories are recalled alongside project-wide ones when the branch matches.
+- Confidence grading on a 1–10 scale, stored per memory.
+- Archived flag. Archived memories are long-term records excluded from search and hygiene by default. Pass `includeArchived: true` to surface them.
+- Write-time duplicate detection. When a new memory is similar to existing ones (cosine ≥ 0.85), the save returns a warning listing the near-duplicates. The save always proceeds — the warning asks the agent to reconcile, never blocks.
+- Asymmetric search. Query text gets a BGE-specific prefix for retrieval; stored passages get no prefix. This follows the BGE training convention for asymmetric search.
+- Multi-model dimension check. Entries embedded by a model with a different vector dimension are silently skipped during search, not ranked. The `model` column is informational — dimension is the discriminator.
+- Recall tracking. Each memory carries `recall_count` and `last_recalled_at`, stamped when an agent-initiated search returns it. The hygiene system uses these to detect stale memories.
+
+## How it works
+
+### Store detection
+
+`src/git.ts` parses `owner/repo` from the git remote URL. The resolution chain is worktree-safe:
+
+1. Parse `owner/repo` from `git remote get-url origin`.
+2. Fall back to the basename of the git common dir (worktree-safe).
+3. Fall back to the directory basename.
+4. Falls back to `"unknown"` if none of the above yield a result.
+
+The "global" store always exists — it is inserted at schema init (`INSERT OR IGNORE INTO stores (name) VALUES ('global')`). Store creation is implicit: the first `memory_remember` to a new store calls `ensureStore`, which creates it via `INSERT OR IGNORE`.
+
+### Embedding model
+
+`src/embeddings.ts` defines the `BgeEmbeddingModel` class.
+
+- Model: `Xenova/bge-small-en-v1.5` — 384 dimensions, ~34 MB.
+- Lazy-loaded via the `@huggingface/transformers` `pipeline("feature-extraction")` API. The first load downloads from Hugging Face Hub; subsequent loads use the cached model.
+- Query prefix: `"Represent this sentence for searching relevant passages: "` — the BGE asymmetric search convention. Queries get the prefix; passages do not.
+- Mean pooling and L2 normalization are applied via pipeline options.
+- Output is a `Float32Array`.
+- `MockEmbeddingModel` is available for tests.
+- The model can be overridden via the `THATCH_MODEL` environment variable.
+
+### Write path (memory_remember)
+
+```text
+agent calls memory_remember(label, content, opts)
+  → model.passageEmbed("# label\n\ncontent")  →  Float32Array
+  → db.findSimilar(store, embedding, { excludeSlug })  →  write-time collision check
+  → db.remember(store, label, content, embedding, model.name, opts)
+      overwrite:false  →  atomic INSERT (PK constraint rejects duplicates)
+      overwrite:true   →  upsert + clear stale dedup verdicts for that slug
+  → return confirmation + warning if similar memories found
+```
+
+The tool prepends `# ${label}\n\n` to the content before embedding. The stored `content` column holds this full formatted text — it is the exact input that was embedded, so a future re-embed requires no reconstruction.
+
+The `findSimilar` call is a write-time collision check with no telemetry. It excludes the slug being written (self-exclusion on overwrite). If it finds entries with cosine ≥ 0.85, the return value includes a warning listing them.
+
+The save always proceeds. The warning asks the agent to reconcile — merge into one entry (overwrite + forget the other) or record that they are genuinely distinct via `dedup_mark_checked`.
+
+On overwrite, the upsert clears stale dedup verdicts: any `dedup_pairs` rows referencing that slug are deleted, since the content change may resolve or create duplicates.
+
+### Read path (memory_recall)
+
+```text
+agent calls memory_recall(query, opts)
+  → model.queryEmbed(query)  →  Float32Array
+  → db.recall([repo, "global"], queryEmbedding, { branch?, limit })
+      → db.search()  →  cosine scoring, sort desc, top-N
+      → stamp recall_count + last_recalled_at on returned rows
+  → return formatted results with scores
+```
+
+The tool layer hardcodes `[repo, "global"]` as the default search scope. Omitting the `store` parameter searches both. Passing a specific store searches only that store.
+
+Entries with a mismatched embedding dimension are skipped during search — the `emb.length !== queryEmbedding.length` guard in `db.search()`. This handles the case where a different embedding model was used for older entries.
+
+### Search vs. recall
+
+Two methods, one scoring engine, different telemetry policy:
+
+| Method | Telemetry | Used by |
+|--------|-----------|---------|
+| `db.search()` | None | Prompt-aware recall nudge (see [nudge-pipeline.md](nudge-pipeline.md)) |
+| `db.recall()` | Stamps `recall_count` / `last_recalled_at` | `thatch_memory_recall` tool, CLI `thatch search` |
+
+The distinction is deliberate. The recall nudge checks whether memories relate to a prompt — the plugin is looking, not the agent. Stamping telemetry on a nudge would inflate the "used recently" signal that hygiene reporting depends on. Only explicit agent-initiated recall stamps telemetry.
+
+### Default recall scope
+
+The tool layer hardcodes `[repo, "global"]` as the default search scope. This means a `memory_recall` call with no `store` argument searches both the project store and the global store. There is no way to search only the project store without the global store via the tool — pass an explicit `store` argument to scope to one.
+
+### Archived memories
+
+The `archived` column is an integer flag: `0` (default) is live, `1` is archived.
+
+- `search()`, `findDuplicates()`, and the stale-entry count in hygiene all filter `WHERE archived = 0`.
+- To search archived memories: pass `includeArchived: true` to `memory_recall`.
+- To archive: write with `archived: true`. To unarchive: write with `archived: false`.
+- Updating an already-archived memory requires an explicit `archived` parameter. The guard prevents accidental unarchival — the caller must consciously pass `archived: true` to keep it archived or `archived: false` to unarchive it.
+
+### Slug generation
+
+`slugify()` converts a label to a slug: lowercase, whitespace to hyphen, Unicode letters and digits preserved. All-symbol labels fall back to a hash so no label ever maps to an empty slug. ASCII labels produce the same slugs as earlier releases.
+
+The slug plus store name form the composite primary key: `PRIMARY KEY (slug, store)`.
+
+### CLI access
+
+The `bin/thatch` CLI provides read-only access to the store:
+
+| Command | Description |
+|---------|-------------|
+| `thatch stores` | List all stores |
+| `thatch list [store]` | List memory labels in a store |
+| `thatch show <label> [store]` | Display one memory |
+| `thatch forget <label> [store]` | Delete one memory |
+| `thatch search <query> [store]` | Semantic cosine search (limit 10; `"all"` searches project + global) |
+
+## Interactions with other features
+
+- **Extraction pipeline** ([extraction.md](extraction.md)): the extraction sub-agent writes memories via `memory_remember`. The extraction buffer drains on any `memory_remember` call.
+- **Deduplication** ([deduplication.md](deduplication.md)): `find_duplicates` scans stored memories for cosine-similar pairs. `dedup_mark_checked` records verdicts in the `dedup_pairs` table. Overwriting or forgetting a memory clears its dedup verdicts.
+- **Hygiene** ([hygiene.md](hygiene.md)): staleness checks use `recall_count` and `last_recalled_at` to find memories nobody has read recently. Duplicate checks use cosine search. Orphaned-branch detection finds branch-scoped memories whose branch no longer exists.
+- **Nudge pipeline** ([nudge-pipeline.md](nudge-pipeline.md)): the recall nudge uses `db.search()` — not `db.recall()` — to avoid inflating telemetry. The nudge fires when search results exceed the similarity threshold (default 0.55).
+- **Prediction engine** ([prediction-engine.md](prediction-engine.md)) and **behavior engine** ([behavior-engine.md](behavior-engine.md)): these share the same embedding model but store vectors in separate tables (`prediction_matchers`, `prediction_predictions`, `behavior_matchers`, `behavior_behaviors`). They do not read from or write to the `entries` table.
+
+## Source files
+
+| File | Responsibility |
+|------|---------------|
+| `src/db.ts` | SQLite schema, CRUD for entries and stores, brute-force cosine search (`search` vs. `recall`), dedup verdict tracking, prediction and behavior tables |
+| `src/embeddings.ts` | `BgeEmbeddingModel` (lazy-load, query/passage embed, mean pooling, L2 normalization) and `MockEmbeddingModel` for tests |
+| `src/git.ts` | Detect repo identity (store name) from git remote; worktree-safe fallback chain |
+| `src/tool-defs.ts` | Tool definitions — single source of truth for all tools, including the six memory tools |
+| `bin/thatch` | CLI subcommands: `stores`, `list`, `show`, `forget`, `search` |
+
+## Key invariants
+
+1. **No global mutable state.** Every module accepts dependencies explicitly. `ThatchDB` takes a path; `BgeEmbeddingModel` takes an optional pipeline factory; tools receive a `ctx` with `db` and `model`.
+
+2. **Embedding is a separate concern.** `db.ts` stores and retrieves BLOBs and compares vectors handed to it. It knows nothing about embedding models — it never calls `passageEmbed` or `queryEmbed`. The tool layer is the bridge: it embeds, then hands the vector to the DB.
+
+3. **Embedding spaces are discriminated by vector dimension, not model tag.** The `model` column is written on every save and returned on every read, but no code path filters or branches on it. Dimension mismatch is the only guard. This means a same-dimension model switch produces silently wrong cosine scores, while a different-dimension switch produces silently skipped entries.
+
+4. **Store creation is implicit.** The first `memory_remember` to a new store creates it. There is no explicit "create store" operation.
+
+5. **Default recall scope is repo + global.** The tool layer hardcodes `[ctx.defaultStore, "global"]` when no `store` argument is provided. This is intentional — cross-project knowledge in the global store is always searched alongside project-specific memories.
+
+6. **The write-time similarity warning never blocks the save.** `findSimilar` returns a warning, `remember` proceeds regardless. The warning asks the agent to reconcile after the fact.
+
+7. **`search()` records no usage. `recall()` stamps telemetry. This is deliberate.** The recall nudge (plugin checking relevance) must not inflate the "used recently" signal. Only agent-initiated recall counts as actual usage.