@mnemonik/shared 1.0.0

package/src/index.ts

@@ -0,0 +1,17 @@
+/**
+ * @mnemonik/shared - Shared constants and utilities
+ *
+ * This package provides a single source of truth for constants
+ * that need to be shared across Mnemonik packages.
+ */
+
+export { MCP_INSTRUCTIONS, MCP_INSTRUCTIONS_RAW, getMcpInstructions } from './instructions.js';
+export { USAGE_GUIDE } from './usageGuide.js';
+export { CodeScanner, type CodeChunk, type ScanOptions } from './codeScanner.js';
+export {
+  FileSystemReader,
+  getFileSystemReader,
+  type ScanFilesResult,
+  type ChangedFilesResult,
+  type FileData,
+} from './FileSystemReader.js';

package/src/instructions.ts

@@ -0,0 +1,55 @@
+/**
+ * MCP Instructions - Persistent agent guidance
+ *
+ * This is the SINGLE SOURCE OF TRUTH for MCP instructions.
+ * Shared instruction content imported by the server.
+ *
+ * Version: 2.92
+ * Updated: 2026-02-24
+ *
+ * v2.93: Code mode permanent — all memory operations via memory_tools sandbox.
+ *        memory_add, file_context etc. are now mnemonik.* methods, not standalone tools.
+ *
+ * v2.92: Zero-cooperation rewrite. Context auto-loads if session_bootstrap is skipped.
+ *        Session summaries are auto-saved if agent doesn't call mnemonik.memory_add().
+ *        Instructions drastically simplified — the server handles the workflow now.
+ *
+ * v2.80: Token-optimised rewrite (superseded by v2.92).
+ */
+
+const INSTRUCTIONS_CONTENT = `You have Mnemonik, a persistent memory system for this project.
+
+First call, every session: session_bootstrap. Read the mnemonik skill (from available_skills) for the full workflow.
+After bootstrap: execute _directive.message actions immediately (scanner daemon check is mandatory).
+
+Proactively call memory_search before starting new work — avoids rediscovering known patterns and contradicting past decisions.
+Proactively call file_context before editing any file — loads past bugs, decisions, and gotchas for that file.
+Proactively call checkpoint after making changes or decisions worth keeping — your context is ephemeral and checkpoint is the only way decisions survive across sessions and context compaction. Do not wait for the user to say "done" or "thanks".
+
+When mnemonik.file_context({ filePaths, cwd }) returns linkedDocs with driftStatus 'stale', update docs then call mnemonik.docs({ action: 'resolve', docPath, cwd }).
+
+Skip: formatting-only, trivial one-line, mechanical refactors, git ops, tests.
+Save: architectural decisions, bug root causes, user preferences, discovered patterns, multi-file changes.`;
+
+/**
+ * Get MCP instructions, respecting MNEMONIK_INSTRUCTIONS_ENABLED env var.
+ * Set MNEMONIK_INSTRUCTIONS_ENABLED=false to disable for testing.
+ */
+export function getMcpInstructions(): string {
+  if (typeof process !== 'undefined' && process.env?.MNEMONIK_INSTRUCTIONS_ENABLED === 'false') {
+    return '';
+  }
+  return INSTRUCTIONS_CONTENT;
+}
+
+/**
+ * Raw instructions content (always returns the content, ignores env var).
+ * Use getMcpInstructions() for production code.
+ */
+export const MCP_INSTRUCTIONS_RAW = INSTRUCTIONS_CONTENT;
+
+/**
+ * Default export for convenience.
+ * Note: This respects the MNEMONIK_INSTRUCTIONS_ENABLED env var.
+ */
+export const MCP_INSTRUCTIONS = getMcpInstructions();

package/src/logger.ts

@@ -0,0 +1,7 @@
+export const debug = (_msg: string, _ctx?: Record<string, unknown>): void => {};
+export const info = (msg: string, ctx?: Record<string, unknown>): void => {
+  console.log(`[info] ${msg}`, ctx ? JSON.stringify(ctx) : '');
+};
+export const warn = (msg: string, ctx?: Record<string, unknown>): void => {
+  console.warn(`[warn] ${msg}`, ctx ? JSON.stringify(ctx) : '');
+};

package/src/usageGuide.ts

@@ -0,0 +1,75 @@
+/**
+ * Mnemonik Usage Guide - Procedural workflow guidance for agents
+ *
+ * This is the SINGLE SOURCE OF TRUTH for the usage guide.
+ * Shared usage guide content imported by the server.
+ *
+ * Version: 2.80
+ * Updated: 2026-02-20 - Aligned with instructions/rules/skill v2.80
+ *
+ * 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 const USAGE_GUIDE = `# Mnemonik Workflow Guide (v2.80)
+
+## Workflow
+
+session_bootstrap → memory_search → file_context → [work] → memory_add → memory_state
+
+## Tool Selection by Stage
+
+### Session start
+- session_bootstrap: loads context, policies, pending tasks (call once, first thing)
+- memory_search: search by task domain; set workflowContext (feature_implementation, debugging, exploration, policy_review)
+- projects: resolve project IDs if context unclear
+- policy: review safety rules
+
+### 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
+- docs(action: 'links'): check doc couplings for the file
+
+### During implementation
+- memory_get: retrieve specific memory by id
+- memory_update: refine memory created this session
+- memory_info: query history, provenance, confidence breakdown, links, graph
+- assist: get tool guidance if uncertain
+
+### After significant work
+- memory_add: save decisions, outcomes, patterns, bug root causes
+- memory_state: reinforce (memory helped), supersede (replace outdated), deprecate, penalize, dispute
+- tasks: mark tasks in progress or complete
+- docs(action: 'drift'): check for stale documentation after code changes
+- docs(action: 'resolve'): mark stale docs as fixed after updating them
+
+### Diagnostics
+- doctor: when tool calls fail or behavior is inconsistent
+- scanner: refresh embeddings, trigger scans, check drift
+
+## Skip conditions
+
+Skip memory tools for: formatting-only edits, trivial one-line changes, mechanical refactors, git operations, running tests.
+
+## Completion gate
+
+Never tell the user significant work is done without calling memory_add first in the same response. Changes made + responding next = completion. "Progress updates" count.
+
+## Memory search tips
+
+- Query should include task intent + key entities
+- Set workflowContext when you know the phase
+- Use currentFile to boost file-linked memories
+- Use filterOnly:true only for narrow filters (no embedding, requires >=1 filter)
+
+## Proactive heuristics
+
+- Long sessions: re-run memory_search after switching topics
+- Conflicting info: use memory_state to supersede/dispute
+- High-impact changes: save memory immediately after verification
+- When file_context returns linkedDocs with driftStatus 'stale': update docs then docs(action: 'resolve')
+
+## Anti-fade (every ~10 tool calls)
+
+Check: (1) memory_search before work? (2) file_context before edit? (3) memory_add after completing? No session_bootstrap? Call it now.
+`;

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}