@jeffober/thatch 0.1.10 → 0.1.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "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/db.ts

@@ -9,6 +9,7 @@ export interface MemoryRow {
   model: string | null;
   branch: string | null;
   confidence: number | null;
+  archived: boolean;
   created_at: string;
   updated_at: string;
   recall_count: number;
@@ -69,6 +70,7 @@ export class ThatchDB {
         model     TEXT,
         branch    TEXT,
         confidence INTEGER,
+        archived  INTEGER NOT NULL DEFAULT 0,
         created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
         updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
         recall_count INTEGER NOT NULL DEFAULT 0,
@@ -102,6 +104,7 @@ export class ThatchDB {
     const wanted: [string, string][] = [
       ["recall_count", "INTEGER NOT NULL DEFAULT 0"],
       ["last_recalled_at", "TEXT"],
+      ["archived", "INTEGER NOT NULL DEFAULT 0"],
     ];
     for (const [col, decl] of wanted) {
       if (!existing.has(col)) {
@@ -170,27 +173,23 @@ export class ThatchDB {
     content: string,
     embedding: Float32Array,
     model: string,
-    opts?: { branch?: string; confidence?: number; overwrite?: boolean },
+    opts?: { branch?: string; confidence?: number; overwrite?: boolean; archived?: boolean },
   ): { ok: true } | { ok: false; error: string } {
     const slug = this.slugify(label);
     this.ensureStore(store);
 
-    // The embedding may be a view into a larger buffer (transformers.js tensor
-    // output); serialize exactly the view's bytes, not the whole backing buffer.
     const blob = new Uint8Array(embedding.buffer, embedding.byteOffset, embedding.byteLength);
     const branch = opts?.branch ?? null;
     const confidence = opts?.confidence ?? null;
+    const archived = opts?.archived === true ? 1 : (opts?.archived === false ? 0 : null);
     const now = new Date().toISOString();
-    const params = [slug, store, label, content, blob, model, branch, confidence, now, now];
 
     if (!opts?.overwrite) {
-      // Plain INSERT so the PK constraint enforces no-clobber atomically —
-      // a check-then-upsert would race against concurrent sessions.
       try {
         this.#db.run(
-          `INSERT INTO entries (slug, store, label, content, embedding, model, branch, confidence, created_at, updated_at)
-           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-          params as any,
+          `INSERT INTO entries (slug, store, label, content, embedding, model, branch, confidence, archived, created_at, updated_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+          [slug, store, label, content, blob, model, branch, confidence, archived ?? 0, now, now] as any,
         );
         return { ok: true };
       } catch (err: any) {
@@ -205,10 +204,25 @@ export class ThatchDB {
       }
     }
 
+    const existing = this.#db
+      .query("SELECT archived FROM entries WHERE slug = ? AND store = ?")
+      .get(slug, store) as { archived: number } | null;
+
+    if (existing && existing.archived && opts?.archived === undefined) {
+      return {
+        ok: false,
+        error: `"${label}" is archived. Pass archived: true to keep it archived, or archived: false to unarchive it.`,
+      };
+    }
+
+    // archived column for upsert: the INSERT VALUES always needs a non-null
+    // value (NOT NULL constraint), so use archived ?? 0. To preserve the
+    // existing value when the caller doesn't specify archived, the UPDATE
+    // clause accepts a nullable extra param: NULL means "keep existing."
     this.#db.run(
       `
-      INSERT INTO entries (slug, store, label, content, embedding, model, branch, confidence, created_at, updated_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      INSERT INTO entries (slug, store, label, content, embedding, model, branch, confidence, archived, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       ON CONFLICT(slug, store) DO UPDATE SET
         label = excluded.label,
         content = excluded.content,
@@ -216,13 +230,12 @@ export class ThatchDB {
         model = excluded.model,
         branch = COALESCE(excluded.branch, entries.branch),
         confidence = COALESCE(excluded.confidence, entries.confidence),
+        archived = COALESCE(?, entries.archived),
         updated_at = excluded.updated_at
       `,
-      params as any,
+      [slug, store, label, content, blob, model, branch, confidence, archived ?? 0, now, now, archived] as any,
     );
 
-    // Content changed, so prior dedup verdicts involving this entry are stale;
-    // clear them so findDuplicates can re-flag the pair.
     this.#db.run(
       "DELETE FROM dedup_pairs WHERE store = ? AND (slug_a = ? OR slug_b = ?)",
       [store, slug, slug],
@@ -242,22 +255,25 @@ export class ThatchDB {
   search(
     stores: string[],
     queryEmbedding: Float32Array,
-    opts?: { branch?: string; limit?: number },
+    opts?: { branch?: string; limit?: number; includeArchived?: boolean },
   ): (MemoryRow & { _score: number })[] {
     if (stores.length === 0) return [];
 
     const limit = opts?.limit ?? 10;
     const branch = opts?.branch;
+    const includeArchived = opts?.includeArchived ?? false;
 
     const placeholders = stores.map(() => "?").join(", ");
 
     interface SqlParams { sql: string; params: any[] }
 
     const { sql, params }: SqlParams = (() => {
+      const clauses = ["store IN (" + placeholders + ")", "embedding IS NOT NULL"];
+      if (!includeArchived) clauses.push("archived = 0");
       const base = `
-        SELECT slug, store, label, content, embedding, model, branch, confidence, created_at, updated_at, recall_count, last_recalled_at
+        SELECT slug, store, label, content, embedding, model, branch, confidence, archived, created_at, updated_at, recall_count, last_recalled_at
         FROM entries
-        WHERE store IN (${placeholders}) AND embedding IS NOT NULL
+        WHERE ${clauses.join(" AND ")}
       `;
 
       if (branch) {
@@ -278,6 +294,7 @@ export class ThatchDB {
     // rather than ranked. Dimension is the discriminator — model tags are
     // informational only.
     const scored = rows.flatMap((row) => {
+      row.archived = !!row.archived;
       const emb = blobToVector(row.embedding!);
       if (emb.length !== queryEmbedding.length) return [];
       return [{ ...row, embedding: row.embedding, _score: cosineSimilarity(queryEmbedding, emb) }];
@@ -295,7 +312,7 @@ export class ThatchDB {
   recall(
     stores: string[],
     queryEmbedding: Float32Array,
-    opts?: { branch?: string; limit?: number },
+    opts?: { branch?: string; limit?: number; includeArchived?: boolean },
   ): (MemoryRow & { _score: number })[] {
     const top = this.search(stores, queryEmbedding, opts);
 
@@ -326,7 +343,7 @@ export class ThatchDB {
     const limit = opts?.limit ?? 3;
 
     const rows = this.#db
-      .query("SELECT slug, label, embedding FROM entries WHERE store = ? AND embedding IS NOT NULL")
+      .query("SELECT slug, label, embedding FROM entries WHERE store = ? AND archived = 0 AND embedding IS NOT NULL")
       .all(store) as any[];
 
     const hits: SimilarEntry[] = [];
@@ -345,10 +362,10 @@ export class ThatchDB {
   }
 
   /** Lists all entries in a store, returning metadata without content. */
-  listEntries(store: string): { slug: string; label: string; branch: string | null; confidence: number | null; updated_at: string }[] {
+  listEntries(store: string): { slug: string; label: string; branch: string | null; confidence: number | null; archived: boolean; updated_at: string }[] {
     return this.#db
       .query(
-        "SELECT slug, label, branch, confidence, updated_at FROM entries WHERE store = ? ORDER BY label",
+        "SELECT slug, label, branch, confidence, archived, updated_at FROM entries WHERE store = ? ORDER BY label",
       )
       .all(store)
       .map((r: any) => ({
@@ -356,6 +373,7 @@ export class ThatchDB {
         label: r.label,
         branch: r.branch,
         confidence: r.confidence,
+        archived: !!r.archived,
         updated_at: r.updated_at,
       }));
   }
@@ -363,11 +381,14 @@ export class ThatchDB {
   /** Full content of a single entry by label. */
   showEntry(store: string, label: string): MemoryRow | null {
     const slug = this.slugify(label);
-    return this.#db
+    const row = this.#db
       .query(
-        "SELECT slug, store, label, content, embedding, model, branch, confidence, created_at, updated_at, recall_count, last_recalled_at FROM entries WHERE slug = ? AND store = ?",
+        "SELECT slug, store, label, content, embedding, model, branch, confidence, archived, created_at, updated_at, recall_count, last_recalled_at FROM entries WHERE slug = ? AND store = ?",
       )
-      .get(slug, store) as MemoryRow | null;
+      .get(slug, store) as Record<string, unknown> | null;
+    if (!row) return null;
+    row.archived = !!row.archived;
+    return row as unknown as MemoryRow;
   }
 
   forgetEntry(store: string, label: string): boolean {
@@ -386,7 +407,7 @@ export class ThatchDB {
   findDuplicates(store: string, threshold = 0.85): DedupCandidate[] {
     const rows = this.#db
       .query(
-        "SELECT slug, label, content, embedding FROM entries WHERE store = ? AND embedding IS NOT NULL ORDER BY slug",
+        "SELECT slug, label, content, embedding FROM entries WHERE store = ? AND archived = 0 AND embedding IS NOT NULL ORDER BY slug",
       )
       .all(store) as any[];
 
@@ -446,7 +467,7 @@ export class ThatchDB {
     const row = this.#db
       .query(
         `SELECT COUNT(*) AS n FROM entries
-         WHERE store = ? AND max(updated_at, COALESCE(last_recalled_at, updated_at)) < ?`,
+         WHERE store = ? AND archived = 0 AND max(updated_at, COALESCE(last_recalled_at, updated_at)) < ?`,
       )
       .get(store, cutoffIso) as any;
     return row?.n ?? 0;
@@ -465,7 +486,7 @@ export class ThatchDB {
     if (branches.length === 0) return 0;
     const placeholders = branches.map(() => "?").join(", ");
     const row = this.#db
-      .query(`SELECT COUNT(*) AS n FROM entries WHERE store = ? AND branch IN (${placeholders})`)
+      .query(`SELECT COUNT(*) AS n FROM entries WHERE store = ? AND archived = 0 AND branch IN (${placeholders})`)
       .get(store, ...branches) as any;
     return row?.n ?? 0;
   }

package/src/prompts.ts

@@ -69,6 +69,25 @@ new project knowledge, conventions, architectural decisions, investigation resul
 Session-specific context, incomplete/unverified info, anything already in
 CLAUDE.md or OPENCODE.md, speculative conclusions.
 
+## Archived Memories
+
+Memories can be marked \`archived\` — a flag for stable, long-term historical
+records that should not trigger hygiene nudges (stale, orphaned, duplicate).
+Archived memories are excluded from search/recall results by default; pass
+\`includeArchived: true\` to surface them for archaeological dives.
+
+When a branch is merged or about to be deleted, consolidate its branch-scoped
+memories into a single archived memory scoped to that same branch (preserving
+provenance). Capture intent, design decisions, review back-and-forth, PR
+number, unexpected pivots — the kind of git-archaeology context that explains
+_why_ the code looks the way it does a year from now. Then memory_forget the
+originals. The archived record outlives the branch. Future sessions searching
+with \`includeArchived: true\` can pull it up when investigating ambiguous code.
+
+Updating an archived memory requires passing \`archived\` explicitly — omit it
+and the tool returns an error. Pass \`archived: true\` to keep it archived,
+\`archived: false\` to unarchive.
+
 ## Explicit Requests
 
 "Remember X" — save immediately.
@@ -94,7 +113,7 @@ Use thatch_store_list then thatch_memory_list to see what's available, then that
   return `${base}
 
 [thatch hygiene] ${hygiene}
-When convenient this session (not before addressing the user's request), tend the store: run thatch_find_duplicates and consolidate clusters, review stale memories with thatch_memory_show and update or forget them, and forget memories scoped to deleted branches.`;
+When convenient this session (not before addressing the user's request), tend the store: run thatch_find_duplicates and consolidate clusters, review stale memories with thatch_memory_show and update or forget them, and for memories scoped to deleted branches, consolidate them into an archived historical record before forgetting the originals.`;
 }
 
 /**
@@ -181,6 +200,25 @@ new project knowledge, conventions, architectural decisions, investigation resul
 Session-specific context, incomplete/unverified info, anything already in
 CLAUDE.md, speculative conclusions.
 
+## Archived Memories
+
+Memories can be marked \`archived\` — a flag for stable, long-term historical
+records that should not trigger hygiene nudges (stale, orphaned, duplicate).
+Archived memories are excluded from search/recall results by default; pass
+\`includeArchived: true\` to surface them for archaeological dives.
+
+When a branch is merged or about to be deleted, consolidate its branch-scoped
+memories into a single archived memory scoped to that same branch (preserving
+provenance). Capture intent, design decisions, review back-and-forth, PR
+number, unexpected pivots — the kind of git-archaeology context that explains
+_why_ the code looks the way it does a year from now. Then memory_forget the
+originals. The archived record outlives the branch. Future sessions searching
+with \`includeArchived: true\` can pull it up when investigating ambiguous code.
+
+Updating an archived memory requires passing \`archived\` explicitly — omit it
+and the tool returns an error. Pass \`archived: true\` to keep it archived,
+\`archived: false\` to unarchive.
+
 ## Explicit Requests
 
 "Remember X" — save immediately.
@@ -205,7 +243,7 @@ Use store_list then memory_list to see what's available, then memory_recall as n
   return `${base}
 
 [thatch hygiene] ${hygiene}
-When convenient this session (not before addressing the user's request), tend the store: run find_duplicates and consolidate clusters, review stale memories with memory_show and update or forget them, and forget memories scoped to deleted branches.`;
+When convenient this session (not before addressing the user's request), tend the store: run find_duplicates and consolidate clusters, review stale memories with memory_show and update or forget them, and for memories scoped to deleted branches, consolidate them into an archived historical record before forgetting the originals.`;
 }
 
 /**
@@ -309,6 +347,25 @@ new project knowledge, conventions, architectural decisions, investigation resul
 Session-specific context, incomplete/unverified info, anything already in
 AGENTS.md, speculative conclusions.
 
+## Archived Memories
+
+Memories can be marked \`archived\` — a flag for stable, long-term historical
+records that should not trigger hygiene nudges (stale, orphaned, duplicate).
+Archived memories are excluded from search/recall results by default; pass
+\`includeArchived: true\` to surface them for archaeological dives.
+
+When a branch is merged or about to be deleted, consolidate its branch-scoped
+memories into a single archived memory scoped to that same branch (preserving
+provenance). Capture intent, design decisions, review back-and-forth, PR
+number, unexpected pivots — the kind of git-archaeology context that explains
+_why_ the code looks the way it does a year from now. Then memory_forget the
+originals. The archived record outlives the branch. Future sessions searching
+with \`includeArchived: true\` can pull it up when investigating ambiguous code.
+
+Updating an archived memory requires passing \`archived\` explicitly — omit it
+and the tool returns an error. Pass \`archived: true\` to keep it archived,
+\`archived: false\` to unarchive.
+
 ## Explicit Requests
 
 "Remember X" — save immediately.

package/src/tool-defs.ts

@@ -40,6 +40,7 @@ function formatEntry(
   let meta = `[${entry.store}]`;
   if (entry.branch) meta += ` branch:${entry.branch}`;
   if (entry.confidence) meta += ` confidence:${entry.confidence}`;
+  if (entry.archived) meta += " archived:true";
   parts.push(meta, "", entry.content);
   return parts.join("\n");
 }
@@ -48,6 +49,7 @@ function formatRecallResult(entry: any): string {
   let meta = `store:${entry.store}`;
   if (entry.branch) meta += ` branch:${entry.branch}`;
   if (entry.confidence) meta += ` confidence:${entry.confidence}`;
+  if (entry.archived) meta += " archived:true";
   const score = entry._score.toFixed(3);
   return `[${meta}] [score:${score}]\n${entry.content}`;
 }
@@ -118,6 +120,11 @@ const rememberDef: ToolDef = {
     overwrite: z.boolean().optional().describe(
       "Set to true to replace an existing memory with the same label.",
     ),
+    archived: z.boolean().optional().describe(
+      "Mark this memory as a stable, long-term record that should not trigger hygiene nudges. " +
+      "When updating an already-archived memory, this param is REQUIRED — " +
+      "pass archived: true to keep it archived, or archived: false to unarchive.",
+    ),
   },
   async execute(args, ctx) {
     const store = (args.store as string) || ctx.defaultStore;
@@ -125,9 +132,6 @@ const rememberDef: ToolDef = {
     const content = `# ${label}\n\n${args.content as string}`;
     const embedding = await ctx.model.passageEmbed(content);
 
-    // Write-time collision check: the embedding is already computed, so
-    // scanning the store is nearly free. The save proceeds regardless —
-    // the agent decides whether and how to reconcile.
     const similar = ctx.db.findSimilar(store, embedding, {
       excludeSlug: ctx.db.slugify(label),
     });
@@ -136,6 +140,7 @@ const rememberDef: ToolDef = {
       branch: args.branch as string | undefined,
       confidence: args.confidence as number | undefined,
       overwrite: args.overwrite as boolean | undefined,
+      archived: args.archived as boolean | undefined,
     });
 
     if (!result.ok) return result.error;
@@ -172,6 +177,9 @@ const recallDef: ToolDef = {
     limit: z.number().int().min(1).max(20).optional().describe(
       "Maximum number of results. Default 10.",
     ),
+    includeArchived: z.boolean().optional().describe(
+      "Include archived memories in results. Default false — archived memories are excluded.",
+    ),
   },
   async execute(args, ctx) {
     const stores = args.store
@@ -183,6 +191,7 @@ const recallDef: ToolDef = {
     const results = ctx.db.recall(stores, queryEmbedding, {
       branch: args.branch as string | undefined,
       limit,
+      includeArchived: args.includeArchived as boolean | undefined,
     });
 
     if (results.length === 0) return "No matching memories found.";
@@ -212,6 +221,7 @@ const listDef: ToolDef = {
         let line = `[${store}] ${e.label}`;
         if (e.branch) line += ` (branch:${e.branch})`;
         if (e.confidence) line += ` (c:${e.confidence})`;
+        if (e.archived) line += " (archived)";
         line += ` (${e.updated_at})`;
         return line;
       })