monomind 2.7.5 → 2.7.6

package/packages/@monomind/cli/dist/src/index.js

@@ -156,42 +156,38 @@ export class CLI {
             let subcommandArgs = positional;
             // Process command path (e.g., ['hooks', 'worker', 'list'])
             // Note: When parser includes subcommand in commandPath, positional already excludes it
+            //
+            // Resolution walks as deep as the tree goes. It previously unrolled
+            // exactly two levels of nesting, so a four-segment invocation silently
+            // resolved to its grandparent and ran that command's action — which for
+            // a group command means printing help instead of doing anything. No
+            // error, no hint. `hooks transfer store list` failed exactly this way,
+            // making the whole pattern-store subtree unreachable without anyone
+            // noticing. This mirrors the loop showHelp() already used (see below),
+            // so `--help` and dispatch now agree on the target at any depth.
+            const findChild = (parent, segment) => parent.subcommands?.find(sc => sc.name === segment || sc.aliases?.includes(segment));
             if (commandPath.length > 1 && command.subcommands) {
-                const subcommandName = commandPath[1];
-                const subcommand = command.subcommands.find(sc => sc.name === subcommandName || sc.aliases?.includes(subcommandName));
-                if (subcommand) {
-                    targetCommand = subcommand;
-                    // Parser already extracted subcommand from positional, so use as-is
-                    subcommandArgs = positional;
-                    // Check for nested subcommand (level 2)
-                    if (commandPath.length > 2 && subcommand.subcommands) {
-                        const nestedName = commandPath[2];
-                        const nestedSubcommand = subcommand.subcommands.find(sc => sc.name === nestedName || sc.aliases?.includes(nestedName));
-                        if (nestedSubcommand) {
-                            targetCommand = nestedSubcommand;
-                            // Parser already extracted nested subcommand too
-                            subcommandArgs = positional;
-                        }
-                    }
+                // Parser already lifted the subcommand names out of positional, so
+                // descend using commandPath and leave the remaining args untouched.
+                for (const segment of commandPath.slice(1)) {
+                    const next = findChild(targetCommand, segment);
+                    if (!next)
+                        break;
+                    targetCommand = next;
                 }
+                subcommandArgs = positional;
             }
             else if (positional.length > 0 && command.subcommands) {
-                // Check if first positional is a subcommand
-                const subcommandName = positional[0];
-                const subcommand = command.subcommands.find(sc => sc.name === subcommandName || sc.aliases?.includes(subcommandName));
-                if (subcommand) {
-                    targetCommand = subcommand;
-                    subcommandArgs = positional.slice(1);
-                    // Check for nested subcommand (level 2 from positional)
-                    if (subcommandArgs.length > 0 && subcommand.subcommands) {
-                        const nestedName = subcommandArgs[0];
-                        const nestedSubcommand = subcommand.subcommands.find(sc => sc.name === nestedName || sc.aliases?.includes(nestedName));
-                        if (nestedSubcommand) {
-                            targetCommand = nestedSubcommand;
-                            subcommandArgs = subcommandArgs.slice(1);
-                        }
-                    }
+                // Subcommand names are still in positional — consume each one we match.
+                let consumed = 0;
+                while (consumed < subcommandArgs.length) {
+                    const next = findChild(targetCommand, subcommandArgs[consumed]);
+                    if (!next)
+                        break;
+                    targetCommand = next;
+                    consumed++;
                 }
+                subcommandArgs = subcommandArgs.slice(consumed);
             }
             // Validate flags
             const validationErrors = this.parser.validateFlags(flags, targetCommand);

package/packages/@monomind/cli/dist/src/mcp-client.js

@@ -124,6 +124,24 @@ export async function callMCPTool(toolName, input = {}, context) {
     if (isToolDisabled(toolName)) {
         throw new MCPClientError(`MCP tool '${toolName}' is disabled. Re-enable with: mcp toggle --enable ${toolName}`, toolName);
     }
+    // Enforce the `required` contract each tool advertises in its inputSchema.
+    // 120 of the ~254 tools declare required params, but nothing used to check
+    // them: handlers were invoked with whatever arrived, so a missing argument
+    // surfaced as whatever the handler happened to hit first — e.g.
+    // `monograph_agent_record` leaked a raw `SqliteError: NOT NULL constraint
+    // failed: agent_interactions.session_id` instead of naming the parameter.
+    // This is the single choke point for both the stdio server and the
+    // in-process CLI path, so validating here covers every tool at once.
+    //
+    // Only missing/undefined/null is rejected — empty strings and 0 are left
+    // alone, since some tools legitimately accept them.
+    const required = tool.inputSchema?.required;
+    if (Array.isArray(required) && required.length > 0) {
+        const missing = required.filter(key => input[key] === undefined || input[key] === null);
+        if (missing.length > 0) {
+            throw new MCPClientError(`MCP tool '${toolName}' missing required parameter${missing.length > 1 ? 's' : ''}: ${missing.join(', ')}`, toolName);
+        }
+    }
     try {
         const result = await tool.handler(input, context);
         return result;

package/packages/@monomind/cli/dist/src/mcp-tools/agent-tools.js

@@ -353,11 +353,14 @@ export const agentTools = [
         inputSchema: {
             type: 'object',
             properties: {
-                action: { type: 'string', enum: ['status', 'scale', 'drain'], description: 'Pool action' },
+                action: { type: 'string', enum: ['status', 'scale', 'drain'], description: 'Pool action (default: status)' },
                 targetSize: { type: 'number', description: 'Target pool size (for scale action)' },
                 agentType: { type: 'string', description: 'Agent type filter' },
             },
-            required: ['action'],
+            // `action` is deliberately NOT required: the handler defaults it to
+            // 'status', and the CLI `agent pool` command relies on that default.
+            // It was previously declared required, which nothing enforced — once
+            // required params became enforced, that false contract broke the CLI.
         },
         handler: async (input) => {
             const action = input.action || 'status'; // Default to status

package/packages/@monomind/cli/dist/src/mcp-tools/autopilot-tools.js

@@ -147,7 +147,7 @@ const autopilotProgress = {
 };
 const autopilotLearn = {
     name: 'autopilot_learn',
-    description: 'Discover success patterns from past task completions. Requires memory backend for full functionality.',
+    description: 'Report success patterns from the optional agentic-flow learning module. That module is not a declared dependency and is absent in normal installs, so this returns available:false with an empty pattern list — no pattern discovery occurs.',
     category: 'autopilot',
     inputSchema: { type: 'object', properties: {} },
     handler: async () => {
@@ -197,7 +197,7 @@ const autopilotHistory = {
 };
 const autopilotPredict = {
     name: 'autopilot_predict',
-    description: 'Predict the optimal next action based on current state and learned patterns.',
+    description: 'Suggest the next action by returning the first incomplete discovered task with a fixed 0.5 confidence — a heuristic over local task files, not ML prediction. The optional agentic-flow learning module that would refine this is not a declared dependency and is absent in normal installs.',
     category: 'autopilot',
     inputSchema: { type: 'object', properties: {} },
     handler: async () => {

package/packages/@monomind/cli/dist/src/mcp-tools/embeddings-tools.js

@@ -484,7 +484,7 @@ export const allEmbeddingsTools = [
     },
     {
         name: 'embeddings_neural',
-        description: 'Embedding substrate operations (drift, memory physics, coherence)',
+        description: 'Report and adjust pattern-store statistics (drift, consolidate, adapt) from intelligence.ts. Reads real counters — but its "init" action only persists a config blob (sona, flashAttention, ewcPlusPlus, memoryPhysics, swarmCoordination…) for which no implementing code exists anywhere; those flags are stored and echoed back, never acted on. There is no neural substrate and no "memory physics".',
         category: 'embeddings',
         inputSchema: {
             type: 'object',
@@ -502,7 +502,7 @@ export const allEmbeddingsTools = [
                 },
                 decayRate: {
                     type: 'number',
-                    description: 'Memory decay rate (hippocampal dynamics)',
+                    description: 'Decay rate applied to stored pattern confidence (plain exponential decay — the "hippocampal dynamics" framing this once carried described nothing in the code)',
                     default: 0.01,
                 },
             },

package/packages/@monomind/cli/dist/src/mcp-tools/guidance-tools.js

@@ -70,7 +70,7 @@ const CAPABILITY_CATALOG = {
         description: 'Multi-agent coordination with topology-aware communication and consensus.',
         tools: ['swarm_init', 'swarm_status', 'swarm_spawn', 'swarm_terminate', 'swarm_topology', 'swarm_metrics'],
         commands: ['swarm init', 'swarm status', 'swarm spawn', 'swarm terminate'],
-        agents: ['mesh-coordinator', 'queen-coordinator', 'collective-intelligence-coordinator'],
+        agents: ['coordinator', 'mesh-coordinator', 'collective-intelligence-coordinator'],
         skills: ['swarm-orchestration', 'swarm-advanced', 'monomind-swarm'],
         whenToUse: 'When a task requires multiple agents working together (3+ files, features, refactoring).',
     },

package/packages/@monomind/cli/dist/src/mcp-tools/hive-mind-tools.js

@@ -204,7 +204,7 @@ function saveAgentStore(store) {
 export const allHiveMindTools = [
     {
         name: 'hive-mind_spawn',
-        description: 'Spawn workers and automatically join them to the hive-mind (combines agent/spawn + hive-mind/join)',
+        description: 'Write worker agent records into the agent store and register their ids on the hive state file (combines agent_spawn + hive-mind_join). Creates bookkeeping entries only — no process, thread, or agent is started. Real concurrency comes from Claude Code\'s Task tool.',
         category: 'hive-mind',
         inputSchema: {
             type: 'object',
@@ -285,7 +285,7 @@ export const allHiveMindTools = [
     },
     {
         name: 'hive-mind_init',
-        description: 'Initialize the hive-mind collective',
+        description: 'Create the hive state file recording topology, consensus strategy, and an empty worker list. Writes JSON state only — nothing is started, and no collective process exists. Note "gossip" and "crdt" strategies are rejected: they are not implemented.',
         category: 'hive-mind',
         inputSchema: {
             type: 'object',
@@ -932,7 +932,7 @@ export const allHiveMindTools = [
     },
     {
         name: 'hive-mind_broadcast',
-        description: 'Broadcast message to all workers',
+        description: 'Append a message to a shared array on the hive state file (capped at 100 entries). This is a noticeboard, not message delivery — there are no live listeners, and a worker only sees it if something later reads that state. The reported recipient count is just the number of ids in the worker list.',
         category: 'hive-mind',
         inputSchema: {
             type: 'object',
@@ -1055,7 +1055,7 @@ export const allHiveMindTools = [
     },
     {
         name: 'hive-mind_memory',
-        description: 'Access hive shared memory',
+        description: 'Read or write a shared JSON blob on the hive state file. Plain key/value bookkeeping in a single local file — not a distributed or replicated store.',
         category: 'hive-mind',
         inputSchema: {
             type: 'object',

package/packages/@monomind/cli/dist/src/mcp-tools/hooks-intelligence.js

@@ -671,7 +671,7 @@ export const hooksIntelligenceStats = {
 // Intelligence learn hook
 export const hooksIntelligenceLearn = {
     name: 'hooks_intelligence_learn',
-    description: 'Force immediate SONA learning cycle with EWC++ consolidation',
+    description: 'Run a consolidation pass over the local keyword-pattern store: time-decay confidence weighting, pruning, and an EWC++-style quadratic penalty derived from squared embedding magnitudes. There are no gradients and no model — no ML training occurs.',
     inputSchema: {
         type: 'object',
         properties: {

package/packages/@monomind/cli/dist/src/mcp-tools/hooks-routing.js

@@ -980,7 +980,7 @@ export const hooksExplain = {
 // Pretrain hook - repository analysis for intelligence bootstrap
 export const hooksPretrain = {
     name: 'hooks_pretrain',
-    description: 'Analyze repository to bootstrap intelligence (4-step pipeline)',
+    description: 'Walk the repository counting file extensions and directory patterns to seed the keyword router. This is a filesystem scan writing JSON state — despite the name, no model is trained.',
     inputSchema: {
         type: 'object',
         properties: {

package/packages/@monomind/cli/dist/src/mcp-tools/session-tools.js

@@ -374,12 +374,25 @@ export const sessionTools = [
         inputSchema: {
             type: 'object',
             properties: {
-                sessionId: { type: 'string', description: 'Session ID' },
+                sessionId: { type: 'string', description: 'Session ID (defaults to the most recently saved session)' },
+                includeStats: { type: 'boolean', description: 'Include per-session statistics in the response' },
             },
-            required: ['sessionId'],
+            // `sessionId` is deliberately NOT required — it defaults to the most
+            // recent session, which is what the `session current` CLI subcommand
+            // asks for. It used to be declared required while the CLI called this
+            // tool with no id at all; nothing enforced the declaration, so instead
+            // of an error the undefined id reached getSessionPath(), threw a
+            // TypeError on `.replace`, and was swallowed by loadSession()'s catch.
+            // The net effect was that `session current` could never succeed — it
+            // always reported "Session not found".
         },
         handler: async (input) => {
-            const sessionId = input.sessionId;
+            const sessionId = input.sessionId
+                ?? listSessions()
+                    .sort((a, b) => new Date(b.savedAt).getTime() - new Date(a.savedAt).getTime())[0]?.sessionId;
+            if (!sessionId) {
+                return { sessionId: null, error: 'No saved sessions found' };
+            }
             const session = loadSession(sessionId);
             if (session) {
                 const path = getSessionPath(sessionId);

package/packages/@monomind/cli/dist/src/mcp-tools/transfer-tools.d.ts

@@ -1,14 +1,25 @@
 /**
  * Transfer MCP Tools
- * Pattern sharing via IPFS-based decentralized registry
+ *
+ * Only the PII scanner remains. The IPFS pattern-marketplace tools that used to
+ * live here (`transfer_ipfs-resolve`, `transfer_store-search`, `-info`,
+ * `-download`, `-featured`, `-trending`) were deleted along with the ~4,600-line
+ * `src/transfer/{store,ipfs,storage,models,serialization}` subtree they wrapped.
+ *
+ * They were unreachable three ways over: gated out of the default MCP surface,
+ * exposed on a CLI path the dispatcher cannot reach (`hooks transfer store …`
+ * is four levels deep; the dispatcher handles three), and pointed at a registry
+ * whose bootstrap config carried the placeholder `publicKey:
+ * 'ed25519:monomind-registry-key'` rather than a real key.
+ *
+ * `transfer_detect-pii` is unrelated to all of that — it is a real regex PII
+ * scanner over `src/transfer/anonymization/`, which has no store or IPFS
+ * dependency, and it stays visible by default.
  *
  * @module @monomind/cli/mcp-tools/transfer-tools
- * @version 3.0.0
+ * @version 4.0.0
  */
 import type { MCPTool } from './types.js';
-/**
- * Transfer MCP tools for pattern export, import, anonymization, and sharing
- */
 /** Ungated — internal/test use only. MCP clients get `transferTools` below. */
 export declare const allTransferTools: MCPTool[];
 export declare const transferTools: MCPTool[];

package/packages/@monomind/cli/dist/src/mcp-tools/transfer-tools.js

@@ -1,9 +1,23 @@
 /**
  * Transfer MCP Tools
- * Pattern sharing via IPFS-based decentralized registry
+ *
+ * Only the PII scanner remains. The IPFS pattern-marketplace tools that used to
+ * live here (`transfer_ipfs-resolve`, `transfer_store-search`, `-info`,
+ * `-download`, `-featured`, `-trending`) were deleted along with the ~4,600-line
+ * `src/transfer/{store,ipfs,storage,models,serialization}` subtree they wrapped.
+ *
+ * They were unreachable three ways over: gated out of the default MCP surface,
+ * exposed on a CLI path the dispatcher cannot reach (`hooks transfer store …`
+ * is four levels deep; the dispatcher handles three), and pointed at a registry
+ * whose bootstrap config carried the placeholder `publicKey:
+ * 'ed25519:monomind-registry-key'` rather than a real key.
+ *
+ * `transfer_detect-pii` is unrelated to all of that — it is a real regex PII
+ * scanner over `src/transfer/anonymization/`, which has no store or IPFS
+ * dependency, and it stays visible by default.
  *
  * @module @monomind/cli/mcp-tools/transfer-tools
- * @version 3.0.0
+ * @version 4.0.0
  */
 /**
  * Helper to create MCP tool result
@@ -19,32 +33,11 @@ function createResult(data, isError = false) {
         isError,
     };
 }
-/**
- * Cached PatternStore — initialize() may open IPFS connections, sql.js/WASM,
- * or download registry data. Re-creating on every handler call wastes work
- * and risks file-descriptor / socket-pool leaks on rapid invocations.
- */
-let cachedPatternStore = null;
-async function getPatternStore() {
-    if (cachedPatternStore)
-        return cachedPatternStore;
-    const { PatternStore } = await import('../transfer/store/index.js');
-    const store = new PatternStore();
-    await store.initialize();
-    cachedPatternStore = store;
-    return cachedPatternStore;
-}
-/**
- * Transfer MCP tools for pattern export, import, anonymization, and sharing
- */
 /** Ungated — internal/test use only. MCP clients get `transferTools` below. */
 export const allTransferTools = [
-    // ═══════════════════════════════════════════════════════════════
-    // ANONYMIZATION TOOLS
-    // ═══════════════════════════════════════════════════════════════
     {
         name: 'transfer_detect-pii',
-        description: 'Detect PII in content without redacting',
+        description: 'Scan content for personally identifiable information with regex patterns and report what was found, without redacting it. Runs locally; no network or registry involved.',
         category: 'transfer',
         version: '1.0.0',
         inputSchema: {
@@ -74,216 +67,10 @@ export const allTransferTools = [
             }
         },
     },
-    // ═══════════════════════════════════════════════════════════════
-    // IPFS TOOLS
-    // ═══════════════════════════════════════════════════════════════
-    {
-        name: 'transfer_ipfs-resolve',
-        description: 'Resolve IPNS name to CID',
-        category: 'transfer',
-        version: '1.0.0',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                name: {
-                    type: 'string',
-                    description: 'IPNS name to resolve',
-                },
-            },
-            required: ['name'],
-        },
-        handler: async (input) => {
-            try {
-                const { resolveIPNS } = await import('../transfer/ipfs/client.js');
-                // Cap IPNS name length — uncapped strings may trigger O(n) path parsing
-                // inside the IPFS client or be reflected in error messages.
-                const MAX_IPNS_NAME_LEN = 512;
-                const rawName = input.name;
-                const name = typeof rawName === 'string' && rawName.length > MAX_IPNS_NAME_LEN
-                    ? rawName.slice(0, MAX_IPNS_NAME_LEN) : rawName;
-                const result = await resolveIPNS(name);
-                return createResult({ success: true, cid: result });
-            }
-            catch (error) {
-                return createResult({ error: error.message }, true);
-            }
-        },
-    },
-    // ═══════════════════════════════════════════════════════════════
-    // PATTERN STORE TOOLS
-    // ═══════════════════════════════════════════════════════════════
-    {
-        name: 'transfer_store-search',
-        description: 'Search the pattern store',
-        category: 'transfer',
-        version: '1.0.0',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                query: {
-                    type: 'string',
-                    description: 'Search query',
-                },
-                category: {
-                    type: 'string',
-                    description: 'Filter by category',
-                },
-                minRating: {
-                    type: 'number',
-                    description: 'Minimum rating',
-                },
-                verified: {
-                    type: 'boolean',
-                    description: 'Only show verified patterns',
-                },
-                limit: {
-                    type: 'number',
-                    description: 'Maximum results',
-                },
-            },
-        },
-        handler: async (input) => {
-            try {
-                const store = await getPatternStore();
-                // Cap query and limit to prevent DoS via large string or result set.
-                const MAX_TRANSFER_QUERY_LEN = 4 * 1024;
-                const MAX_TRANSFER_LIMIT = 500;
-                const inp = input;
-                const cappedInput = {
-                    ...inp,
-                    query: typeof inp.query === 'string' && inp.query.length > MAX_TRANSFER_QUERY_LEN
-                        ? inp.query.slice(0, MAX_TRANSFER_QUERY_LEN) : inp.query,
-                    limit: typeof inp.limit === 'number' && Number.isFinite(inp.limit)
-                        ? Math.min(Math.floor(Math.max(inp.limit, 1)), MAX_TRANSFER_LIMIT) : inp.limit,
-                };
-                const results = store.search(cappedInput);
-                return createResult(results);
-            }
-            catch (error) {
-                return createResult({ error: error.message }, true);
-            }
-        },
-    },
-    {
-        name: 'transfer_store-info',
-        description: 'Get detailed info about a pattern',
-        category: 'transfer',
-        version: '1.0.0',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                id: {
-                    type: 'string',
-                    description: 'Pattern ID',
-                },
-            },
-            required: ['id'],
-        },
-        handler: async (input) => {
-            try {
-                const store = await getPatternStore();
-                const pattern = store.getPattern(input.id);
-                if (!pattern) {
-                    return createResult({ error: 'Pattern not found' }, true);
-                }
-                return createResult(pattern);
-            }
-            catch (error) {
-                return createResult({ error: error.message }, true);
-            }
-        },
-    },
-    {
-        name: 'transfer_store-download',
-        description: 'Download a pattern from the store',
-        category: 'transfer',
-        version: '1.0.0',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                id: {
-                    type: 'string',
-                    description: 'Pattern ID',
-                },
-                verify: {
-                    type: 'boolean',
-                    description: 'Verify pattern integrity',
-                },
-            },
-            required: ['id'],
-        },
-        handler: async (input) => {
-            try {
-                const store = await getPatternStore();
-                const result = await store.download(input.id, { verify: input.verify });
-                return createResult(result);
-            }
-            catch (error) {
-                return createResult({ error: error.message }, true);
-            }
-        },
-    },
-    {
-        name: 'transfer_store-featured',
-        description: 'Get featured patterns from the store',
-        category: 'transfer',
-        version: '1.0.0',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                limit: {
-                    type: 'number',
-                    description: 'Maximum results',
-                },
-            },
-        },
-        handler: async (input) => {
-            try {
-                const store = await getPatternStore();
-                const featured = store.getFeatured();
-                const limit = input.limit || 10;
-                return createResult(featured.slice(0, limit));
-            }
-            catch (error) {
-                return createResult({ error: error.message }, true);
-            }
-        },
-    },
-    {
-        name: 'transfer_store-trending',
-        description: 'Get trending patterns from the store',
-        category: 'transfer',
-        version: '1.0.0',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                limit: {
-                    type: 'number',
-                    description: 'Maximum results',
-                },
-            },
-        },
-        handler: async (input) => {
-            try {
-                const store = await getPatternStore();
-                const trending = store.getTrending();
-                const limit = input.limit || 10;
-                return createResult(trending.slice(0, limit));
-            }
-            catch (error) {
-                return createResult({ error: error.message }, true);
-            }
-        },
-    },
 ];
-// The IPFS pattern-registry tools (ipfs-resolve, store-*) have zero test
-// coverage and no evidence of production use — gated behind
-// MONOMIND_MCP_SPECULATIVE=1. transfer_detect-pii is an unrelated, real PII
-// scanner bundled in this file and stays visible by default.
-const SPECULATIVE = process.env['MONOMIND_MCP_SPECULATIVE'] === '1';
-const CORE_TRANSFER_NAMES = new Set(['transfer_detect-pii']);
-export const transferTools = SPECULATIVE
-    ? allTransferTools
-    : allTransferTools.filter(t => CORE_TRANSFER_NAMES.has(t.name));
+// Nothing here is gated any more — the speculative IPFS tools this flag used to
+// hide have been deleted outright. The export shape is kept so callers and the
+// category loader continue to work unchanged.
+export const transferTools = allTransferTools;
 export default transferTools;
 //# sourceMappingURL=transfer-tools.js.map

package/packages/@monomind/cli/dist/src/memory/ewc-consolidation.d.ts

@@ -1,21 +1,33 @@
 /**
- * EWC++ (Elastic Weight Consolidation) Implementation
- * Prevents catastrophic forgetting of important patterns during continual learning
+ * EWC-inspired pattern consolidation.
  *
- * Algorithm:
- * L_total = L_new + (lambda/2) * sum_i(F_i * (theta_i - theta_old_i)^2)
+ * Protects high-importance stored patterns from being overwritten by newer,
+ * similar ones — the pattern-store analogue of avoiding catastrophic
+ * forgetting.
  *
- * Where:
- * - L_new is the loss on new data
- * - lambda is the importance weight (ewcLambda)
- * - F_i is the Fisher information for parameter i
- * - theta_i is the current parameter value
- * - theta_old_i is the previous parameter value
+ * HONEST SCOPE — read before extending this:
+ * This is *not* Elastic Weight Consolidation. Real EWC penalises drift in a
+ * model's parameters using Fisher information estimated from training
+ * gradients:
  *
- * Features:
- * - Fisher Information Matrix computation from gradient history
- * - Online EWC updates for streaming patterns
- * - Selective consolidation based on pattern importance
+ *   L_total = L_new + (lambda/2) * sum_i(F_i * (theta_i - theta_old_i)^2)
+ *
+ * There is no model here, no training loop, and therefore no gradients. What
+ * this file actually computes is a per-dimension importance weight from the
+ * *squared embedding values* of stored patterns, used as a stand-in for the
+ * Fisher diagonal (see computeFisherMatrix — the substitution is noted at the
+ * line that performs it), smoothed with an EMA and applied as a quadratic
+ * penalty when a new pattern would displace an existing one.
+ *
+ * That heuristic is real, deterministic, and useful. The EWC name and the
+ * formula above describe the *inspiration*, not the implementation — do not
+ * cite this as an EWC implementation or reason about it as if `F_i` carried
+ * Fisher semantics.
+ *
+ * What it does:
+ * - Per-dimension importance from squared embedding magnitudes (gradient proxy)
+ * - Online EMA updates as new patterns stream in
+ * - Selective consolidation based on that importance
  * - Persistent storage in .swarm/ewc-fisher.json
  *
  * @module v1/cli/memory/ewc-consolidation