@mxf-dev/core 1.0.0 → 2.0.0

package/src/config/knowledge-graph.config.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 

package/src/config/memory-strata.config.ts

@@ -0,0 +1,136 @@
+/**
+ * Memory strata configuration (Nested Learning).
+ *
+ * The strata services — StratumManager, SurpriseCalculator, MemoryCompressor,
+ * RetentionGateService — take their configuration as a constructor argument, and until
+ * now the only place that argument was ever built was inside test files. There was no
+ * production configuration path and no boot-time initialization, so StratumManager stayed
+ * disabled no matter what MEMORY_STRATA_ENABLED was set to, and the whole layer — which
+ * PhaseMemoryOperations and PhaseStrataRouter sit on top of — was inert.
+ *
+ * This module is the missing production path. It reads the same env flag the rest of the
+ * framework already exposes and produces a config the server initializes the strata
+ * services with at boot.
+ */
+
+import { MemoryStrataConfig, MemoryImportance } from '../types/MemoryStrataTypes.js';
+import { isMemoryStrataEnabled } from './FeatureFlags.js';
+
+export { isMemoryStrataEnabled };
+
+const MINUTE = 60 * 1000;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+
+const parseIntEnv = (value: string | undefined, fallback: number): number => {
+    if (value === undefined || value.trim() === '') {
+        return fallback;
+    }
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed)) {
+        throw new Error(
+            `Invalid integer for memory strata configuration: "${value}". ` +
+            `Remove the variable to use the default (${fallback}), or set a whole number.`
+        );
+    }
+    return parsed;
+};
+
+const parseFloatEnv = (value: string | undefined, fallback: number): number => {
+    if (value === undefined || value.trim() === '') {
+        return fallback;
+    }
+    const parsed = Number.parseFloat(value);
+    if (!Number.isFinite(parsed)) {
+        throw new Error(
+            `Invalid number for memory strata configuration: "${value}". ` +
+            `Remove the variable to use the default (${fallback}), or set a number.`
+        );
+    }
+    return parsed;
+};
+
+/**
+ * Resolve the minimum long-term importance, which is a numeric enum, not a string.
+ */
+const parseImportanceEnv = (value: string | undefined): MemoryImportance => {
+    if (value === undefined || value.trim() === '') {
+        return MemoryImportance.Medium;
+    }
+    const byName = (MemoryImportance as unknown as Record<string, number>)[value.trim()];
+    if (typeof byName === 'number') {
+        return byName as MemoryImportance;
+    }
+    throw new Error(
+        `Invalid MEMORY_STRATA_LONG_TERM_MIN_IMPORTANCE: "${value}". ` +
+        `Expected one of: Critical, High, Medium, Low, Trivial.`
+    );
+};
+
+/**
+ * Build the strata configuration from the environment.
+ *
+ * Invalid numeric values throw rather than silently falling back, so a typo in a tuning
+ * variable surfaces at boot instead of quietly changing how memory is retained.
+ */
+export function getMemoryStrataConfig(): MemoryStrataConfig {
+    return {
+        enabled: isMemoryStrataEnabled(),
+
+        working: {
+            maxEntries: parseIntEnv(process.env.MEMORY_STRATA_WORKING_MAX_ENTRIES, 50),
+            ttl: parseIntEnv(process.env.MEMORY_STRATA_WORKING_TTL_MS, 30 * MINUTE)
+        },
+
+        shortTerm: {
+            maxEntries: parseIntEnv(process.env.MEMORY_STRATA_SHORT_TERM_MAX_ENTRIES, 500),
+            ttl: parseIntEnv(process.env.MEMORY_STRATA_SHORT_TERM_TTL_MS, 7 * DAY),
+            consolidationThreshold: parseIntEnv(
+                process.env.MEMORY_STRATA_SHORT_TERM_CONSOLIDATION_THRESHOLD,
+                3
+            )
+        },
+
+        longTerm: {
+            maxEntriesPerAgent: parseIntEnv(process.env.MEMORY_STRATA_LONG_TERM_MAX_ENTRIES, 5000),
+            minImportance: parseImportanceEnv(process.env.MEMORY_STRATA_LONG_TERM_MIN_IMPORTANCE),
+            enableArchival: process.env.MEMORY_STRATA_LONG_TERM_ARCHIVAL !== 'false',
+            archivalAge: parseIntEnv(process.env.MEMORY_STRATA_LONG_TERM_ARCHIVAL_AGE_MS, 90 * DAY)
+        },
+
+        episodic: {
+            maxEpisodesPerAgent: parseIntEnv(process.env.MEMORY_STRATA_EPISODIC_MAX_EPISODES, 200),
+            episodeDuration: parseIntEnv(process.env.MEMORY_STRATA_EPISODIC_DURATION_MS, HOUR)
+        },
+
+        semantic: {
+            maxConceptsPerAgent: parseIntEnv(process.env.MEMORY_STRATA_SEMANTIC_MAX_CONCEPTS, 1000),
+            minConfidence: parseFloatEnv(process.env.MEMORY_STRATA_SEMANTIC_MIN_CONFIDENCE, 0.6)
+        },
+
+        surprise: {
+            enabled: process.env.MEMORY_STRATA_SURPRISE_ENABLED !== 'false',
+            threshold: parseFloatEnv(process.env.MEMORY_STRATA_SURPRISE_THRESHOLD, 0.5),
+            analysisWindow: parseIntEnv(process.env.MEMORY_STRATA_SURPRISE_WINDOW, 20)
+        },
+
+        consolidation: {
+            enabled: process.env.MEMORY_STRATA_CONSOLIDATION_ENABLED !== 'false',
+            interval: parseIntEnv(process.env.MEMORY_STRATA_CONSOLIDATION_INTERVAL_MS, HOUR),
+            similarityThreshold: parseFloatEnv(
+                process.env.MEMORY_STRATA_CONSOLIDATION_SIMILARITY,
+                0.85
+            )
+        },
+
+        patterns: {
+            enabled: process.env.MEMORY_STRATA_PATTERNS_ENABLED !== 'false',
+            minLength: parseIntEnv(process.env.MEMORY_STRATA_PATTERN_MIN_LENGTH, 3),
+            minConfidence: parseFloatEnv(process.env.MEMORY_STRATA_PATTERN_MIN_CONFIDENCE, 0.7),
+            analysisInterval: parseIntEnv(
+                process.env.MEMORY_STRATA_PATTERN_ANALYSIS_INTERVAL_MS,
+                30 * MINUTE
+            )
+        }
+    };
+}

