@mxf-dev/core 1.0.0

package/dist/events/event-definitions/MemoryEvents.d.ts

@@ -0,0 +1,328 @@
+/**
+ * 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 Events
+ *
+ * This file defines all memory-related events used in the MXF Memory System.
+ * These events integrate with the main event system and follow the same patterns.
+ */
+import { MemoryScope } from '../../types/MemoryTypes.js';
+export { MemoryScope };
+/**
+ * Events for memory operations
+ */
+export declare const MemoryEvents: {
+    GET: string;
+    GET_RESULT: string;
+    GET_ERROR: string;
+    UPDATE: string;
+    UPDATE_RESULT: string;
+    UPDATE_ERROR: string;
+    CREATE: string;
+    CREATE_RESULT: string;
+    CREATE_ERROR: string;
+    DELETE: string;
+    DELETE_RESULT: string;
+    DELETE_ERROR: string;
+    CLEAR: string;
+    CLEAR_RESULT: string;
+    CLEAR_ERROR: string;
+    CLEAR_ALL: string;
+    CLEAR_ALL_RESULT: string;
+    CLEAR_ALL_ERROR: string;
+    RECALL: string;
+    STORE: string;
+    FORGET: string;
+    SYNC: string;
+    SYNC_COMPLETE: string;
+    SYNC_ERROR: string;
+    EXPIRE: string;
+    EXPIRE_COMPLETE: string;
+    EXPIRE_ERROR: string;
+};
+/**
+ * Base memory event interface
+ */
+export interface MemoryEventBase {
+    /**
+     * Unique identifier for this memory operation
+     */
+    operationId: string;
+    /**
+     * Timestamp of the event
+     */
+    timestamp: number;
+    /**
+     * Scope of the memory (agent, channel, relationship)
+     */
+    scope: MemoryScope;
+}
+/**
+ * Memory query event payload
+ */
+export interface MemoryGetEvent extends MemoryEventBase {
+    /**
+     * ID to get (agentId, channelId, or [agentId1, agentId2] for relationships)
+     */
+    id: string | string[];
+    /**
+     * Optional key to retrieve specific data
+     */
+    key?: string;
+    /**
+     * Optional filters
+     */
+    filters?: Record<string, any>;
+}
+/**
+ * Memory get result event payload
+ */
+export interface MemoryGetResultEvent extends MemoryEventBase {
+    /**
+     * ID that was queried
+     */
+    id: string | string[];
+    /**
+     * Result data
+     */
+    data: any;
+}
+/**
+ * Memory update event payload
+ */
+export interface MemoryUpdateEvent extends MemoryEventBase {
+    /**
+     * ID to update (agentId, channelId, or [agentId1, agentId2] for relationships)
+     */
+    id: string | string[];
+    /**
+     * Data to update
+     */
+    data: Record<string, any>;
+    /**
+     * Optional metadata
+     */
+    metadata?: Record<string, any>;
+}
+/**
+ * Memory update result event payload
+ */
+export interface MemoryUpdateResultEvent extends MemoryEventBase {
+    /**
+     * ID that was updated
+     */
+    id: string | string[];
+    /**
+     * Updated data
+     */
+    data: any;
+    /**
+     * Success status
+     */
+    success: boolean;
+}
+/**
+ * Memory create event payload
+ */
+export interface MemoryCreateEvent extends MemoryEventBase {
+    /**
+     * ID to create (agentId, channelId, or [agentId1, agentId2] for relationships)
+     */
+    id: string | string[];
+    /**
+     * Data to store
+     */
+    data: Record<string, any>;
+    /**
+     * Optional metadata
+     */
+    metadata?: Record<string, any>;
+}
+/**
+ * Memory create result event payload
+ */
+export interface MemoryCreateResultEvent extends MemoryEventBase {
+    /**
+     * ID that was created
+     */
+    id: string | string[];
+    /**
+     * Created data
+     */
+    data: any;
+    /**
+     * Success status
+     */
+    success: boolean;
+}
+/**
+ * Memory delete event payload
+ */
+export interface MemoryDeleteEvent extends MemoryEventBase {
+    /**
+     * ID to delete (agentId, channelId, or [agentId1, agentId2] for relationships)
+     */
+    id: string | string[];
+    /**
+     * Optional key to delete specific data
+     */
+    key?: string;
+}
+/**
+ * Memory delete result event payload
+ */
+export interface MemoryDeleteResultEvent extends MemoryEventBase {
+    /**
+     * ID that was deleted
+     */
+    id: string | string[];
+    /**
+     * Success status
+     */
+    success: boolean;
+}
+/**
+ * Memory error event payload
+ */
+export interface MemoryErrorEvent extends MemoryEventBase {
+    /**
+     * ID associated with the error
+     */
+    id: string | string[];
+    /**
+     * Error message
+     */
+    error: string;
+    /**
+     * Error code
+     */
+    code?: string;
+    /**
+     * Optional details
+     */
+    details?: Record<string, any>;
+}
+/**
+ * Memory clear event payload
+ */
+export interface MemoryClearEvent extends MemoryEventBase {
+    /**
+     * Scope to clear
+     */
+    scope: MemoryScope;
+}
+/**
+ * Memory clear result event payload
+ */
+export interface MemoryClearResultEvent extends MemoryEventBase {
+    /**
+     * Number of items cleared
+     */
+    clearedCount: number;
+    /**
+     * Success status
+     */
+    success: boolean;
+}
+/**
+ * Memory clear all event payload
+ */
+export interface MemoryClearAllEvent extends Omit<MemoryEventBase, 'scope'> {
+    /**
+     * Optional scope to clear all
+     * For a clear all operation, the scope can be specified to clear all memory of a specific type,
+     * or it can be undefined to clear all memory across all scopes
+     */
+    scope?: MemoryScope;
+}
+/**
+ * Memory clear all result event payload
+ */
+export interface MemoryClearAllResultEvent extends MemoryEventBase {
+    /**
+     * Number of items cleared
+     */
+    clearedCount: number;
+    /**
+     * Success status
+     */
+    success: boolean;
+}
+/**
+ * Memory sync event payload
+ */
+export interface MemorySyncEvent extends MemoryEventBase {
+    /**
+     * IDs to sync (agentId, channelId, or [agentId1, agentId2] for relationships)
+     */
+    ids: Array<string | string[]>;
+}
+/**
+ * Memory sync result event payload
+ */
+export interface MemorySyncResultEvent extends MemoryEventBase {
+    /**
+     * Number of items synced
+     */
+    syncedCount: number;
+    /**
+     * Success status
+     */
+    success: boolean;
+}
+/**
+ * All memory event payload types
+ */
+export interface MemoryPayloads {
+    'memory:get': MemoryGetEvent;
+    'memory:get:result': MemoryGetResultEvent;
+    'memory:get:error': MemoryErrorEvent;
+    'memory:update': MemoryUpdateEvent;
+    'memory:update:result': MemoryUpdateResultEvent;
+    'memory:update:error': MemoryErrorEvent;
+    'memory:create': MemoryCreateEvent;
+    'memory:create:result': MemoryCreateResultEvent;
+    'memory:create:error': MemoryErrorEvent;
+    'memory:delete': MemoryDeleteEvent;
+    'memory:delete:result': MemoryDeleteResultEvent;
+    'memory:delete:error': MemoryErrorEvent;
+    'memory:recall': MemoryGetEvent;
+    'memory:store': MemoryUpdateEvent;
+    'memory:forget': MemoryDeleteEvent;
+    'memory:sync': MemorySyncEvent;
+    'memory:sync:complete': MemorySyncResultEvent;
+    'memory:sync:error': MemoryErrorEvent;
+    'memory:clear': MemoryClearEvent;
+    'memory:clear:result': MemoryClearResultEvent;
+    'memory:clear:error': MemoryErrorEvent;
+    'memory:clear:all': MemoryClearAllEvent;
+    'memory:clear:all:result': MemoryClearAllResultEvent;
+    'memory:clear:all:error': MemoryErrorEvent;
+    'memory:expire': {
+        scope: MemoryScope;
+        olderThan?: number;
+    };
+    'memory:expire:complete': {
+        scope: MemoryScope;
+        expiredCount: number;
+    };
+    'memory:expire:error': MemoryErrorEvent;
+}
+//# sourceMappingURL=MemoryEvents.d.ts.map

