@jeffober/thatch 0.1.44 → 0.1.45

package/docs/user/cli.md

@@ -46,6 +46,7 @@ Read-only access to the chat directory your opencode sessions share
 
 ```bash
 thatch chat list               # who is registered: name, age, project, topic
+thatch chat list --stale all   # also show stale sessions older than a day
 thatch chat tail               # follow sent and read events, live (JSONL)
 thatch chat tail --once        # print the last 20 messages and exit
 thatch chat tail --once --limit 50   # a longer backlog (or --limit all)
@@ -59,9 +60,15 @@ Stale, each as aligned columns under a header row: how long since its
 last heartbeat, its status (`fresh` or `stale` for opencode sessions;
 `active` or `idle` for Claude Code and Cursor sessions, which only beat
 when a prompt runs), its project, and its topic (the session's title) -
-the fastest way to answer "which session should I talk to about X?" A
+the fastest way to answer "which session should I talk to about X?"
+Rows are grouped by project (alphabetical; sessions with no project
+last), most recently seen first within each project. A
 stale session has missed two heartbeats, about a minute: the opencode
-process hosting it has probably stopped. Color is added only when the
+process hosting it has probably stopped. The stale section shows rows
+up to one day old by default; older ones collapse into a hidden-count
+note so long-dead sessions cannot bury the fresh signal. Pass
+`--stale N` (days) to widen the window or `--stale all` to see every
+stale row. Color is added only when the
 output is a terminal; a pipe prints plain aligned text.
 
 `chat tail` prints the conversation as a JSONL event log: one JSON
@@ -160,7 +167,9 @@ thatch setup --claude [--cursor] [--global]  # install config + hooks + skills
 
 ## Limitations
 
-- Requires `bun` on PATH. Thatch does not bundle its own runtime.
+- For non-Nix installs, `bun` must be installed and on PATH. Thatch does
+  not bundle its own runtime (the Nix package bundles it; see the
+  README's Nix section).
 - `search` is limited to 10 results. There is no pagination.
 - `prime` requires an external CLI (`opencode`, `agent`, or `claude`)
   on PATH. If none is found, it exits with an error.

package/docs/user/commands.md

@@ -0,0 +1,50 @@
+# Slash commands
+
+Thatch ships `/thatch/*` commands you run yourself, on top of the nudges the
+plugin fires on its own schedule. Nudges and commands share the same
+instruction text, so a behavior works the same whether it fires automatically
+or you invoke it.
+
+## Commands
+
+- `/thatch/defrag` — find duplicate-candidate memory pairs and clusters,
+  classify each one, consolidate duplicates, and mark the rest checked.
+  Text after the command narrows the scope (for example, a store name).
+- `/thatch/extract` — drain the extraction queue now, instead of waiting
+  for the next nudge or idle-time extraction. opencode only.
+- `/thatch/hygiene` — run the hygiene report and act on it: stale
+  memories, memories scoped to deleted branches, and pending dedup pairs.
+  The agent asks before forgetting anything that may still matter.
+- `/thatch/reflect` — run the session-reflection skill to persist what the
+  current session learned.
+- `/thatch/compact` and `/thatch/exit` — the wrap-up commands. They run a
+  pre-flight checklist (flush extraction, finish promised memory writes,
+  surface loose ends) before a compaction or an exit, gated by a greenlight
+  token. opencode only; the greenlight mechanics are described in the
+  [user guide overview](README.md).
+
+## Host support
+
+| Command | opencode | Claude Code | Cursor |
+|---|---|---|---|
+| `/thatch/defrag` | yes | yes | yes (as an MCP prompt) |
+| `/thatch/extract` | yes | no | no |
+| `/thatch/hygiene` | yes | yes | yes (as an MCP prompt) |
+| `/thatch/reflect` | yes | yes | yes (as an MCP prompt) |
+| `/thatch/compact`, `/thatch/exit` | yes | no | no |
+
+Why the gaps: `/thatch/extract` needs the invoking session's ID, which only
+the opencode plugin can supply. The wrap-up commands trigger TUI actions
+through the plugin. Cursor has no file-based commands; its prompts come from
+the MCP server (`prompts/list` and `prompts/get`).
+
+## Installation
+
+- **opencode**: installed by the plugin on every load.
+- **Claude Code**: installed by `thatch setup --claude` into the same scope
+  as the skills (`.claude/commands/thatch/` project-local, or the Claude
+  config dir for `--global`). Re-run setup to refresh after an upgrade.
+
+Tool names inside the command text follow each host's spelling
+(`thatch_memory_remember` on opencode, `mcp__thatch__memory_remember` on
+Claude Code and Cursor).

package/docs/user/cross-session-chat.md

@@ -8,8 +8,10 @@ between tabs all afternoon.
 
 ## What it does
 
-opencode sessions join the directory automatically, on their first idle
-moment. Names are assigned by thatch, never chosen: a name drawn from a
+opencode sessions join the directory automatically, the moment their
+first user message arrives (before the assistant responds), and a session
+resumed with `opencode -c` or `opencode -s <id>` is back in the directory
+at harness start with its old name. Names are assigned by thatch, never chosen: a name drawn from a
 built-in pool plus a counter (`al-go-rithm-00001`). The counter only ever
 increments, so a name is
 minted exactly once per machine - pruning an old session never reissues its
@@ -60,11 +62,13 @@ toggle reveals those output blocks if you want them.)
 ## How to use it
 
 With auto-registration you usually do nothing: a session joins the
-directory when it first goes idle, and a session continued with
-`opencode -s <id>` is registered again the moment its harness starts -
-same session id, same name, reclaimed. The agent gets a quiet toast with
-its assigned name when it first registers. To introduce two sessions,
-just tell each one who to talk to:
+directory when its first user message arrives, and a session continued
+with `opencode -c` or `opencode -s <id>` is registered again the moment
+its harness starts - same session id, same name, reclaimed. The agent
+gets a quiet toast with
+its assigned name when it first registers, and a resumed session
+announces its reclaimed name on its first prompt. To introduce two
+sessions, just tell each one who to talk to:
 
 > Ask the other session whether the release has shipped; answer its
 > questions directly.

package/docs/user/setup.md

@@ -90,6 +90,7 @@ and `--json` output for hook commands.
 | `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_EMBEDDING_BACKEND` | `wasm` | Set to `native` to run embeddings on onnxruntime-node (NAPI) instead of the wasm runtime |
+| `THATCH_MODEL_CACHE` | platform per-user cache dir | Where downloaded model files are stored |
 | `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 |
@@ -110,10 +111,15 @@ instructions are deployed without requiring you to manually re-run
 
 ## Limitations
 
-- `bun` must be installed and on PATH. Thatch does not bundle its
-  own runtime.
+- For non-Nix installs, `bun` must be installed and on PATH. Thatch does
+  not bundle its own runtime (the Nix package bundles it; see the
+  README's Nix section).
 - The embedding model (~34 MB) is downloaded once on first use and
-  cached in `node_modules/@huggingface/transformers/.cache/`.
+  cached in the platform's per-user cache dir
+  (`~/Library/Caches/thatch/models` on macOS (or
+  `$XDG_CACHE_HOME/thatch/models` when `XDG_CACHE_HOME` is set),
+  `$XDG_CACHE_HOME/thatch/models` elsewhere). Override with
+  `THATCH_MODEL_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 keeps the embedding model

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.1.44",
+  "version": "0.1.45",
   "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",

package/src/chat.ts

@@ -304,17 +304,45 @@ export function chatLiveness(row: ChatSessionRow, now = Date.now()): "fresh" | "
   return stale ? "stale" : "fresh";
 }
 
+/** Orders roster rows for display: project first (so a shared-tree reader
+ *  sees each repo's sessions together; rows with no project sort last),
+ *  then by heartbeat, most recently seen first, so the recoverable rows
+ *  lead and the long-dead trail at the bottom. Pure ordering - it never
+ *  drops rows; the stale display cap is splitChatRoster's job. */
+export function sortChatRoster(rows: ChatSessionRow[]): ChatSessionRow[] {
+  return [...rows].sort((a, b) => {
+    const projectA = a.project ?? "\uffff";
+    const projectB = b.project ?? "\uffff";
+    if (projectA !== projectB) return projectA.localeCompare(projectB);
+    return Date.parse(b.last_seen) - Date.parse(a.last_seen);
+  });
+}
+
 /** Splits the roster for the two-section display: Active (wake-able or
  *  reachable - fresh opencode rows and every MCP row, which read mail at
  *  their next prompt) and Stale (opencode rows whose harness has stopped
- *  reporting; mail to them waits until they resume). */
-export function splitChatRoster(rows: ChatSessionRow[], now = Date.now()): { active: ChatSessionRow[]; stale: ChatSessionRow[] } {
+ *  reporting; mail to them waits until they resume).
+ *  staleCapMs bounds how old a stale row the roster displays, so
+ *  long-dead sessions cannot bury the fresh signal; hidden rows come
+ *  back only as the staleHidden count, so the CLI can say what it left
+ *  out. null (the default) shows every stale row - the tool surface has
+ *  no cap, only the CLI applies one. */
+export function splitChatRoster(rows: ChatSessionRow[], now = Date.now(), staleCapMs: number | null = null): { active: ChatSessionRow[]; stale: ChatSessionRow[]; staleHidden: number } {
   const active: ChatSessionRow[] = [];
   const stale: ChatSessionRow[] = [];
+  let staleHidden = 0;
   for (const row of rows) {
-    (chatLiveness(row, now) === "stale" ? stale : active).push(row);
+    if (chatLiveness(row, now) === "stale") {
+      if (staleCapMs !== null && now - Date.parse(row.last_seen) > staleCapMs) {
+        staleHidden++;
+      } else {
+        stale.push(row);
+      }
+    } else {
+      active.push(row);
+    }
   }
-  return { active, stale };
+  return { active, stale, staleHidden };
 }
 
 /**

package/src/commands.ts

@@ -1,12 +1,35 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import {
+  defragCore,
+  extractionCore,
+  hygieneCore,
+  mcpToolName,
+  opencodeToolName,
+  reflectCore,
+  type ToolNamer,
+} from "./prompts";
 
 /**
- * Thatch's wrap-up slash commands for opencode, shipped as command markdown
- * files synced into the global opencode config dir (~/.config/opencode/command/
- * thatch/). The plugin writes them on every load so template updates self-heal
- * without a reinstall. Config is loaded before plugins during server startup,
- * so a first-ever install becomes visible on the next start.
+ * Thatch's slash commands, shipped as command markdown files synced into each
+ * host's command directory:
+ *
+ * - opencode: ~/.config/opencode/command/thatch/ - synced by the plugin on
+ *   every load, so template updates self-heal without a reinstall. Config is
+ *   loaded before plugins during server startup, so a first-ever install
+ *   becomes visible on the next start.
+ * - Claude Code: ~/.claude/commands/thatch/ (or the project's .claude/
+ *   commands/thatch/) - synced by `thatch setup --claude`, which has no
+ *   plugin to do it on load.
+ *
+ * Two command families live here:
+ *
+ * - Actions (/thatch/defrag, extract, hygiene, reflect): user-invoked
+ *   wrappers around a behavior that the nudges otherwise only run on their
+ *   own schedule. Each action body is a prompt core from src/prompts.ts, so
+ *   nudge and command wording cannot drift.
+ * - Wrap-ups (/thatch/compact, exit): greenlight-token commands that need
+ *   the opencode plugin's TUI control routes, so they are opencode-only.
  */
 
 /** Greenlight token ending /thatch/compact's assistant response when compaction is safe. */
