threadnote 0.3.6 → 0.3.8

package/README.md

@@ -7,12 +7,17 @@ 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, Claude, and Cursor instructions so new agents automatically recall recent handoffs and relevant memories before they start changing code.
+`threadnote install` adds user-level Codex, Claude, Cursor, and Copilot instructions so new agents automatically recall recent handoffs and relevant memories before they start changing code.
+
+**Working on a feature branch over several sessions?**
+Agents recall the branch handoff for current status, then recall durable feature memories for the design, decisions,
+interfaces, and gotchas behind the feature. As useful implementation knowledge appears, agents update the durable feature
+memory instead of leaving everything buried in transient handoffs.
 
 **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, Claude, and Cursor?**\
+**Switching between Codex, Claude, Cursor, and Copilot?**\
 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.
 
@@ -33,6 +38,43 @@ keeping future recall sharper without losing useful detail.
 Use `threadnote remember --replace <uri>` or `threadnote handoff --replace <uri>` to keep one current-state memory fresh
 instead of accumulating near-duplicate progress notes.
 
+## Memory Lifecycle
+
+Threadnote separates current durable knowledge from the historical handoff trail.
+
+New `remember` records default to `kind: durable` and `status: active`. New `handoff` records use `kind: handoff` and
+`status: active`. Add `--project` and `--topic` when the memory represents an ongoing issue or stable fact:
+
+```bash
+threadnote remember --project threadnote --topic install-health --text "Install/repair waits for OpenViking health."
+threadnote handoff --project threadnote --topic lifecycle-storage --task "Implement lifecycle-aware memories"
+```
+
+Active memories with the same project/topic write to a stable lifecycle path, so later updates replace the current
+version instead of creating another timestamped note. Untagged memories still use timestamped files when you want a
+historical trail.
+
+For feature branches, keep a durable feature memory and an active handoff side by side with the same project/topic:
+
+```bash
+threadnote remember --kind durable --project my-repo --topic feature-x --text "Feature knowledge: ..."
+threadnote handoff --project my-repo --topic feature-x --task "Current status for feature X"
+```
+
+Agents should update the durable feature memory when valuable implementation knowledge changes, and update the handoff
+when current status, tests, blockers, or next steps change.
+
+Use `archive` when an old handoff is useful for provenance but should stop being treated as current working context:
+
+```bash
+threadnote archive viking://user/example/memories/handoffs/active/threadnote/lifecycle-storage.md
+threadnote recall --query "threadnote lifecycle storage"
+threadnote recall --query "threadnote lifecycle storage" --include-archived
+```
+
+If OpenViking is still processing the original file, `archive` keeps the archived copy and tells you to retry
+`threadnote forget <uri>` later.
+
 ## Why Not Just CLAUDE.md Or AGENTS.md?
 
 Use them. Threadnote is not a replacement for checked-in instructions.
@@ -45,11 +87,12 @@ refactor, what an on-call investigation concluded, which workaround was verified
 memories should be compacted. Putting that history into instruction files makes them noisy, stale, and expensive to load
 into every context window.
 
-Threadnote keeps that moving layer local, searchable, and shared across agents. Agents recall only the relevant memories,
-handoffs, and skill/resource pointers when they need them, while the source files stay authoritative for project rules.
+Threadnote keeps that moving layer local, searchable, and shared across agents. Agents recall only the relevant durable
+feature memories, handoffs, and skill/resource pointers when they need them, while the source files stay authoritative
+for project rules.
 
-The split is simple: put durable repo policy in `CLAUDE.md`/`AGENTS.md`; put task history, handoffs, personal workflow
-facts, and local cross-agent memory in Threadnote.
+The split is simple: put durable repo policy in `CLAUDE.md`/`AGENTS.md`; put feature knowledge, task history, handoffs,
+personal workflow facts, and local cross-agent memory in Threadnote.
 
 ## Safety Model
 
@@ -60,8 +103,9 @@ facts, and local cross-agent memory in Threadnote.
 - Redaction: known config files such as `.mcp.json`, `config.toml`, and settings JSON are copied through a redactor
   before import.
 - Secret scanning: candidate files are skipped if common token or private-key patterns remain after redaction.
