@jeffober/thatch 0.1.28 → 0.1.29

package/docs/user/hygiene.md

@@ -0,0 +1,76 @@
+# Hygiene
+
+Thatch checks your memory store for maintenance issues at the start of
+every session. The agent sees the report and can tend the store when
+convenient. Thatch never deletes memories on its own.
+
+## How it works
+
+At session start, thatch runs three checks against the current project
+store. Only non-zero signals are reported. A healthy store stays
+silent.
+
+### Duplicate candidates
+
+Memories whose content is very similar (cosine similarity >= 0.85).
+These are the same pairs that `thatch_find_duplicates` surfaces. The
+hygiene report shows the count, not the full list. To see the actual
+pairs, the agent calls `thatch_find_duplicates`.
+
+See [deduplication.md](deduplication.md) for the full dedup workflow.
+
+### Stale entries
+
+Memories that have not been updated or recalled in 90+ days. The check
+uses `recall_count` and `last_recalled_at` columns, which are stamped
+by `thatch_memory_recall` and CLI `thatch search`. Archived memories
+are excluded.
+
+If a memory is stale but still accurate, the agent can recall it
+(which resets the timer). If it is stale and wrong, the agent can
+update it with `overwrite: true` or delete it with
+`thatch_memory_forget`.
+
+### Orphaned branch memories
+
+Memories scoped to a git branch that no longer exists. The check
+cross-references the `branch` column against `git branch --list`. This
+check is skipped when the working directory is not a git repo, so it
+never produces false positives outside a repo.
+
+To fix orphaned memories, the agent can consolidate them into
+project-wide memories (re-save without the `branch` param) or archive
+them.
+
+## CLI
+
+```bash
+thatch hygiene    # print the hygiene report standalone
+```
+
+The session-start reminder (`thatch reminder`, called automatically by
+hooks) also includes the hygiene report when any signal is non-zero.
+
+## What you see
+
+You do not see the hygiene report directly. The agent sees it in the
+session-start reminder and may mention it: "Your store has 3 duplicate
+candidates and 2 stale memories. Want me to clean those up?"
+
+On opencode, the reminder is a synthetic prompt injected at session
+start. On Claude Code and Cursor, it is printed by the SessionStart
+hook and fed into the session as context.
+
+## Limitations
+
+- The plugin never deletes memories. It surfaces problems; the agent
+  decides what to do.
+- Stale entries use a 90-day window (hardcoded `STALE_DAYS = 90`).
+  There is no configuration for this.
+- The duplicate threshold (0.85) is higher than the recall nudge
+  threshold (0.55) because "duplicate" is a stronger claim than
+  "relates to."
+- Orphaned branch check is skipped outside a git repo.
+
+See [memory.md](memory.md) for the memory system and
+[deduplication.md](deduplication.md) for the dedup workflow.

package/docs/user/memory.md

