threadnote 0.4.1 → 0.6.0

package/README.md

@@ -1,9 +1,15 @@
+<p align="center">
+  <img src="./docs/threadnote-logo.svg" alt="Threadnote logo" width="200">
+</p>
+
 # Threadnote
 
 `threadnote` is a safe local workflow for using [OpenViking](https://openviking.ai/) as shared, agent-neutral context for development work.
 It is intentionally scoped to curated docs, memories, skills, and handoffs. It is not a source-navigation replacement,
 and it does not index whole repositories by default.
 
+> **Walkthrough deck:** https://kashkovsky.github.io/threadnote/
+
 ## Real-World Uses
 
 **Want to continue work in a fresh agent session?**  
@@ -222,6 +228,39 @@ claude mcp add threadnote -- threadnote-mcp-server
 Cursor uses the equivalent entry in `~/.cursor/mcp.json`.
 Copilot uses the VS Code MCP `servers` entry in the user-profile `mcp.json`.
 
+### Agent hooks (optional, opt-in)
+
+The instruction files (`~/.codex/AGENTS.md`, `~/.claude/CLAUDE.md`, etc.) are the **cross-agent guidance floor** — they
+ask agents to recall context, store handoffs, and so on, and they work for every supported agent. They rely on the
+agent to comply.
+
+For deterministic moments where the agent shouldn't have to remember, Threadnote can also install agent-side
+**hooks** — currently for Claude Code (the only supported agent that exposes a hook surface today):
+
+- **`PreCompact`** auto-stores a handoff snapshot for the current repo right before Claude compacts the conversation,
+  so the next turn can recall it even if the agent forgot to write a handoff manually.
+- **`SessionStart`** preloads the latest threadnote handoff/feature memory for the current repo into the new session
+  context, so the first turn already knows where you left off.
+
+Install them per agent (Codex / Cursor / Copilot are no-ops today — Threadnote prints a clear explanation):
+
+```bash
+threadnote install-hooks claude --dry-run   # preview the change
+threadnote install-hooks claude --apply     # add managed entries to ~/.claude/settings.json
+threadnote install-hooks claude --remove --apply  # take them out again
+```
+
+Or opt in at install time and let Threadnote drive every supported agent in one shot:
+
+```bash
+threadnote install --with-hooks
+```
+
+Managed entries are tagged with `"_threadnote": "managed"` so `threadnote repair` and `threadnote uninstall` can find
+and rewrite/remove only those entries without touching any of your own hooks. Hooks complement, not replace, the
+instruction files: the soft guidance covers semantic decisions ("is this memory durable?", "is this work meaningful
+enough to publish?"); hooks cover deterministic moments the agent shouldn't be trusted to remember.
+
 If a future OpenViking build exposes a healthy native endpoint, install it explicitly:
 
 ```bash

package/dist/mcp_server.cjs

@@ -33736,6 +33736,8 @@ var TEAMS_FILE_VERSION = 1;
 var SHARED_SEGMENT = "shared";
 var DEFAULT_GIT_REMOTE_NAME = "origin";
 var SCRUBBER_PATTERNS = [
+  // Credentials: never redactable. Blocking is the only safe response —
+  // automated redaction risks false negatives that leave material in git.
   { name: "private key", regex: /-----BEGIN [A-Z ]*PRIVATE KEY-----/ },
   { name: "API key (sk-...)", regex: /\bsk-[A-Za-z0-9_-]{16,}/ },
   { name: "GitHub token", regex: /\bgh[pousr]_[A-Za-z0-9_]{16,}/ },
@@ -33748,8 +33750,35 @@ var SCRUBBER_PATTERNS = [
   { name: "AWS access key", regex: /\bAKIA[0-9A-Z]{16}\b/ },
   // Slack tokens: xoxa/xoxb/xoxc (configuration)/xoxd (legacy user cookie)/
   // xoxe (refresh)/xoxp/xoxr/xoxs, with optional -N- segment for the workspace tier.
-  { name: "Slack token", regex: /\bxox[abcdeprs](?:-\d-)?[A-Za-z0-9._-]{10,}/i }
+  { name: "Slack token", regex: /\bxox[abcdeprs](?:-\d-)?[A-Za-z0-9._-]{10,}/i },
+  // Soft leaks: block by default (so the agent sees them and decides), but
+  // allow opt-in redaction so curated memories with incidental matches can
+  // ship without a manual rewrite. Local home paths are the recurring
+  // real-world leak; the regexes greedily consume the whole path segment
+  // (including subdirectories) up to whitespace or common closing punctuation
+  // so redaction collapses an entire path to a single placeholder rather than
+  // leaving the subpath visible.
+  { name: "macOS home path", placeholder: "<local-path>", regex: /\/Users\/[^\s)>"'`,]+/ },
+  { name: "linux home path", placeholder: "<local-path>", regex: /\b\/home\/[^\s)>"'`,]+/ }
 ];
