@mxf-dev/core 1.0.0

package/dist/types/MemoryStrataTypes.js

@@ -0,0 +1,34 @@
+/**
+ * Memory Strata Types for MXF
+ *
+ * Type definitions for multi-layered memory architecture with surprise detection.
+ * Feature flag: MEMORY_STRATA_ENABLED
+ */
+/**
+ * Memory layer/stratum level
+ */
+export var MemoryStratum;
+(function (MemoryStratum) {
+    /** Working memory (immediate context) */
+    MemoryStratum["Working"] = "working";
+    /** Short-term memory (recent history) */
+    MemoryStratum["ShortTerm"] = "short_term";
+    /** Long-term memory (persistent knowledge) */
+    MemoryStratum["LongTerm"] = "long_term";
+    /** Episodic memory (specific events) */
+    MemoryStratum["Episodic"] = "episodic";
+    /** Semantic memory (facts and concepts) */
+    MemoryStratum["Semantic"] = "semantic";
+})(MemoryStratum || (MemoryStratum = {}));
+/**
+ * Memory importance level
+ */
+export var MemoryImportance;
+(function (MemoryImportance) {
+    MemoryImportance[MemoryImportance["Critical"] = 5] = "Critical";
+    MemoryImportance[MemoryImportance["High"] = 4] = "High";
+    MemoryImportance[MemoryImportance["Medium"] = 3] = "Medium";
+    MemoryImportance[MemoryImportance["Low"] = 2] = "Low";
+    MemoryImportance[MemoryImportance["Trivial"] = 1] = "Trivial";
+})(MemoryImportance || (MemoryImportance = {}));
+//# sourceMappingURL=MemoryStrataTypes.js.map

package/dist/types/MemoryStrataTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MemoryStrataTypes.js","sourceRoot":"","sources":["../../src/types/MemoryStrataTypes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,CAAN,IAAY,aAWX;AAXD,WAAY,aAAa;IACvB,yCAAyC;IACzC,oCAAmB,CAAA;IACnB,yCAAyC;IACzC,yCAAwB,CAAA;IACxB,8CAA8C;IAC9C,uCAAsB,CAAA;IACtB,wCAAwC;IACxC,sCAAqB,CAAA;IACrB,2CAA2C;IAC3C,sCAAqB,CAAA;AACvB,CAAC,EAXW,aAAa,KAAb,aAAa,QAWxB;AAED;;GAEG;AACH,MAAM,CAAN,IAAY,gBAMX;AAND,WAAY,gBAAgB;IAC1B,+DAAY,CAAA;IACZ,uDAAQ,CAAA;IACR,2DAAU,CAAA;IACV,qDAAO,CAAA;IACP,6DAAW,CAAA;AACb,CAAC,EANW,gBAAgB,KAAhB,gBAAgB,QAM3B"}

package/dist/types/MemoryTypes.d.ts