@@ -32,6 +55,71 @@ $ARGUMENTS
 
 (That section carries the text typed after the command. When it is empty, treat the user message as n/a - the command was run bare.)`;
 
+/**
+ * One on-demand action: the command name (minus the thatch/ prefix), the
+ * description shown in the command menu, and the instruction body (a prompt
+ * core). opencodeOnly marks actions that need a session identity or other
+ * plugin-only capability; those are excluded from Claude Code command files
+ * and MCP prompts.
+ */
+export interface ActionDef {
+  name: string;
+  description: string;
+  body: string;
+  opencodeOnly?: boolean;
+}
+
+/**
+ * The on-demand action set, shared by every host that renders actions. The
+ * bodies come from prompt cores so a wording change lands in the nudge and
+ * the command at once. `tool` renders tool names in the host's spelling.
+ */
+export function actionDefs(tool: ToolNamer): ActionDef[] {
+  return [
+    {
+      name: "defrag",
+      description: "Consolidate duplicate and near-duplicate memories in the store",
+      body: defragCore(tool),
+    },
+    {
+      name: "extract",
+      description: "Drain the extraction queue now",
+      // Needs the invoking session's ID (via get_session_info, opencode-only)
+      // and the plugin's extraction payload provider.
+      opencodeOnly: true,
+      body: `First call thatch_get_session_info to learn this session's ID. Below, replace SESSION_ID with that value.
+
+Dispatch a task with background: true and subagent_type: "general" (required for thatch tool access) with this prompt:
+
+"${extractionCore("thatch_get_extraction_payload", "thatch_extraction_done", ' with session_id \\"SESSION_ID\\"')}"
+
+After dispatching, call thatch_extraction_done to acknowledge.`,
+    },
+    {
+      name: "hygiene",
+      description: "Tend the memory store: stale entries, orphans, pending dedup pairs",
+      body: hygieneCore(),
+    },
+    {
+      name: "reflect",
+      description: "Persist what this session learned as memories",
+      body: reflectCore(tool),
+    },
+  ];
+}
+
+/** Renders one action as a full command markdown file. */
+export function renderActionCommand(action: ActionDef): string {
+  return `---
+description: ${action.description}
+---
+${userMessageSection}
+
+# ${action.name.charAt(0).toUpperCase() + action.name.slice(1)}
+
+${action.body}`;
+}
+
 const COMPACT_TEMPLATE = `---
 description: Flush thatch persistence, check for loose ends, then compact if clear
 ---
