threadnote 0.3.3 → 0.3.4

package/README.md

@@ -6,18 +6,28 @@ and it does not index whole repositories by default.
 
 ## Real-World Uses
 
-Want to continue work in a fresh agent session? `threadnote install` adds user-level Codex and Claude instructions so
-new agents automatically recall recent handoffs and relevant memories before they start changing code.
+**Want to continue work in a fresh agent session?**  
+`threadnote install` adds user-level Codex, Claude, and Cursor instructions so new agents automatically recall recent handoffs and relevant memories before they start changing code.
 
-Implemented a feature a while ago and need to pick it up again? Ask the agent to recall the feature, branch, or repo.
-Threadnote returns auditable `viking://` pointers that the agent can read before deciding what still matters.
+**Implemented a feature a while ago and need to pick it up again?**  
+Ask the agent to recall the feature, branch, or repo. Threadnote returns auditable `viking://` pointers that the agent can read before deciding what still matters.
 
-Switching between Codex and Claude? Install the MCP adapter for both. The user-level instructions tell agents to store a
-handoff before they pause, so the next agent can search the same local memory layer instead of reconstructing context
+**Switching between Codex, Claude, and Cursor?**\
+Install the MCP adapter for each agent you use. The user-level instructions tell agents to store a handoff before they pause, so the next agent can search the same local memory layer instead of reconstructing context
 from chat history.
 
-Found a durable workflow fact, like how a repo runs tests or where release notes live? Ask the agent to remember it.
-Threadnote keeps that memory local and searchable without editing unrelated repo files.
+**Working through a long task until the agent context window fills up?**  
+After compaction, the next agent turn can recall the relevant Threadnote memories and handoffs instead of relying only on the compressed conversation summary.
+
+**Found a durable workflow fact, like how a repo runs tests or where release notes live?**  
+Ask the agent to remember it. Threadnote keeps that memory local and searchable without editing unrelated repo files.
+
+**Have reusable agent workflows already installed as skills?**\
+Run `threadnote seed-skills` to make local `SKILL.md` guidance discoverable through recall. Agents can find relevant testing, release, on-call, debugging, or plugin-provided workflows without you reopening the same skill files by hand.
+
+**Recall returned several overlapping memories?**
+Agents are instructed to compact them into one concise replacement memory and forget only the clearly redundant originals,
+keeping future recall sharper without losing useful detail.
 
 ## Safety Model
 
@@ -50,7 +60,7 @@ threadnote start
 threadnote doctor --dry-run
 ```
 
-If install or health checks fail, see `docs/troubleshooting.md`.
+If install or health checks fail, see [Troubleshooting](docs/troubleshooting.md).
 
 To force a runtime:
 
@@ -157,7 +167,19 @@ threadnote seed --dry-run
 threadnote seed
 ```
 
-Optionally seed shared and repo-local skills:
+For Git worktrees, seed the stable checkout by default:
+
+```bash
+threadnote init-manifest --repo ~/src/coda
+```
+
+You usually do not need to add every temporary worktree such as `~/src/worktrees/coda/my-branch`. Threadnote treats each
+worktree path as its own manifest project today, so adding every worktree can duplicate seeded repo resources and make
+recall noisier. Add a worktree only when it is long-lived or has branch-specific docs, instructions, or repo-local skills
+that should be recalled separately.
+
+Optionally seed shared and repo-local skills. This imports existing `SKILL.md` files as a searchable resource catalog so
+agents can discover relevant workflow guidance; it does not install or activate skills in the agent runtime.
 
 ```bash
 threadnote seed-skills --dry-run
@@ -183,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

package/docs/agent-instructions.md

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

package/docs/migration.md

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

package/package.json

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