@jeffober/thatch 0.1.31 → 0.1.33

package/README.md

@@ -84,8 +84,9 @@ Thatch gives your agent three layers of persistent context:
   classifier. Confidence adjusts the same way as predictions. An anti-laziness
   guard in the prompt prevents the agent from codifying shortcuts.
 
-Plus **24 skills** for memory workflows, structured multi-specialist code
-review, review response, change and feature walkthroughs, and writing tasks
+Plus **26 skills** for memory workflows, structured multi-specialist code
+review, review response, change and feature walkthroughs, memory verification,
+knowledge export, and writing tasks
 (PR descriptions, tickets, PR splitting).
 
 See the [user guide](docs/user/README.md) for the full tool list, CLI

package/artifacts/skills/thatch-knowledge-export.md

@@ -0,0 +1,149 @@
+---
+name: thatch-knowledge-export
+description: 'Compile everything thatch knows about a topic into a curated, self-contained markdown file for knowledge transfer to another engineer. Searches across stores with varied query phrasings, curates out personal noise, fact-checks code-related memories against the current codebase, and generates a clean export. Use when the user asks to export, compile, or transfer knowledge about a topic.'
+---
+
+You are a knowledge exporter.
+Your job is to find everything thatch knows about a topic, verify it, curate it, and write it into a markdown file that another engineer can use to get up to speed.
+
+# The Use Case
+
+The user and a teammate work on the same project. The user's agent has accumulated memories across sessions. The teammate needs that knowledge. This skill compiles it into a portable, self-contained document.
+
+The export is **knowledge transfer**, not personality transfer. It contains technical and project context that a colleague needs to be productive. It does not contain the user's inner monologue about their teammates.
+
+# Method
+
+## Step 1: Store Selection
+
+Call `thatch_store_list` to enumerate all available stores.
+
+Ask the user which stores are relevant to this export. The user may have personal and work stores on the same machine. Including personal stores would add confusing noise. The user is the filter.
+
+Present the store list and ask: "Which of these stores should I search? Exclude any that are personal or unrelated."
+
+Default to all stores if the user says "all" or does not specify. But asking is the right default because the personal-vs-work distinction matters.
+
+## Step 2: Broad Search
+
+`thatch_memory_recall` caps at 20 results per call and uses semantic search. A single query will miss memories that use different vocabulary for the same concept. To be comprehensive, issue multiple calls with deliberately varied phrasings.
+
+For each selected store, run `thatch_memory_recall` with:
+- The topic name directly
+- Synonyms and alternate phrasings (e.g. "rotation keys" and "key rotation" and "KMS key cycling")
+- Broader framings (e.g. "database architecture" when the topic is "migration system")
+- Narrower framings (e.g. "batch cursor implementation" when the topic is "rotation system")
+- Related subsystem names (e.g. "scanner API" when the topic is "scanning pipeline")
+- Jargon variants the team might use
+
+Set `limit` to 20 (the maximum) on each call to cast the widest net.
+
+Also call `thatch_memory_list` for each selected store. This enumerates every label, catching memories that semantic search missed because the label text does not match the query but the content is relevant.
+
+Set `includeArchived: true` on recall calls. Archived memories are historical context that may be valuable for the export, even though they are excluded from default search.
+
+## Step 3: Dedup by Label
+
+Multiple recall calls with different phrasings will return overlapping results. Collect unique labels only. A memory that appears in three query results is still one memory.
+
+## Step 4: Read and Classify
+
+Call `thatch_memory_show` for each unique label. Read the full content.
+
+Classify each memory into one of three categories:
+
+- **Code-related** — architecture, data models, file paths, function names, conventions, API contracts, configuration. These need fact-checking.
+- **Preference/process** — user preferences, workflow decisions, review attitudes, coding style guidance. These do not need fact-checking but need curation.
+- **Archived** — historical records, flagged with `archived:true`. Included in the export as-is. No fact-checking.
+
+## Step 5: Curation Filter
+
+Review every memory for content that is personal to the user or could cause friction if shared with a colleague. This applies to all categories, including code-related ones.
+
+**Exclude or sanitize content that includes:**
+- Attitudes toward specific reviewers, reviewees, or managers (e.g. "Jeff finds Cody's PRs frustrating because...")
+- Emotional reactions to code, people, or process (e.g. "OMFG this react was written like COBOL")
+- Interpersonal dynamics or opinions about individuals' coding ability
+- Anything the user would not want a colleague to read
+
+**When in doubt, exclude.** The export is for a colleague, not for the user's therapist.
+
+Strip the "who said what" and keep the "what is true about the code." If a memory says "Jeff prefers X because Nik's approach caused a bug in PR #123," the export should say "Approach X is preferred. Approach Y caused a bug in PR #123." Keep the technical fact, drop the personal framing.
+
+This curation applies to the export file only. Do not modify the original memories in the store. The user's memories are the user's memories. The export is a curated view.
+
+## Step 6: Fact-Check
+
+Load the `thatch-memory-verify` skill. Apply it to each code-related, non-archived memory.
+
+If your harness supports sub-agent dispatch, you may process multiple memories concurrently by dispatching `thatch-memory-verify` for each one in parallel.
+
+Wait for all verifications to complete before proceeding to generation. Each verification may correct stale memories in the store.
+
+**After all verifications complete**, re-read each memory that was corrected by calling `thatch_memory_show` again. The verify skill corrects memories in-place via `overwrite: true`, so the version in your context may be stale. You need the corrected version for the export.
+
+## Step 7: Generate the Export
+
+Ask the user where to write the export file. Write to the specified path.
+
+Structure the markdown as follows:
+
+```
+# Knowledge Export: <topic>
+
+Generated: <date>
+Stores: <list of stores searched>
+
+## Summary
+
+<2-3 paragraph synthesis of what is known about this topic. Write for an engineer who is new to this area. Lead with the most important architectural facts, then conventions, then gotchas.>
+
+## Verified Knowledge
+
+### <memory label>
+
+Store: <store> | Confidence: <n>/10 | Verified: <date>
+
+<memory content, corrected if needed. Include `path:line` citations from the fact-check where available.>
+
+### <next memory label>
+
+...
+
+## Historical Context
+
+### <memory label>
+
+Store: <store> | Archived
+
+<memory content as-is. These are historical records and may describe a state that no longer exists. They are included for context, not as current truth.>
+
+## Preferences & Process
+
+### <memory label>
+
+Store: <store>
+
+<memory content, curated for professional relevance. Personal opinions and interpersonal observations have been removed.>
+```
+
+**Do not include a corrections section in the export file.** The receiving LLM or engineer should see only the corrected state, not the history of what was wrong. Including stale-then-corrected facts risks hallucination about the old version. Corrections are reported to the user separately (Step 8).
+
+Branch-scoped memories get a note: `(scoped to branch: <branch>)` after the store name.
+
+## Step 8: Report to User
+
+Tell the user:
+- Where the export file was written
+- How many memories were included (by category: verified, historical, preferences)
+- A brief summary of corrections made during fact-checking (which memories were updated and what changed)
+
+This correction summary is for the user only. It does not go in the export file.
+
+# Notes
+
+- The export file is self-contained. The receiving engineer should not need thatch database access to use it. Include full memory content, not just labels.
+- Confidence scores and store names are included so the reader can assess reliability.
+- If the user asks to export knowledge for a specific purpose (e.g. "for Nik to review my project"), tailor the summary to that purpose.
+- Archived memories are valuable for understanding why code looks the way it does. Include them, but label them clearly as historical.
+- The curation step is about professional relevance, not about hiding technical truth. If a memory records that a specific approach caused a bug, that is technical information the colleague needs. The personal framing around it is what gets stripped.

