threadnote 0.3.5 → 0.3.7

package/docs/agent-instructions.md

@@ -36,8 +36,30 @@ 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.
 
+Use lifecycle metadata when storing memories:
+
+- `kind: durable` for facts future agents should use by default.
+- `kind: handoff` for current work logs and next steps.
+- `project` for the repo/product namespace.
+- `topic` for the active issue or stable fact. Reusing the same project/topic keeps one current memory updated.
+
+Archived handoffs are provenance, not default working context. Read them only when current durable memories or active
+handoffs are insufficient.
+
 ## 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 the issue has a stable name, prefer project/topic storage over timestamped memories:
+
+```bash
+threadnote remember --kind durable --project my-repo --topic test-workflow --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:
 
@@ -45,6 +67,8 @@ them when it is safe:
   URIs you merged.
 - Remove superseded duplicates with `threadnote forget <uri>` only when they are clearly redundant or stale and contain
   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.
 - 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.
@@ -71,7 +95,9 @@ threadnote start
 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 --kind durable --project example --topic workflow --text "Durable engineering note..."
+threadnote remember --replace viking://user/example/memories/durable/projects/example/workflow.md --text "Updated durable engineering note..."
+threadnote archive viking://user/example/memories/handoffs/active/example/old-issue.md
 threadnote forget viking://user/example/memories/events/duplicate.md
-threadnote handoff --task "short task summary" --tests "checks run" --next-step "what to do next"
+threadnote handoff --project example --topic active-issue --task "short task summary" --tests "checks run" --next-step "what to do next"
 ```

package/docs/migration.md

@@ -170,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,
@@ -180,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/package.json

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