-- User instructions: `install` upserts a managed Threadnote block in `~/.codex/AGENTS.md`, `~/.claude/CLAUDE.md`, and
-  `~/.cursor/rules/threadnote.md` without replacing existing personal instructions.
+- User instructions: `install` upserts managed Threadnote guidance in `~/.codex/AGENTS.md`, `~/.claude/CLAUDE.md`,
+  `~/.cursor/rules/threadnote.md`, and `~/.copilot/instructions/threadnote.instructions.md` without replacing existing
+  personal instructions.
 - Agent config changes are explicit: `mcp-install` prints commands and snippets by default; use `--apply` to run them.
 
 ## Install
@@ -118,7 +162,16 @@ threadnote update --check
 threadnote update --dry-run
 ```
 
-After updating, restart Cursor, Codex, Claude, or open a fresh agent session so MCP tools reload.
+After updating, restart Cursor, Copilot, Codex, Claude, or open a fresh agent session so MCP tools reload.
+
+Some releases include post-update memory migrations. `threadnote update` runs the new package's migration prompt after
+repair, explains what will change, and asks before applying it. Use `threadnote update --yes` for unattended local
+migrations or `threadnote update --no-post-update` to skip them.
+
+Applied migrations are tracked by id under `THREADNOTE_HOME`, and migration commands are written to be safe to rerun.
+
+If you update from an older Threadnote version that only knew how to run `repair`, the new repair step will still detect
+applicable migrations and print the manual command to run next.
 
 ### MCP
 
@@ -131,6 +184,7 @@ Dry-run examples:
 threadnote mcp-install codex
 threadnote mcp-install claude
 threadnote mcp-install cursor
+threadnote mcp-install copilot
 ```
 
 Apply after review:
@@ -139,11 +193,14 @@ Apply after review:
 threadnote mcp-install codex --apply
 threadnote mcp-install claude --apply
 threadnote mcp-install cursor --apply
+threadnote mcp-install copilot --apply
 ```
 
 Claude installs at `user` scope by default so the same OpenViking MCP server is available from any repo or worktree.
 Use `--scope local` or `--scope project` only when you intentionally want repo-scoped Claude MCP config.
 Cursor installs by updating the global `~/.cursor/mcp.json` file.
+Copilot installs by updating the VS Code user-profile `mcp.json` file. Set `THREADNOTE_COPILOT_MCP_CONFIG` if you use a
+custom VS Code profile or want to test against a temporary file.
 
 If the package or checkout that originally installed `threadnote` has moved, run repair:
 
@@ -163,6 +220,7 @@ 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`.
 
 If a future OpenViking build exposes a healthy native endpoint, install it explicitly:
 
@@ -219,8 +277,8 @@ This is it! Start working with your agents as usual. The agent will automaticall
   `--no-start` to skip the health check.
 - `update`: updates the published Threadnote package, then runs `repair` so shims and MCP config point at the new
   version.
-- `repair`: fixes install/config/shim/manifest/server health issues and rewrites Codex/Claude/Cursor MCP configs from the
-  current checkout.
+- `repair`: fixes install/config/shim/manifest/server health issues and rewrites Codex/Claude/Cursor/Copilot MCP configs
+  from the current checkout.
 - `start`: starts `openviking-server` on `127.0.0.1:1933`.
 - `stop`: stops the detached server pid or macOS LaunchAgent.
 - `uninstall`: removes Threadnote shims, MCP config, launchd config, and managed user instructions. Memories are
@@ -229,17 +287,23 @@ This is it! Start working with your agents as usual. The agent will automaticall
 - `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 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.
+- `mcp-install codex|claude|cursor|copilot`: installs or prints OpenViking MCP configuration for Codex, Claude, Cursor,
+  or GitHub Copilot in VS Code.
 - `remember`: stores a durable memory. Use `--replace <uri>` to store an updated memory and remove a superseded one
-  after the new memory succeeds.
+  after the new memory succeeds. Use `--kind`, `--project`, and `--topic` to store lifecycle-aware current knowledge.
 - `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.
+- `migrate-lifecycle`: moves clear legacy handoff memories from the old events path into archived lifecycle handoff
+  paths. It dry-runs by default; use `--apply` after reviewing the output.
 - `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.
+  `skills for api service`; use `--uri` or `--no-infer-scope` to override. Exact durable-memory matches skip archived
+  lifecycle paths unless `--include-archived` is passed.
 - `read`: reads a `viking://` URI returned by `recall` or `list`.
 - `list` / `ls`: lists a `viking://` directory.
 - `handoff`: stores current git state and next-step notes as a durable handoff. Use `--replace <uri>` to update the