package/artifacts/skills/thatch-memory-verify.md

@@ -0,0 +1,116 @@
+---
+name: thatch-memory-verify
+description: 'Fact-check a single thatch memory against the current codebase and correct it if stale. Use when the user asks to verify memories, or when a coordinating skill (like thatch-knowledge-export) needs each memory checked before use. Dispatches sub-agents when available; falls back to inline investigation. Reports corrections to the coordinating agent and reminds it to refresh its context.'
+---
+
+You are a memory verifier.
+Your job is to take a single thatch memory, check every code-related claim it makes against the current codebase, correct what is stale, and report the result.
+
+This skill operates on one memory at a time. A coordinating agent (such as `thatch-knowledge-export`) may dispatch this skill multiple times in parallel for different memories.
+
+# The Problem
+
+Memories are written when knowledge is discovered. Code changes. A memory that was accurate when written may now describe a world that no longer exists: a function that was renamed, a file that was moved, a convention that was replaced, a data model that was refactored. The memory stays in the store, confidently wrong, until someone catches it.
+
+This skill is the catch.
+
+# Method
+
+## Step 1: Read the Memory
+
+Call `thatch_memory_show` with the label (or accept the memory content directly if dispatched by a coordinator that already read it).
+
+Note the `created_at` and `updated_at` dates. A memory that was last updated recently is less likely to be stale than one that has not been touched in months.
+
+## Step 2: Classify Claims
+
+Read the memory content and identify every claim that references code. These include:
+
+- File paths and module locations
+- Function, class, or variable names
+- Architecture descriptions (how components connect, what calls what)
+- Data model descriptions (table names, column names, relationships)
+- API contracts (endpoint paths, request/response shapes)
+- Conventions (naming patterns, file organization rules)
+- Configuration details (env vars, settings, defaults)
+
+Claims that are NOT code-related do not need verification:
+- User preferences and personality
+- Process decisions and workflow rules
+- Historical narratives about why something was done
+- General engineering principles
+
+If the memory has no code-related claims, report it as "no code claims to verify" and stop.
+
+## Step 3: Investigate
+
+For each code-related claim, check it against the current codebase.
+
+**If your harness supports sub-agent dispatch** (e.g. opencode's Task tool), dispatch a sub-agent with:
+- The memory's full content and label
+- The specific claim to verify
+- Instructions: investigate the codebase, report VERIFIED (cite `path:line`) or STALE (describe what changed, cite `path:line`). Read-only. No file modifications.
+- If sub-agents are available, you may process multiple claims concurrently.
+
+**If sub-agents are not available** (e.g. Claude Code without Task support), investigate each claim inline. Read the referenced files, grep for the named functions, check the data model, trace the architecture.
+
+For each claim, your investigation produces one of:
+- **VERIFIED** — the claim is still accurate. Cite `path:line` as evidence.
+- **STALE** — the claim is no longer accurate. Describe what changed. Cite `path:line` as evidence.
+- **UNVERIFIABLE** — you cannot determine whether the claim is still accurate (e.g. the referenced file was deleted, the referenced service is not in this repo). Explain why.
+
+## Step 4: Git Archaeology for Stale Claims
+
+When a claim is STALE, do git archaeology to understand why it changed:
+
+1. `git log --oneline -- <referenced file>` — find recent commits to the file
+2. `git log --all --oneline --grep="<old function name>"` — find commits that mention the old name
+3. `git blame <referenced file> -L <line>,<line>` — find when a specific line changed
+4. Check commit messages and linked PRs/tickets for intent
+
+You are looking for the commit that changed the claim from true to false. Determine whether the change was **intentional** (a deliberate design decision for a named project or ticket) or **incidental** (a side effect of a refactor or cleanup).
+
+## Step 5: Correct the Memory
+
+If any claims are STALE, update the memory with `thatch_memory_remember`, using `overwrite: true` and the same label.
+
+**For unintentional changes or when the commit cannot be found**: correct the claim to reflect the current state. Remove the stale claim and replace it with the accurate description.
+
+**For intentional changes where the commit and project are identified**: correct the claim but preserve the history. Frame the correction so the memory records both what is true now and what was true before:
+
+> X is true. Y was true until commit `abc1234` (PR #123, project PLAT-122) intentionally changed it to X.
+
+This keeps the memory useful as both a current reference and a historical record. The receiving engineer understands both where things stand and why they changed.
+
+Preserve the original confidence level unless the correction materially changes the durability assessment. Keep non-code claims (preferences, process notes) unchanged.
+
+If no claims are STALE, do not update the memory.
+
+## Step 6: Report to Coordinator
+
+Report your results to the coordinating agent. Format:
+
+```
+Memory: "<label>" (store: <store>)
+Verified: N claims
+Corrected: M claims
+Unverifiable: K claims
+
+Corrections applied:
+- Claim: "<old claim>"
+  Status: stale (intentional, commit abc1234, PLAT-122)
+  Corrected to: "<new claim>"
+- Claim: "<old claim>"
+  Status: stale (incidental)
+  Corrected to: "<new claim>"
+```
+
+**Remind the coordinating agent** that corrections have already been written to the store via `thatch_memory_remember` with `overwrite: true`. The coordinator must call `thatch_memory_show` again for this label to refresh its context with the corrected version before using the memory in downstream output. This is load-bearing: without the refresh, the coordinator will use the stale version it already has in context.
+
+If no corrections were needed, report "all claims verified, no updates needed."
+
+# Proactive Use
+
+When `thatch_memory_show` or `thatch_memory_recall` returns a memory with an old `updated_at` date (more than a few weeks), consider loading this skill to fact-check it before relying on its code-related claims. The `updated_at` date is included in the memory output for this purpose.
+
+This is not mandatory for every old memory. Use judgment: a memory about a stable architectural decision may be fine for months, while a memory about file locations or function names is more likely to drift.

package/docs/dev/README.md

@@ -69,7 +69,7 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 | `extract-queue.ts` | File-backed per-session JSONL queue (caps 20, oldest dropped). Shared by the Claude Code and Cursor hook paths, which fire one-shot per event with no cross-call state. This is the MCP-side equivalent of `extraction.ts`. |
 | `sideband.ts` | Unix domain socket server + client. The MCP server (long-lived, warm model) runs `SidebandServer` so one-shot hook processes can ask it to embed a prompt and search for matches without loading the model themselves. Handles three methods: `match` (recall nudge), `predictions` (prediction auto-fire), and `behaviors` (behavior auto-fire). Socket path is a hash of the DB path — both processes compute it independently. |
 | `prompts.ts` | Text constants: opencode system prompt, compaction context, session-start reminder, prompt-aware recall nudge (`recallNudge` / `claudeRecallNudge`), prediction nudge (`predictionNudge`), behavior nudge (`behaviorNudge`), prediction verb selection (`predictionVerb`), Claude Code CLAUDE.md instructions, Cursor AGENTS.md instructions, Claude Code hook text. |
-| `skills.ts` | `SKILL.md` content for all thatch skills, plus the installer. Skills are split into `SHARED_SKILLS` (23 skills: fact-extractor, dedup-classifier, project-primer, 8 review specialists, review synthesizer, review context, code archaeology, review followup, review response, change walkthrough, code walkthrough, session reflection, coding-workflow, thatch-pr-description, thatch-ticket-description, thatch-split-overlarge-pr — work on all three hosts) and `OPENCODE_ONLY_SKILLS` (1 skill: code-review coordinator — requires sub-agent support, not installed for Claude Code or Cursor). `installSkills(dir, skills)` defaults to `SHARED_SKILLS`; the opencode plugin passes `[...SHARED_SKILLS, ...OPENCODE_ONLY_SKILLS]`. |
+| `skills.ts` | `SKILL.md` content for all thatch skills, plus the installer. Skills are split into `SHARED_SKILLS` (25 skills: fact-extractor, dedup-classifier, project-primer, 8 review specialists, review synthesizer, review context, code archaeology, review followup, review response, change walkthrough, code walkthrough, session reflection, coding-workflow, thatch-pr-description, thatch-ticket-description, thatch-split-overlarge-pr, memory-verify, knowledge-export — work on all three hosts) and `OPENCODE_ONLY_SKILLS` (1 skill: code-review coordinator — requires sub-agent support, not installed for Claude Code or Cursor). `installSkills(dir, skills)` defaults to `SHARED_SKILLS`; the opencode plugin passes `[...SHARED_SKILLS, ...OPENCODE_ONLY_SKILLS]`. |
 | `scoring-engine.ts` | Generic four-table scoring engine with Bayesian confidence. Shared base for prediction and behavior engines — each wraps it with table-specific names. |
 | `prediction.ts` | Thin wrapper around `ScoringEngine` with prediction-specific table names. |
 | `behavior.ts` | Thin wrapper around `ScoringEngine` with behavior-specific table names. |

package/docs/dev/skills.md

@@ -29,9 +29,9 @@ description: Extract durable project facts ... Use when ...
   Code, and Cursor all auto-discover skills and use the description for
   relevance).
 
-## The 24 skills
+## The 26 skills
 
-**Shared (23)** — installed everywhere; no sub-agents required:
+**Shared (25)** — installed everywhere; no sub-agents required:
 
 | Skill | Role |
 |-------|------|
@@ -58,6 +58,8 @@ description: Extract durable project facts ... Use when ...
 | `thatch-ticket-description` | Draft ticket/issue descriptions with clear sections, project-context research, clarity checks, and bold+italic emphasis for scanning. |
 | `thatch-split-overlarge-pr` | Split already-completed work from an overlarge PR into human-reviewable, release-safe PRs targeting main. |
 | `thatch-review-response` | Author-side review response: triage findings, fix bugs one by one, reply on each thread, post a top-level summary comment. |
+| `thatch-memory-verify` | Fact-check a single memory against the current codebase and correct stale claims. Uses git archaeology to preserve historical context when changes were intentional. |
+| `thatch-knowledge-export` | Compile everything thatch knows about a topic into a curated markdown file for knowledge transfer. Searches across stores, curates out personal noise, fact-checks code-related memories via `thatch-memory-verify`. |
 
 **opencode-only (1)** — the coordinator needs sub-agent support:
 
@@ -97,7 +99,7 @@ The synthesizer reuses the same verification rigor but has its own structure
 ## The two arrays
 
 ```ts
-const SHARED_SKILLS: SkillDef[] = [ /* 23 skills above */ ];
+const SHARED_SKILLS: SkillDef[] = [ /* 25 skills above */ ];
 const OPENCODE_ONLY_SKILLS: SkillDef[] = [ /* code-review coordinator */ ];
 ```
 

package/docs/user/README.md

@@ -218,6 +218,8 @@ With `thatch setup --claude`, skills install to `~/.claude/skills/` (or
 | `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. |
+| `thatch-memory-verify` | Fact-checks a single memory against the current codebase and corrects stale claims. Uses git archaeology to preserve historical context when changes were intentional. |
+| `thatch-knowledge-export` | Compiles everything thatch knows about a topic into a curated markdown file for knowledge transfer to another engineer. Searches across stores, curates out personal noise, fact-checks code-related memories. |
 
 ### Code review skills
 
@@ -261,7 +263,7 @@ response, walkthrough, and workflow skills that support the review pipeline:
 
 | Skill | opencode | Claude Code | Cursor |
 |-------|----------|-------------|--------|
-| Memory skills (4) | Yes | Yes | Yes |
+| Memory skills (6) | Yes | Yes | Yes |
 | Review specialists (8) | Yes | Yes | Yes |
 | Review synthesizer | Yes | Yes | Yes |
 | Review context + code archaeology | Yes | Yes | Yes |

package/docs/user/skills.md

@@ -20,7 +20,7 @@ becomes part of the agent's context.
 
 ## What ships
 
-24 skills total (23 shared, 1 opencode-only):
+26 skills total (25 shared, 1 opencode-only):
 
 ### Memory skills
 
@@ -30,6 +30,8 @@ becomes part of the agent's context.
 | `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. |
+| `thatch-memory-verify` | Fact-checks a single memory against the current codebase and corrects stale claims. Uses git archaeology to preserve historical context when changes were intentional. |
+| `thatch-knowledge-export` | Compiles everything thatch knows about a topic into a curated markdown file for knowledge transfer to another engineer. Searches across stores, curates out personal noise, fact-checks code-related memories. |
 
 ### Code review skills
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.1.31",
+  "version": "0.1.33",
   "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/index.ts

@@ -20,7 +20,7 @@ import { ExtractionPipeline, type ToolInteraction } from "./extraction";
 import { installSkills, SHARED_SKILLS, OPENCODE_ONLY_SKILLS } from "./skills";
 import { hygieneReport } from "./hygiene";
 import { seedDefaultBehaviors } from "./seed-behaviors";
-import { startVersionChecker, stopVersionChecker, getVersionChecker, readOnDiskVersion } from "./version-check";
+import { startVersionChecker, stopVersionChecker, getVersionChecker, readOnDiskVersion, compareSemver } from "./version-check";
 import pkg from "../package.json";
 
 // ---------------------------------------------------------------------------
@@ -398,7 +398,7 @@ export const server: Plugin = async ({ client, worktree }) => {
         const onDisk = readOnDiskVersion();
         const checker = getVersionChecker();
         const npmUpdate = checker?.getUpdateWarning() ?? null;
-        const skewWarning = onDisk && onDisk !== runningVersion
+        const skewWarning = onDisk && compareSemver(runningVersion, onDisk) < 0
           ? `thatch was upgraded to v${onDisk} but this session is running v${runningVersion}. Restart opencode to apply the update.`
           : null;
         const warning = skewWarning ?? npmUpdate;
@@ -411,6 +411,20 @@ export const server: Plugin = async ({ client, worktree }) => {
             text: versionWarningNudge(warning),
             synthetic: true,
           });
+          try {
+            const short = skewWarning
+              ? `\u26A0\uFE0F thatch upgraded to v${onDisk} (running v${runningVersion})`
+              : `\u26A0\uFE0F thatch v${checker?.getLatestVersion()} is available`;
+            await client.tui.showToast({
+              body: {
+                message: short,
+                variant: "warning",
+                duration: 5000,
+              },
+            });
+          } catch {
+            // TUI may not be connected. Best-effort.
+          }
         }
       } catch {
         // Best-effort. Version check failure must not block nudges.

package/src/prompts.ts

@@ -63,6 +63,8 @@ workflows. The host auto-discovers them, but reach for them proactively:
 - \`thatch-ticket-description\` - draft a ticket, issue, or work item (Linear or Jira) with clear sections and bold/italic emphasis for scanning.
 - \`thatch-split-overlarge-pr\` - split already-completed work from an overlarge PR into human-reviewable, release-safe PRs targeting main.
 - \`thatch-review-response\` - respond to code review on the user's own PR. Triage findings, fix bugs one by one, reply on each thread, then post a top-level summary comment.
+- \`thatch-memory-verify\` - fact-check a single memory against the current codebase and correct stale claims. Use when a memory has an old \`updated_at\` date or when preparing a knowledge export.
+- \`thatch-knowledge-export\` - compile everything thatch knows about a topic into a curated markdown file for knowledge transfer. Searches across stores, curates out personal noise, fact-checks code-related memories, and generates a clean export.
 
 ## When to Write
 
@@ -80,6 +82,16 @@ whether you've discovered knowledge worth persisting. Use thatch_memory_recall
 to check for duplicates, then thatch_memory_remember for new findings. Then
 deliver your response.
 
+## Memory Verification
+
+When thatch_memory_show or thatch_memory_recall returns a memory with an old
+updated_at date (more than a few weeks), consider loading the
+thatch-memory-verify skill to fact-check its code-related claims against the
+current codebase before relying on them. This is not mandatory for every old
+memory. Use judgment: a memory about a stable architectural decision may be
+fine for months, while a memory about file locations or function names is
+more likely to drift.
+
 ## Background Task Completions
 
 When a background task completes and its result is injected into the session,
@@ -297,6 +309,8 @@ workflows. The host auto-discovers them, but reach for them proactively:
 - \`thatch-ticket-description\` - draft a ticket, issue, or work item (Linear or Jira) with clear sections and bold/italic emphasis for scanning.
 - \`thatch-split-overlarge-pr\` - split already-completed work from an overlarge PR into human-reviewable, release-safe PRs targeting main.
 - \`thatch-review-response\` - respond to code review on the user's own PR. Triage findings, fix bugs one by one, reply on each thread, then post a top-level summary comment.
+- \`thatch-memory-verify\` - fact-check a single memory against the current codebase and correct stale claims. Use when a memory has an old \`updated_at\` date or when preparing a knowledge export.
+- \`thatch-knowledge-export\` - compile everything thatch knows about a topic into a curated markdown file for knowledge transfer. Searches across stores, curates out personal noise, fact-checks code-related memories, and generates a clean export.
 
 ## When to Write
 
@@ -314,6 +328,15 @@ whether you've discovered knowledge worth persisting. Use memory_recall to
 check for duplicates, then memory_remember for new findings. Then deliver
 your response.
 
+## Memory Verification
+
+When memory_show or memory_recall returns a memory with an old updated_at
+date (more than a few weeks), consider loading the thatch-memory-verify skill
+to fact-check its code-related claims against the current codebase before
+relying on them. This is not mandatory for every old memory. Use judgment: a
+memory about a stable architectural decision may be fine for months, while a
+memory about file locations or function names is more likely to drift.
+
 ## User Decision Model
 
 A statistical model of the user's decision-making preferences is maintained by

package/src/skills.ts

@@ -54,6 +54,8 @@ function loadSharedSkills(): SkillDef[] {
     "thatch-ticket-description",
     "thatch-split-overlarge-pr",
     "thatch-review-response",
+    "thatch-memory-verify",
+    "thatch-knowledge-export",
   ];
   return names.map((name) => ({ name, content: loadSkillFile(name) }));
 }

package/src/tool-defs.ts

@@ -66,6 +66,7 @@ function formatEntry(
   if (entry.branch) meta += ` branch:${entry.branch}`;
   if (entry.confidence) meta += ` confidence:${entry.confidence}`;
   if (entry.archived) meta += " archived:true";
+  meta += ` created:${entry.created_at} updated:${entry.updated_at}`;
   parts.push(meta, "", entry.content);
   return parts.join("\n");
 }
@@ -75,6 +76,7 @@ function formatRecallResult(entry: MemoryRow & { _score: number }): string {
   if (entry.branch) meta += ` branch:${entry.branch}`;
   if (entry.confidence) meta += ` confidence:${entry.confidence}`;
   if (entry.archived) meta += " archived:true";
+  meta += ` updated:${entry.updated_at}`;
   const score = entry._score.toFixed(3);
   return `[${meta}] [score:${score}]\n${entry.content}`;
 }

package/src/version-check.ts

@@ -4,6 +4,23 @@ import { tmpdir } from "node:os";
 import { join, dirname } from "node:path";
 import pkg from "../package.json";
 
+/**
+ * Compares two semver strings (e.g. "0.1.30", "0.1.31"). Returns a negative
+ * number if a < b, positive if a > b, 0 if equal. Pre-release tags are not
+ * supported because @jeffober/thatch does not use them.
+ */
+export function compareSemver(a: string, b: string): number {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const va = pa[i] ?? 0;
+    const vb = pb[i] ?? 0;
+    if (va < vb) return -1;
+    if (va > vb) return 1;
+  }
+  return 0;
+}
+
 /**
  * Version skew detection and npm update checking.
  *
@@ -198,7 +215,7 @@ class NpmVersionChecker {
    */
   isOutdated(): boolean {
     if (!this.#latestVersion) return false;
-    return this.#latestVersion !== pkg.version;
+    return compareSemver(pkg.version, this.#latestVersion) < 0;
   }
 
   /**
@@ -309,7 +326,7 @@ export function readNpmCacheForUpdate(dbPath: string): string | null {
     const raw = readFileSync(path, "utf-8");
     const parsed = JSON.parse(raw) as NpmCacheEntry;
     if (!parsed.version) return null;
-    if (parsed.version === pkg.version) return null;
+    if (compareSemver(pkg.version, parsed.version) >= 0) return null;
     return `thatch v${parsed.version} is available. ` +
       `Run \`npm update ${NPM_PACKAGE}\` to update, then restart your editor.`;
   } catch {