threadnote 0.3.6 → 0.3.8

package/docs/agent-instructions.md

@@ -1,6 +1,6 @@
 # Agent Instructions
 
-Threadnote installs this as user-level agent guidance for Codex, Claude, and Cursor.
+Threadnote installs this as user-level agent guidance for Codex, Claude, Cursor, and Copilot.
 
 ## Shared Context
 
@@ -20,9 +20,14 @@ At the start of a non-trivial task, recall relevant context before making change
 
 - the current repo and branch;
 - recent handoffs;
+- durable feature memories for the branch, feature name, project/topic, or issue;
 - task-specific skills or workflow guidance;
 - user or team preferences that may affect the work.
 
+When a recalled handoff describes an active branch or feature, do a second recall for durable memories about that
+feature before coding. The handoff tells you the current work state; durable feature memories tell you the design,
+decisions, invariants, interfaces, and gotchas that should survive beyond one session.
+
 Skip proactive recall for tiny one-shot questions where context would add noise.
 
 Search results are not the final payload. Treat returned `viking://` URIs as pointers: read the relevant URI, or list a
@@ -36,6 +41,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.
 
+During feature work on a branch, maintain durable feature knowledge in addition to handoffs. Store or update a durable
+memory when you learn something future agents should know about the feature itself: the intended behavior, design
+decisions, API contracts, data flow, migration semantics, edge cases, known limitations, or why an implementation choice
+was made. Do not wait until the end of the branch; update the feature memory whenever a valuable change lands or a
+decision becomes clear.
+
+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.
+
+For branch feature work, prefer two stable memories with the same project and topic:
+
+- `kind: durable` for the feature knowledge that should remain useful after the current agent session.
+- `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.
+
 ## Memory Compaction
 
 When working on the same active issue, prefer keeping one current-state memory updated instead of creating many small
@@ -43,6 +72,14 @@ progress memories. If an existing memory is clearly the current state for the is
 `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 recall --query "my-repo active-bug durable feature knowledge"
+threadnote remember --kind durable --project my-repo --topic active-bug --text "Feature knowledge: ..."
+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:
 
@@ -50,6 +87,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.
@@ -59,6 +98,7 @@ Never compact secrets, credentials, customer data, raw production logs, or check
 Before pausing, switching agents, or ending meaningful work with local changes, store a concise handoff. Include:
 
 - repo and branch;
+- related durable feature memory URI or topic, when known;
 - files touched;
 - current status;
 - tests or checks run;
@@ -74,10 +114,13 @@ Use these only when MCP tools are not available:
 ```bash
 threadnote start
 threadnote recall --query "last handoff for this branch"
+threadnote recall --query "durable feature knowledge 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 --replace viking://user/example/memories/events/current.md --text "Updated durable engineering note..."
+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 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

@@ -30,8 +30,8 @@ Developers should not need to run `recall`, `remember`, or `handoff` as a normal
 
 The intended workflow has three layers:
 
-- Agent-first: Codex, Claude, or another MCP-enabled agent calls OpenViking tools when the task calls for shared
-  context.
+- Agent-first: Codex, Claude, Copilot, or another MCP-enabled agent calls OpenViking tools when the task calls for
+  shared context.
 - Short CLI fallback: humans and scripts can run `threadnote recall`, `threadnote remember`, or
   `threadnote handoff` from any repo.
 - Checkout-local command: `npm run threadnote -- ...` is the bootstrap and debugging path before the short command shim
@@ -46,8 +46,8 @@ Create a handoff for the next agent before you stop.
 ```
 
 For better continuity, run `threadnote install` so it can add the agent-side guidance from `docs/agent-instructions.md`
-to user-level Codex, Claude, and Cursor instruction files. That guidance tells agents to recall context at task start,
-store durable memories when explicitly asked or when a reusable workflow fact is learned, and create handoffs
+to user-level Codex, Claude, Cursor, and Copilot instruction files. That guidance tells agents to recall context at task
+start, store durable memories when explicitly asked or when a reusable workflow fact is learned, and create handoffs
 automatically before stopping meaningful work.
 
 ## Migration Steps
@@ -141,6 +141,16 @@ paths.
 
    Cursor installs by updating the global `~/.cursor/mcp.json` file.
 
+   For GitHub Copilot in VS Code:
+
+   ```bash
+   threadnote mcp-install copilot
+   threadnote mcp-install copilot --apply
+   ```
+
+   Copilot installs by updating the VS Code user-profile `mcp.json` file. If VS Code uses a custom profile path, set
+   `THREADNOTE_COPILOT_MCP_CONFIG` to that `mcp.json` path before running `mcp-install copilot`.
+
    Later, if the checkout that installed the MCP adapter is deleted or moved, repair it from any fresh checkout:
 
    ```bash
@@ -162,16 +172,21 @@ Preferred developer behavior is conversational:
 
 ```text
 Recall anything relevant for this branch before you start.