@@ -0,0 +1,230 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/mxf-dev/mxf
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+/**
+ * Memory scope defines the visibility and access context of the memory
+ */
+export declare enum MemoryScope {
+    /**
+     * Agent-specific memory only accessible to that agent
+     */
+    AGENT = "agent",
+    /**
+     * Channel-wide memory shared by all agents in the channel
+     */
+    CHANNEL = "channel",
+    /**
+     * Relationship memory specific to agent-agent interactions
+     */
+    RELATIONSHIP = "relationship"
+}
+/**
+ * Memory persistence level defines how long memory is stored
+ */
+export declare enum MemoryPersistenceLevel {
+    /**
+     * Temporary memory that does not survive restarts
+     */
+    TEMPORARY = "temporary",
+    /**
+     * Persistent memory stored in database that survives restarts
+     */
+    PERSISTENT = "persistent"
+}
+/**
+ * Base memory entry interface with common properties across all memory types
+ */
+export interface IMemoryEntry {
+    /**
+     * Unique identifier for the memory entry
+     */
+    id: string;
+    /**
+     * When the memory was created
+     */
+    createdAt: Date;
+    /**
+     * When the memory was last updated
+     */
+    updatedAt: Date;
+    /**
+     * Memory persistence level (temporary or persistent)
+     */
+    persistenceLevel: MemoryPersistenceLevel;
+}
+/**
+ * Agent memory interface
+ */
+export interface IAgentMemory extends IMemoryEntry {
+    /**
+     * Agent ID that owns this memory
+     */
+    agentId: string;
+    /**
+     * Persistent notes stored by the agent
+     */
+    notes?: Record<string, any>;
+    /**
+     * History of conversations
+     */
+    conversationHistory?: any[];
+    /**
+     * Any custom persistent data
+     */
+    customData?: Record<string, any>;
+}
+/**
+ * Channel memory interface
+ */
+export interface IChannelMemory extends IMemoryEntry {
+    /**
+     * Channel ID that owns this memory
+     */
+    channelId: string;
+    /**
+     * Shared persistent notes
+     */
+    notes?: Record<string, any>;
+    /**
+     * Shared state between agents
+     */
+    sharedState?: Record<string, any>;
+    /**
+     * Channel conversation records
+     */
+    conversationHistory?: any[];
+    /**
+     * Any custom shared data
+     */
+    customData?: Record<string, any>;
+}
+/**
+ * Relationship memory interface for agent-to-agent memories
+ */
+export interface IRelationshipMemory extends IMemoryEntry {
+    /**
+     * First agent in the relationship
+     */
+    agentId1: string;
+    /**
+     * Second agent in the relationship
+     */
+    agentId2: string;
+    /**
+     * Optional channel context
+     */
+    channelId?: string;
+    /**
+     * Interaction history between agents
+     */
+    interactionHistory?: any[];
+    /**
+     * Relationship-specific notes
+     */
+    notes?: Record<string, any>;
+    /**
+     * Any custom relationship data
+     */
+    customData?: Record<string, any>;
+}
+/**
+ * Union type of all memory interfaces
+ */
+export type MemoryData = IAgentMemory | IChannelMemory | IRelationshipMemory;
+/**
+ * Memory access permissions
+ */
+export declare enum MemoryAccessPermission {
+    READ = "read",
+    WRITE = "write",
+    DELETE = "delete"
+}
+/**
+ * Memory query parameters
+ */
+export interface MemoryQueryParams {
+    /**
+     * Memory scope to query (agent, channel, relationship)
+     */
+    scope: MemoryScope;
+    /**
+     * ID to look up (agentId, channelId, or [agentId1, agentId2] for relationships)
+     */
+    id: string | string[];
+    /**
+     * Optional filters to apply to the query
+     */
+    filters?: Record<string, any>;
+}
+/**
+ * Memory update structure
+ */
+export interface MemoryUpdate<T extends MemoryData> {
+    /**
+     * Fields to update
+     */
+    updates: Partial<T>;
+}
+/**
+ * Create a memory validator for runtime type checking
+ * @param context The context string for error messages
+ * @returns A validator object with memory-specific validation methods
+ */
+export declare const createMemoryValidator: (context: string) => {
+    /**
+     * Validates a memory scope value
+     * @param scope The memory scope to validate
+     */
+    validateMemoryScope: (scope: any) => scope is MemoryScope;
+    /**
+     * Validates a persistence level value
+     * @param level The persistence level to validate
+     */
+    validatePersistenceLevel: (level: any) => level is MemoryPersistenceLevel;
+    /**
+     * Validates a memory query parameters object
+     * @param params The query parameters to validate
+     */
+    validateQueryParams: (params: any) => params is MemoryQueryParams;
+    assertIsString: (value: unknown, customMessage?: string) => value is string;
+    assertIsNumber: (value: unknown, customMessage?: string) => value is number;
+    assertIsBoolean: (value: unknown) => value is boolean;
+    assertIsBigInt: (value: unknown) => value is bigint;
+    assertIsSymbol: (value: unknown) => value is symbol;
+    assertIsFunction: (value: unknown) => value is Function;
+    assertIsObject: (value: unknown, customMessage?: string) => value is object;
+    assertIsNull: (value: unknown) => value is null;
+    assertIsUndefined: (value: unknown) => value is undefined;
+    assertIsArray: (value: unknown, customMessage?: string) => value is Array<unknown>;
+    assertIsNonEmptyString: (value: unknown, customMessage?: string) => value is string;
+    assertIsUuid: (value: unknown) => value is string;
+    assertIsIsoDateString: (value: unknown) => value is string;
+    assertHasProperty: <T extends object>(obj: T, prop: string, customMessage?: string) => obj is T & Record<string, unknown>;
+    assertIsValidMessageId: (value: unknown) => value is string;
+    assertHasFunction: (obj: unknown, propertyName: string) => boolean;
+    assertIsEventPayload: (obj: unknown) => obj is Record<string, unknown>;
+    assertIsControlLoopPayload: (obj: unknown) => obj is Record<string, unknown>;
+    assertIsChannelMessage: (obj: unknown, paramName?: string) => void;
+    assertIsAgentMessage: (obj: unknown, paramName?: string) => void;
+    assert: (condition: boolean, customMessage?: string) => boolean;
+    assertEqual: <T>(actual: T, expected: T, customMessage?: string) => boolean;
+    assertIsGreaterThanOrEqual: (value: number, min: number, customMessage?: string) => boolean;
+    assertIsInRange: (value: number, min: number, max: number, customMessage?: string) => boolean;
+};
+//# sourceMappingURL=MemoryTypes.d.ts.map