@@ -0,0 +1,81 @@
+# Persistent Memory
+
+Thatch gives your AI coding agent the ability to remember information across
+sessions. Memories are stored in a local SQLite database using local
+embeddings (no network calls, no API keys).
+
+## How it works
+
+Each memory has a label, content, and an embedding vector. When you ask the
+agent to save something, it embeds the text and stores it. When a future
+session's prompt semantically matches a stored memory, thatch injects a
+nudge telling the agent to recall it.
+
+You never see the nudge. The agent sees it and decides whether to act
+on it. The memory surfaces as context the agent reads, not as text
+printed to your terminal.
+
+## Stores
+
+Memories are organized into stores:
+
+- **global**: user preferences, personality, system environment. Shared
+  across all projects.
+- **Per-project**: detected from your git remote. Each repo gets its
+  own store.
+- **Branch-scoped**: memories can be scoped to a git branch for
+  feature-specific context (design decisions, WIP notes, PR status).
+
+The agent defaults to searching both the project store and the global
+store when recalling.
+
+## Tools
+
+| Tool | What it does |
+|------|-------------|
+| `thatch_memory_remember` | Save a memory with a label and content. Optional: branch, confidence (1-10), archived flag, overwrite. |
+| `thatch_memory_recall` | Semantic search across stores. Returns matching memories with similarity scores. |
+| `thatch_memory_list` | List all memories in a store (metadata only, no content). |
+| `thatch_memory_show` | Show full content of a single memory by label. |
+| `thatch_memory_forget` | Delete a memory by label. |
+| `thatch_store_list` | List all active stores. |
+| `thatch_find_duplicates` | Surface pairs of memories with suspiciously similar content. |
+| `thatch_dedup_mark_checked` | Record a verdict for a reviewed pair so it stops being re-reported. |
+
+## Configuration
+
+- `THATCH_DB_PATH`: path to the SQLite database file. Defaults to
+  `~/.config/thatch/thatch.db` (opencode) or the project directory
+  (MCP).
+- `THATCH_MODEL`: Hugging Face model name for embeddings. Defaults to
+  `Xenova/bge-small-en-v1.5` (34 MB, 384-dimensional).
+- `THATCH_RECALL_THRESHOLD`: cosine score threshold for the recall
+  nudge. Defaults to 0.55. Lower surfaces more matches (noisier);
+  higher surfaces fewer (stricter).
+
+## Limitations
+
+- Search is brute-force cosine similarity across all entries in the
+  store. No approximate nearest neighbor index. Fine for thousands of
+  memories; would slow down at tens of thousands.
+- Embeddings are local (bge-small-en-v1.5). Quality is good for
+  code-related content but not state-of-the-art compared to large
+  API-based models.
+- There is no full-text search. Recall is semantic only (cosine on
+  embeddings). If you need exact string matching, use the agent's
+  grep or read tools.
+- Memories are not versioned. Updating a memory with `overwrite: true`
+  replaces the content and embedding. The old content is lost (git
+  history does not track it).
+
+## Archived memories
+
+Memories can be marked `archived` to exclude them from default search
+results without deleting them. Archived memories are useful for
+consolidating branch-scoped context after a merge: the branch-scoped
+memories become a single archived record that future sessions can find
+with `includeArchived: true` but that does not clutter normal recall.
+
+See [prediction-engine.md](prediction-engine.md) for the user decision
+model and [behavior-engine.md](behavior-engine.md) for self-discipline
+rules.

package/docs/user/prediction-engine.md

