@mnemonik/shared 7.2.2 → 7.27.0

package/dist/instructions.d.ts

@@ -4,8 +4,33 @@
  * This is the SINGLE SOURCE OF TRUTH for MCP instructions.
  * Shared instruction content imported by the server.
  *
- * Version: 2.107
- * Updated: 2026-07-25
+ * Version: 2.109
+ * Updated: 2026-08-11
+ *
+ * v2.109 — Compressed the v2.108 memory-search clause. It restated, verbatim,
+ *          the same search guidance carried by SESSION_OPENER_INSTRUCTION
+ *          (bootstrapDigestRender.ts) — and both co-occur in the same agent
+ *          session as the bootstrap digest's capabilities.search block, which
+ *          already states the memory_search/code_search call signatures in
+ *          full. Kept the essential behavior (memory holds the why; search it
+ *          before assuming files or git history are the whole story; verify
+ *          with Grep/Read; reach for code_search when concepts don't share
+ *          the user's words), dropped the restated call shapes, and pointed at
+ *          the session context's capabilities block for the exact signatures
+ *          once it loads — this text fires at `initialize`, before any
+ *          digest exists, so it cannot point "above" the way the trimmed
+ *          SESSION_OPENER clause does. recall-first-class plan, Task A3
+ *          rider (reviewer-flagged: character-for-character duplicate).
+ * v2.108 — Added front-loaded education that persistent project memory is part
+ *          of the agent's working knowledge. A live Config-B fixture rejected
+ *          the first generic invitation: the agent searched code, docs, and git
+ *          history, then called the rationale undocumented without searching
+ *          memory. The instruction now names the missing reasoning step and its
+ *          address: rationale/intent questions use mnemonik.memory_search inside
+ *          memory_tools, paired with current-source inspection; conceptual code
+ *          discovery uses code_search alongside exact Grep/Read. The accepted
+ *          wording stays a compact startup floor, not a token-heavy tutorial or
+ *          recurring nudge.
  *
  * v2.106 — Added a static "Which tool for what" floor map. Rides the already-
  *         cached instructions at near-zero cost and gives every agent a baseline
@@ -123,7 +148,7 @@ export declare function getMcpInstructions(): string;
  * Raw instructions content (always returns the content, ignores env var).
  * Use getMcpInstructions() for production code.
  */
-export declare const MCP_INSTRUCTIONS_RAW = "If your context does not contain a block beginning \"PROJECT_CONTEXT schemaVersion=\", call session_bootstrap before replying or taking any other action \u2014 e.g. session_bootstrap({ cwd: \"/absolute/path/to/project\" }), where cwd is the real absolute path to the project root you are working in (required; the call fails without it \u2014 substitute your actual path, not the example). It loads this project's prior decisions, open tasks, and policies. If that block is already present, do not call session_bootstrap; the context is already loaded.\n\nLarge retrievals arrive as complete hydrated records plus exact pointer rows and extent/facet counts. Select relevant IDs and hydrate exact originals with mnemonik.memory_get({ memoryIds: [...], includeRaw: true }); refine the query or continue the index cursor when the visible index is incomplete\u2014do not page full bodies merely to discover what exists.\n\nProject work items and pending tasks live in mnemonik.tasks, not the host TaskList. A pending-task list requires mnemonik.tasks({ action:\"list\", status:\"pending\", ... }); never omit action:\"list\". If the request says pending, status:\"pending\" is required\u2014an unfiltered list is wrong. For in-progress, completed, or all-status requests, use the matching status or no status filter. Each list page is { hydrated, index, extent, cursor }, not { tasks }. When the user requests a complete or all-results list, collect [...page.hydrated, ...page.index] in one memory_tools program, repeat the same inner query with each returned cursor until cursor is null, then return compact id/title/status rows. Every row carries title, priority and status \u2014 hydrated and pointer alike; read them uniformly and never hydrate a body just to label it. Do not stop at the first retrieval envelope.\n\nWhich tool for what \u2014 reach past memory_search and checkpoint for these:\n- memory_add \u2014 persist a discrete decision or root cause the moment you make it; do not bury it in a checkpoint summary.\n- memory_state \u2014 a memory is wrong or outdated: supersede/deprecate/dispute it, do not add a competing copy.\n- memory_info \u2014 a memory looks suspect (low confidence, odd origin): investigate it before you act on or discard it.\n- memory_links \u2014 connect related decisions so they surface together.\n- assist \u2014 search results are thin or empty: check for coverage gaps.\n- search_summaries \u2014 find past work by topic or date across prior sessions.\n- policy \u2014 a durable rule or preference belongs here (enforced), not in a memory.\n- tasks \u2014 create follow-up work here, and close tasks when done so the pending list stays honest.";
+export declare const MCP_INSTRUCTIONS_RAW = "If your context does not contain a block beginning \"PROJECT_CONTEXT schemaVersion=\", call session_bootstrap before replying or taking any other action \u2014 e.g. session_bootstrap({ cwd: \"/absolute/path/to/project\" }), where cwd is the real absolute path to the project root you are working in (required; the call fails without it \u2014 substitute your actual path, not the example). It loads this project's prior decisions, open tasks, and policies. If that block is already present, do not call session_bootstrap; the context is already loaded.\n\nTreat persistent memory as working knowledge: code and docs show current artifacts, git shows changes, and Mnemonik can remember why. For rationale or intent, search memory before relying on files or git history alone, then verify current source with Grep or Read; use code_search when concepts don't share the user's words. Exact call shapes load with the session context.\n\nLarge retrievals arrive as complete hydrated records plus exact pointer rows and extent/facet counts. Select relevant IDs and hydrate exact originals with mnemonik.memory_get({ memoryIds: [...], includeRaw: true }); refine the query or continue the index cursor when the visible index is incomplete\u2014do not page full bodies merely to discover what exists.\n\nProject work items and pending tasks live in mnemonik.tasks, not the host TaskList. A pending-task list requires mnemonik.tasks({ action:\"list\", status:\"pending\", ... }); never omit action:\"list\". If the request says pending, status:\"pending\" is required\u2014an unfiltered list is wrong. For in-progress, completed, or all-status requests, use the matching status or no status filter. Each list page is { hydrated, index, extent, cursor }, not { tasks }. When the user requests a complete or all-results list, collect [...page.hydrated, ...page.index] in one memory_tools program, repeat the same inner query with each returned cursor until cursor is null, then return compact id/title/status rows. Every row carries title, priority and status \u2014 hydrated and pointer alike; read them uniformly and never hydrate a body just to label it. Do not stop at the first retrieval envelope.\n\nWhich tool for what \u2014 reach past memory_search and checkpoint for these:\n- memory_add \u2014 persist a discrete decision or root cause the moment you make it; do not bury it in a checkpoint summary.\n- memory_state \u2014 a memory is wrong or outdated: supersede/deprecate/dispute it, do not add a competing copy.\n- memory_info \u2014 a memory looks suspect (low confidence, odd origin): investigate it before you act on or discard it.\n- memory_links \u2014 connect related decisions so they surface together.\n- assist \u2014 search results are thin or empty: check for coverage gaps.\n- search_summaries \u2014 find past work by topic or date across prior sessions.\n- policy \u2014 a durable rule or preference belongs here (enforced), not in a memory.\n- tasks \u2014 create follow-up work here, and close tasks when done so the pending list stays honest.";
 /**
  * Default export for convenience.
  * Note: This respects the MNEMONIK_INSTRUCTIONS_ENABLED env var.

package/dist/instructions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8GG;AAoBH;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAa3C;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,koFAAuB,CAAC;AAEzD;;;GAGG;AACH,eAAO,MAAM,gBAAgB,QAAuB,CAAC"}
+{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuIG;AAsBH;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAa3C;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,2/FAAuB,CAAC;AAEzD;;;GAGG;AACH,eAAO,MAAM,gBAAgB,QAAuB,CAAC"}

package/dist/instructions.js

@@ -4,8 +4,33 @@
  * This is the SINGLE SOURCE OF TRUTH for MCP instructions.
  * Shared instruction content imported by the server.
  *
- * Version: 2.107
- * Updated: 2026-07-25
+ * Version: 2.109
+ * Updated: 2026-08-11
+ *
+ * v2.109 — Compressed the v2.108 memory-search clause. It restated, verbatim,
+ *          the same search guidance carried by SESSION_OPENER_INSTRUCTION
+ *          (bootstrapDigestRender.ts) — and both co-occur in the same agent
+ *          session as the bootstrap digest's capabilities.search block, which
+ *          already states the memory_search/code_search call signatures in
+ *          full. Kept the essential behavior (memory holds the why; search it
+ *          before assuming files or git history are the whole story; verify
+ *          with Grep/Read; reach for code_search when concepts don't share
+ *          the user's words), dropped the restated call shapes, and pointed at
+ *          the session context's capabilities block for the exact signatures
+ *          once it loads — this text fires at `initialize`, before any
+ *          digest exists, so it cannot point "above" the way the trimmed
+ *          SESSION_OPENER clause does. recall-first-class plan, Task A3
+ *          rider (reviewer-flagged: character-for-character duplicate).
+ * v2.108 — Added front-loaded education that persistent project memory is part
+ *          of the agent's working knowledge. A live Config-B fixture rejected
+ *          the first generic invitation: the agent searched code, docs, and git
+ *          history, then called the rationale undocumented without searching
+ *          memory. The instruction now names the missing reasoning step and its
+ *          address: rationale/intent questions use mnemonik.memory_search inside
+ *          memory_tools, paired with current-source inspection; conceptual code
+ *          discovery uses code_search alongside exact Grep/Read. The accepted
+ *          wording stays a compact startup floor, not a token-heavy tutorial or
+ *          recurring nudge.
  *
  * v2.106 — Added a static "Which tool for what" floor map. Rides the already-
  *         cached instructions at near-zero cost and gives every agent a baseline
@@ -113,6 +138,8 @@
 // Config-A interpretation fallback when no hook/proxy guidance channel is available.
 const INSTRUCTIONS_CONTENT = `If your context does not contain a block beginning "PROJECT_CONTEXT schemaVersion=", call session_bootstrap before replying or taking any other action — e.g. session_bootstrap({ cwd: "/absolute/path/to/project" }), where cwd is the real absolute path to the project root you are working in (required; the call fails without it — substitute your actual path, not the example). It loads this project's prior decisions, open tasks, and policies. If that block is already present, do not call session_bootstrap; the context is already loaded.
 
+Treat persistent memory as working knowledge: code and docs show current artifacts, git shows changes, and Mnemonik can remember why. For rationale or intent, search memory before relying on files or git history alone, then verify current source with Grep or Read; use code_search when concepts don't share the user's words. Exact call shapes load with the session context.
+
 Large retrievals arrive as complete hydrated records plus exact pointer rows and extent/facet counts. Select relevant IDs and hydrate exact originals with mnemonik.memory_get({ memoryIds: [...], includeRaw: true }); refine the query or continue the index cursor when the visible index is incomplete—do not page full bodies merely to discover what exists.
 
 Project work items and pending tasks live in mnemonik.tasks, not the host TaskList. A pending-task list requires mnemonik.tasks({ action:"list", status:"pending", ... }); never omit action:"list". If the request says pending, status:"pending" is required—an unfiltered list is wrong. For in-progress, completed, or all-status requests, use the matching status or no status filter. Each list page is { hydrated, index, extent, cursor }, not { tasks }. When the user requests a complete or all-results list, collect [...page.hydrated, ...page.index] in one memory_tools program, repeat the same inner query with each returned cursor until cursor is null, then return compact id/title/status rows. Every row carries title, priority and status — hydrated and pointer alike; read them uniformly and never hydrate a body just to label it. Do not stop at the first retrieval envelope.

package/dist/instructions.js.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8GG;AAEH,oFAAoF;AACpF,qFAAqF;AACrF,MAAM,oBAAoB,GAAG;;;;;;;;;;;;;;kGAcqE,CAAC;AAEnG;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB;IAChC,0EAA0E;IAC1E,2EAA2E;IAC3E,+DAA+D;IAC/D,MAAM,OAAO,GAAI,UAAyE;SACvF,OAAO,CAAC;IACX,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC;QAClB,OAAO,oBAAoB,CAAC;IAC9B,CAAC;IACD,IAAI,OAAO,CAAC,GAAG,CAAC,6BAA6B,KAAK,OAAO,EAAE,CAAC;QAC1D,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,oBAAoB,CAAC;AAC9B,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,oBAAoB,CAAC;AAEzD;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,kBAAkB,EAAE,CAAC"}
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuIG;AAEH,oFAAoF;AACpF,qFAAqF;AACrF,MAAM,oBAAoB,GAAG;;;;;;;;;;;;;;;;kGAgBqE,CAAC;AAEnG;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB;IAChC,0EAA0E;IAC1E,2EAA2E;IAC3E,+DAA+D;IAC/D,MAAM,OAAO,GAAI,UAAyE;SACvF,OAAO,CAAC;IACX,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC;QAClB,OAAO,oBAAoB,CAAC;IAC9B,CAAC;IACD,IAAI,OAAO,CAAC,GAAG,CAAC,6BAA6B,KAAK,OAAO,EAAE,CAAC;QAC1D,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,oBAAoB,CAAC;AAC9B,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,oBAAoB,CAAC;AAEzD;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,kBAAkB,EAAE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemonik/shared",
-  "version": "7.2.2",
+  "version": "7.27.0",
   "description": "Shared constants and utilities for Mnemonik packages",
   "type": "module",
   "main": "dist/index.js",

package/src/instructions.ts

@@ -4,8 +4,33 @@
  * This is the SINGLE SOURCE OF TRUTH for MCP instructions.
  * Shared instruction content imported by the server.
  *
- * Version: 2.107
- * Updated: 2026-07-25
+ * Version: 2.109
+ * Updated: 2026-08-11
+ *
+ * v2.109 — Compressed the v2.108 memory-search clause. It restated, verbatim,
+ *          the same search guidance carried by SESSION_OPENER_INSTRUCTION
+ *          (bootstrapDigestRender.ts) — and both co-occur in the same agent
+ *          session as the bootstrap digest's capabilities.search block, which
+ *          already states the memory_search/code_search call signatures in
+ *          full. Kept the essential behavior (memory holds the why; search it
+ *          before assuming files or git history are the whole story; verify
+ *          with Grep/Read; reach for code_search when concepts don't share
+ *          the user's words), dropped the restated call shapes, and pointed at
+ *          the session context's capabilities block for the exact signatures
+ *          once it loads — this text fires at `initialize`, before any
+ *          digest exists, so it cannot point "above" the way the trimmed
+ *          SESSION_OPENER clause does. recall-first-class plan, Task A3
+ *          rider (reviewer-flagged: character-for-character duplicate).
+ * v2.108 — Added front-loaded education that persistent project memory is part
+ *          of the agent's working knowledge. A live Config-B fixture rejected
+ *          the first generic invitation: the agent searched code, docs, and git
+ *          history, then called the rationale undocumented without searching
+ *          memory. The instruction now names the missing reasoning step and its
+ *          address: rationale/intent questions use mnemonik.memory_search inside
+ *          memory_tools, paired with current-source inspection; conceptual code
+ *          discovery uses code_search alongside exact Grep/Read. The accepted
+ *          wording stays a compact startup floor, not a token-heavy tutorial or
+ *          recurring nudge.
  *
  * v2.106 — Added a static "Which tool for what" floor map. Rides the already-
  *         cached instructions at near-zero cost and gives every agent a baseline
@@ -114,6 +139,8 @@
 // Config-A interpretation fallback when no hook/proxy guidance channel is available.
 const INSTRUCTIONS_CONTENT = `If your context does not contain a block beginning "PROJECT_CONTEXT schemaVersion=", call session_bootstrap before replying or taking any other action — e.g. session_bootstrap({ cwd: "/absolute/path/to/project" }), where cwd is the real absolute path to the project root you are working in (required; the call fails without it — substitute your actual path, not the example). It loads this project's prior decisions, open tasks, and policies. If that block is already present, do not call session_bootstrap; the context is already loaded.
 
+Treat persistent memory as working knowledge: code and docs show current artifacts, git shows changes, and Mnemonik can remember why. For rationale or intent, search memory before relying on files or git history alone, then verify current source with Grep or Read; use code_search when concepts don't share the user's words. Exact call shapes load with the session context.
+
 Large retrievals arrive as complete hydrated records plus exact pointer rows and extent/facet counts. Select relevant IDs and hydrate exact originals with mnemonik.memory_get({ memoryIds: [...], includeRaw: true }); refine the query or continue the index cursor when the visible index is incomplete—do not page full bodies merely to discover what exists.
 
 Project work items and pending tasks live in mnemonik.tasks, not the host TaskList. A pending-task list requires mnemonik.tasks({ action:"list", status:"pending", ... }); never omit action:"list". If the request says pending, status:"pending" is required—an unfiltered list is wrong. For in-progress, completed, or all-status requests, use the matching status or no status filter. Each list page is { hydrated, index, extent, cursor }, not { tasks }. When the user requests a complete or all-results list, collect [...page.hydrated, ...page.index] in one memory_tools program, repeat the same inner query with each returned cursor until cursor is null, then return compact id/title/status rows. Every row carries title, priority and status — hydrated and pointer alike; read them uniformly and never hydrate a body just to label it. Do not stop at the first retrieval envelope.