@mnemonik/shared 7.17.0 → 7.31.0

package/dist/instructions.d.ts

@@ -4,9 +4,23 @@
  * This is the SINGLE SOURCE OF TRUTH for MCP instructions.
  * Shared instruction content imported by the server.
  *
- * Version: 2.108
- * Updated: 2026-08-03
- *
+ * 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
@@ -134,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\nTreat persistent memory as working knowledge: code and docs show current artifacts, git shows changes, and Mnemonik can remember why. For rationale, intent, or prior attempts, do not stop at files or git history\u2014call mnemonik.memory_search(...) inside memory_tools, then verify current source with Grep or Read. Use mnemonik.code_search(...) when conceptual locations may not share the user's words.\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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyHG;AAsBH;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAa3C;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,0hGAAuB,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,9 +4,23 @@
  * This is the SINGLE SOURCE OF TRUTH for MCP instructions.
  * Shared instruction content imported by the server.
  *
- * Version: 2.108
- * Updated: 2026-08-03
- *
+ * 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
@@ -124,7 +138,7 @@
 // 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, intent, or prior attempts, do not stop at files or git history—call mnemonik.memory_search(...) inside memory_tools, then verify current source with Grep or Read. Use mnemonik.code_search(...) when conceptual locations may not share the user's words.
+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.
 

