threadnote 0.3.4 → 0.3.6

package/README.md

@@ -29,6 +29,28 @@ Run `threadnote seed-skills` to make local `SKILL.md` guidance discoverable thro
 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.
 
+**Still working on the same issue?**
+Use `threadnote remember --replace <uri>` or `threadnote handoff --replace <uri>` to keep one current-state memory fresh
+instead of accumulating near-duplicate progress notes.
+
+## Why Not Just CLAUDE.md Or AGENTS.md?
+
+Use them. Threadnote is not a replacement for checked-in instructions.
+
+`CLAUDE.md`, `AGENTS.md`, Cursor rules, and repo docs are the right place for stable, canonical guidance: coding
+standards, test commands, review rules, architecture notes, and anything the whole team should version and discuss.
+
+They are less ideal for living context: what happened in the last agent session, which branch was halfway through a
+refactor, what an on-call investigation concluded, which workaround was verified on one machine, or which duplicate
+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.
+
+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.
+
 ## Safety Model
 
 - Machine writes stay **locally** under `THREADNOTE_HOME`, which defaults to `~/.openviking`.
@@ -50,13 +72,13 @@ Install with one command:
 curl -fsSL https://raw.githubusercontent.com/Kashkovsky/threadnote/main/scripts/install.sh | sh
 ```
 
-This installs the published package from npmjs and runs `threadnote install`. It does not use npm `postinstall`,
-because setup writes local machine config and should be an explicit action.
+This installs the published package from npmjs and runs `threadnote install`. The install command sets up local config,
+repairs the OpenViking Python environment, and starts the local server so health problems surface immediately. It does
+not use npm `postinstall`, because setup writes local machine config and should be an explicit action.
 
-Start the local server and confirm it is healthy:
+Confirm it is healthy:
 
 ```bash
-threadnote start
 threadnote doctor --dry-run
 ```
 
@@ -74,7 +96,6 @@ Or install manually:
 ```bash
 npm install --global threadnote
 threadnote install
-threadnote start
 threadnote doctor --dry-run
 ```
 
@@ -194,7 +215,8 @@ This is it! Start working with your agents as usual. The agent will automaticall
 
 - `doctor`: checks prerequisites, the generated command shim, manifest shape, templates, and local OpenViking health.
 - `install`: installs `openviking[local-embed]==0.3.12` if missing, creates `~/.openviking` config files if absent,
-  writes the command shim, and upserts user-level agent instructions.
+  writes the command shim, upserts user-level agent instructions, and starts/checks OpenViking health by default. Use
+  `--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
@@ -208,14 +230,16 @@ This is it! Start working with your agents as usual. The agent will automaticall
 - `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.
+- `remember`: stores a durable memory. Use `--replace <uri>` to store an updated memory and remove a superseded one
+  after the new memory succeeds.
 - `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`.
 - `list` / `ls`: lists a `viking://` directory.
-- `handoff`: stores current git state and next-step notes as a durable handoff.
+- `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.
 - `forget`: removes a `viking://` URI.
 - `export-pack` / `import-pack`: moves local context through `.ovpack` files.
 
@@ -240,7 +264,6 @@ any repo or working directory:
 ```bash
 threadnote doctor --dry-run
 threadnote init-manifest --repo ~/src/my-service --repo ~/work/mobile-app
-threadnote start
 threadnote seed --dry-run
 threadnote seed-skills --dry-run
 ```

package/dist/mcp_server.cjs

@@ -31095,6 +31095,7 @@ 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.",
         "Do not store secrets, customer data, raw production logs, or credentials."
       ].join("\n")
     }
