threadnote 0.7.5 → 0.7.7

package/docs/agent-instructions.md

@@ -8,9 +8,11 @@ Use OpenViking through Threadnote as a shared local context and memory layer. Re
 follow the nearest `AGENTS.md`, `CLAUDE.md`, or other checked-in instruction file first.
 
 When OpenViking MCP tools are available, use them directly. Prefer Threadnote-named MCP tools when present:
-`recall_context`, `read_context`, `list_context`, `remember_context`, and `share_publish`. Always pass JSON arguments to
-MCP tools, for example `recall_context({"query":"current repo latest handoff"})`. Older Threadnote MCP adapters may
-expose `search`, `read`, `list`, and `store` instead.
+`recall_context`, `read_context`, `list_context`, `remember_context`, `compact_context`, and `share_publish`. Always
+pass JSON arguments to MCP tools. When a recall query says "current repo" or "this branch", include the current
+workspace path as `callerCwd`, for example
+`recall_context({"query":"current repo latest handoff","callerCwd":"/absolute/workspace/path"})`. Older Threadnote MCP
+adapters may expose `search`, `read`, `list`, and `store` instead.
 
 If MCP is unavailable, use the `threadnote` CLI fallback.
 
@@ -71,14 +73,17 @@ For branch feature work, prefer two stable memories with the same project and to
 - `kind: handoff` for current status, files touched, tests, blockers, and next step.
 
 If a durable feature memory already exists, update it in place with the same project/topic or with `--replace <uri>` /
-`replaceUri`. Avoid creating a new timestamped durable memory for every small progress note.
+`replaceUri`. When `replaceUri` points at a shared `durable/` URI, Threadnote updates that shared memory in place and
+pushes the shared repo; do not create a personal replacement and then run `share_publish` again. Avoid creating a new
+timestamped durable memory for every small progress note.
 
 ## 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.
+`threadnote handoff --replace <uri>` so the old personal memory is removed only after the replacement is stored. Shared
+`durable/` replacements are updated in place and pushed instead.
 
 When the issue has a stable name, prefer project/topic storage over timestamped memories:
 
@@ -88,8 +93,19 @@ threadnote remember --kind durable --project my-repo --topic active-bug --text "
 threadnote handoff --project my-repo --topic active-bug --task "..." --tests "..."
 ```
 
-When recall/read surfaces several memories that describe the same durable fact, incident, branch, or handoff, compact
-them when it is safe:
+Bare `threadnote handoff` stores the current repo/current branch handoff by default. Use `threadnote handoff
+--timestamped` only when you intentionally want a historical note instead of updating the active branch handoff.
+
+When recall/read surfaces several memories that describe the same durable fact, incident, branch, or handoff, run a
+scoped hygiene dry-run before deciding what to change:
+
+```bash
+threadnote compact --project my-repo --topic active-bug --dry-run
+```
+
+```text
+compact_context({"project":"my-repo","topic":"active-bug","dryRun":true})
+```
 
 - Store one concise replacement memory that preserves the current status, the important facts, and the source `viking://`
   URIs you merged.
@@ -97,6 +113,8 @@ them when it is safe:
   no unique useful detail.
 - Use `threadnote archive <uri>` instead of `forget` when the old handoff still has provenance value but should no
   longer be treated as current context.
+- Keep hygiene scoped to the current project/topic. Do not run global cleanup.
+- For cross-repo features, link related durable memories explicitly in the body so recall can bridge the projects.
 - 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.
@@ -142,6 +160,9 @@ Before pausing, switching agents, or ending meaningful work with local changes,
 - blockers;
 - next suggested step.
 
+If you wrote or read multiple memories for the same project/topic during the task, run a scoped hygiene dry-run before
+the handoff. Do not do global memory cleanup.
+
 Do not store long diffs, secrets, raw logs, or customer data in handoffs.
 
 ## CLI Fallback