package/dist/events/event-definitions/MemoryEvents.d.ts.map

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

package/dist/events/event-definitions/MemoryEvents.js

@@ -0,0 +1,69 @@
+/**
+ * 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 Events
+ *
+ * This file defines all memory-related events used in the MXF Memory System.
+ * These events integrate with the main event system and follow the same patterns.
+ */
+import { MemoryScope } from '../../types/MemoryTypes.js';
+export { MemoryScope };
+/**
+ * Events for memory operations
+ */
+export const MemoryEvents = {
+    // Query events
+    GET: 'memory:get', // Get memory
+    GET_RESULT: 'memory:get:result', // Get memory result
+    GET_ERROR: 'memory:get:error', // Get memory error
+    // Update events
+    UPDATE: 'memory:update', // Update memory
+    UPDATE_RESULT: 'memory:update:result', // Update memory result
+    UPDATE_ERROR: 'memory:update:error', // Update memory error
+    // Create events
+    CREATE: 'memory:create', // Create memory
+    CREATE_RESULT: 'memory:create:result', // Create memory result
+    CREATE_ERROR: 'memory:create:error', // Create memory error
+    // Delete events
+    DELETE: 'memory:delete', // Delete memory
+    DELETE_RESULT: 'memory:delete:result', // Delete memory result
+    DELETE_ERROR: 'memory:delete:error', // Delete memory error
+    // Clear events
+    CLEAR: 'memory:clear', // Clear memory of specific scope
+    CLEAR_RESULT: 'memory:clear:result', // Clear memory result
+    CLEAR_ERROR: 'memory:clear:error', // Clear memory error
+    // Clear all events
+    CLEAR_ALL: 'memory:clear:all', // Clear all memory
+    CLEAR_ALL_RESULT: 'memory:clear:all:result', // Clear all memory result
+    CLEAR_ALL_ERROR: 'memory:clear:all:error', // Clear all memory error
+    // Memory lifecycle events
+    RECALL: 'memory:recall', // Memory recall
+    STORE: 'memory:store', // Memory store
+    FORGET: 'memory:forget', // Memory forget
+    // Memory sync events
+    SYNC: 'memory:sync', // Sync memory with persistence layer
+    SYNC_COMPLETE: 'memory:sync:complete', // Sync complete
+    SYNC_ERROR: 'memory:sync:error', // Sync error
+    // Memory expiration events
+    EXPIRE: 'memory:expire', // Memory expiration
+    EXPIRE_COMPLETE: 'memory:expire:complete', // Expiration complete
+    EXPIRE_ERROR: 'memory:expire:error', // Expiration error
+};
+//# sourceMappingURL=MemoryEvents.js.map