@@ -31379,32 +31380,36 @@ function registerStoreTool(server, config2, name, description) {
   server.registerTool(
     name,
     {
-      annotations: { readOnlyHint: false, destructiveHint: false },
+      annotations: { readOnlyHint: false, destructiveHint: true },
       description: `${description} Never store secrets, credentials, customer data, or raw logs.`,
       inputSchema: {
+        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")
       }
     },
-    async ({ sourceAgentClient, text }) => {
+    async ({ replaceUri, sourceAgentClient, text }) => {
       const checkedText = requiredText(text, name, "text", { text: "Durable engineering note..." });
       if (!checkedText.ok) {
         return checkedText.error;
       }
-      return writeDurableMemory(
-        config2,
-        [
-          "MEMORY",
-          `source_agent_client: ${sourceAgentClient ?? "mcp"}`,
-          `timestamp: ${(/* @__PURE__ */ new Date()).toISOString()}`,
-          "",
-          checkedText.value
-        ].join("\n")
-      );
+      const checkedReplaceUri = optionalVikingUri(replaceUri, name);
+      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}`);
+      }
+      return writeDurableMemory(config2, [...header, "", checkedText.value].join("\n"), checkedReplaceUri.value);
     }
   );
 }
-async function writeDurableMemory(config2, memory) {
+async function writeDurableMemory(config2, memory, replaceUri) {
   try {
     const ov = await requiredOpenVikingCli();
     const directoryUri = durableMemoryDirectoryUri(config2);
@@ -31427,8 +31432,13 @@ async function writeDurableMemory(config2, memory) {
       memoryUri,
       withIdentity(config2, ["write", memoryUri, "--content", memory, "--mode", "create", "--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 text = [result.stdout.trim(), result.stderr.trim()].filter(Boolean).join("\n");
-    return { content: [{ type: "text", text: [`Stored durable memory: ${memoryUri}`, text].filter(Boolean).join("\n") }] };
+    return { content: [{ type: "text", text: [...messages, text].filter(Boolean).join("\n") }] };
   } catch (err) {
     return { content: [{ type: "text", text: errorMessage(err) }], isError: true };
   }

package/dist/threadnote.cjs

@@ -7038,14 +7038,16 @@ async function runRemember(config, options) {
   if (!text.trim()) {
     throw new Error("Provide memory text with --text or --stdin.");
   }
-  const memory = [
+  const header = [
     "MEMORY",
     `source_agent_client: ${options.sourceAgentClient ?? "codex"}`,
-    `timestamp: ${(/* @__PURE__ */ new Date()).toISOString()}`,
-    "",
-    text.trim()
-  ].join("\n");
-  await storeMemory(config, memory, options.dryRun === true);
+    `timestamp: ${(/* @__PURE__ */ new Date()).toISOString()}`
+  ];
+  if (options.replace) {
+    header.push(`supersedes: ${options.replace}`);
+  }
+  const memory = [...header, "", text.trim()].join("\n");
+  await storeMemory(config, memory, { dryRun: options.dryRun === true, replaceUri: options.replace });
 }
 async function runMigrateMemories(config, options) {
   const dryRun = options.dryRun === true;
@@ -7160,7 +7162,7 @@ async function runList(config, uri, options) {
 }
 async function runHandoff(config, options) {
   const handoff = await buildHandoff(options);
-  await storeMemory(config, handoff, options.dryRun === true);
+  await storeMemory(config, handoff, { dryRun: options.dryRun === true, replaceUri: options.replace });
 }
 async function runForget(config, uri, options) {
   assertVikingUri(uri);
@@ -7231,11 +7233,14 @@ async function printExactMemoryMatches(config, ov, query, dryRun) {
   console.log("\nExact durable memory matches:");
   console.log(outputs.join("\n\n"));
 }
-async function storeMemory(config, memory, dryRun) {
-  const ov = await openVikingCliForMode(dryRun);
+async function storeMemory(config, memory, options) {
+  if (options.replaceUri) {
+    assertVikingUri(options.replaceUri);
+  }
+  const ov = await openVikingCliForMode(options.dryRun);
   const memoryPath = (0, import_node_path4.join)(config.agentContextHome, "last-memory.txt");
   const memoryUri = durableMemoryUri(config, memory);
-  if (dryRun) {
+  if (options.dryRun) {
     console.log(memory);
     console.log("\nWould run:");
     console.log(
@@ -7254,6 +7259,9 @@ async function storeMemory(config, memory, dryRun) {
         ])
       )
     );
+    if (options.replaceUri) {
+      console.log(formatShellCommand(ov, withIdentity(config, ["rm", options.replaceUri])));
+    }
     return;
   }
   await (0, import_promises4.writeFile)(memoryPath, memory, { encoding: "utf8", mode: 384 });
@@ -7261,6 +7269,10 @@ async function storeMemory(config, memory, dryRun) {
   await ensureDurableMemoryDirectory(ov, config);
   await writeDurableMemoryFile(ov, config, memoryUri, memoryPath);
   console.log(`Stored durable memory: ${memoryUri}`);
+  if (options.replaceUri) {
+    await maybeRun(false, ov, withIdentity(config, ["rm", options.replaceUri]));
+    console.log(`Forgot replaced memory: ${options.replaceUri}`);
+  }
 }
 async function writeDurableMemoryFile(ov, config, memoryUri, memoryPath) {
   const args = withIdentity(config, [
@@ -7501,13 +7513,19 @@ async function buildHandoff(options) {
   const status = await gitValue(["status", "--short"], repoRoot) ?? "";
   const diffStat = await gitValue(["diff", "--stat", "HEAD"], repoRoot) ?? "";
   const touchedFiles = await gitTouchedFiles(repoRoot);
-  return [
+  const header = [
     "HANDOFF",
     `repo: ${(0, import_node_path4.basename)(repoRoot)}`,
     `repo_path: ${repoRoot}`,
     `branch: ${branch || "unknown"}`,
     `source_agent_client: ${options.sourceAgentClient ?? "codex"}`,
-    `timestamp: ${(/* @__PURE__ */ new Date()).toISOString()}`,
+    `timestamp: ${(/* @__PURE__ */ new Date()).toISOString()}`
+  ];
+  if (options.replace) {
+    header.push(`supersedes: ${options.replace}`);
+  }
+  return [
+    ...header,
     `task: ${options.task ?? "unspecified"}`,
     "",
     "files_touched:",
@@ -7903,12 +7921,13 @@ Summary: ${failureCount} failure(s), ${warningCount} warning(s)`);
 }
 async function runInstall(config, options) {
   const repairInvalidConfigs = options.repairInvalidConfigs === true;
-  await ensureDirectory(config.agentContextHome, options.dryRun === true);
-  await ensureDirectory((0, import_node_path6.join)(config.agentContextHome, "logs"), options.dryRun === true);
-  await ensureDirectory((0, import_node_path6.join)(config.agentContextHome, "redacted"), options.dryRun === true);
-  await ensureDirectory((0, import_node_path6.join)(config.agentContextHome, "mcp"), options.dryRun === true);
-  await installCommandShim(options.dryRun === true);
-  await installUserAgentInstructions(options.dryRun === true);
+  const dryRun = options.dryRun === true;
+  await ensureDirectory(config.agentContextHome, dryRun);
+  await ensureDirectory((0, import_node_path6.join)(config.agentContextHome, "logs"), dryRun);
+  await ensureDirectory((0, import_node_path6.join)(config.agentContextHome, "redacted"), dryRun);
+  await ensureDirectory((0, import_node_path6.join)(config.agentContextHome, "mcp"), dryRun);
+  await installCommandShim(dryRun);
+  await installUserAgentInstructions(dryRun);
   const serverPath = await findExecutable([OPENVIKING_SERVER_COMMAND]);
   if (serverPath) {
     console.log(`OpenViking server already installed: ${serverPath}`);
@@ -7921,37 +7940,49 @@ async function runInstall(config, options) {
         repairReasons.push("Python system certificate bridge is missing");
       }
       console.log(`OpenViking install needs repair: ${repairReasons.join("; ")}.`);
-      await runInstallCommands(config, options.packageManager, true, options.dryRun === true);
+      await runInstallCommands(config, options.packageManager, true, dryRun);
     } else if (pythonSystemCertificatesMissing) {
       console.log("OpenViking install needs repair: Python system certificate bridge is missing.");
       const installCommand = await getPythonSystemCertificatesInstallCommand(serverPath);
-      await maybeRun(options.dryRun === true, installCommand.executable, installCommand.args);
+      await maybeRun(dryRun, installCommand.executable, installCommand.args);
     }
   } else {
-    await runInstallCommands(config, options.packageManager, false, options.dryRun === true);
+    await runInstallCommands(config, options.packageManager, false, dryRun);
   }
   await writeTemplateIfMissing({
     config,
     destinationPath: (0, import_node_path6.join)(config.agentContextHome, "ov.conf"),
-    dryRun: options.dryRun === true,
+    dryRun,
     shouldRepair: (content) => shouldRepairOpenVikingConfig(content, config) || repairInvalidConfigs && parseJsonConfigObject(content) === void 0,
     templatePath: (0, import_node_path6.join)(toolRoot(), "config", "ov.conf.template.json")
   });
   await writeTemplateIfMissing({
     config,
     destinationPath: (0, import_node_path6.join)(config.agentContextHome, "ovcli.conf"),
-    dryRun: options.dryRun === true,
+    dryRun,
     shouldRepair: (content) => shouldRepairLegacyOvCliConfig(content) || repairInvalidConfigs && parseJsonConfigObject(content) === void 0,
     templatePath: (0, import_node_path6.join)(toolRoot(), "config", "ovcli.conf.template.json")
   });
-  console.log("Install complete. Run start, then doctor:");
-  console.log("  threadnote start");
-  console.log("  threadnote doctor");
+  if (options.start !== false) {
+    const healthy = await repairServerHealth(config, dryRun);
+    if (!healthy && !dryRun) {
+      throw new Error(`OpenViking did not become healthy. Check logs: ${openVikingLogPath(config)}`);
+    }
+  }
+  if (options.printNextSteps !== false) {
+    printInstallNextSteps({ dryRun, startsServer: options.start !== false });
+  }
 }
 async function runRepair(config, options) {
   const dryRun = options.dryRun === true;
   console.log("Repairing local OpenViking agent context from this checkout.");
-  await runInstall(config, { dryRun, packageManager: options.packageManager, repairInvalidConfigs: true });
+  await runInstall(config, {
+    dryRun,
+    packageManager: options.packageManager,
+    printNextSteps: false,
+    repairInvalidConfigs: true,
+    start: false
+  });
   await repairManifest(config, dryRun);
   if (options.start !== false) {
     await repairServerHealth(config, dryRun);
@@ -8047,13 +8078,15 @@ async function repairServerHealth(config, dryRun) {
   const existingHealth = await readOpenVikingHealthIfAvailable(config, 800);
   if (existingHealth) {
     console.log(`OpenViking health OK at http://${config.host}:${config.port}/health`);
-    return;
+    return true;
   }
   console.log(`OpenViking health is not responding at http://${config.host}:${config.port}/health; starting server.`);
   try {
     await runStart(config, { dryRun });
+    return true;
   } catch (err) {
     console.log(`WARN could not repair OpenViking health: ${errorMessage(err)}`);
+    return false;
   }
 }
 async function runStart(config, options) {
@@ -8385,14 +8418,28 @@ async function getInstallCommands(config, preferred, force) {
   return [{ executable: "python3", args: pipArgs }];
 }
 async function detectPackageManager() {
-  if (await findExecutable(["pipx"])) {
-    return "pipx";
-  }
   if (await findExecutable(["uv"])) {
     return "uv";
   }
+  if (await findExecutable(["pipx"])) {
+    return "pipx";
+  }
   return "pip";
 }
+function printInstallNextSteps(options) {
+  if (options.dryRun) {
+    console.log("Dry run complete. Run without --dry-run to install and start OpenViking.");
+    return;
+  }
+  if (options.startsServer) {
+    console.log("Install complete. OpenViking health is ready. Next:");
+    console.log("  threadnote doctor --dry-run");
+    return;
+  }
+  console.log("Install complete. Run start, then doctor:");
+  console.log("  threadnote start");
+  console.log("  threadnote doctor --dry-run");
+}
 async function writeTemplateIfMissing(options) {
   if (await exists(options.destinationPath)) {
     const currentContent = await (0, import_promises6.readFile)(options.destinationPath, "utf8");
@@ -8946,7 +8993,7 @@ async function main() {
     await runDoctor(config, options);
     await maybeNotifyUpdate(config, { dryRun: options.dryRun === true });
   });
-  program2.command("install").description("Install OpenViking, local config files, command shim, and user-level agent instructions").option("--dry-run", "Print the actions without making changes").option("--package-manager <manager>", "pipx, uv, or pip", parsePackageManager).action(async (options) => {
+  program2.command("install").description("Install OpenViking, local config files, command shim, and user-level agent instructions").option("--dry-run", "Print the actions without making changes").option("--no-start", "Do not start OpenViking or check server health after installing").option("--package-manager <manager>", "uv, pipx, or pip", parsePackageManager).action(async (options) => {
     const config = getRuntimeConfig(program2);
     await runInstall(config, options);
     await maybeNotifyUpdate(config, { dryRun: options.dryRun === true });
@@ -8958,7 +9005,7 @@ async function main() {
     "--mcp <clients>",
     "MCP clients to repair: available, all, none, codex, claude, cursor, or comma-separated list",
     "available"
-  ).option("--no-start", "Do not start OpenViking if health is failing").option("--package-manager <manager>", "pipx, uv, or pip", parsePackageManager).action(async (options) => {
+  ).option("--no-start", "Do not start OpenViking if health is failing").option("--package-manager <manager>", "uv, pipx, or pip", parsePackageManager).action(async (options) => {
     const config = getRuntimeConfig(program2);
     await runRepair(config, options);
     await maybeNotifyUpdate(config, { dryRun: options.dryRun === true });
@@ -8990,7 +9037,7 @@ async function main() {
   program2.command("mcp-install").description("Install OpenViking MCP config for a supported agent").argument("<agent>", "codex, claude, or cursor").option("--apply", "Actually modify the selected agent config").option("--name <name>", "MCP server name", OPENVIKING_MCP_NAME).option("--native-http", "Install OpenViking native HTTP MCP endpoint instead of the local stdio adapter").option("--scope <scope>", "Claude MCP config scope: user, local, or project", parseClaudeMcpScope, "user").option("--url <url>", "OpenViking native HTTP MCP URL").option("--bearer-token-env-var <name>", "Environment variable containing the local API key").action(async (agent, options) => {
     await runMcpInstall(getRuntimeConfig(program2), parseAgentClient(agent), options);
   });
-  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) => {
+  program2.command("remember").description("Store a durable engineering memory in OpenViking").option("--dry-run", "Print memory and ov command without storing").option("--replace <uri>", "Supersede an existing viking:// memory after the new memory is stored").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(
@@ -9010,7 +9057,7 @@ async function main() {
   program2.command("list").alias("ls").description("List a viking:// directory").argument("[uri]", "viking:// URI to list", "viking://").option("-a, --all", "Show hidden files such as .abstract.md and .overview.md").option("--dry-run", "Print ov command without listing").option("-n, --node-limit <count>", "Maximum number of nodes to list").option("-r, --recursive", "List subdirectories recursively").option("-s, --simple", "Print only paths").action(async (uri, options) => {
     await runList(getRuntimeConfig(program2), uri, options);
   });
-  program2.command("handoff").description("Capture current repo state as a durable cross-agent handoff memory").option("--blockers <text>", "Known blockers").option("--dry-run", "Print handoff without storing").option("--next-step <text>", "Suggested next step").option("--source-agent-client <name>", "codex, claude, cursor, gemini, or another client name", "codex").option("--task <text>", "Current task summary").option("--tests <text>", "Tests or checks run").action(async (options) => {
+  program2.command("handoff").description("Capture current repo state as a durable cross-agent handoff memory").option("--blockers <text>", "Known blockers").option("--dry-run", "Print handoff without storing").option("--next-step <text>", "Suggested next step").option("--replace <uri>", "Supersede an existing viking:// memory after the new handoff is stored").option("--source-agent-client <name>", "codex, claude, cursor, gemini, or another client name", "codex").option("--task <text>", "Current task summary").option("--tests <text>", "Tests or checks run").action(async (options) => {
     await runHandoff(getRuntimeConfig(program2), options);
   });
   program2.command("forget").description("Remove a viking:// URI from local OpenViking context").argument("<uri>", "viking:// URI to remove").option("--dry-run", "Print ov command without deleting").action(async (uri, options) => {

package/docs/agent-instructions.md

@@ -38,6 +38,11 @@ canonical docs. Prefer updating checked-in docs for canonical repo rules.
 
 ## Memory Compaction
 
+When working on the same active issue, prefer keeping one current-state memory updated instead of creating many small
+progress memories. If an existing memory is clearly the current state for the issue, store the updated version with
+`remember_context({"text":"...","replaceUri":"<uri>"})`, `threadnote remember --replace <uri>`, or
+`threadnote handoff --replace <uri>` so the old memory is removed only after the replacement is stored.
+
 When recall/read surfaces several memories that describe the same durable fact, incident, branch, or handoff, compact
 them when it is safe:
 
@@ -72,6 +77,7 @@ 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 remember --replace viking://user/example/memories/events/current.md --text "Updated 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

@@ -90,10 +90,9 @@ paths.
    `--repo` can be repeated. Paths may be anywhere on the machine. If no `--repo` is provided, the current git repo is
    used. The manifest is written to `~/.openviking/seed-manifest.yaml` by default and is intentionally not checked in.
 
-4. Start the local service:
+4. Verify the local service:
 
    ```bash
-   threadnote start
    threadnote doctor --dry-run
    ```
 
@@ -171,6 +170,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 continuing the same active issue, update the current-state memory with `remember --replace <uri>` or
+  `handoff --replace <uri>` instead of creating another near-duplicate progress memory.
 - 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,
@@ -181,6 +182,7 @@ Manual CLI remains available for scripts and emergencies:
 ```bash
 threadnote recall --query "last handoff for this branch"
 threadnote remember --text "Durable engineering note..."
+threadnote remember --replace viking://user/example/memories/events/current.md --text "Updated durable engineering note..."
 threadnote handoff --task "short task summary" --tests "checks run" --next-step "what the next agent should do"
 ```
 

package/docs/troubleshooting.md

@@ -8,7 +8,7 @@ Run:
 threadnote install
 ```
 
-The installer prefers `pipx`, then `uv`, then `python3 -m pip install --user`.
+The installer prefers `uv`, then `pipx`, then `python3 -m pip install --user`.
 
 ## `uv` Fails With `UnknownIssuer`
 
@@ -30,13 +30,13 @@ threadnote install --package-manager pip
 
 ## Model Download Fails With `CERTIFICATE_VERIFY_FAILED`
 
-On first start, OpenViking may download the local embedding model from Hugging Face. If `~/.openviking/logs/server.log`
-shows `SSLCertVerificationError`, `self-signed certificate in certificate chain`, or `Failed to download local embedding
-model`, repair the OpenViking Python environment and start again:
+On install or first start, OpenViking may download the local embedding model from Hugging Face. If
+`~/.openviking/logs/server.log` shows `SSLCertVerificationError`, `self-signed certificate in certificate chain`, or
+`Failed to download local embedding model`, repair the OpenViking Python environment and start again:
 
 ```bash
 threadnote repair --package-manager uv
-threadnote start
+threadnote doctor --dry-run
 ```
 
 Threadnote installs `pip-system-certs` into the OpenViking environment so Python `requests` can use certificates trusted
@@ -63,8 +63,8 @@ The installer repairs this by installing `openviking[local-embed]`.
 
 ## Server Health Fails
 
-If `doctor` reports `WARN openviking health: connect ECONNREFUSED 127.0.0.1:1933`, the local server is not running.
-Start it and recheck:
+Current Threadnote installs start the local server by default. If `doctor` reports
+`WARN openviking health: connect ECONNREFUSED 127.0.0.1:1933`, the local server is not running. Start it and recheck:
 
 ```bash
 threadnote start

package/package.json

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

package/scripts/install.sh

@@ -126,7 +126,6 @@ fi
 
 say ""
 say "Threadnote is installed. Next:"
-say "  threadnote start"
 say "  threadnote doctor --dry-run"
 say "  threadnote mcp-install codex --apply    # if you use Codex"
 say "  threadnote mcp-install claude --apply   # if you use Claude"