-Remember this workflow note for future agents: ...
+Remember this feature decision for future agents: ...
 Create a handoff now.
 ```
 
 Preferred agent behavior is automatic after `threadnote install` has updated the user-level instruction files:
 
-- On non-trivial task start, search OpenViking for recent handoffs and relevant repo guidance.
+- On non-trivial task start, search OpenViking for recent handoffs, durable feature memories for the branch/topic, 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 continuing the same active issue, keep two current-state records when useful: a durable feature memory for design,
+  decisions, interfaces, and gotchas, plus a handoff for status, tests, blockers, and next steps.
+- When valuable feature knowledge changes, update the durable feature memory with the same project/topic or
+  `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.
 - Before pausing, switching agents, or finishing meaningful code changes, store a concise handoff with status, tests,
@@ -181,9 +196,10 @@ Manual CLI remains available for scripts and emergencies:
 
 ```bash
 threadnote recall --query "last handoff for this branch"
-threadnote remember --text "Durable engineering note..."
+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 handoff --task "short task summary" --tests "checks run" --next-step "what the next agent should do"
+threadnote handoff --project example --topic active-feature --task "short task summary" --tests "checks run" --next-step "what the next agent should do"
 ```
 
 ## Repo Paths

package/docs/rollout.md

@@ -18,7 +18,7 @@ Start with a local-only pilot.
 
 - Install completes in under 10 minutes after prerequisites.
 - `doctor` reports clear actionable checks.
-- Codex, Claude, or Cursor can store and recall a shared handoff after MCP setup.
+- Codex, Claude, Cursor, or Copilot can store and recall a shared handoff after MCP setup.
 - Seeding curated guidance does not import known secret patterns.
 - Fresh agents can recall repo testing guidance and discover relevant skills.
 - `uninstall --dry-run` previews removal, and `uninstall` leaves memories intact unless `--erase-memories` is explicit.

package/docs/security.md

@@ -6,7 +6,8 @@
 
 - Credentials, access tokens, API keys, certificates, private keys, or shell history.
 - Customer data, production data, HIPAA data, or production logs without explicit approval and scrubbing.
-- Local auth files such as `~/.codex/auth.json`, `~/.claude/.credentials.json`, or Cursor account/session files.
+- Local auth files such as `~/.codex/auth.json`, `~/.claude/.credentials.json`, Cursor account/session files, or VS Code
+  Copilot account/session files.
 - Local settings files that may contain secrets unless they go through redaction.
 
 ## Built-In Controls
@@ -14,9 +15,9 @@
 - `.threadnoteignore` excludes common secret and build-output paths.
 - `.mcp.json`, `config.toml`, and settings JSON are redacted before import.
 - Files are skipped if common secret patterns remain after redaction.
-- `mcp-install` requires `--apply` before it changes Codex, Claude, or Cursor config.
-- `install` updates user-level Codex, Claude, and Cursor instruction files through a managed Markdown block. Existing
-  personal instructions outside that block are preserved.
+- `mcp-install` requires `--apply` before it changes Codex, Claude, Cursor, or Copilot config.
+- `install` updates user-level Codex, Claude, Cursor, and Copilot instruction files through managed Threadnote content.
+  Existing personal instructions outside managed blocks are preserved.
 - `uninstall` preserves local memories by default. `--erase-memories` is required before deleting `THREADNOTE_HOME`.
 - Config files created under `THREADNOTE_HOME` are written with user-only permissions.
 

package/docs/troubleshooting.md

@@ -147,7 +147,7 @@ threadnote repair
 ```
 
 `repair` reinstalls the `threadnote` shim, repairs generated config files, starts OpenViking if needed, and rewrites
-Codex/Claude/Cursor MCP configs to point at the current checkout.
+Codex/Claude/Cursor/Copilot MCP configs to point at the current checkout.
 
 ## MCP Install Is Only Printing Commands
 
@@ -166,6 +166,16 @@ threadnote mcp-install cursor --apply
 This updates the global `~/.cursor/mcp.json` file. Restart Cursor or open a fresh agent session after changing MCP
 config.
 
+For GitHub Copilot in VS Code:
+
+```bash
+threadnote mcp-install copilot --apply
+```
+
+This updates the VS Code user-profile `mcp.json` file. Restart VS Code or run `MCP: List Servers` from the Command
+Palette after changing MCP config. If VS Code uses a custom profile path, set `THREADNOTE_COPILOT_MCP_CONFIG` to that
+`mcp.json` path before running the command.
+
 ## Cursor MCP Tool Says Query Is Missing
 
 If Cursor shows an error like `expected string, received undefined` for Threadnote `search`, the MCP server started but

package/package.json

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