package/dist/types/MemoryTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MemoryTypes.d.ts","sourceRoot":"","sources":["../../src/types/MemoryTypes.ts"],"names":[],"mappings":"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"}

package/dist/types/MemoryTypes.js

@@ -0,0 +1,118 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/mxf-dev/mxf
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+/**
+ * Memory System Types and Interfaces
+ *
+ * This file contains all the type definitions for the Memory System.
+ * It defines different memory scopes, persistence levels, and standard interfaces
+ * used across the MXF framework for memory operations.
+ */
+import { createStrictValidator } from '../utils/validation.js';
+/**
+ * Memory scope defines the visibility and access context of the memory
+ */
+export var MemoryScope;
+(function (MemoryScope) {
+    /**
+     * Agent-specific memory only accessible to that agent
+     */
+    MemoryScope["AGENT"] = "agent";
+    /**
+     * Channel-wide memory shared by all agents in the channel
+     */
+    MemoryScope["CHANNEL"] = "channel";
+    /**
+     * Relationship memory specific to agent-agent interactions
+     */
+    MemoryScope["RELATIONSHIP"] = "relationship";
+})(MemoryScope || (MemoryScope = {}));
+/**
+ * Memory persistence level defines how long memory is stored
+ */
+export var MemoryPersistenceLevel;
+(function (MemoryPersistenceLevel) {
+    /**
+     * Temporary memory that does not survive restarts
+     */
+    MemoryPersistenceLevel["TEMPORARY"] = "temporary";
+    /**
+     * Persistent memory stored in database that survives restarts
+     */
+    MemoryPersistenceLevel["PERSISTENT"] = "persistent";
+})(MemoryPersistenceLevel || (MemoryPersistenceLevel = {}));
+/**
+ * Memory access permissions
+ */
+export var MemoryAccessPermission;
+(function (MemoryAccessPermission) {
+    MemoryAccessPermission["READ"] = "read";
+    MemoryAccessPermission["WRITE"] = "write";
+    MemoryAccessPermission["DELETE"] = "delete";
+})(MemoryAccessPermission || (MemoryAccessPermission = {}));
+/**
+ * Create a memory validator for runtime type checking
+ * @param context The context string for error messages
+ * @returns A validator object with memory-specific validation methods
+ */
+export const createMemoryValidator = (context) => {
+    const validator = createStrictValidator(context);
+    return {
+        ...validator,
+        /**
+         * Validates a memory scope value
+         * @param scope The memory scope to validate
+         */
+        validateMemoryScope: (scope) => {
+            if (!Object.values(MemoryScope).includes(scope)) {
+                validator.assertIsString(scope, `Invalid memory scope: ${scope}`);
+                return false;
+            }
+            return true;
+        },
+        /**
+         * Validates a persistence level value
+         * @param level The persistence level to validate
+         */
+        validatePersistenceLevel: (level) => {
+            if (!Object.values(MemoryPersistenceLevel).includes(level)) {
+                validator.assertIsString(level, `Invalid persistence level: ${level}`);
+                return false;
+            }
+            return true;
+        },
+        /**
+         * Validates a memory query parameters object
+         * @param params The query parameters to validate
+         */
+        validateQueryParams: (params) => {
+            validator.assertIsObject(params, 'Query parameters must be an object');
+            if (!params.scope) {
+                validator.assertIsString(params.scope, 'Memory scope is required');
+                return false;
+            }
+            if (!params.id) {
+                validator.assertIsString(params.id, 'ID parameter is required');
+                return false;
+            }
+            return true;
+        }
+    };
+};
+//# sourceMappingURL=MemoryTypes.js.map