@@ -157,6 +178,7 @@ threadnote list viking://agent/threadnote/memories --all --recursive
 threadnote remember --kind durable --project example --topic workflow --text "Durable engineering note..."
 threadnote remember --kind durable --project example --topic active-issue --text "Feature knowledge..."
 threadnote remember --replace viking://user/example/memories/durable/projects/example/workflow.md --text "Updated durable engineering note..."
+threadnote compact --project example --topic active-issue --dry-run
 threadnote archive viking://user/example/memories/handoffs/active/example/old-issue.md
 threadnote forget viking://user/example/memories/events/duplicate.md
 threadnote handoff --project example --topic active-issue --task "short task summary" --tests "checks run" --next-step "what to do next"

package/docs/index.html

@@ -1341,7 +1341,7 @@ threadnote remember \
               <p class="muted" style="font-size: 0.9rem; margin-top: 0.6rem">
                 Refuses to publish if the memory matches secret patterns (PEM, <code>sk-</code>, <code>gh*_</code>,
                 <code>github_pat_</code>, <code>glpat-</code>, JWTs, AWS keys, Slack tokens). Refuses to silently
-                overwrite an existing shared URI.
+                overwrite an existing shared URI; update shared memories with <code>remember --replace</code>.
               </p>
             </div>
 

package/docs/migration.md

@@ -187,8 +187,9 @@ Preferred agent behavior is automatic after `threadnote install` has updated the
   `remember --replace <uri>` instead of burying that knowledge only in a handoff.
 - When current status changes, update the active handoff with the same project/topic 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.
+- When recall surfaces clearly duplicate or stale memories, run `threadnote compact --project <name> --topic <topic>
+--dry-run` or `compact_context({"project":"<name>","topic":"<topic>","dryRun":true})`. Keep cleanup scoped to the
+  current project/topic; archive stale handoffs by default and forget only exact redundant duplicates.
 - Before pausing, switching agents, or finishing meaningful code changes, store a concise handoff with status, tests,
   blockers, and next steps.
 
@@ -199,6 +200,7 @@ threadnote recall --query "last handoff for this branch"
 threadnote recall --query "durable feature knowledge for this branch"
 threadnote remember --kind durable --project example --topic active-feature --text "Feature knowledge..."
 threadnote remember --replace viking://user/example/memories/events/current.md --text "Updated durable engineering note..."
+threadnote compact --project example --topic active-feature --dry-run
 threadnote handoff --project example --topic active-feature --task "short task summary" --tests "checks run" --next-step "what the next agent should do"
 ```
 

package/docs/share.md

@@ -71,6 +71,21 @@ lines from the memory's header block. Those pointers only resolve on the
 publisher's machine — teammates pull via git and cannot dereference them — so
 keeping them would just leak local-only provenance into team git history.
 
+To update an existing shared durable memory, replace the shared URI directly:
+
+```bash
+threadnote remember \
+  --replace viking://user/you/memories/shared/default/durable/projects/foo/bar.md \
+  --project foo \
+  --topic bar \
+  --text "Updated shared knowledge."
+```
+
+For MCP, pass the same shared URI as `replaceUri` to `remember_context`.
+Threadnote rewrites the shared memory in place, strips local-only provenance
+headers, commits, and pushes the shared repo. You do not need to store a
+personal replacement and run `share publish` again.
+
 ### Keep teammates' updates current
 
 Threadnote does a periodic background `git fetch` for configured share teams.
@@ -155,7 +170,9 @@ otherwise unpublished work is lost.
   keep both, copy the memory to a new URI first (`ov read` then
   `threadnote remember`).
 - `share publish` refuses to overwrite an existing shared memory at the same
-  URI; forget the existing shared copy first or pick a different topic name.
+  URI; use `threadnote remember --replace <shared-uri>` or
+  `remember_context({replaceUri:"<shared-uri>"})` for updates, or pick a
+  different topic name.
 
 ## Conflict resolution
 

package/package.json

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