package/src/config/orpar-memory.config.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 

package/src/config/tensorflow.config.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 

package/src/constants/CoreTools.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 

package/src/constants/DefaultPhaseProfiles.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 

package/src/constants/ToolNames.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 
@@ -53,19 +53,10 @@ export const COORDINATION_TOOLS = {
     LIST: 'coordination_list'
 } as const;
 
-/**
- * Control Loop Tools - ORPAR cognitive cycle management
- */
-export const CONTROL_LOOP_TOOLS = {
-    START: 'controlLoop_start',
-    STOP: 'controlLoop_stop',
-    STATUS: 'controlLoop_status',
-    OBSERVE: 'controlLoop_observe',
-    REASON: 'controlLoop_reason',
-    PLAN: 'controlLoop_plan',
-    EXECUTE: 'controlLoop_execute',
-    REFLECT: 'controlLoop_reflect'
-} as const;
+// The controlLoop_* tool family was removed. It was a second, parallel implementation of
+// the ORPAR cognitive cycle with its own state machine and result shape, and agents could
+// see both families at once. orpar_* is the maintained one; controlLoop_status also
+// returned fabricated metrics. See protocols/mcp/tools/OrparTools.ts.
 
 /**
  * Infrastructure Tools - System interaction and data management
@@ -325,7 +316,6 @@ export const ALL_INTERNAL_TOOLS = {
     ...WOLFRAM_TOOLS,
     ...COMMUNICATION_TOOLS,
     ...COORDINATION_TOOLS,
-    ...CONTROL_LOOP_TOOLS,
     ...INFRASTRUCTURE_TOOLS,
     ...CONTEXT_MEMORY_TOOLS,
     ...META_TOOLS,
@@ -409,7 +399,6 @@ export const TOOL_CATEGORIES = {
  */
 export type CommunicationToolName = typeof COMMUNICATION_TOOLS[keyof typeof COMMUNICATION_TOOLS];
 export type CoordinationToolName = typeof COORDINATION_TOOLS[keyof typeof COORDINATION_TOOLS];
-export type ControlLoopToolName = typeof CONTROL_LOOP_TOOLS[keyof typeof CONTROL_LOOP_TOOLS];
 export type InfrastructureToolName = typeof INFRASTRUCTURE_TOOLS[keyof typeof INFRASTRUCTURE_TOOLS];
 export type ContextMemoryToolName = typeof CONTEXT_MEMORY_TOOLS[keyof typeof CONTEXT_MEMORY_TOOLS];
 export type MetaToolName = typeof META_TOOLS[keyof typeof META_TOOLS];