package/dist/types/MemoryTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MemoryTypes.js","sourceRoot":"","sources":["../../src/types/MemoryTypes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;GAMG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAE/D;;GAEG;AACH,MAAM,CAAN,IAAY,WAeX;AAfD,WAAY,WAAW;IACnB;;OAEG;IACH,8BAAe,CAAA;IAEf;;OAEG;IACH,kCAAmB,CAAA;IAEnB;;OAEG;IACH,4CAA6B,CAAA;AACjC,CAAC,EAfW,WAAW,KAAX,WAAW,QAetB;AAED;;GAEG;AACH,MAAM,CAAN,IAAY,sBAUX;AAVD,WAAY,sBAAsB;IAC9B;;OAEG;IACH,iDAAuB,CAAA;IAEvB;;OAEG;IACH,mDAAyB,CAAA;AAC7B,CAAC,EAVW,sBAAsB,KAAtB,sBAAsB,QAUjC;AA0HD;;GAEG;AACH,MAAM,CAAN,IAAY,sBAIX;AAJD,WAAY,sBAAsB;IAC9B,uCAAa,CAAA;IACb,yCAAe,CAAA;IACf,2CAAiB,CAAA;AACrB,CAAC,EAJW,sBAAsB,KAAtB,sBAAsB,QAIjC;AAgCD;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,OAAe,EAAE,EAAE;IACrD,MAAM,SAAS,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAEjD,OAAO;QACH,GAAG,SAAS;QAEZ;;;WAGG;QACH,mBAAmB,EAAE,CAAC,KAAU,EAAwB,EAAE;YACtD,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC9C,SAAS,CAAC,cAAc,CAAC,KAAK,EAAE,yBAAyB,KAAK,EAAE,CAAC,CAAC;gBAClE,OAAO,KAAK,CAAC;YACjB,CAAC;YACD,OAAO,IAAI,CAAC;QAChB,CAAC;QAED;;;WAGG;QACH,wBAAwB,EAAE,CAAC,KAAU,EAAmC,EAAE;YACtE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,sBAAsB,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;gBACzD,SAAS,CAAC,cAAc,CAAC,KAAK,EAAE,8BAA8B,KAAK,EAAE,CAAC,CAAC;gBACvE,OAAO,KAAK,CAAC;YACjB,CAAC;YACD,OAAO,IAAI,CAAC;QAChB,CAAC;QAED;;;WAGG;QACH,mBAAmB,EAAE,CAAC,MAAW,EAA+B,EAAE;YAC9D,SAAS,CAAC,cAAc,CAAC,MAAM,EAAE,oCAAoC,CAAC,CAAC;YAEvE,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;gBAChB,SAAS,CAAC,cAAc,CAAC,MAAM,CAAC,KAAK,EAAE,0BAA0B,CAAC,CAAC;gBACnE,OAAO,KAAK,CAAC;YACjB,CAAC;YAED,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;gBACb,SAAS,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,EAAE,0BAA0B,CAAC,CAAC;gBAChE,OAAO,KAAK,CAAC;YACjB,CAAC;YAED,OAAO,IAAI,CAAC;QAChB,CAAC;KACJ,CAAC;AACN,CAAC,CAAC"}