+function applyScrubber(content, { redact }) {
+  let cleaned = content;
+  const redactions = [];
+  for (const pattern of SCRUBBER_PATTERNS) {
+    if (!pattern.regex.test(cleaned)) {
+      continue;
+    }
+    if (!pattern.placeholder || !redact) {
+      return { blocker: pattern.name, cleaned: content, redactions: [] };
+    }
+    const flags = pattern.regex.flags.includes("g") ? pattern.regex.flags : `${pattern.regex.flags}g`;
+    const globalRegex = new RegExp(pattern.regex.source, flags);
+    const matches = cleaned.match(globalRegex) ?? [];
+    cleaned = cleaned.replace(globalRegex, pattern.placeholder);
+    redactions.push({ count: matches.length, name: pattern.name });
+  }
+  return { cleaned, redactions };
+}
 function normalizeTeamName(input) {
   const candidate = (input ?? "default").trim();
   if (!candidate) {
@@ -33852,8 +33881,26 @@ function vikingUriToWorktreeRelative(config2, uri, team) {
   }
   return uri.slice(prefix.length);
 }
-function scrubberBlocker(content) {
-  return SCRUBBER_PATTERNS.find((pattern) => pattern.regex.test(content))?.name;
+function stripPersonalProvenance(content) {
+  const lines = content.split("\n");
+  let headerEnd = lines.length;
+  for (let index = 0; index < lines.length; index += 1) {
+    if (lines[index].trim() === "") {
+      headerEnd = index;
+      break;
+    }
+  }
+  const cleaned = [];
+  for (let index = 0; index < headerEnd; index += 1) {
+    if (/^(?:supersedes|archived_from):\s/.test(lines[index])) {
+      continue;
+    }
+    cleaned.push(lines[index]);
+  }
+  for (let index = headerEnd; index < lines.length; index += 1) {
+    cleaned.push(lines[index]);
+  }
+  return cleaned.join("\n");
 }
 async function ensureSharedDirectoryChain(config2, ov, memoryUri, dryRun) {
   const directoryUri = parentUri(memoryUri);
@@ -34230,15 +34277,19 @@ function registerTools(server, config2) {
     "share_publish",
     {
       annotations: { readOnlyHint: false, destructiveHint: true },
-      description: "Publish a personal memory into a team's shared memories git repo. Reads the memory, refuses publish if it matches secret patterns, copies it into the shared subtree, removes the personal original, and commits/pushes. Default team is used unless team is provided.",
+      description: "Publish a personal memory into a team's shared memories git repo. Reads the memory, strips local-only provenance frontmatter (supersedes:, archived_from:), refuses publish if it matches secret patterns, copies it into the shared subtree, removes the personal original, and commits/pushes. Default team is used unless team is provided. Pass preview=true to return the would-be-published bytes without writing or committing.",
       inputSchema: {
         message: external_exports.string().optional().describe('Commit message override; defaults to "share: publish <path>"'),
+        preview: external_exports.boolean().optional().describe(
+          "Return the bytes that would land in the shared git repo (after frontmatter strip and redaction) without writing or committing. Use this to inspect the body before publishing."
+        ),
         push: external_exports.boolean().optional().describe("Push to remote after committing; defaults to true"),
+        redact: external_exports.boolean().optional().describe("Replace soft-leak matches (local paths) with placeholders and continue; credentials still block."),
         team: external_exports.string().optional().describe("Team name; defaults to the configured default team"),
         uri: external_exports.string().optional().describe("Required viking:// memory URI to publish")
       }
     },
-    async ({ message, push, team, uri }) => {
+    async ({ message, preview, push, redact, team, uri }) => {
       const checkedUri = requiredVikingUri(
         uri,
         "share_publish",
@@ -34247,7 +34298,7 @@ function registerTools(server, config2) {
       if (!checkedUri.ok) {
         return checkedUri.error;
       }
-      return runSharePublishTool(config2, checkedUri.value, { message, push, team });
+      return runSharePublishTool(config2, checkedUri.value, { message, preview, push, redact, team });
     }
   );
 }
@@ -34408,16 +34459,14 @@ function registerStoreTool(server, config2, name, description) {
         project: normalizeOptionalMetadata(project),
         sourceAgentClient: sourceAgentClient ?? "mcp",
         status: status ?? "active",
-        supersedes: checkedReplaceUri.value,
         timestamp: (/* @__PURE__ */ new Date()).toISOString(),
         topic: normalizeOptionalMetadata(topic)
       };
-      return writeDurableMemory(
-        config2,
-        formatMemoryDocument("MEMORY", metadata, checkedText.value),
+      return writeDurableMemory(config2, {
+        bodyText: checkedText.value,
         metadata,
-        checkedReplaceUri.value
-      );
+        replaceUri: checkedReplaceUri.value
+      });
     }
   );
 }
@@ -34458,12 +34507,10 @@ function registerArchiveTool(server, config2, name, description) {
           timestamp: (/* @__PURE__ */ new Date()).toISOString(),
           topic: normalizeOptionalMetadata(topic)
         };
-        const archiveResult = await writeDurableMemory(
-          config2,
-          formatMemoryDocument("MEMORY", metadata, ["Archived original Threadnote memory.", "", original].join("\n")),
-          metadata,
-          void 0
-        );
+        const archiveResult = await writeDurableMemory(config2, {
+          bodyText: ["Archived original Threadnote memory.", "", original].join("\n"),
+          metadata
+        });
         if (archiveResult.isError === true) {
           return archiveResult;
         }
@@ -34486,13 +34533,18 @@ Archive stored, but original memory is still processing. Retry later with forget
     }
   );
 }