package/dist/events/event-definitions/MemoryEvents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MemoryEvents.js","sourceRoot":"","sources":["../../../src/events/event-definitions/MemoryEvents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,CAAC;AAEvB;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IACxB,eAAe;IACf,GAAG,EAAE,YAAY,EAAE,aAAa;IAChC,UAAU,EAAE,mBAAmB,EAAE,oBAAoB;IACrD,SAAS,EAAE,kBAAkB,EAAE,mBAAmB;IAElD,gBAAgB;IAChB,MAAM,EAAE,eAAe,EAAE,gBAAgB;IACzC,aAAa,EAAE,sBAAsB,EAAE,uBAAuB;IAC9D,YAAY,EAAE,qBAAqB,EAAE,sBAAsB;IAE3D,gBAAgB;IAChB,MAAM,EAAE,eAAe,EAAE,gBAAgB;IACzC,aAAa,EAAE,sBAAsB,EAAE,uBAAuB;IAC9D,YAAY,EAAE,qBAAqB,EAAE,sBAAsB;IAE3D,gBAAgB;IAChB,MAAM,EAAE,eAAe,EAAE,gBAAgB;IACzC,aAAa,EAAE,sBAAsB,EAAE,uBAAuB;IAC9D,YAAY,EAAE,qBAAqB,EAAE,sBAAsB;IAE3D,eAAe;IACf,KAAK,EAAE,cAAc,EAAE,iCAAiC;IACxD,YAAY,EAAE,qBAAqB,EAAE,sBAAsB;IAC3D,WAAW,EAAE,oBAAoB,EAAE,qBAAqB;IAExD,mBAAmB;IACnB,SAAS,EAAE,kBAAkB,EAAE,mBAAmB;IAClD,gBAAgB,EAAE,yBAAyB,EAAE,0BAA0B;IACvE,eAAe,EAAE,wBAAwB,EAAE,yBAAyB;IAEpE,0BAA0B;IAC1B,MAAM,EAAE,eAAe,EAAE,gBAAgB;IACzC,KAAK,EAAE,cAAc,EAAE,eAAe;IACtC,MAAM,EAAE,eAAe,EAAE,gBAAgB;IAEzC,qBAAqB;IACrB,IAAI,EAAE,aAAa,EAAE,qCAAqC;IAC1D,aAAa,EAAE,sBAAsB,EAAE,gBAAgB;IACvD,UAAU,EAAE,mBAAmB,EAAE,aAAa;IAE9C,2BAA2B;IAC3B,MAAM,EAAE,eAAe,EAAE,oBAAoB;IAC7C,eAAe,EAAE,wBAAwB,EAAE,sBAAsB;IACjE,YAAY,EAAE,qBAAqB,EAAE,mBAAmB;CAC3D,CAAC"}

