threadnote 0.3.2 → 0.3.4

package/README.md

@@ -6,18 +6,28 @@ and it does not index whole repositories by default.
 
 ## Real-World Uses
 
-Want to continue work in a fresh agent session? `threadnote install` adds user-level Codex and Claude instructions so
-new agents automatically recall recent handoffs and relevant memories before they start changing code.
+**Want to continue work in a fresh agent session?**  
+`threadnote install` adds user-level Codex, Claude, and Cursor instructions so new agents automatically recall recent handoffs and relevant memories before they start changing code.
 
-Implemented a feature a while ago and need to pick it up again? Ask the agent to recall the feature, branch, or repo.
-Threadnote returns auditable `viking://` pointers that the agent can read before deciding what still matters.
+**Implemented a feature a while ago and need to pick it up again?**  
+Ask the agent to recall the feature, branch, or repo. Threadnote returns auditable `viking://` pointers that the agent can read before deciding what still matters.
 
-Switching between Codex and Claude? Install the MCP adapter for both. The user-level instructions tell agents to store a
-handoff before they pause, so the next agent can search the same local memory layer instead of reconstructing context
+**Switching between Codex, Claude, and Cursor?**\
+Install the MCP adapter for each agent you use. The user-level instructions tell agents to store a handoff before they pause, so the next agent can search the same local memory layer instead of reconstructing context
 from chat history.
 
-Found a durable workflow fact, like how a repo runs tests or where release notes live? Ask the agent to remember it.
-Threadnote keeps that memory local and searchable without editing unrelated repo files.
+**Working through a long task until the agent context window fills up?**  
+After compaction, the next agent turn can recall the relevant Threadnote memories and handoffs instead of relying only on the compressed conversation summary.
+
+**Found a durable workflow fact, like how a repo runs tests or where release notes live?**  
+Ask the agent to remember it. Threadnote keeps that memory local and searchable without editing unrelated repo files.
+
+**Have reusable agent workflows already installed as skills?**\
+Run `threadnote seed-skills` to make local `SKILL.md` guidance discoverable through recall. Agents can find relevant testing, release, on-call, debugging, or plugin-provided workflows without you reopening the same skill files by hand.
+
+**Recall returned several overlapping memories?**
+Agents are instructed to compact them into one concise replacement memory and forget only the clearly redundant originals,
+keeping future recall sharper without losing useful detail.
 
 ## Safety Model
 
@@ -50,7 +60,7 @@ threadnote start
 threadnote doctor --dry-run
 ```
 
-If install or health checks fail, see `docs/troubleshooting.md`.
+If install or health checks fail, see [Troubleshooting](docs/troubleshooting.md).
 
 To force a runtime:
 
@@ -157,7 +167,19 @@ threadnote seed --dry-run
 threadnote seed
 ```
 
-Optionally seed shared and repo-local skills:
+For Git worktrees, seed the stable checkout by default:
+
+```bash
+threadnote init-manifest --repo ~/src/coda
+```
+
+You usually do not need to add every temporary worktree such as `~/src/worktrees/coda/my-branch`. Threadnote treats each
+worktree path as its own manifest project today, so adding every worktree can duplicate seeded repo resources and make
+recall noisier. Add a worktree only when it is long-lived or has branch-specific docs, instructions, or repo-local skills
+that should be recalled separately.
+
+Optionally seed shared and repo-local skills. This imports existing `SKILL.md` files as a searchable resource catalog so
+agents can discover relevant workflow guidance; it does not install or activate skills in the agent runtime.
 
 ```bash
 threadnote seed-skills --dry-run
@@ -183,10 +205,12 @@ This is it! Start working with your agents as usual. The agent will automaticall
   preserved by default; pass `--erase-memories` to delete `THREADNOTE_HOME`.
 - `init-manifest`: creates or updates `~/.openviking/seed-manifest.yaml` from one or more developer repo roots.
 - `seed`: imports curated repo guidance and docs from the manifest.
-- `seed-skills`: imports global and repo-local `SKILL.md` files as a searchable resource catalog. Use
-  `seed-skills --native` only after configuring a working VLM provider.
+- `seed-skills`: imports global and repo-local `SKILL.md` files as a searchable resource catalog so agents can discover
+  reusable workflow guidance. Use `seed-skills --native` only after configuring a working VLM provider.
 - `mcp-install codex|claude|cursor`: installs or prints OpenViking MCP configuration for Codex, Claude, or Cursor.
 - `remember`: stores a durable memory.
+- `migrate-memories`: migrates legacy session-only `MEMORY` and `HANDOFF` records into durable memory files. Run
+  `migrate-memories --dry-run` first; use `--all-accounts` when importing from older local OpenViking accounts.
 - `recall`: searches shared OpenViking context. It infers repo or skill scope from queries like
   `skills for api service`; use `--uri` or `--no-infer-scope` to override.
 - `read`: reads a `viking://` URI returned by `recall` or `list`.