-async function writeDurableMemory(config2, memory, metadata, replaceUri) {
+async function writeDurableMemory(config2, params) {
   try {
     const ov = await requiredOpenVikingCli();
-    const directoryUri = memoryDirectoryUri(config2, metadata);
+    const directoryUri = memoryDirectoryUri(config2, params.metadata);
     await ensureMemoryDirectory(ov, config2, directoryUri);
-    const memoryUri = memoryUriFor(config2, memory, metadata);
-    const writeMode = await memoryWriteMode(ov, config2, memoryUri, metadata);
+    const candidateMetadata = { ...params.metadata, supersedes: params.replaceUri };
+    const candidateMemory = formatMemoryDocument("MEMORY", candidateMetadata, params.bodyText);
+    const memoryUri = memoryUriFor(config2, candidateMemory, candidateMetadata);
+    const isInPlaceUpdate = params.replaceUri !== void 0 && params.replaceUri === memoryUri;
+    const finalMetadata = isInPlaceUpdate ? { ...params.metadata, supersedes: void 0 } : candidateMetadata;
+    const memory = isInPlaceUpdate ? formatMemoryDocument("MEMORY", finalMetadata, params.bodyText) : candidateMemory;
+    const writeMode = await memoryWriteMode(ov, config2, memoryUri, finalMetadata);
     const result = await runOpenVikingWriteWithRetry(
       ov,
       config2,
@@ -34510,12 +34562,12 @@ async function writeDurableMemory(config2, memory, metadata, replaceUri) {
       ])
     );
     const messages = [`Stored memory: ${memoryUri}`];
-    if (replaceUri && replaceUri !== memoryUri) {
-      const removedReplacedMemory = await removeVikingResourceWithRetry(ov, config2, replaceUri);
+    if (params.replaceUri && !isInPlaceUpdate) {
+      const removedReplacedMemory = await removeVikingResourceWithRetry(ov, config2, params.replaceUri);
       messages.push(
-        removedReplacedMemory ? `Forgot replaced memory: ${replaceUri}` : `Replacement stored, but superseded memory is still processing. Retry later with forget: ${replaceUri}`
+        removedReplacedMemory ? `Forgot replaced memory: ${params.replaceUri}` : `Replacement stored, but superseded memory is still processing. Retry later with forget: ${params.replaceUri}`
       );
-    } else if (replaceUri === memoryUri) {
+    } else if (isInPlaceUpdate) {
       messages.push(`Updated existing memory in place: ${memoryUri}`);
     }
     const text = [result.stdout.trim(), result.stderr.trim()].filter(Boolean).join("\n");
@@ -34732,14 +34784,31 @@ async function runSharePublishTool(config2, sourceUri, options) {
         isError: true
       };
     }
-    const content = readResult.stdout;
-    const blocker = scrubberBlocker(content);
-    if (blocker) {
+    const stripped = stripPersonalProvenance(readResult.stdout);
+    const scrub = applyScrubber(stripped, { redact: options.redact === true });
+    const targetUri = sharedUriFor(config2, sourceUri, resolved.name);
+    if (options.preview === true) {
+      const previewLines = [`PREVIEW source: ${sourceUri}`, `PREVIEW destination: ${targetUri}`];
+      if (scrub.blocker) {
+        previewLines.push(
+          `PREVIEW BLOCKED: ${scrub.blocker}. Strip the sensitive value or pass redact=true for soft-leak patterns.`
+        );
+        return { content: [{ type: "text", text: previewLines.join("\n") }] };
+      }
+      for (const redaction of scrub.redactions) {
+        previewLines.push(`PREVIEW redact: ${redaction.count}\xD7 ${redaction.name}`);
+      }
+      previewLines.push("-----BEGIN PREVIEW-----");
+      previewLines.push(scrub.cleaned);
+      previewLines.push("-----END PREVIEW-----");
+      return { content: [{ type: "text", text: previewLines.join("\n") }] };
+    }
+    if (scrub.blocker) {
       return argumentError(
-        `Refusing to publish ${sourceUri}: possible ${blocker}. Strip the sensitive value, then retry.`
+        `Refusing to publish ${sourceUri}: possible ${scrub.blocker}. Strip the sensitive value or pass redact=true for soft-leak patterns.`
       );
     }
-    const targetUri = sharedUriFor(config2, sourceUri, resolved.name);
+    const content = scrub.cleaned;
     if (await vikingResourceExists(ov, config2, targetUri)) {
       return argumentError(
         `Refusing to publish: ${targetUri} already exists in the shared namespace. Inspect it via threadnote read; if it should be replaced, forget the existing shared copy first.`
@@ -34766,6 +34835,9 @@ async function runSharePublishTool(config2, sourceUri, options) {
       };
     }
     const messages = [`Published ${sourceUri} -> ${targetUri}`];
+    for (const redaction of scrub.redactions) {
+      messages.push(`Redacted ${redaction.count}\xD7 ${redaction.name} before publish.`);
+    }
     const relativePath = vikingUriToWorktreeRelative(config2, targetUri, resolved.name);
     const commitMessage = options.message ?? `share: publish ${relativePath}`;
     const gitMessages = await gitPublishWorkflow(