@@ -0,0 +1,87 @@
+# Prediction Engine
+
+Thatch learns your decision-making preferences over time. When you correct
+the agent, answer its questions, or express a preference, thatch
+records it as a prediction. On future sessions, if your prompt
+semantically matches a learned context, thatch surfaces the prediction
+as a nudge the agent can follow.
+
+## How it works
+
+Predictions are context-dependent. Each prediction has two parts:
+
+- **Matcher**: a description of the situation ("when reviewing a PR
+  with tech debt"). This is what gets embedded and matched against
+  your prompt.
+- **Prediction**: the preference statement ("flag tech debt before
+  reviewing the diff"). This is what the agent reads and follows.
+
+A matcher can link to multiple predictions (different preferences for the
+same situation). A prediction can be linked from multiple matchers (the
+same preference applies in different situations).
+
+## Confidence
+
+Each prediction has a confidence score from 0 to 1, based on a Bayesian
+posterior:
+
+- Starts at 0.5 (no evidence either way).
+- Each confirm moves it up. Each disconfirm moves it down.
+- Soft signals count as 0.25 of a full signal (weak disconfirm).
+- No wall-clock decay. Confidence only moves when you provide feedback.
+
+The agent follows strong predictions silently, surfaces ambiguous or
+competing predictions to you, and updates the model when you respond.
+
+## Auto-fire
+
+When you send a prompt, thatch embeds it and searches for matching
+matchers. If any match above the threshold (default 0.60), thatch injects
+a `User decision model` block into the agent's context. The block looks
+like:
+
+```text
+[thatch] User decision model
+- [0.72 conf, 4 tests] When reviewing a PR with tech debt: you tend to
+  flag tech debt before reviewing the diff
+- [0.61 conf, 2 tests] When choosing test scope: you may prefer
+  integration tests over unit tests
+```
+
+The agent reads this and decides whether to follow the prediction,
+surface it to you, or ignore it. You never see the nudge directly.
+
+## Tools
+
+| Tool | What it does |
+|------|-------------|
+| `thatch_prediction_query` | Query the model for predictions matching a context. Returns scored predictions with confidence and evidence count. |
+| `thatch_prediction_update` | Create, reinforce, or weaken a prediction. Takes a matcher (situation), prediction (preference), signal (confirm/disconfirm/soft/create), and rationale. |
+| `thatch_prediction_list` | List all predictions with matchers, confidence, evidence count, and provenance history. |
+| `thatch_prediction_delete` | Delete a prediction by semantic match. Edges and provenance are cascade-deleted. |
+
+## Configuration
+
+- `THATCH_PREDICTION_THRESHOLD`: cosine score threshold for prediction
+  auto-fire. Defaults to 0.60. Lower surfaces more predictions
+  (noisier); higher surfaces fewer (stricter).
+
+## Limitations
+
+- The agent creates predictions based on your feedback. Thatch never
+  creates predictions on its own. If the agent does not proactively
+  record your preferences, the model stays empty.
+- There is no formation nudge. The system prompt instructs the agent
+  to watch for preference signals, but the agent must decide to act on
+  those instructions.
+- 0-evidence predictions (confidence 0.5) still surface. The nudge
+  uses "you may prefer" language for these, which hedges appropriately.
+- Confidence never reaches 0 or 1. A disconfirmed prediction can still
+  fire if its matcher matches strongly. Delete it with
+  `thatch_prediction_delete` if it is wrong.
+- Predictions are per-store. A preference learned in one project's
+  store does not automatically apply to other projects. The global
+  store is shared across projects.
+
+See [memory.md](memory.md) for the base memory system and
+[behavior-engine.md](behavior-engine.md) for the self-discipline rules.

package/docs/user/setup.md

@@ -0,0 +1,110 @@
+# Setup and Configuration
+
+Thatch works with three AI coding tools. Each has a different
+integration mechanism, but all share the same core: local embeddings,
+SQLite, and the same tool definitions.
+
+## OpenCode
+
+OpenCode is the primary integration. Thatch runs as a plugin.
+
+### Install
+
+```jsonc
+// opencode.jsonc or opencode.json
+{
+  "plugin": ["@jeffober/thatch"]
+}
+```
+
+OpenCode installs the plugin and its dependencies automatically on
+next start.
+
+### Async extraction
+
+For background extraction (child sessions run in the background):
+
+```bash
+export OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true
+```
+
+Without this env var, extraction still works. The child session runs
+synchronously instead of asynchronously (blocks the turn briefly).
+Put it in your shell rc, `mise.toml [env]`, or `.envrc`.
+
+### Local development
+
+Before publishing, use a file path:
+
+```jsonc
+{ "plugin": ["./path/to/thatch/src/index.ts"] }
+```
+
+Or place the thatch repo in `.opencode/plugins/` for auto-loading.
+
+## Claude Code
+
+Thatch runs as an MCP server. The setup command installs the server
+config, instructions, hooks, and skills:
+
+```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 uses a flat hooks format (`{version, hooks:{event:[{command}]}}`)
+and `--json` output for hook commands.
+
+## Environment variables
+
+| Variable | Default | What it controls |
+|----------|---------|-----------------|
+| `THATCH_DB_PATH` | `~/.config/thatch/thatch.db` | SQLite database path |
+| `THATCH_MODEL` | `Xenova/bge-small-en-v1.5` | Hugging Face model name for embeddings |
+| `THATCH_RECALL_THRESHOLD` | `0.55` | Cosine threshold for recall nudge |
+| `THATCH_PREDICTION_THRESHOLD` | `0.60` | Cosine threshold for prediction auto-fire |
+| `THATCH_BEHAVIOR_THRESHOLD` | `0.60` | Cosine threshold for behavior auto-fire |
+| `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS` | (unset) | Enables async extraction (opencode only) |
+
+## Setup detection
+
+When the MCP server starts (Claude Code or Cursor), it checks whether
+`thatch setup` was run for the current host. If setup was never run,
+or if the instruction markers are broken (e.g., the file was edited
+externally), the server emits a warning the agent can see and tell you
+to run setup.
+
+The MCP server also auto-refreshes skills, instructions, and hooks on
+every startup. This ensures the latest skill files and prompt
+instructions are deployed without requiring you to manually re-run
+`thatch setup` after updating thatch.
+
+## Limitations
+
+- `bun` must be installed and on PATH. Thatch does not bundle its
+  own runtime.
+- The embedding model (~34 MB) is downloaded once on first use and
+  cached in `node_modules/@huggingface/transformers/.cache/`.
+- There is no web UI or dashboard. All interaction is through the
+  agent's tool calls and the `thatch` CLI.
+- The MCP server is a long-lived process that holds the warm embedding
+  model in memory. Hook commands connect to it via a Unix domain
+  socket (the sideband) to avoid loading the model themselves.
+
+See [memory.md](memory.md) for the memory system,
+[skills.md](skills.md) for skills, and [extraction.md](extraction.md)
+for the fact extraction pipeline.

package/docs/user/skills.md

@@ -0,0 +1,97 @@
+# Skills
+
+Thatch ships skills that guide the agent through structured workflows:
+code review, project investigation, memory management, PR and ticket
+writing, and code change planning. Skills are markdown files with
+frontmatter (name, description) that opencode auto-discovers.
+
+## How they work
+
+On startup, thatch installs skill files into your global config
+(`~/.config/opencode/skills/` for opencode, `~/.claude/skills/` for
+Claude Code, `~/.cursor/skills/` for Cursor). The host's skill
+discovery scans these directories and presents them to the agent as
+available skills.
+
+The agent loads a skill when the user's request matches the skill's
+description, or when another skill or the system prompt directs the
+agent to load it. Once loaded, the skill body (the markdown content)
+becomes part of the agent's context.
+
+## What ships
+
+24 skills total (23 shared, 1 opencode-only):
+
+### Memory skills
+
+| Skill | Purpose |
+|-------|---------|
+| `thatch-fact-extractor` | Guides the agent through turning buffered tool interactions into memories. Auto-triggered by the extraction pipeline. |
+| `thatch-dedup-classifier` | Guides the agent through classifying and resolving duplicate-candidate pairs. |
+| `thatch-project-primer` | Investigates a new project from multiple angles and writes foundational memories. |
+| `thatch-session-reflection` | End-of-session skill for recording what was learned about the project, user, tools, and self. |
+
+### Code review skills
+
+| Skill | Focus |
+|-------|-------|
+| `thatch-review-pedantic` | Mechanical correctness: spelling, naming, doc accuracy, specs, guidelines, stale artifacts. |
+| `thatch-review-acceptance` | Behavioral/product review: UX coherency, behavioral delta, integration effects, user assumptions. |
+| `thatch-review-state-flow` | Data flow and contracts: module boundaries, implicit state machines, error propagation, separation of concerns. |
+| `thatch-review-economy` | Design simplicity and maintainability: is the complexity earned? Evaluates both the overall change design (forest) and individual touch points (trees) for unnecessary complexity, redundancy, and simpler available alternatives. |
+| `thatch-review-no-slop` | AI writing anti-patterns: change narration, fourth wall breaks, em dashes, hedging, filler. |
+| `thatch-review-breadcrumbs` | Comment narrative: do comments form a coherent outline of the code's behavior? |
+| `thatch-review-mark-and-sweep` | Mechanical change completeness: whole-repo sweep for stragglers after renames, flag removals, API substitutions. |
+| `thatch-review-highlights` | Positive finding detection: notably clever solutions, cleanup done along the way, documentation that helps. Medium-high bar. |
+| `thatch-review-synthesizer` | Verifies and synthesizes findings from multiple specialists into a deduplicated, severity-grouped report. |
+| `thatch-review-context` | Gathers project context (PRs, tickets, TODOs, deferred work) before a review. Prevents false positives about intentionally deferred work. |
+| `thatch-code-archaeology` | Investigates an existing feature, debugs an unfamiliar area, or begins a new ticket. The research skill; pair with `thatch-coding-workflow`. |
+| `thatch-review-followup` | Verifies whether the author's responses and code changes since your last review adequately addressed your prior findings. |
+| `thatch-review-response` | Author-side review response: triage findings on your own PR, fix bugs one by one, reply on each thread, post a top-level summary comment. |
+| `thatch-code-review` | Multi-agent review coordinator (opencode-only). Dispatches parallel sub-agents for specialist fan-out and synthesis. |
+
+### Walkthrough skills
+
+| Skill | Purpose |
+|-------|---------|
+| `thatch-change-walkthrough` | Explains a change to you as a teaching walkthrough: researches each affected workflow at the merge-base, teaches current behavior, then overlays the modifications with file:line citations. |
+| `thatch-code-walkthrough` | Explains a feature, module, or workflow as a teaching walkthrough with file:line citations. Also used to draft high-level docs for new or undocumented features. |
+
+### Writing skills
+
+| Skill | Purpose |
+|-------|---------|
+| `thatch-pr-description` | Drafts PR descriptions with SYNOPSIS / PURPOSE / DESCRIPTION / WALK-THROUGH / NOTES, using bold and italic emphasis for scanning. |
+| `thatch-ticket-description` | Drafts ticket or issue descriptions (Linear or Jira) with clear sections and bold/italic emphasis for scanning. |
+| `thatch-split-overlarge-pr` | Splits already-completed work from an overlarge PR into human-reviewable, release-safe PRs targeting main. |
+
+### Workflow skills
+
+| Skill | Purpose |
+|-------|---------|
+| `thatch-coding-workflow` | Plans and executes code changes with a task-list-driven workflow: complexity triage, milestone planning, research before coding, post-coding verification. Pairs with `thatch-code-archaeology` (research first, then plan). |
+
+## Stale skill cleanup
+
+When skills are renamed or removed in a new release, thatch automatically
+deletes the old skill directories from your config on next startup.
+Prefixed skills (`thatch-*`) are always cleaned up. Non-prefixed
+skills (from early releases) are cleaned up through a version-gated
+window.
+
+## Limitations
+
+- Skills are installed as copies, not symlinks. If you manually edit
+  an installed copy, your changes are lost on next startup (thatch
+  re-installs from its canonical source). Edit the canonical source
+  in the thatch repo instead.
+- The opencode-only coordinator (`thatch-code-review`) requires
+  sub-agent support. It is not available on Claude Code or Cursor.
+- Skill content is markdown read at runtime, not compiled into the
+  binary. If the skill file is missing or corrupted, the skill will
+  not load (silent failure).
+
+See [code-review.md](code-review.md) for the review pipeline,
+[extraction.md](extraction.md) for the fact-extractor skill,
+[memory.md](memory.md) for the memory skills, and
+[setup.md](setup.md) for installation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.1.28",
+  "version": "0.1.29",
   "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",
@@ -28,7 +28,7 @@
   },
   "devDependencies": {
     "@opencode-ai/plugin": "^1.17.13",
-    "@types/bun": "latest",
+    "@types/bun": "^1.3.14",
     "markdownlint-cli2": "^0.23.0",
     "typescript": "^5.7.0",
     "yaml": "^2.7.0"

package/src/behavior.ts

@@ -0,0 +1,120 @@
+import { Database } from "bun:sqlite";
+import { ScoringEngine } from "./scoring-engine";
+
+export interface BehaviorRow {
+  id: string;
+  store: string;
+  statement: string;
+  rationale: string | null;
+  confidence: number;
+  confirm_count: number;
+  disconfirm_count: number;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface BehaviorNudgeItem {
+  confidence: number;
+  evidence_count: number;
+  matcher_description: string;
+  statement: string;
+}
+
+export interface ScoredBehavior {
+  matcher_id: string;
+  matcher_description: string;
+  behavior_id: string;
+  statement: string;
+  confidence: number;
+  evidence_count: number;
+  score: number;
+  rationale: string | null;
+}
+
+const config = {
+  matchersTable: "behavior_matchers",
+  itemsTable: "behaviors",
+  edgesTable: "behavior_edges",
+  provenanceTable: "behavior_provenance",
+  itemForeignKey: "behavior_id",
+};
+
+/**
+ * Behavior engine: the LLM's codified self-discipline rules.
+ * Same four-table shape as the prediction engine but separate
+ * tables because the semantics differ. Predictions model what
+ * the USER wants; behaviors model what the LLM should do.
+ * Delegates to ScoringEngine for all SQL and scoring logic.
+ */
+export class BehaviorEngine {
+  #engine: ScoringEngine;
+
+  constructor(db: Database) {
+    this.#engine = new ScoringEngine(db, config);
+  }
+
+  findBehaviorMatchers(stores: string[], queryEmbedding: Float32Array, opts?: { limit?: number }) {
+    return this.#engine.findMatchers(stores, queryEmbedding, opts);
+  }
+
+  scoreBehaviors(matchers: { id: string; description: string; score: number }[]): ScoredBehavior[] {
+    return this.#engine.scoreItems(matchers).map((s) => ({
+      matcher_id: s.matcher_id,
+      matcher_description: s.matcher_description,
+      behavior_id: s.item_id,
+      statement: s.statement,
+      confidence: s.confidence,
+      evidence_count: s.evidence_count,
+      score: s.score,
+      rationale: s.rationale,
+    }));
+  }
+
+  scoreBehaviorNudge(stores: string[], embedding: Float32Array, threshold: number, limit = 5): BehaviorNudgeItem[] {
+    return this.#engine.scoreNudge(stores, embedding, threshold, limit);
+  }
+
+  findNearestBehaviorMatcher(store: string, embedding: Float32Array, threshold: number): { id: string; description: string } | null {
+    return this.#engine.findNearestMatcher(store, embedding, threshold);
+  }
+
+  createBehaviorMatcher(store: string, description: string, embedding: Float32Array, model: string): string {
+    return this.#engine.createMatcher(store, description, embedding, model);
+  }
+
+  findNearestBehavior(store: string, embedding: Float32Array, threshold: number): BehaviorRow | null {
+    return this.#engine.findNearestItem(store, embedding, threshold) as BehaviorRow | null;
+  }
+
+  createBehavior(store: string, statement: string, rationale: string, embedding: Float32Array, model: string): string {
+    return this.#engine.createItem(store, statement, rationale, embedding, model);
+  }
+
+  createBehaviorEdge(matcherId: string, behaviorId: string, weight: number): void {
+    return this.#engine.createEdge(matcherId, behaviorId, weight);
+  }
+
+  adjustBehaviorConfidence(behaviorId: string, signal: "confirm" | "disconfirm" | "soft"): void {
+    return this.#engine.adjustConfidence(behaviorId, signal);
+  }
+
+  getBehavior(behaviorId: string): BehaviorRow | null {
+    return this.#engine.getItem(behaviorId) as BehaviorRow | null;
+  }
+
+  addBehaviorProvenance(behaviorId: string, signal: string, detail: string): void {
+    return this.#engine.addProvenance(behaviorId, signal, detail);
+  }
+
+  getBehaviorProvenance(behaviorId: string): { signal: string; detail: string | null; created_at: string }[] {
+    return this.#engine.getProvenance(behaviorId);
+  }
+
+  deleteBehavior(behaviorId: string): boolean {
+    return this.#engine.deleteItem(behaviorId);
+  }
+
+  listBehaviors(store: string) {
+    return this.#engine.listItems(store);
+  }
+}