@mnemonik/shared 6.23.3 → 6.34.0

package/dist/instructions.d.ts

@@ -4,8 +4,16 @@
  * This is the SINGLE SOURCE OF TRUTH for MCP instructions.
  * Shared instruction content imported by the server.
  *
- * Version: 2.105
- * Updated: 2026-07-14
+ * Version: 2.107
+ * Updated: 2026-07-25
+ *
+ * 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
+ *         "which tool for what" for the under-surfaced tools (memory_add,
+ *         memory_state, memory_info, memory_links, assist, search_summaries,
+ *         policy, tasks). This is the floor under the reactive tool-education
+ *         nudges; memory_info in particular has no reactive trigger, so the floor
+ *         is its only education.
  *
  * v2.105 — Bootstrap's agent-facing label is generic project context. Use the
  *         canonical text body's stable `PROJECT_CONTEXT schemaVersion=` marker
@@ -115,7 +123,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. Pointer rows already contain title; use title: row.title ?? row.text without hydrating bodies. Do not stop at the first retrieval envelope.";
+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.";
 /**
  * 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsGG;AAUH;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAa3C;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,2uDAAuB,CAAC;AAEzD;;;GAGG;AACH,eAAO,MAAM,gBAAgB,QAAuB,CAAC"}
+{"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"}

package/dist/instructions.js

@@ -4,8 +4,16 @@
  * This is the SINGLE SOURCE OF TRUTH for MCP instructions.
  * Shared instruction content imported by the server.
  *
- * Version: 2.105
- * Updated: 2026-07-14
+ * Version: 2.107
+ * Updated: 2026-07-25
+ *
+ * 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
+ *         "which tool for what" for the under-surfaced tools (memory_add,
+ *         memory_state, memory_info, memory_links, assist, search_summaries,
+ *         policy, tasks). This is the floor under the reactive tool-education
+ *         nudges; memory_info in particular has no reactive trigger, so the floor
+ *         is its only education.
  *
  * v2.105 — Bootstrap's agent-facing label is generic project context. Use the
  *         canonical text body's stable `PROJECT_CONTEXT schemaVersion=` marker
@@ -107,7 +115,17 @@ const INSTRUCTIONS_CONTENT = `If your context does not contain a block beginning
 
 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. Pointer rows already contain title; use title: row.title ?? row.text without hydrating bodies. Do not stop at the first retrieval envelope.`;
+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.
+
+Which tool for what — reach past memory_search and checkpoint for these:
+- memory_add — persist a discrete decision or root cause the moment you make it; do not bury it in a checkpoint summary.
+- memory_state — a memory is wrong or outdated: supersede/deprecate/dispute it, do not add a competing copy.
+- memory_info — a memory looks suspect (low confidence, odd origin): investigate it before you act on or discard it.
+- memory_links — connect related decisions so they surface together.
+- assist — search results are thin or empty: check for coverage gaps.
+- search_summaries — find past work by topic or date across prior sessions.
+- policy — a durable rule or preference belongs here (enforced), not in a memory.
+- tasks — create follow-up work here, and close tasks when done so the pending list stays honest.`;
 /**
  * Get MCP instructions, respecting MNEMONIK_INSTRUCTIONS_ENABLED env var.
  * Set MNEMONIK_INSTRUCTIONS_ENABLED=false to disable for testing.

package/dist/instructions.js.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsGG;AAEH,oFAAoF;AACpF,qFAAqF;AACrF,MAAM,oBAAoB,GAAG;;;;m0BAIsyB,CAAC;AAEp0B;;;;;;;;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}

package/package.json

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

package/src/instructions.ts

@@ -4,8 +4,16 @@
  * This is the SINGLE SOURCE OF TRUTH for MCP instructions.
  * Shared instruction content imported by the server.
  *
- * Version: 2.105
- * Updated: 2026-07-14
+ * Version: 2.107
+ * Updated: 2026-07-25
+ *
+ * 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
+ *         "which tool for what" for the under-surfaced tools (memory_add,
+ *         memory_state, memory_info, memory_links, assist, search_summaries,
+ *         policy, tasks). This is the floor under the reactive tool-education
+ *         nudges; memory_info in particular has no reactive trigger, so the floor
+ *         is its only education.
  *
  * v2.105 — Bootstrap's agent-facing label is generic project context. Use the
  *         canonical text body's stable `PROJECT_CONTEXT schemaVersion=` marker
@@ -108,7 +116,17 @@ const INSTRUCTIONS_CONTENT = `If your context does not contain a block beginning
 
 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. Pointer rows already contain title; use title: row.title ?? row.text without hydrating bodies. Do not stop at the first retrieval envelope.`;
+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.
+
+Which tool for what — reach past memory_search and checkpoint for these:
+- memory_add — persist a discrete decision or root cause the moment you make it; do not bury it in a checkpoint summary.
+- memory_state — a memory is wrong or outdated: supersede/deprecate/dispute it, do not add a competing copy.
+- memory_info — a memory looks suspect (low confidence, odd origin): investigate it before you act on or discard it.
+- memory_links — connect related decisions so they surface together.
+- assist — search results are thin or empty: check for coverage gaps.
+- search_summaries — find past work by topic or date across prior sessions.
+- policy — a durable rule or preference belongs here (enforced), not in a memory.
+- tasks — create follow-up work here, and close tasks when done so the pending list stays honest.`;
 
 /**
  * Get MCP instructions, respecting MNEMONIK_INSTRUCTIONS_ENABLED env var.