-  current handoff for the same active issue.
+  current handoff for the same active issue, or `--project` and `--topic` to keep one active handoff file updated.
+- `archive`: copies a memory into the archived lifecycle tree, then removes the original after the archive write
+  succeeds.
 - `forget`: removes a `viking://` URI.
 - `export-pack` / `import-pack`: moves local context through `.ovpack` files.
 
@@ -258,8 +322,9 @@ npm run threadnote -- install
 ```
 
 `install` writes a small command shim to `~/.local/bin/threadnote` by default and upserts user-level agent guidance in
-`~/.codex/AGENTS.md`, `~/.claude/CLAUDE.md`, and `~/.cursor/rules/threadnote.md`. After that, use the short command from
-any repo or working directory:
+`~/.codex/AGENTS.md`, `~/.claude/CLAUDE.md`, `~/.cursor/rules/threadnote.md`, and
+`~/.copilot/instructions/threadnote.instructions.md`. After that, use the short command from any repo or working
+directory:
 
 ```bash
 threadnote doctor --dry-run
@@ -288,6 +353,7 @@ Environment variables:
 - `THREADNOTE_NPM_REGISTRY`: npm registry used by the installer and updater, default `https://registry.npmjs.org/`.
 - `THREADNOTE_NO_UPDATE_CHECK`: disables opportunistic update notifications.
 - `THREADNOTE_BIN_DIR`: directory for the `threadnote` shim, default `~/.local/bin`.
+- `THREADNOTE_COPILOT_MCP_CONFIG`: explicit VS Code/Copilot `mcp.json` path for `mcp-install copilot`.
 - `THREADNOTE_HOST`: local bind host, default `127.0.0.1`.
 - `THREADNOTE_PORT`: local bind port, default `1933`.
 

package/config/post-update-migrations.json

@@ -0,0 +1,23 @@
+{
+  "version": 1,
+  "migrations": [
+    {
+      "id": "memory-lifecycle-handoff-archive-v1",
+      "introducedIn": "0.3.7",
+      "title": "Move legacy handoff memories into lifecycle archive paths",
+      "description": [
+        "Threadnote now separates current durable knowledge from the historical handoff trail.",
+        "This migration scans legacy viking://user/<you>/memories/events/*.md files for clear handoff records only.",
+        "Matching handoffs are copied to viking://user/<you>/memories/handoffs/archived/<project>/legacy-<hash>.md with lifecycle metadata.",
+        "After each archived copy is stored, Threadnote removes the original legacy events file to reduce duplicate recall results.",
+        "Ambiguous MEMORY records, preferences, durable facts, incidents, and sensitive-looking content are left untouched for manual review."
+      ],
+      "commandArgs": ["migrate-lifecycle", "--apply"],
+      "instructions": [
+        "Post-update lifecycle migration finished. Future agents should store durable facts with --kind durable --project <name> --topic <topic> and active work logs with handoff --project <name> --topic <topic>.",
+        "If Threadnote reported any original files were still being processed, rerun the printed threadnote forget <uri> command later."
+      ],
+      "requiresLegacyHandoffs": true
+    }
+  ]
+}

package/dist/mcp_server.cjs

@@ -31095,7 +31095,10 @@ async function main() {
         "Prefer `recall_context` to find candidate viking:// URIs, then `read_context` files or `list_context` directories.",
         'Always pass JSON arguments. Example: recall_context({"query":"current repo latest handoff"}).',
         "Older clients may use the compatibility aliases `search`, `read`, and `list`.",
-        "When updating the same active issue, pass replaceUri to remember_context so the superseded memory is forgotten after the replacement is stored.",
+        'For durable facts, store kind="durable"; for current work logs, store kind="handoff" with project/topic so Threadnote keeps one active memory updated.',
+        "When a handoff describes an active branch or feature, recall durable feature memories for the same branch/topic before coding.",
+        "During feature work, update durable feature knowledge when valuable implementation details, decisions, interfaces, or gotchas change.",
+        "When updating the same active issue, pass project/topic or replaceUri to remember_context so duplicate durable memories or handoffs do not accumulate.",
         "Do not store secrets, customer data, raw production logs, or credentials."
       ].join("\n")
     }
