threadnote 0.3.3 → 0.3.5

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
 
@@ -40,17 +50,17 @@ 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
 ```
 
-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:
 
@@ -64,7 +74,6 @@ Or install manually:
 ```bash
 npm install --global threadnote
 threadnote install
-threadnote start
 threadnote doctor --dry-run
 ```
 
@@ -157,7 +166,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
@@ -172,7 +193,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
@@ -183,8 +205,8 @@ 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
@@ -218,7 +240,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/threadnote.cjs

@@ -7903,12 +7903,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 +7922,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 +8060,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 +8400,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 +8975,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 +8987,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 });

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

@@ -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 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/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.3",
+  "version": "0.3.5",
   "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"