package/dist/threadnote.cjs

@@ -7047,6 +7047,75 @@ async function runRemember(config, options) {
   ].join("\n");
   await storeMemory(config, memory, options.dryRun === true);
 }
+async function runMigrateMemories(config, options) {
+  const dryRun = options.dryRun === true;
+  const limit = options.limit ? parsePositiveInteger(options.limit, "migration limit") : void 0;
+  const sourceAccounts = await legacySourceAccounts(config, options);
+  if (sourceAccounts.length === 0) {
+    console.log("No local OpenViking accounts found to scan.");
+    return;
+  }
+  const candidates = await legacyMemoryCandidates(config, sourceAccounts);
+  const existingHashes = await existingDurableMemoryHashes(config);
+  const ov = await openVikingCliForMode(dryRun);
+  const migrationPath = (0, import_node_path4.join)(config.agentContextHome, "legacy-memory-migration.txt");
+  let duplicateCount = 0;
+  let migratedCount = 0;
+  let sensitiveCount = 0;
+  if (!dryRun && candidates.length > 0) {
+    await ensureDurableMemoryDirectory(ov, config);
+  }
+  try {
+    for (const candidate of candidates) {
+      if (existingHashes.has(candidate.hash)) {
+        duplicateCount += 1;
+        continue;
+      }
+      if (existingHashes.has(candidate.comparableHash)) {
+        duplicateCount += 1;
+        continue;
+      }
+      const sensitiveReason = sensitiveMemoryReason(candidate.text);
+      if (sensitiveReason) {
+        sensitiveCount += 1;
+        console.log(
+          `SKIP ${legacySourceLabel(candidate)}: possible ${sensitiveReason}; inspect the source archive manually if needed.`
+        );
+        continue;
+      }
+      if (limit !== void 0 && migratedCount >= limit) {
+        break;
+      }
+      const memoryUri = migratedDurableMemoryUri(config, candidate.hash);
+      if (!dryRun && await vikingResourceExists(ov, config, memoryUri)) {
+        duplicateCount += 1;
+        existingHashes.add(candidate.hash);
+        continue;
+      }
+      console.log(`${dryRun ? "Would migrate" : "Migrating"} ${legacySourceLabel(candidate)} -> ${memoryUri}`);
+      if (!dryRun) {
+        await (0, import_promises4.writeFile)(migrationPath, candidate.text, { encoding: "utf8", mode: 384 });
+        await (0, import_promises4.chmod)(migrationPath, 384);
+        await writeDurableMemoryFile(ov, config, memoryUri, migrationPath);
+        existingHashes.add(candidate.hash);
+      }
+      migratedCount += 1;
+    }
+  } finally {
+    if (!dryRun) {
+      await (0, import_promises4.rm)(migrationPath, { force: true });
+    }
+  }
+  console.log(
+    [
+      `Migration summary: ${migratedCount} ${dryRun ? "would be migrated" : "migrated"}`,
+      `${duplicateCount} duplicate(s) skipped`,
+      `${sensitiveCount} sensitive-looking item(s) skipped`,
+      `${candidates.length} legacy Threadnote item(s) scanned`,
+      `source account(s): ${sourceAccounts.join(", ")}`
+    ].join("; ")
+  );
+}
 async function runRecall(config, options) {
   const ov = await openVikingCliForMode(options.dryRun === true);
   const inferredUri = options.uri ?? (options.inferScope === false ? void 0 : await inferRecallUri(config, options.query));
@@ -7238,13 +7307,13 @@ async function waitForOpenVikingQueue(ov, config) {
   }
 }
 async function vikingResourceExists(ov, config, uri) {
-  const stat2 = await runCommand(ov, withIdentity(config, ["stat", uri]), { allowFailure: true });
-  return stat2.exitCode === 0;
+  const stat3 = await runCommand(ov, withIdentity(config, ["stat", uri]), { allowFailure: true });
+  return stat3.exitCode === 0;
 }
 async function ensureDurableMemoryDirectory(ov, config) {
   const directoryUri = durableMemoryDirectoryUri(config);
-  const stat2 = await runCommand(ov, withIdentity(config, ["stat", directoryUri]), { allowFailure: true });
-  if (stat2.exitCode === 0) {
+  const stat3 = await runCommand(ov, withIdentity(config, ["stat", directoryUri]), { allowFailure: true });
+  if (stat3.exitCode === 0) {
     return;
   }
   await maybeRun(
@@ -7264,6 +7333,164 @@ function durableMemoryUri(config, memory) {
 function durableMemoryDirectoryUri(config) {
   return `viking://user/${uriSegment(config.user)}/memories/events`;
 }
+function migratedDurableMemoryUri(config, hash) {
+  return `${durableMemoryDirectoryUri(config)}/threadnote-migrated-${hash.slice(0, 16)}.md`;
+}
+async function legacySourceAccounts(config, options) {
+  const explicitAccounts = options.sourceAccount?.filter((account) => account.trim().length > 0) ?? [];
+  if (explicitAccounts.length > 0) {
+    return uniqueStrings(explicitAccounts);
+  }
+  if (options.allAccounts === true) {
+    const accounts = await childDirectoryNames(localVikingDataRoot(config));
+    return accounts.filter((account) => !account.startsWith("_"));
+  }
+  return [config.account];
+}
+async function legacyMemoryCandidates(config, sourceAccounts) {
+  const candidates = [];
+  for (const sourceAccount of sourceAccounts) {
+    const sessionRoot = (0, import_node_path4.join)(localVikingDataRoot(config), sourceAccount, "session");
+    for (const sourceSession of await childDirectoryNames(sessionRoot)) {
+      const historyRoot = (0, import_node_path4.join)(sessionRoot, sourceSession, "history");
+      for (const sourceArchive of await childDirectoryNames(historyRoot)) {
+        if (!sourceArchive.startsWith("archive_")) {
+          continue;
+        }
+        const sourcePath = (0, import_node_path4.join)(historyRoot, sourceArchive, "messages.jsonl");
+        for (const text of await legacyMemoryTexts(sourcePath)) {
+          candidates.push({
+            comparableHash: sha256(comparableMemoryText(text)),
+            hash: sha256(text),
+            sourceAccount,
+            sourceArchive,
+            sourceSession,
+            text
+          });
+        }
+      }
+    }
+  }
+  return candidates.sort((left, right) => legacySourceLabel(left).localeCompare(legacySourceLabel(right)));
+}
+async function legacyMemoryTexts(sourcePath) {
+  const raw = await readTextIfExists(sourcePath);
+  if (!raw) {
+    return [];
+  }
+  const memories = [];
+  for (const line of raw.split("\n")) {
+    const trimmedLine = line.trim();
+    if (!trimmedLine) {
+      continue;
+    }
+    try {
+      const parsed = JSON.parse(trimmedLine);
+      const text = legacyMessageText(parsed)?.trim();
+      if (text && isLegacyThreadnoteMemory(text)) {
+        memories.push(text);
+      }
+    } catch (_err) {
+      continue;
+    }
+  }
+  return memories;
+}
+function legacyMessageText(value) {
+  if (!isJsonObject(value)) {
+    return void 0;
+  }
+  if (typeof value.content === "string") {
+    return value.content;
+  }
+  if (!Array.isArray(value.parts)) {
+    return void 0;
+  }
+  const parts = value.parts.map((part) => isJsonObject(part) && part.type === "text" && typeof part.text === "string" ? part.text : void 0).filter((text) => text !== void 0);
+  return parts.length > 0 ? parts.join("\n") : void 0;
+}
+function isLegacyThreadnoteMemory(text) {
+  return text.startsWith("MEMORY\n") || text.startsWith("HANDOFF\n");
+}
+async function existingDurableMemoryHashes(config) {
+  const hashes = /* @__PURE__ */ new Set();
+  await collectDurableMemoryHashes(localVikingDataRoot(config), hashes);
+  return hashes;
+}
+async function collectDurableMemoryHashes(root, hashes) {
+  let entries;
+  try {
+    entries = await (0, import_promises4.readdir)(root, { withFileTypes: true });
+  } catch (_err) {
+    return;
+  }
+  for (const entry of entries) {
+    const path = (0, import_node_path4.join)(root, entry.name);
+    if (entry.isDirectory()) {
+      await collectDurableMemoryHashes(path, hashes);
+      continue;
+    }
+    if (!entry.isFile() || entry.name.startsWith(".") || !entry.name.endsWith(".md") || !isDurableMemoryPath(path)) {
+      continue;
+    }
+    const content = await readTextIfExists(path);
+    if (content) {
+      const trimmedContent = content.trim();
+      hashes.add(sha256(trimmedContent));
+      hashes.add(sha256(comparableMemoryText(trimmedContent)));
+    }
+  }
+}
+function isDurableMemoryPath(path) {
+  return path.split(import_node_path4.sep).includes("memories");
+}
+async function childDirectoryNames(path) {
+  let entries;
+  try {
+    entries = await (0, import_promises4.readdir)(path, { withFileTypes: true });
+  } catch (_err) {
+    return [];
+  }
+  return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+}
+async function readTextIfExists(path) {
+  try {
+    const pathStat = await (0, import_promises4.stat)(path);
+    if (!pathStat.isFile()) {
+      return void 0;
+    }
+    return await (0, import_promises4.readFile)(path, "utf8");
+  } catch (_err) {
+    return void 0;
+  }
+}
+function sensitiveMemoryReason(text) {
+  const patterns = [
+    { name: "private key", regex: /-----BEGIN [A-Z ]*PRIVATE KEY-----/ },
+    { name: "API key", regex: /\bsk-[A-Za-z0-9_-]{16,}/ },
+    { name: "GitHub token", regex: /\bgh[pousr]_[A-Za-z0-9_]{16,}/ },
+    { name: "bearer token", regex: /\bBearer\s+[A-Za-z0-9._~+/=-]{20,}/i },
+    { name: "AWS access key", regex: /\bAKIA[0-9A-Z]{16}\b/ }
+  ];
+  return patterns.find((pattern) => pattern.regex.test(text))?.name;
+}
+function comparableMemoryText(text) {
+  const trimmed = text.trim();
+  if (!trimmed.startsWith("MEMORY\n")) {
+    return trimmed;
+  }
+  const separatorIndex = trimmed.indexOf("\n\n");
+  return separatorIndex === -1 ? trimmed : trimmed.slice(separatorIndex + 2).trim();
+}
+function legacySourceLabel(candidate) {
+  return `${candidate.sourceAccount}/${candidate.sourceSession}/${candidate.sourceArchive}`;
+}
+function localVikingDataRoot(config) {
+  return (0, import_node_path4.join)(config.agentContextHome, "data", "viking");
+}
+function uniqueStrings(values) {
+  return [...new Set(values)].sort();
+}
 function isResourceBusy(stderr, stdout) {
   return `${stderr}
 ${stdout}`.includes("resource is busy");
@@ -8766,6 +8993,14 @@ async function main() {
   program2.command("remember").description("Store a durable engineering memory in OpenViking").option("--dry-run", "Print memory and ov command without storing").option("--source-agent-client <name>", "codex, claude, cursor, gemini, or another client name", "codex").option("--stdin", "Read memory text from stdin").option("--text <text>", "Memory text to store").action(async (options) => {
     await runRemember(getRuntimeConfig(program2), options);
   });
+  program2.command("migrate-memories").description("Migrate legacy session-only Threadnote memories into durable memory files").option("--all-accounts", "Scan all local OpenViking accounts under THREADNOTE_HOME").option("--dry-run", "Print migration actions without writing memories").option("--limit <count>", "Maximum number of memories to migrate").option(
+    "--source-account <account>",
+    "Source OpenViking account to scan; repeat for multiple accounts",
+    collectOption,
+    []
+  ).action(async (options) => {
+    await runMigrateMemories(getRuntimeConfig(program2), options);
+  });
   program2.command("recall").description("Search shared OpenViking context").requiredOption("--query <query>", "Search query").option("--dry-run", "Print ov command without searching").option("-n, --node-limit <count>", "Maximum number of search results").option("--no-infer-scope", "Disable query-based scope inference").option("--uri <uri>", "Restrict search to a viking:// URI").action(async (options) => {
     await runRecall(getRuntimeConfig(program2), options);
   });

package/docs/agent-instructions.md

@@ -36,6 +36,19 @@ logs, or other sensitive data.
 Also remember durable workflow facts you discover during work when they would help future agents and are not already in
 canonical docs. Prefer updating checked-in docs for canonical repo rules.
 
+## Memory Compaction
+
+When recall/read surfaces several memories that describe the same durable fact, incident, branch, or handoff, compact
+them when it is safe:
+
+- Store one concise replacement memory that preserves the current status, the important facts, and the source `viking://`
+  URIs you merged.
+- Remove superseded duplicates with `threadnote forget <uri>` only when they are clearly redundant or stale and contain
+  no unique useful detail.
+- If the memories disagree or you are not sure what can be deleted, keep them and mention the possible cleanup instead.
+
+Never compact secrets, credentials, customer data, raw production logs, or checked-in canonical docs into memory.
+
 ## Handoff
 
 Before pausing, switching agents, or ending meaningful work with local changes, store a concise handoff. Include:
@@ -59,5 +72,6 @@ threadnote recall --query "last handoff for this branch"
 threadnote read viking://agent/threadnote/memories/.abstract.md
 threadnote list viking://agent/threadnote/memories --all --recursive
 threadnote remember --text "Durable engineering note..."
+threadnote forget viking://user/example/memories/events/duplicate.md
 threadnote handoff --task "short task summary" --tests "checks run" --next-step "what to do next"
 ```

package/docs/migration.md

@@ -171,6 +171,8 @@ Preferred agent behavior is automatic after `threadnote install` has updated the
 
 - On non-trivial task start, search OpenViking for recent handoffs and relevant repo guidance.
 - When the user says "remember", store the memory after checking that it contains no secret or customer data.
+- When recall surfaces clearly duplicate or stale memories, store one concise replacement memory and forget only the
+  redundant originals.
 - Before pausing, switching agents, or finishing meaningful code changes, store a concise handoff with status, tests,
   blockers, and next steps.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "threadnote",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "type": "commonjs",
   "main": "dist/threadnote.cjs",
   "description": "Shared local context and handoffs for development agents",