@@ -31140,6 +31143,13 @@ function registerTools(server, config2) {
     "Store a durable Threadnote memory. Required: pass JSON arguments with text."
   );
   registerStoreTool(server, config2, "store", "Compatibility alias for remember_context.");
+  registerArchiveTool(
+    server,
+    config2,
+    "archive_context",
+    "Archive a memory so it remains readable as provenance but is no longer current working context."
+  );
+  registerArchiveTool(server, config2, "archive", "Compatibility alias for archive_context.");
   server.registerTool(
     "forget",
     {
@@ -31154,7 +31164,21 @@ function registerTools(server, config2) {
       if (!checkedUri.ok) {
         return checkedUri.error;
       }
-      return runOpenVikingTool(config2, ["rm", checkedUri.value]);
+      try {
+        const ov = await requiredOpenVikingCli();
+        const removed = await removeVikingResourceWithRetry(ov, config2, checkedUri.value);
+        return {
+          content: [
+            {
+              type: "text",
+              text: removed ? `Removed: ${checkedUri.value}` : `Resource is still being processed; retry later: ${checkedUri.value}`
+            }
+          ],
+          isError: !removed
+        };
+      } catch (err) {
+        return { content: [{ type: "text", text: errorMessage(err) }], isError: true };
+      }
     }
   );
   server.registerTool(
@@ -31260,10 +31284,11 @@ function registerSearchTool(server, config2, name, description) {
       inputSchema: {
         query: external_exports.string().optional().describe('Required search query, for example "unity-ui-ccc latest handoff"'),
         uri: external_exports.string().optional().describe("Optional viking:// subtree to search"),
-        nodeLimit: external_exports.number().int().positive().max(100).optional().describe("Maximum result count")
+        nodeLimit: external_exports.number().int().positive().max(100).optional().describe("Maximum result count"),
+        includeArchived: external_exports.boolean().optional().describe("Include archived memories in exact durable-memory matches")
       }
     },
-    async ({ nodeLimit, query, uri }) => {
+    async ({ includeArchived, nodeLimit, query, uri }) => {
       const checkedQuery = requiredText(query, name, "query", { query: "unity-ui-ccc latest handoff" });
       if (!checkedQuery.ok) {
         return checkedQuery.error;
@@ -31272,22 +31297,26 @@ function registerSearchTool(server, config2, name, description) {
       if (!checkedUri.ok) {
         return checkedUri.error;
       }
-      return runRecallTool(config2, [
-        "search",
-        checkedQuery.value,
-        ...checkedUri.value ? ["--uri", checkedUri.value] : [],
-        ...nodeLimit ? ["--node-limit", String(nodeLimit)] : []
-      ]);
+      return runRecallTool(
+        config2,
+        [
+          "search",
+          checkedQuery.value,
+          ...checkedUri.value ? ["--uri", checkedUri.value] : [],
+          ...nodeLimit ? ["--node-limit", String(nodeLimit)] : []
+        ],
+        includeArchived === true
+      );
     }
   );
 }
-async function runRecallTool(config2, args) {
+async function runRecallTool(config2, args, includeArchived) {
   const semanticResult = await runOpenVikingTool(config2, args);
   if (semanticResult.isError === true) {
     return semanticResult;
   }
   const query = args[1];
-  const exactMatches = typeof query === "string" ? await exactMemoryMatchesText(config2, query) : void 0;
+  const exactMatches = typeof query === "string" ? await exactMemoryMatchesText(config2, query, includeArchived) : void 0;
   if (!exactMatches) {
     return semanticResult;
   }
@@ -31303,16 +31332,13 @@ Exact durable memory matches:
 ${exactMatches}` }]
   };
 }
-async function exactMemoryMatchesText(config2, query) {
+async function exactMemoryMatchesText(config2, query, includeArchived) {
   const terms = exactRecallTerms(query);
   if (terms.length === 0) {
     return void 0;
   }
   const ov = await requiredOpenVikingCli();
-  const scopes = [
-    `viking://user/${uriSegment(config2.user)}/memories`,
-    `viking://agent/${uriSegment(config2.agentId)}/memories`
-  ];
+  const scopes = exactMemoryScopes(config2, includeArchived);
   const outputs = [];
   for (const term of terms) {
     for (const scope of scopes) {
@@ -31383,12 +31409,16 @@ function registerStoreTool(server, config2, name, description) {
       annotations: { readOnlyHint: false, destructiveHint: true },
       description: `${description} Never store secrets, credentials, customer data, or raw logs.`,
       inputSchema: {
+        kind: external_exports.enum(["durable", "handoff", "incident", "preference", "smoke"]).optional().describe("Memory lifecycle kind; durable facts and handoffs are most common"),
+        project: external_exports.string().optional().describe("Project/repo namespace, for example threadnote or mobile-native"),
         replaceUri: external_exports.string().optional().describe("Optional viking:// memory URI to forget after the new memory is safely stored"),
         text: external_exports.string().optional().describe("Required memory text to store"),
-        sourceAgentClient: external_exports.string().optional().describe("Originating client, for example cursor, codex, or claude")
+        sourceAgentClient: external_exports.string().optional().describe("Originating client, for example cursor, copilot, codex, or claude"),
+        status: external_exports.enum(["active", "archived", "superseded"]).optional().describe("Memory lifecycle status"),
+        topic: external_exports.string().optional().describe("Stable topic; active project/topic memories update one file")
       }
     },
-    async ({ replaceUri, sourceAgentClient, text }) => {
+    async ({ kind, project, replaceUri, sourceAgentClient, status, text, topic }) => {
       const checkedText = requiredText(text, name, "text", { text: "Durable engineering note..." });
       if (!checkedText.ok) {
         return checkedText.error;
@@ -31397,45 +31427,120 @@ function registerStoreTool(server, config2, name, description) {
       if (!checkedReplaceUri.ok) {
         return checkedReplaceUri.error;
       }
-      const header = [
-        "MEMORY",
-        `source_agent_client: ${sourceAgentClient ?? "mcp"}`,
-        `timestamp: ${(/* @__PURE__ */ new Date()).toISOString()}`
-      ];
-      if (checkedReplaceUri.value) {
-        header.push(`supersedes: ${checkedReplaceUri.value}`);
+      const metadata = {
+        kind: kind ?? "durable",
+        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),
+        metadata,
+        checkedReplaceUri.value
+      );
+    }
+  );
+}
+function registerArchiveTool(server, config2, name, description) {
+  server.registerTool(
+    name,
+    {
+      annotations: { readOnlyHint: false, destructiveHint: true },
+      description: `${description} The archive is written before the original URI is removed.`,
+      inputSchema: {
+        kind: external_exports.enum(["durable", "handoff", "incident", "preference", "smoke"]).optional(),
+        project: external_exports.string().optional().describe("Project/repo namespace for the archived copy"),
+        topic: external_exports.string().optional().describe("Topic for the archived copy"),
+        uri: external_exports.string().optional().describe("Required viking:// memory URI to archive")
+      }
+    },
+    async ({ kind, project, topic, uri }) => {
+      const checkedUri = requiredVikingUri(uri, name, "viking://user/example/memories/handoffs/active/repo/topic.md");
+      if (!checkedUri.ok) {
+        return checkedUri.error;
+      }
+      try {
+        const ov = await requiredOpenVikingCli();
+        const readResult = await runCommand(ov, withIdentity(config2, ["read", checkedUri.value]));
+        const original = readResult.stdout.trim();
+        if (!original) {
+          return {
+            content: [{ type: "text", text: `Could not read ${checkedUri.value} before archiving.` }],
+            isError: true
+          };
+        }
+        const metadata = {
+          archivedFrom: checkedUri.value,
+          kind: kind ?? "handoff",
+          project: normalizeOptionalMetadata(project),
+          sourceAgentClient: "mcp",
+          status: "archived",
+          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
+        );
+        if (archiveResult.isError === true) {
+          return archiveResult;
+        }
+        const removedOriginal = await removeVikingResourceWithRetry(ov, config2, checkedUri.value);
+        const [content] = archiveResult.content;
+        const text = content?.type === "text" ? content.text : "Archived memory stored.";
+        return {
+          content: [
+            {
+              type: "text",
+              text: removedOriginal ? `${text}
+Archived original memory: ${checkedUri.value}` : `${text}
+Archive stored, but original memory is still processing. Retry later with forget: ${checkedUri.value}`
+            }
+          ]
+        };
+      } catch (err) {
+        return { content: [{ type: "text", text: errorMessage(err) }], isError: true };
       }
-      return writeDurableMemory(config2, [...header, "", checkedText.value].join("\n"), checkedReplaceUri.value);
     }
   );
 }
-async function writeDurableMemory(config2, memory, replaceUri) {
+async function writeDurableMemory(config2, memory, metadata, replaceUri) {
   try {
     const ov = await requiredOpenVikingCli();
-    const directoryUri = durableMemoryDirectoryUri(config2);
-    const stat = await runCommand(ov, withIdentity(config2, ["stat", directoryUri]), { allowFailure: true });
-    if (stat.exitCode !== 0) {
-      await runCommand(
-        ov,
-        withIdentity(config2, [
-          "mkdir",
-          directoryUri,
-          "--description",
-          "Threadnote durable handoffs, memories, and cross-agent notes."
-        ])
-      );
-    }
-    const memoryUri = durableMemoryUri(config2, memory);
+    const directoryUri = memoryDirectoryUri(config2, metadata);
+    await ensureMemoryDirectory(ov, config2, directoryUri);
+    const memoryUri = memoryUriFor(config2, memory, metadata);
+    const writeMode = await memoryWriteMode(ov, config2, memoryUri, metadata);
     const result = await runOpenVikingWriteWithRetry(
       ov,
       config2,
       memoryUri,
-      withIdentity(config2, ["write", memoryUri, "--content", memory, "--mode", "create", "--wait", "--timeout", "120"])
+      withIdentity(config2, [
+        "write",
+        memoryUri,
+        "--content",
+        memory,
+        "--mode",
+        writeMode,
+        "--wait",
+        "--timeout",
+        "120"
+      ])
     );
-    const messages = [`Stored durable memory: ${memoryUri}`];
-    if (replaceUri) {
-      await runCommand(ov, withIdentity(config2, ["rm", replaceUri]));
-      messages.push(`Forgot replaced memory: ${replaceUri}`);
+    const messages = [`Stored memory: ${memoryUri}`];
+    if (replaceUri && replaceUri !== memoryUri) {
+      const removedReplacedMemory = await removeVikingResourceWithRetry(ov, config2, replaceUri);
+      messages.push(
+        removedReplacedMemory ? `Forgot replaced memory: ${replaceUri}` : `Replacement stored, but superseded memory is still processing. Retry later with forget: ${replaceUri}`
+      );
+    } else if (replaceUri === memoryUri) {
+      messages.push(`Updated existing memory in place: ${memoryUri}`);
     }
     const text = [result.stdout.trim(), result.stderr.trim()].filter(Boolean).join("\n");
     return { content: [{ type: "text", text: [...messages, text].filter(Boolean).join("\n") }] };
@@ -31464,15 +31569,111 @@ async function vikingResourceExists(ov, config2, uri) {
   const stat = await runCommand(ov, withIdentity(config2, ["stat", uri]), { allowFailure: true });
   return stat.exitCode === 0;
 }
+async function removeVikingResourceWithRetry(ov, config2, uri) {
+  const args = withIdentity(config2, ["rm", uri]);
+  for (let attempt = 0; attempt < 4; attempt += 1) {
+    const result = await runCommand(ov, args, { allowFailure: true });
+    if (result.exitCode === 0) {
+      return true;
+    }
+    if (isResourceBusy(result.stderr, result.stdout) && attempt === 3) {
+      return false;
+    }
+    if (!isResourceBusy(result.stderr, result.stdout)) {
+      throw new Error(`${ov} ${args.join(" ")} failed: ${result.stderr || result.stdout}`);
+    }
+    await sleep(1e3 * (attempt + 1));
+  }
+  return false;
+}
 function isResourceBusy(stderr, stdout) {
-  return `${stderr}
-${stdout}`.includes("resource is busy");
+  const output = `${stderr}
+${stdout}`.toLowerCase();
+  return output.includes("resource is busy") || output.includes("resource is being processed");
+}
+async function ensureMemoryDirectory(ov, config2, directoryUri) {
+  for (const uri of vikingDirectoryChain(directoryUri)) {
+    const statResult = await runCommand(ov, withIdentity(config2, ["stat", uri]), { allowFailure: true });
+    if (statResult.exitCode === 0) {
+      continue;
+    }
+    await runCommand(
+      ov,
+      withIdentity(config2, ["mkdir", uri, "--description", "Threadnote lifecycle-aware local memories."])
+    );
+  }
 }
-function durableMemoryUri(config2, memory) {
-  return `${durableMemoryDirectoryUri(config2)}/threadnote-${safeTimestamp()}-${sha256(memory).slice(0, 12)}.md`;
+function memoryUriFor(config2, memory, metadata) {
+  const filename = shouldUseStableMemoryUri(metadata) ? `${uriSegment(metadata.topic ?? "current")}.md` : `threadnote-${safeTimestamp()}-${sha256(memory).slice(0, 12)}.md`;
+  return `${memoryDirectoryUri(config2, metadata)}/${filename}`;
+}
+function memoryDirectoryUri(config2, metadata) {
+  const baseUri = `viking://user/${uriSegment(config2.user)}/memories`;
+  const projectSegment = uriSegment(metadata.project ?? "general");
+  switch (metadata.kind) {
+    case "preference":
+      return metadata.status === "active" ? `${baseUri}/preferences` : `${baseUri}/preferences/${uriSegment(metadata.status)}`;
+    case "handoff":
+      return `${baseUri}/handoffs/${uriSegment(metadata.status)}/${projectSegment}`;
+    case "incident":
+      return `${baseUri}/incidents/${uriSegment(metadata.status)}/${projectSegment}`;
+    case "smoke":
+      return `${baseUri}/smoke/${uriSegment(metadata.status)}`;
+    case "durable":
+      return metadata.status === "active" ? `${baseUri}/durable/projects/${projectSegment}` : `${baseUri}/durable/${uriSegment(metadata.status)}/${projectSegment}`;
+  }
 }
-function durableMemoryDirectoryUri(config2) {
-  return `viking://user/${uriSegment(config2.user)}/memories/events`;
+function shouldUseStableMemoryUri(metadata) {
+  return metadata.status === "active" && metadata.topic !== void 0 && metadata.kind !== "smoke";
+}
+async function memoryWriteMode(ov, config2, memoryUri, metadata) {
+  if (!shouldUseStableMemoryUri(metadata)) {
+    return "create";
+  }
+  return await vikingResourceExists(ov, config2, memoryUri) ? "replace" : "create";
+}
+function vikingDirectoryChain(directoryUri) {
+  const prefix = "viking://";
+  if (!directoryUri.startsWith(prefix)) {
+    return [directoryUri];
+  }
+  const parts = directoryUri.slice(prefix.length).split("/").filter(Boolean);
+  const startIndex = parts[0] === "user" && parts.length > 2 ? 3 : 1;
+  const chain = [];
+  for (let index = startIndex; index <= parts.length; index += 1) {
+    chain.push(`${prefix}${parts.slice(0, index).join("/")}`);
+  }
+  return chain;
+}
+function exactMemoryScopes(config2, includeArchived) {
+  const userBase = `viking://user/${uriSegment(config2.user)}/memories`;
+  const scopes = [
+    `${userBase}/preferences`,
+    `${userBase}/durable/projects`,
+    `${userBase}/handoffs/active`,
+    `${userBase}/incidents/active`,
+    `${userBase}/events`,
+    `viking://agent/${uriSegment(config2.agentId)}/memories`
+  ];
+  return includeArchived ? [...scopes, `${userBase}/durable/archived`, `${userBase}/handoffs/archived`, `${userBase}/incidents/archived`] : scopes;
+}
+function formatMemoryDocument(title, metadata, body) {
+  const header = [
+    title,
+    `kind: ${metadata.kind}`,
+    `status: ${metadata.status}`,
+    metadata.project ? `project: ${metadata.project}` : void 0,
+    metadata.topic ? `topic: ${metadata.topic}` : void 0,
+    `source_agent_client: ${metadata.sourceAgentClient}`,
+    `timestamp: ${metadata.timestamp}`,
+    metadata.supersedes ? `supersedes: ${metadata.supersedes}` : void 0,
+    metadata.archivedFrom ? `archived_from: ${metadata.archivedFrom}` : void 0
+  ].filter((line) => line !== void 0);
+  return [...header, "", body.trim()].join("\n");
+}
+function normalizeOptionalMetadata(value) {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : void 0;
 }
 function uriSegment(value) {
   const normalized = value.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");