package/dist/events/event-definitions/MemoryUtilityEvents.d.ts

@@ -0,0 +1,233 @@
+/**
+ * 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 Utility Learning System (MULS) Events
+ *
+ * Events emitted by the MULS components for analytics, monitoring, and debugging.
+ * These events track Q-value updates, utility-based retrieval, and reward attribution.
+ *
+ * Feature flag: MEMORY_UTILITY_LEARNING_ENABLED
+ */
+import type { MemoryQValueUpdatedEventData, MemoryQValueBatchUpdatedEventData, MemoryRewardAttributedEventData } from '../../schemas/EventPayloadSchema.js';
+import { OrparPhase, TaskOutcomeStatus } from '../../types/MemoryUtilityTypes.js';
+/**
+ * MULS event names
+ */
+export declare const MemoryUtilityEvents: {
+    /** Emitted when a single Q-value is updated */
+    readonly QVALUE_UPDATED: "memory:qvalue_updated";
+    /** Emitted when multiple Q-values are updated in a batch */
+    readonly QVALUE_BATCH_UPDATED: "memory:qvalue_batch_updated";
+    /** Emitted when utility-based retrieval is completed */
+    readonly UTILITY_RETRIEVAL_COMPLETED: "memory:utility_retrieval_completed";
+    /** Emitted when rewards are attributed to memories after task completion */
+    readonly REWARD_ATTRIBUTED: "memory:reward_attributed";
+    /** Emitted when memory usage is tracked for a task */
+    readonly MEMORY_TRACKED: "memory:tracked";
+    /** Emitted when MULS configuration changes */
+    readonly CONFIG_UPDATED: "memory:utility_config_updated";
+};
+/**
+ * Type for MULS event names
+ */
+export type MemoryUtilityEventName = typeof MemoryUtilityEvents[keyof typeof MemoryUtilityEvents];
+/**
+ * Base payload for all MULS events
+ */
+export interface MemoryUtilityBasePayload {
+    /** Event type */
+    eventType: MemoryUtilityEventName;
+    /** Timestamp of the event */
+    timestamp: number;
+}
+/**
+ * Payload for QVALUE_UPDATED event
+ */
+export interface QValueUpdatedPayload extends MemoryUtilityBasePayload {
+    eventType: typeof MemoryUtilityEvents.QVALUE_UPDATED;
+    data: {
+        /** The memory ID that was updated */
+        memoryId: string;
+        /** Q-value before the update */
+        oldValue: number;
+        /** Q-value after the update */
+        newValue: number;
+        /** Reward signal that triggered the update */
+        reward: number;
+        /** Change in Q-value (newValue - oldValue) */
+        delta: number;
+        /** Optional task ID that triggered the update */
+        taskId?: string;
+        /** Optional agent ID */
+        agentId?: string;
+        /** Optional channel ID */
+        channelId?: string;
+        /** Optional ORPAR phase */
+        phase?: OrparPhase;
+    };
+}
+/**
+ * Payload for QVALUE_BATCH_UPDATED event
+ */
+export interface QValueBatchUpdatedPayload extends MemoryUtilityBasePayload {
+    eventType: typeof MemoryUtilityEvents.QVALUE_BATCH_UPDATED;
+    data: {
+        /** Total number of updates attempted */
+        totalUpdates: number;
+        /** Number of successful updates */
+        updated: number;
+        /** Number of failed updates */
+        failed: number;
+        /** Optional task ID that triggered the batch update */
+        taskId?: string;
+        /** Optional summary of errors */
+        errors?: Array<{
+            memoryId: string;
+            error: string;
+        }>;
+    };
+}
+/**
+ * Payload for UTILITY_RETRIEVAL_COMPLETED event
+ */
+export interface UtilityRetrievalCompletedPayload extends MemoryUtilityBasePayload {
+    eventType: typeof MemoryUtilityEvents.UTILITY_RETRIEVAL_COMPLETED;
+    data: {
+        /** Query used for retrieval */
+        query: string;
+        /** ORPAR phase (if specified) */
+        phase?: OrparPhase;
+        /** Lambda value used for scoring */
+        lambda: number;
+        /** Number of candidates in Phase A */
+        totalCandidates: number;
+        /** Number of results returned */
+        resultsReturned: number;
+        /** Time for semantic search (ms) */
+        semanticSearchTimeMs: number;
+        /** Time for utility scoring (ms) */
+        utilityScoringTimeMs: number;
+        /** Total retrieval time (ms) */
+        totalTimeMs: number;
+        /** IDs of retrieved memories */
+        memoryIds: string[];
+        /** Optional agent ID */
+        agentId?: string;
+        /** Optional channel ID */
+        channelId?: string;
+    };
+}
+/**
+ * Payload for REWARD_ATTRIBUTED event
+ */
+export interface RewardAttributedPayload extends MemoryUtilityBasePayload {
+    eventType: typeof MemoryUtilityEvents.REWARD_ATTRIBUTED;
+    data: {
+        /** Task ID (if task-level attribution) */
+        taskId?: string;
+        /** Task outcome status */
+        status?: TaskOutcomeStatus;
+        /** Reward value attributed */
+        reward: number;
+        /** Number of memories that received the reward */
+        memoriesUpdated: number;
+        /** Number of memories that failed to update */
+        memoriesFailed: number;
+        /** IDs of memories that received the reward */
+        memoryIds: string[];
+        /** Whether this was a manual injection */
+        isManual?: boolean;
+        /** Reason for manual injection */
+        reason?: string;
+        /** New Q-value (for single memory manual injection) */
+        newQValue?: number;
+        /** Single memory ID (for manual injection) */
+        memoryId?: string;
+    };
+}
+/**
+ * Payload for MEMORY_TRACKED event
+ */
+export interface MemoryTrackedPayload extends MemoryUtilityBasePayload {
+    eventType: typeof MemoryUtilityEvents.MEMORY_TRACKED;
+    data: {
+        /** Task ID the memory is tracked for */
+        taskId: string;
+        /** Memory ID being tracked */
+        memoryId: string;
+        /** ORPAR phase when tracked */
+        phase: OrparPhase;
+        /** Usage type */
+        usageType?: 'context' | 'reasoning' | 'action-guidance' | 'pattern-match';
+        /** Timestamp of tracking */
+        trackedAt: Date;
+    };
+}
+/**
+ * Payload for CONFIG_UPDATED event
+ */
+export interface ConfigUpdatedPayload extends MemoryUtilityBasePayload {
+    eventType: typeof MemoryUtilityEvents.CONFIG_UPDATED;
+    data: {
+        /** Whether MULS is now enabled */
+        enabled: boolean;
+        /** New global lambda value */
+        lambda?: number;
+        /** New learning rate */
+        learningRate?: number;
+        /** Updated phase lambdas */
+        phaseLambdas?: Record<OrparPhase, number>;
+        /** Source of the update */
+        source: 'api' | 'config' | 'env' | 'tool';
+    };
+}
+/**
+ * Union type for all MULS payloads
+ */
+export type MemoryUtilityPayload = QValueUpdatedPayload | QValueBatchUpdatedPayload | UtilityRetrievalCompletedPayload | RewardAttributedPayload | MemoryTrackedPayload | ConfigUpdatedPayload;
+/**
+ * Payload types for MULS events (indexed by event name)
+ */
+/**
+ * Data carried by UTILITY_RETRIEVAL_COMPLETED (envelope data — the
+ * BaseEventPayload wrapper carries eventType/agentId/channelId/timestamp).
+ */
+export interface UtilityRetrievalCompletedEventData {
+    query: string;
+    phase?: string;
+    lambda: number;
+    totalCandidates: number;
+    resultsReturned: number;
+    semanticSearchTimeMs: number;
+    utilityScoringTimeMs: number;
+    totalTimeMs: number;
+    memoryIds: string[];
+    agentId?: string;
+    channelId?: string;
+}
+export interface MemoryUtilityPayloads {
+    'memory:qvalue_updated': MemoryQValueUpdatedEventData;
+    'memory:qvalue_batch_updated': MemoryQValueBatchUpdatedEventData;
+    'memory:utility_retrieval_completed': UtilityRetrievalCompletedEventData;
+    'memory:reward_attributed': MemoryRewardAttributedEventData;
+    'memory:tracked': MemoryTrackedPayload;
+    'memory:utility_config_updated': ConfigUpdatedPayload;
+}
+//# sourceMappingURL=MemoryUtilityEvents.d.ts.map

package/dist/events/event-definitions/MemoryUtilityEvents.d.ts.map

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

package/dist/events/event-definitions/MemoryUtilityEvents.js

@@ -0,0 +1,37 @@
+/**
+ * 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/
+ */
+/**
+ * MULS event names
+ */
+export const MemoryUtilityEvents = {
+    /** Emitted when a single Q-value is updated */
+    QVALUE_UPDATED: 'memory:qvalue_updated',
+    /** Emitted when multiple Q-values are updated in a batch */
+    QVALUE_BATCH_UPDATED: 'memory:qvalue_batch_updated',
+    /** Emitted when utility-based retrieval is completed */
+    UTILITY_RETRIEVAL_COMPLETED: 'memory:utility_retrieval_completed',
+    /** Emitted when rewards are attributed to memories after task completion */
+    REWARD_ATTRIBUTED: 'memory:reward_attributed',
+    /** Emitted when memory usage is tracked for a task */
+    MEMORY_TRACKED: 'memory:tracked',
+    /** Emitted when MULS configuration changes */
+    CONFIG_UPDATED: 'memory:utility_config_updated'
+};
+//# sourceMappingURL=MemoryUtilityEvents.js.map