docs(session): clarify note continuity protocol

Author: vicary

opencode.json

@@ -12,6 +12,7 @@ import {
   SESSION_NOTES_READ_DESCRIPTION,
   SESSION_NOTES_WRITE_DESCRIPTION,
   SESSION_SEARCH_BASELINE_DESCRIPTION,
+  SESSION_SEARCH_STRENGTHENED_DESCRIPTION,
 } from "./session-mcp-runtime.ts";
 import type { SessionExecutor } from "./session-executor.ts";
 import {
@@ -752,6 +753,71 @@ describe("session-mcp-runtime", () => {
     }
   });
 
+  it("pins the cross-tool continuity protocol language in shipped descriptions", () => {
+    const search = SESSION_SEARCH_BASELINE_DESCRIPTION.toLowerCase();
+    const strengthened = SESSION_SEARCH_STRENGTHENED_DESCRIPTION.toLowerCase();
+    const read = SESSION_NOTES_READ_DESCRIPTION.toLowerCase();
+    const write = SESSION_NOTES_WRITE_DESCRIPTION.toLowerCase();
+
+    // session_search should bias agents toward search-first recall, especially
+    // at the start of a new session or after compaction, and should explicitly
+    // chain to session_notes_read for note hits.
+    assertStringIncludes(search, "first");
+    assertStringIncludes(search, "after compaction");
+    assertStringIncludes(search, "session_notes_read");
+    assertStringIncludes(search, "session_notes_write");
+
+    // The strengthened overlay (used on new sessions and post-compaction turns)
+    // must keep the strong recommendation and still chain to session_notes_read.
+    assertStringIncludes(strengthened, "new session");
+    assertStringIncludes(strengthened, "post-compaction");
+    assertStringIncludes(strengthened, "strongly recommended");
+    assertStringIncludes(strengthened, "session_search");
+    assertStringIncludes(strengthened, "session_notes_read");
+
+    // session_notes_read should reinforce that it is the second step after
+    // session_search and that new-session/post-compaction are recall moments.
+    // It must also tell agents that progress updates use non-empty text so
+    // they don't accidentally delete via empty-text replace.
+    assertStringIncludes(read, "session_search");
+    assertStringIncludes(read, "after compaction");
+    assertStringIncludes(read, "non-empty");
+    // Pin the empty-text deletion footgun warning on the read description so
+    // future edits cannot silently drop it. Use small lowercase-normalized
+    // fragments rather than exact sentence/casing.
+    assertStringIncludes(read, "empty `text`");
+    assertStringIncludes(read, "delete");
+    assertStringIncludes(read, "fully");
+    assertStringIncludes(read, "complete");
+
+    // session_notes_write should encode the full lifecycle protocol:
+    // start -> search/read existing then create with checklist;
+    // sub-task done -> upsert; stop mid-task -> update before reporting;
+    // ~75% context counts as stopping mid-task; complete -> clear (delete)
+    // only when fully done, before reporting back.
+    for (
+      const phrase of [
+        // Step 1: search before creating, then create checklist.
+        "session_search",
+        "session_notes_read",
+        "checklist",
+        // Step 2: upsert with id.
+        "replace: <id>",
+        "non-empty",
+        // Step 3: stop mid-task / approaching context limit.
+        "mid-task",
+        "before reporting back",
+        "75%",
+        // Step 4: clear only when fully complete; clearing == delete.
+        "fully",
+        "complete",
+        "empty `text`",
+      ]
+    ) {
+      assertStringIncludes(write, phrase.toLowerCase());
+    }
+  });
+
   it("executes the full note action contract through the runtime", async () => {
     const redis = new RedisClient({ endpoint: "redis://unused" });
     const runtime = createSessionMcpRuntime({

src/services/session-mcp-runtime.test.ts

@@ -45,18 +45,39 @@ const SEARCH_RESULT_CREATED_AT_FALLBACK = "1970-01-01T00:00:00.000Z";
 
 export const SESSION_NOTES_WRITE_DESCRIPTION = [
   "Pin working context as a session note so it survives topic switches, long tool",
-  "loops, and compaction. Use this BEFORE drifting away from important context:",
+  "loops, and compaction. Notes are the primary continuity surface — write or",
+  "update one BEFORE you stop, hand back to the user, or risk losing context.",
+  "",
+  "Required lifecycle (follow this protocol — do not skip steps):",
+  "",
+  "1. **Starting a new task** → first run `session_search` and",
+  "   `session_notes_read` on relevant note hits to check whether an existing",
+  "   note already covers this work. If one does, upsert it (see step 2). If",
+  "   none exists, create a new note with a short description and a markdown",
+  "   checklist of the planned sub-tasks.",
+  "2. **Finishing a sub-task** → upsert the same note (call this tool with",
+  "   non-empty `text` and `replace: <id>`) to check off the completed item.",
+  "3. **Stopping mid-task** (blocker, finding, awaiting user input) → upsert",
+  "   the note with current progress and findings BEFORE reporting back to the",
+  "   user. Approaching ~75% context usage counts as stopping mid-task: upsert",
+  "   with full detail so a post-compaction agent can resume without",
+  "   re-derivation.",
+  "4. **Completing the task** → ONLY when the task is fully done, clear the",
+  "   note BEFORE reporting back. Clearing means deleting it: call this tool",
+  '   with empty `text` and `replace: <id>` (or `replace: "*"` with empty text',
+  "   to clear all notes for this scope). Do not clear a note for a paused,",
+  "   blocked, or partially complete task — upsert per step 3 instead.",
+  "",
+  "Also write/update a note:",
   "",
-  "- Before switching to a different topic or task",
   "- After a user correction changes your assumptions",
-  "- When a small task stalls and work shifts elsewhere",
+  "- Before switching to a different topic or task",
   "- During long tool-calling sequences where key state lives only in your context",
-  "- Before compaction is likely (many messages into a session)",
   "",
   "Do NOT use this for ephemeral state that will be irrelevant within a few turns",
   "(e.g., intermediate variable values, transient build errors you are about to",
-  "fix, or scratchpad reasoning). Notes are for context you need to survive",
-  "across topic switches or compaction — not for every observation.",
+  "fix, or scratchpad reasoning). Notes are for context that must survive topic",
+  "switches, compaction, or a fresh agent picking up the work.",
   "",
   "Accepts `text` (markdown body) and optional `replace`:",
   "",
@@ -70,59 +91,84 @@ export const SESSION_NOTES_WRITE_DESCRIPTION = [
   '- omit `replace` to create a new note and return `{ action: "created", id }`',
   "",
   "Always rely on the returned `action` instead of inferring the outcome from the",
-  "inputs alone.",
+  "inputs alone. Capture the returned `id` so subsequent updates upsert the same",
+  "note rather than creating duplicates.",
   "",
-  "Prefer concise markdown with headings, bullets, and short code snippets:",
+  "Prefer concise markdown with a heading and a checklist:",
   "",
   "    ## Current Task: Fix Redis TTL bug",
   "    - **File:** `src/services/redis-client.ts`",
   "    - **Root cause:** TTL not refreshed on read",
-  "    - **Next step:** Add EXPIRE call after GET in `refreshEntry()`",
+  "    - **Progress:**",
+  "      - [x] Reproduce on staging",
+  "      - [x] Identify missing EXPIRE in `refreshEntry()`",
+  "      - [ ] Add regression test",
+  "      - [ ] Land fix",
   "    - **User correction:** Use seconds not milliseconds for TTL",
 ].join("\n");
 
 export const SESSION_NOTES_READ_DESCRIPTION = [
-  "Reopen exact pinned note text instead of reconstructing it from memory. Use this",
-  "when you resume an interrupted topic, need the exact wording of a pinned user",
-  "instruction, or want to verify what you previously noted before acting on it.",
+  "Reopen exact pinned note text instead of reconstructing it from memory. This",
+  "is the second step of the recall protocol: after `session_search` surfaces a",
+  "matching note hit, call `session_notes_read` with that note `id` to load the",
+  "full body before acting.",
+  "",
+  "Call this tool whenever you need authoritative pinned context, especially:",
+  "",
+  "- At the start of a new session, after compaction, or when resuming an",
+  "  interrupted task — these are the highest-priority recall moments.",
+  '- When `session_search` returns a `type: "note"` hit relevant to your task.',
+  "- When you need the exact wording of a pinned user instruction, plan, or",
+  "  checklist before acting on it.",
   "",
   "If `id` is provided, returns that single note as",
   "`{ note: { id, text, created_at, updated_at } }`; when the id does not exist,",
   "returns `{ note: null }`.",
   "",
   "Always prefer reading a pinned note over reciting its contents from recall —",
-  "notes are the source of truth for intentionally preserved context.",
+  "notes are the source of truth for intentionally preserved context. After",
+  "reading, update the note as you make progress by calling",
+  "`session_notes_write` with non-empty `text` and `replace: <id>` (passing",
+  "empty `text` would delete the note — only do that when the task is fully",
+  "complete).",
 ].join("\n");
 
 export const SESSION_SEARCH_BASELINE_DESCRIPTION = [
-  "Search local indexed content for the current root session. This is the default",
-  "recall path — use it FIRST when you need prior context, especially:",
+  "Search local indexed content for the current root session. This is the FIRST",
+  "step of the recall protocol — run a `session_search` BEFORE doing other work",
+  "whenever prior context may exist, especially:",
   "",
-  "- At the start of a new session or after compaction",
-  "- When resuming a topic you worked on earlier",
-  "- Before re-solving a problem that may already have a solution in session history",
-  "- To check whether pinned session notes already contain the context you need",
+  "- At the start of a new session or immediately after compaction (highest",
+  "  priority — pinned notes and prior decisions may not be in working memory).",
+  "- When resuming a topic you worked on earlier in this or a sibling session.",
+  "- Before re-solving a problem that may already have a solution in session",
+  "  history, or contradicting an earlier decision.",
+  "- To check whether pinned session notes already contain the context you need.",
   "",
   'Results may include indexed memory content (type: "memory") and, when pinned',
   'session notes exist, matching notes (type: "note"). Note results include',
   '`id`, `root_session_id`, `scope: "local" | "project"`, `created_at`, and',
-  "`updated_at` — use `session_notes_read` with the note `id` to reopen the full",
-  "note text. Not every query will return note results; notes only appear when they",
-  "match the search query and the session has pinned notes.",
+  "`updated_at` — when a note hit is relevant, immediately call",
+  "`session_notes_read` with that `id` to load the full note text. Do not",
+  "paraphrase a note from its snippet. Not every query returns note results;",
+  "notes only appear when they match the query and the session has pinned notes.",
   "",
-  "Prefer session_search over reconstructing context from scratch. If search",
-  "returns relevant note hits, read the note before duplicating its contents.",
+  "Prefer `session_search` over reconstructing context from scratch. The full",
+  "continuity protocol is: (1) `session_search` to discover, (2)",
+  "`session_notes_read` for relevant note hits, (3) `session_notes_write` to",
+  "pin or update progress before stopping or reporting back.",
 ].join("\n");
 
 export const SESSION_SEARCH_STRENGTHENED_DESCRIPTION =
   SESSION_SEARCH_BASELINE_DESCRIPTION +
   "\n\n" +
   [
     "⚠️ This is a new session or a post-compaction turn. Prior context may have been",
-    "summarized or is not yet in your working memory. STRONGLY RECOMMENDED: run a",
-    "session_search query before starting work to recover earlier decisions, pinned",
-    "notes, and task state. This avoids re-solving problems or contradicting earlier",
-    "decisions that survived compaction.",
+    "summarized or is not yet in your working memory. STRONGLY RECOMMENDED before",
+    "doing anything else: run `session_search` to recover earlier decisions, pinned",
+    "notes, and task state, then call `session_notes_read` on any relevant note",
+    "hits to load their exact text. This avoids re-solving problems, contradicting",
+    "earlier decisions, or duplicating notes that already track the work.",
   ].join("\n");
 
 type PluginToolArgs = Parameters<typeof tool>[0]["args"];