@@ -67,29 +155,40 @@ ${EXIT_READY_TOKEN}
 
 If anything is outstanding, list the items concisely so the user can address them, and do NOT include the token. opencode will only exit when the token is present.`;
 
-/** One wrap-up command: the command name (minus the thatch/ prefix) and its full markdown file content. */
+/** One command: the command name (minus the thatch/ prefix) and its full markdown file content. */
 export interface CommandDef {
   name: string;
   content: string;
 }
 
-/** The wrap-up command set, as full command-file contents ready to write. */
+/** The opencode command set: wrap-ups plus every action, as full file contents. */
 export function opencodeCommandDefs(): CommandDef[] {
   return [
     { name: "compact", content: COMPACT_TEMPLATE },
     { name: "exit", content: EXIT_TEMPLATE },
+    ...actionDefs(opencodeToolName).map((a) => ({ name: a.name, content: renderActionCommand(a) })),
   ];
 }
 
 /**
- * Sync the wrap-up commands into <configHome>/opencode/command/thatch/.
- * Idempotent: each file is written only when its on-disk content differs.
- * Returns the paths that were written (empty when everything was current).
+ * The Claude Code command set: the actions minus the opencode-only ones.
+ * The wrap-up commands are excluded too - their greenlight check needs the
+ * plugin's command.execute.before arming and TUI control routes.
  */
-export function installOpencodeCommands(configHome: string): string[] {
-  const dir = join(configHome, "opencode", "command", "thatch");
+export function claudeCommandDefs(): CommandDef[] {
+  return actionDefs(mcpToolName)
+    .filter((a) => !a.opencodeOnly)
+    .map((a) => ({ name: a.name, content: renderActionCommand(a) }));
+}
+
+/**
+ * Sync command files into dir. Idempotent: each file is written only when
+ * its on-disk content differs. Returns the paths that were written (empty
+ * when everything was current).
+ */
+function syncCommandFiles(dir: string, defs: CommandDef[]): string[] {
   const written: string[] = [];
-  for (const def of opencodeCommandDefs()) {
+  for (const def of defs) {
     const path = join(dir, `${def.name}.md`);
     let current: string | null = null;
     try {
@@ -105,3 +204,13 @@ export function installOpencodeCommands(configHome: string): string[] {
   }
   return written;
 }
+
+/** Sync opencode's commands into <configHome>/opencode/command/thatch/. */
+export function installOpencodeCommands(configHome: string): string[] {
+  return syncCommandFiles(join(configHome, "opencode", "command", "thatch"), opencodeCommandDefs());
+}
+
+/** Sync Claude Code's commands into <claudeDir>/commands/thatch/ (claudeDir is ~/.claude or <project>/.claude). */
+export function installClaudeCommands(claudeDir: string): string[] {
+  return syncCommandFiles(join(claudeDir, "commands", "thatch"), claudeCommandDefs());
+}

package/src/db.ts

@@ -1,4 +1,6 @@
 import { Database } from "bun:sqlite";
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
 import { blobToVector, cosineSimilarity } from "./vector-math";
 import {
   PredictionEngine,
@@ -58,6 +60,13 @@ export class ThatchDB {
   #chat: ChatStore;
 
   constructor(path: string) {
+    // bun:sqlite creates the file but not its parent directory. On a fresh
+    // machine the default path (~/.config/thatch/thatch.db) has no dir yet, so
+    // create it here - otherwise every command fails with SQLITE_CANTOPEN.
+    // `:memory:` and other special paths have no meaningful parent to create.
+    if (path !== ":memory:" && !path.startsWith("file:")) {
+      mkdirSync(dirname(path), { recursive: true });
+    }
     this.#db = new Database(path, { create: true });
     this.#db.run("PRAGMA journal_mode = WAL");
     this.#db.run("PRAGMA busy_timeout = 5000");

package/src/embeddings.ts

@@ -1,9 +1,48 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
 // BGE-small-en-v1.5 requires a query prefix for asymmetric search.
 // Passage (memory content) gets no prefix - the model was trained
 // to encode passages without instruction.
 const QUERY_PREFIX =
   "Represent this sentence for searching relevant passages: ";
 
+/**
+ * Writable directory for the downloaded model files.
+ *
+ * transformers.js defaults its filesystem cache to a `.cache` folder *inside*
+ * its own package directory (`node_modules/@huggingface/transformers/.cache`).
+ * That breaks any read-only install - a global `bun install -g`, and Nix store
+ * paths in particular - and gets wiped on every reinstall. Anchor the cache in
+ * the platform's per-user cache location instead so it survives upgrades and
+ * works from an immutable store path.
+ *
+ *   THATCH_MODEL_CACHE  explicit override (highest priority)
+ *   XDG_CACHE_HOME      explicit base dir -> $XDG_CACHE_HOME/thatch/models
+ *   macOS              ~/Library/Caches/thatch/models
+ *   Windows            %LOCALAPPDATA%\thatch\models
+ *   Linux / other      ~/.cache/thatch/models
+ *
+ * `platform` and `home` are injectable for testing; they default to the real
+ * runtime values.
+ */
+export function modelCacheDir(
+  platform: NodeJS.Platform = process.platform,
+  home: string = homedir(),
+): string {
+  const env = process.env;
+  if (env.THATCH_MODEL_CACHE) return env.THATCH_MODEL_CACHE;
+  // Respect an explicit XDG override on any platform (some macOS users set it).
+  if (env.XDG_CACHE_HOME) return join(env.XDG_CACHE_HOME, "thatch", "models");
+  const base =
+    platform === "darwin"
+      ? join(home, "Library", "Caches")
+      : platform === "win32"
+        ? (env.LOCALAPPDATA ?? join(home, "AppData", "Local"))
+        : join(home, ".cache");
+  return join(base, "thatch", "models");
+}
+
 /**
  * Interface for an embedding model so tests can supply a mock.
  * `name` is the tag stored alongside each entry so a future reader can tell
@@ -90,7 +129,9 @@ export function resetBackendForTests(): void {
 
 const defaultPipelineFactory: PipelineFactory = async (modelName) => {
   const mode = await configureBackend();
-  const { pipeline } = await import("@huggingface/transformers");
+  const { pipeline, env } = await import("@huggingface/transformers");
+  // Redirect the model cache out of the (possibly read-only) package tree.
+  env.cacheDir = modelCacheDir();
   if (mode === "native") {
     return pipeline("feature-extraction", modelName);
   }