package/dist/instructions.js.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyHG;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"}
+{"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/dist/usageGuide.d.ts

@@ -10,5 +10,5 @@
  * This guide focuses on HOW to use Mnemonik effectively, not WHAT tools exist.
  * Tool schemas already tell agents what's available - they need the workflow.
  */
-export declare const USAGE_GUIDE = "# Mnemonik Workflow Guide (v2.85)\n\n## Workflow\n\nsession_bootstrap \u2192 memory_search \u2192 file_context \u2192 [work] \u2192 memory_add \u2192 memory_state\n\n## Tool Selection by Stage\n\n### Session start\n- session_bootstrap: loads context, policies, pending tasks (call once, first thing)\n- memory_search: search by task domain; set workflowContext (feature_implementation, debugging, exploration, policy_review)\n- projects: resolve project IDs if context unclear\n- policy: review safety rules\n\n### Before editing files\n- file_context: fetch memories for the file \u2014 call for EVERY file you edit\n- memory_search: second search scoped to file/module if needed\n- mnemonik.docs({ action: 'links' }): check doc couplings for the file\n\n### During implementation\n- memory_get: retrieve specific memory by id\n- memory_update: refine memory created this session\n- memory_info: query history, provenance, confidence breakdown, links, graph\n- assist: get tool guidance if uncertain\n\n### Documentation drift\n- An unscoped mnemonik.docs({ action: 'drift' }) call defaults to the schema-v3 affected-document inventory; a scoped call defaults to its detailed packet. Each document is an independent work unit. Recommended default: delegate each affected document to a subagent and start available document workers together; pass docPath and the compact retrieve call instead of copying finding bodies. This is advisory orchestration, not a host-enforced ownership rule.\n- Detailed retrieval defaults to one document and returns at most 8 findings within 16 KiB. Each packet carries compact causal triggers plus current Markdown and code locations resolved from stable identities; line numbers are display metadata and may move.\n- Complete every finding in the document: edit update_doc/regenerate_doc items, submit mnemonik.docs({ action: 'verdicts', scopePath, items: [...] }) with independently cited evidence for settled verify_and_report items, or call mnemonik.docs({ action: 'flag_for_review', scopePath, findingId, evidence }) when inspected evidence cannot settle a claim.\n- The document under review cannot confirm or refute its own claim. Verdict evidence must cite an independent source; route a rejected circular verdict to flag_for_review.\n- Absence of repository evidence is not refutation. Claims about human intent, plans, positioning, or external facts require affirmative contradictory evidence to refute; otherwise flag them for review.\n- Follow the document-local retrieveMore call until that document is complete, and follow inventory cursors until every affected document has a terminal disposition.\n\n### After significant work\n- memory_add: save decisions, outcomes, patterns, bug root causes\n- memory_state: reinforce (memory helped), supersede (replace outdated), deprecate, penalize, dispute\n- tasks: mark tasks in progress or complete\n- mnemonik.docs({ action: 'status' }): view doc-truth health (legacy coupling counts are diagnostic only \u2014 do not act on them as drift)\n\n### Diagnostics\n- doctor: when tool calls fail or behavior is inconsistent\n- scanner: refresh embeddings, trigger scans, check drift\n\n## Skip conditions\n\nSkip memory tools for: formatting-only edits, trivial one-line changes, mechanical refactors, git operations, running tests.\n\n## Completion gate\n\nNever tell the user significant work is done without calling memory_add first in the same response. Changes made + responding next = completion. \"Progress updates\" count.\n\n## Memory search tips\n\n- Query should include task intent + key entities\n- Set workflowContext when you know the phase\n- Use currentFile to boost file-linked memories\n- Use filterOnly:true only for narrow filters (no embedding, requires >=1 filter)\n\n## Proactive heuristics\n\n- Long sessions: re-run memory_search after switching topics\n- Conflicting info: use memory_state to supersede/dispute\n- High-impact changes: save memory immediately after verification\n- Treat each affected document in docTruthFindings/_docDrift as an independent work unit. Complete its scoped packet with edits, supported verdicts, or an evidenced review disposition. linkedDocs and stale-coupling counts alone remain legacy diagnostics\n\n## Anti-fade (every ~10 tool calls)\n\nCheck: (1) memory_search before work? (2) file_context before edit? (3) memory_add after completing? No session_bootstrap? Call it now.\n";
+export declare const USAGE_GUIDE = "# Mnemonik Workflow Guide (v2.85)\n\n## Workflow\n\nsession_bootstrap \u2192 memory_search \u2192 file_context \u2192 [work] \u2192 memory_add \u2192 memory_state\n\n## Tool Selection by Stage\n\n### Session start\n- session_bootstrap: loads context, policies, pending tasks (call once, first thing)\n- memory_search: search by task domain; set workflowContext (feature_implementation, debugging, exploration, policy_review)\n- projects: resolve project IDs if context unclear\n- policy: review safety rules\n\n### Before editing files\n- file_context: fetch memories for the file \u2014 call for EVERY file you edit\n- memory_search: second search scoped to file/module if needed\n- mnemonik.docs({ action: 'drift', scopePath }): check doc-truth findings for the file\n\n### During implementation\n- memory_get: retrieve specific memory by id\n- memory_update: refine memory created this session\n- memory_info: query history, provenance, confidence breakdown, links, graph\n- assist: get tool guidance if uncertain\n\n### Documentation drift\n- An unscoped mnemonik.docs({ action: 'drift' }) call defaults to the schema-v3 affected-document inventory; a scoped call defaults to its detailed packet. Each document is an independent work unit. Recommended default: delegate each affected document to a subagent and start available document workers together; pass docPath and the compact retrieve call instead of copying finding bodies. This is advisory orchestration, not a host-enforced ownership rule.\n- Detailed retrieval defaults to one document and returns at most 8 findings within 16 KiB. Each packet carries compact causal triggers plus current Markdown and code locations resolved from stable identities; line numbers are display metadata and may move.\n- Complete every finding in the document: edit update_doc/regenerate_doc items, submit mnemonik.docs({ action: 'verdicts', scopePath, items: [...] }) with independently cited evidence for settled verify_and_report items, or call mnemonik.docs({ action: 'flag_for_review', scopePath, findingId, evidence }) when inspected evidence cannot settle a claim.\n- The document under review cannot confirm or refute its own claim. Verdict evidence must cite an independent source; route a rejected circular verdict to flag_for_review.\n- Absence of repository evidence is not refutation. Claims about human intent, plans, positioning, or external facts require affirmative contradictory evidence to refute; otherwise flag them for review.\n- Follow the document-local retrieveMore call until that document is complete, and follow inventory cursors until every affected document has a terminal disposition.\n\n### After significant work\n- memory_add: save decisions, outcomes, patterns, bug root causes\n- memory_state: reinforce (memory helped), supersede (replace outdated), deprecate, penalize, dispute\n- tasks: mark tasks in progress or complete\n- mnemonik.docs({ action: 'status' }): view doc-truth health (legacy coupling counts are diagnostic only \u2014 do not act on them as drift)\n\n### Diagnostics\n- doctor: when tool calls fail or behavior is inconsistent\n- scanner: metrics (is the indexing daemon alive), history, drift. Nothing here starts indexing \u2014 the daemon owns it\n\n## Skip conditions\n\nSkip memory tools for: formatting-only edits, trivial one-line changes, mechanical refactors, git operations, running tests.\n\n## Completion gate\n\nNever tell the user significant work is done without calling memory_add first in the same response. Changes made + responding next = completion. \"Progress updates\" count.\n\n## Memory search tips\n\n- Query should include task intent + key entities\n- Set workflowContext when you know the phase\n- Use currentFile to boost file-linked memories\n- Use filterOnly:true only for narrow filters (no embedding, requires >=1 filter)\n\n## Proactive heuristics\n\n- Long sessions: re-run memory_search after switching topics\n- Conflicting info: use memory_state to supersede/dispute\n- High-impact changes: save memory immediately after verification\n- Treat each affected document in docTruthFindings/_docDrift as an independent work unit. Complete its scoped packet with edits, supported verdicts, or an evidenced review disposition. linkedDocs and stale-coupling counts alone remain legacy diagnostics\n\n## Anti-fade (every ~10 tool calls)\n\nCheck: (1) memory_search before work? (2) file_context before edit? (3) memory_add after completing? No session_bootstrap? Call it now.\n";
 //# sourceMappingURL=usageGuide.d.ts.map

package/dist/usageGuide.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usageGuide.d.ts","sourceRoot":"","sources":["../src/usageGuide.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,WAAW,+0IAoEvB,CAAC"}
+{"version":3,"file":"usageGuide.d.ts","sourceRoot":"","sources":["../src/usageGuide.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,WAAW,+5IAoEvB,CAAC"}

package/dist/usageGuide.js

@@ -27,7 +27,7 @@ session_bootstrap → memory_search → file_context → [work] → memory_add
 ### Before editing files
 - file_context: fetch memories for the file — call for EVERY file you edit
 - memory_search: second search scoped to file/module if needed
-- mnemonik.docs({ action: 'links' }): check doc couplings for the file
+- mnemonik.docs({ action: 'drift', scopePath }): check doc-truth findings for the file
 
 ### During implementation
 - memory_get: retrieve specific memory by id
@@ -51,7 +51,7 @@ session_bootstrap → memory_search → file_context → [work] → memory_add
 
 ### Diagnostics
 - doctor: when tool calls fail or behavior is inconsistent
-- scanner: refresh embeddings, trigger scans, check drift
+- scanner: metrics (is the indexing daemon alive), history, drift. Nothing here starts indexing — the daemon owns it
 
 ## Skip conditions
 

package/package.json

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

package/src/instructions.ts

@@ -4,9 +4,23 @@
  * This is the SINGLE SOURCE OF TRUTH for MCP instructions.
  * Shared instruction content imported by the server.
  *
- * Version: 2.108
- * Updated: 2026-08-03
- *
+ * 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
@@ -125,7 +139,7 @@
 // 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, intent, or prior attempts, do not stop at files or git history—call mnemonik.memory_search(...) inside memory_tools, then verify current source with Grep or Read. Use mnemonik.code_search(...) when conceptual locations may not share the user's words.
+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.
 

package/src/usageGuide.ts

@@ -28,7 +28,7 @@ session_bootstrap → memory_search → file_context → [work] → memory_add
 ### Before editing files
 - file_context: fetch memories for the file — call for EVERY file you edit
 - memory_search: second search scoped to file/module if needed
-- mnemonik.docs({ action: 'links' }): check doc couplings for the file
+- mnemonik.docs({ action: 'drift', scopePath }): check doc-truth findings for the file
 
 ### During implementation
 - memory_get: retrieve specific memory by id
@@ -52,7 +52,7 @@ session_bootstrap → memory_search → file_context → [work] → memory_add
 
 ### Diagnostics
 - doctor: when tool calls fail or behavior is inconsistent
-- scanner: refresh embeddings, trigger scans, check drift
+- scanner: metrics (is the indexing daemon alive), history, drift. Nothing here starts indexing — the daemon owns it
 
 ## Skip conditions