threadnote 0.7.5 → 0.7.7

package/README.md

@@ -37,12 +37,14 @@ Ask the agent to remember it. Threadnote keeps that memory local and searchable
 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.
+Run `threadnote compact --project <repo> --topic <issue> --dry-run` or ask the agent to use
+`compact_context({"project":"<repo>","topic":"<issue>","dryRun":true})`. Threadnote produces a scoped plan first:
+which memory to keep/update, which old handoffs to archive, and which exact duplicates are safe to forget.
 
 **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.
+instead of accumulating near-duplicate progress notes. Replacing a shared `durable/` URI updates that shared memory in
+place and pushes the shared repo, so you do not need a separate `share publish` step.
 
 ## Memory Lifecycle
 
@@ -70,6 +72,20 @@ threadnote handoff --project my-repo --topic feature-x --task "Current status fo
 Agents should update the durable feature memory when valuable implementation knowledge changes, and update the handoff
 when current status, tests, blockers, or next steps change.
 
+Bare `threadnote handoff` defaults to the current repo and current git branch as its stable project/topic, so routine
+handoffs update one active branch record. Use `threadnote handoff --timestamped` only when you intentionally want a
+historical note.
+
+Use `compact` when active memories for a project/topic start to overlap:
+
+```bash
+threadnote compact --project my-repo --topic feature-x --dry-run
+threadnote compact --project my-repo --topic feature-x --apply
+```
+
+The dry-run plan is the default. Applying archives stale handoffs, forgets only exact duplicates, and preserves source
+`viking://` URIs in the kept memory. Ambiguous durable or incident memories are left for manual review.
+
 Use `archive` when an old handoff is useful for provenance but should stop being treated as current working context:
 
 ```bash
@@ -332,19 +348,25 @@ This is it! Start working with your agents as usual. The agent will automaticall
   reusable workflow guidance. Use `seed-skills --native` only after configuring a working VLM provider.
 - `mcp-install codex|claude|cursor|copilot`: installs or prints OpenViking MCP configuration for Codex, Claude, Cursor,
   or GitHub Copilot in VS Code.
-- `remember`: stores a durable memory. Use `--replace <uri>` to store an updated memory and remove a superseded one
-  after the new memory succeeds. Use `--kind`, `--project`, and `--topic` to store lifecycle-aware current knowledge.
+- `remember`: stores a durable memory. Use `--replace <uri>` to store an updated memory and remove a superseded personal
+  memory after the new memory succeeds; if `<uri>` is shared, Threadnote updates that shared memory in place and pushes
+  the shared repo. Use `--kind`, `--project`, and `--topic` to store lifecycle-aware current knowledge.
 - `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.
 - `migrate-lifecycle`: moves clear legacy handoff memories from the old events path into archived lifecycle handoff
   paths. It dry-runs by default; use `--apply` after reviewing the output.
 - `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. Exact durable-memory matches skip archived
-  lifecycle paths unless `--include-archived` is passed.
+  `skills for api service`; use `--uri` or `--no-infer-scope` to override. Queries that mention `this branch` or
+  `current branch` are enriched with local git/workspace terms when available. Exact memory/resource matches skip
+  archived lifecycle paths unless `--include-archived` is passed. Recall also nudges scoped cleanup when many active
+  handoffs or overlapping returned memories surface.
+- `compact`: prints or applies scoped memory hygiene for active personal memories. It dry-runs by default; use `--apply`
+  after reviewing the plan. It archives stale handoffs, forgets exact duplicates, and leaves ambiguous durable memories
+  for manual review.
 - `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. Use `--replace <uri>` to update the
-  current handoff for the same active issue, or `--project` and `--topic` to keep one active handoff file updated.
+- `handoff`: stores current git state and next-step notes as a durable handoff. Bare handoffs use the current repo and
+  current branch as stable project/topic; use `--timestamped` for historical notes or `--project` / `--topic` to override.
 - `archive`: copies a memory into the archived lifecycle tree, then removes the original after the archive write
   succeeds.
 - `forget`: removes a `viking://` URI.
@@ -428,7 +450,10 @@ threadnote list viking://agent/threadnote/memories --all --recursive
 ```
 
 When MCP is installed, the agent should use Threadnote MCP `recall_context`, then `read_context` or `list_context`.
-Agents must pass JSON arguments, for example `recall_context({"query":"agent context"})`. Older adapters expose
-`search`, `read`, and `list` aliases. Before recall/read returns, Threadnote automatically syncs clean incoming shared
-memory updates when a configured share repo is behind; failures are reported as warnings and the local read still
-continues. The CLI commands are the fallback path.
+Agents must pass JSON arguments, for example `recall_context({"query":"agent context"})`. For MCP recall queries that
+say "current repo" or "this branch", pass the current workspace path as `callerCwd` so Threadnote can resolve branch and
+workspace terms without guessing from the MCP server's launch directory. Use `compact_context` for scoped memory hygiene
+dry-runs before applying cleanup. Older adapters expose `search`, `read`, and `list` aliases. Before recall/read returns,
+Threadnote automatically syncs clean incoming shared memory updates when a
+configured share repo is behind; failures are reported as warnings and the local read still continues. The CLI commands
+are the fallback path.