@mnemonik/shared 7.27.0 → 7.31.0

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.27.0",
+  "version": "7.31.0",
   "description": "Shared constants and utilities for Mnemonik packages",
   "type": "module",
   "main": "dist/index.js",

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