@@ -461,9 +450,6 @@ export const getToolCategory = (toolName: string): ToolCategory | null => {
     if (Object.values(COORDINATION_TOOLS).includes(toolName as CoordinationToolName)) {
         return TOOL_CATEGORIES.COORDINATION;
     }
-    if (Object.values(CONTROL_LOOP_TOOLS).includes(toolName as ControlLoopToolName)) {
-        return TOOL_CATEGORIES.CONTROL_LOOP;
-    }
     if (Object.values(INFRASTRUCTURE_TOOLS).includes(toolName as InfrastructureToolName)) {
         return TOOL_CATEGORIES.INFRASTRUCTURE;
     }

package/src/database/DatabaseAdapterFactory.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 
@@ -73,6 +73,14 @@ export class DatabaseAdapterFactory {
     private static config: DatabaseConfig | null = null;
     private static connected: boolean = false;
 
+    /**
+     * True only when connect() opened the connection itself, as opposed to
+     * reusing one the host application (e.g. the server) had already opened.
+     * disconnect() closes the connection only in the first case — otherwise the
+     * factory would close the server's connection out from under it.
+     */
+    private static ownsConnection: boolean = false;
+
     /**
      * Initialize the factory with database configuration.
      * Must be called before create().
@@ -81,6 +89,7 @@ export class DatabaseAdapterFactory {
         this.config = config;
         this.instance = null; // Reset instance on re-initialization
         this.connected = false;
+        this.ownsConnection = false;
     }
 
     /**
@@ -115,7 +124,8 @@ export class DatabaseAdapterFactory {
     private static async connectMongo(): Promise<void> {
         // Check if mongoose is already connected (e.g., server has established connection)
         if (mongoose.connection.readyState === 1) {
-            // Already connected, reuse existing connection
+            // Reuse the existing connection. We did not open it, so we must not close it.
+            this.ownsConnection = false;
             return;
         }
 
@@ -127,6 +137,7 @@ export class DatabaseAdapterFactory {
         };
 
         await mongoose.connect(this.config!.connectionString, options);
+        this.ownsConnection = true;
     }
 
     /**
@@ -180,22 +191,28 @@ export class DatabaseAdapterFactory {
         this.instance = null;
         this.config = null;
         this.connected = false;
+        this.ownsConnection = false;
     }
 
     /**
      * Disconnect from the database.
-     * Note: Only disconnects if the factory established the connection.
-     * If mongoose was already connected (e.g., by server), this is a no-op.
+     *
+     * Closes the connection only when connect() opened it. If mongoose was
+     * already connected when connect() ran — the usual case inside the server —
+     * the connection belongs to the host and is left alone.
+     *
+     * Previously `connected` was set true in both cases, so calling disconnect()
+     * closed the server's own mongoose connection.
      */
     static async disconnect(): Promise<void> {
-        if (this.connected && this.config?.type === 'mongodb') {
-            // Only disconnect if we established the connection
-            // Check if mongoose connection was established by us
+        if (this.connected && this.ownsConnection && this.config?.type === 'mongodb') {
             if (mongoose.connection.readyState === 1) {
                 await mongoose.connection.close();
             }
         }
+
         this.connected = false;
+        this.ownsConnection = false;
     }
 
     /**

package/src/database/adapters/mongodb/MongoAgentRepository.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 

package/src/database/adapters/mongodb/MongoBaseRepository.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 
@@ -184,7 +184,13 @@ export abstract class MongoBaseRepository<T, D extends Document, CreateDTO = Par
     }
 
     /**
-     * Map comparison operator to MongoDB operator
+     * Map comparison operator to MongoDB operator.
+     *
+     * An unknown operator throws. Defaulting to '$eq' turned, say, a mistyped
+     * 'gte' into an equality match: the query ran, returned the wrong rows, and
+     * nothing anywhere said so.
+     *
+     * @throws If the operator is not one this repository supports
      */
     private mapComparisonOperator(op: ComparisonOperator): string {
         const mapping: Record<string, string> = {
@@ -198,6 +204,14 @@ export abstract class MongoBaseRepository<T, D extends Document, CreateDTO = Par
             'nin': '$nin',
             'regex': '$regex'
         };
-        return mapping[op] || '$eq';
+
+        const mongoOperator = mapping[op];
+        if (!mongoOperator) {
+            throw new Error(
+                `Unsupported comparison operator '${op}'. Supported operators: ${Object.keys(mapping).join(', ')}`
+            );
+        }
+
+        return mongoOperator;
     }
 }

package/src/database/adapters/mongodb/MongoChannelRepository.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 

package/src/database/adapters/mongodb/MongoDagRepository.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 

package/src/database/adapters/mongodb/MongoKnowledgeGraphRepository.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 

package/src/database/adapters/mongodb/MongoMemoryRepository.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 

package/src/database/adapters/mongodb/MongoTaskRepository.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 

package/src/database/adapters/mongodb/index.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 

package/src/database/index.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */