@mxf-dev/core 1.0.0

package/dist/types/MemoryUtilityTypes.d.ts

@@ -0,0 +1,451 @@
+/**
+ * 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) Types
+ *
+ * Type definitions for the utility-based memory retrieval system inspired by MemRL.
+ * The core innovation: treat memory retrieval as a decision problem rather than
+ * similarity search - Q-values track which memories actually lead to successful task outcomes.
+ *
+ * Key Formula: score = (1-λ) × sim_normalized + λ × Q_normalized
+ */
+import { AgentId, ChannelId } from './ChannelContext.js';
+/**
+ * ORPAR cognitive phases used for phase-specific lambda values
+ */
+export type OrparPhase = 'observation' | 'reasoning' | 'planning' | 'action' | 'reflection';
+/**
+ * Q-Value update request
+ */
+export interface QValueUpdate {
+    /** The memory ID to update */
+    memoryId: string;
+    /** The reward signal to incorporate */
+    reward: number;
+    /** Optional learning rate override */
+    learningRate?: number;
+    /** Optional context for the update */
+    context?: {
+        taskId?: string;
+        agentId?: AgentId;
+        channelId?: ChannelId;
+        phase?: OrparPhase;
+        timestamp?: number;
+    };
+}
+/**
+ * History entry for Q-value changes over time
+ */
+export interface QValueHistoryEntry {
+    /** Q-value after update */
+    value: number;
+    /** Reward signal that triggered this update */
+    reward: number;
+    /** Timestamp of the update */
+    timestamp: Date;
+    /** Task ID associated with the update */
+    taskId?: string;
+    /** Phase during which the update occurred */
+    phase?: OrparPhase;
+}
+/**
+ * Methods for normalizing Q-values across a candidate pool
+ */
+export type NormalizationMethod = 'z-score' | 'min-max' | 'softmax';
+/**
+ * Statistics about Q-value distribution for a memory or agent
+ */
+export interface QValueStatistics {
+    /** Mean Q-value */
+    mean: number;
+    /** Standard deviation of Q-values */
+    stdDev: number;
+    /** Minimum Q-value */
+    min: number;
+    /** Maximum Q-value */
+    max: number;
+    /** Number of Q-values in the distribution */
+    count: number;
+    /** Percentile distribution */
+    percentiles?: {
+        p25: number;
+        p50: number;
+        p75: number;
+        p90: number;
+        p99: number;
+    };
+}
+/**
+ * A memory candidate with both similarity and Q-value scores
+ */
+export interface MemoryCandidate {
+    /** The memory ID */
+    memoryId: string;
+    /** Similarity score from semantic search (0-1) */
+    similarity: number;
+    /** Current Q-value (default 0.5) */
+    qValue: number;
+    /** The actual memory content (optional, for convenience) */
+    content?: any;
+    /** Additional metadata */
+    metadata?: Record<string, any>;
+}
+/**
+ * A scored memory after applying the composite scoring formula
+ */
+export interface ScoredMemory {
+    /** The memory ID */
+    memoryId: string;
+    /** Final composite score after applying lambda weighting */
+    finalScore: number;
+    /** Breakdown of score components */
+    breakdown?: {
+        /** Normalized similarity score (0-1) */
+        normalizedSimilarity: number;
+        /** Normalized Q-value (z-score) */
+        normalizedQValue: number;
+        /** Lambda value used */
+        lambda: number;
+        /** Original similarity before normalization */
+        rawSimilarity: number;
+        /** Original Q-value before normalization */
+        rawQValue: number;
+    };
+    /** The actual memory content (optional) */
+    content?: any;
+    /** Additional metadata */
+    metadata?: Record<string, any>;
+}
+/**
+ * Options for the scoring operation
+ */
+export interface ScoringOptions {
+    /** Lambda value for utility weighting (0=pure similarity, 1=pure utility) */
+    lambda?: number;
+    /** Maximum candidates to consider in Phase A */
+    maxCandidates?: number;
+    /** Maximum results to return after scoring */
+    maxResults?: number;
+    /** Normalization method for Q-values */
+    normalizationMethod?: NormalizationMethod;
+    /** Minimum similarity threshold for Phase A filtering */
+    similarityThreshold?: number;
+    /** Include score breakdown in results */
+    includeBreakdown?: boolean;
+}
+/**
+ * Result of a scoring operation
+ */
+export interface ScoringResult {
+    /** Scored memories sorted by final score descending */
+    memories: ScoredMemory[];
+    /** Statistics about the scoring operation */
+    stats: {
+        /** Number of candidates considered */
+        candidatesConsidered: number;
+        /** Number of results returned */
+        resultsReturned: number;
+        /** Lambda value used */
+        lambdaUsed: number;
+        /** Time taken for scoring (ms) */
+        scoringTimeMs: number;
+    };
+}
+/**
+ * Task outcome status for reward calculation
+ */
+export type TaskOutcomeStatus = 'success' | 'failure' | 'partial' | 'timeout';
+/**
+ * Record of how a memory was used during a task
+ */
+export interface MemoryUsageRecord {
+    /** The memory ID */
+    memoryId: string;
+    /** Phase when the memory was retrieved */
+    phase: OrparPhase;
+    /** Timestamp of retrieval */
+    retrievedAt: Date;
+    /** How the memory was used (if known) */
+    usageType?: 'context' | 'reasoning' | 'action-guidance' | 'pattern-match';
+    /** Any explicit feedback about the memory's usefulness */
+    feedback?: {
+        helpful: boolean;
+        reason?: string;
+    };
+}
+/**
+ * Complete task outcome for reward attribution
+ */
+export interface TaskOutcome {
+    /** The task ID */
+    taskId: string;
+    /** Agent that executed the task */
+    agentId: AgentId;
+    /** Channel where the task was executed */
+    channelId: ChannelId;
+    /** Task completion status */
+    status: TaskOutcomeStatus;
+    /** All memories used during the task */
+    memoriesUsed: MemoryUsageRecord[];
+    /** Optional task-level metrics */
+    metrics?: {
+        /** Time to complete (ms) */
+        completionTimeMs?: number;
+        /** Number of tool calls made */
+        toolCallCount?: number;
+        /** Number of errors encountered */
+        errorCount?: number;
+        /** Task quality score (0-1) if available */
+        qualityScore?: number;
+    };
+    /** Timestamp of task completion */
+    completedAt: Date;
+}
+/**
+ * Mapping of task outcomes to reward values
+ */
+export interface RewardMapping {
+    /** Reward for successful task completion */
+    success: number;
+    /** Reward (penalty) for task failure */
+    failure: number;
+    /** Reward for partial task completion */
+    partial: number;
+    /** Reward (penalty) for task timeout */
+    timeout: number;
+}
+/**
+ * Default reward mapping values
+ */
+export declare const DEFAULT_REWARD_MAPPING: RewardMapping;
+/**
+ * Step-level outcome for more granular reward attribution
+ */
+export interface StepOutcome {
+    /** The step ID */
+    stepId: string;
+    /** The parent task ID */
+    taskId: string;
+    /** Step completion status */
+    status: 'success' | 'failure' | 'skipped';
+    /** Memories used specifically in this step */
+    memoriesUsed: string[];
+    /** Optional step quality score */
+    qualityScore?: number;
+    /** Timestamp */
+    timestamp: Date;
+}
+/**
+ * Phase-specific lambda configuration
+ */
+export interface PhaseLambdaConfig {
+    observation: number;
+    reasoning: number;
+    planning: number;
+    action: number;
+    reflection: number;
+}
+/**
+ * Default phase-specific lambda values
+ * Rationale:
+ * - OBSERVATION (0.2): Prioritize semantic accuracy for gathering context
+ * - REASONING (0.5): Balance explore/exploit for analysis
+ * - PLANNING (0.7): Exploit proven patterns for strategy
+ * - ACTION (0.3): Stay grounded for tool execution
+ * - REFLECTION (0.6): Favor memories that led to good assessments
+ */
+export declare const DEFAULT_PHASE_LAMBDAS: PhaseLambdaConfig;
+/**
+ * Complete MULS configuration
+ */
+export interface MemoryUtilityConfig {
+    /** Whether MULS is enabled */
+    enabled: boolean;
+    /** Default lambda value when phase not specified */
+    lambda: number;
+    /** Phase-specific lambda overrides */
+    phaseLambdas?: Partial<PhaseLambdaConfig>;
+    /** Default Q-value for new memories */
+    defaultQValue: number;
+    /** Learning rate for EMA updates */
+    learningRate: number;
+    /** Maximum candidates in Phase A */
+    maxCandidates: number;
+    /** Maximum results to return */
+    maxResults: number;
+    /** Similarity threshold for Phase A filtering */
+    similarityThreshold: number;
+    /** Normalization method */
+    normalizationMethod: NormalizationMethod;
+    /** Reward mapping configuration */
+    rewardMapping: RewardMapping;
+    /** Q-value history retention (number of entries per memory) */
+    qValueHistoryLimit: number;
+    /** Whether to track memory usage for reward attribution */
+    trackMemoryUsage: boolean;
+    /** Cache configuration */
+    cache?: {
+        enabled: boolean;
+        maxSize: number;
+        ttlMs: number;
+    };
+}
+/**
+ * Default MULS configuration
+ */
+export declare const DEFAULT_MEMORY_UTILITY_CONFIG: MemoryUtilityConfig;
+/**
+ * Source of Q-value initialization
+ */
+export type QValueInitSource = 'default' | 'surprise' | 'transfer' | 'manual';
+/**
+ * Utility subdocument to add to memory schemas
+ */
+export interface MemoryUtilitySubdocument {
+    /** Current Q-value */
+    qValue: number;
+    /** History of Q-value updates */
+    qValueHistory: QValueHistoryEntry[];
+    /** Total number of times this memory was retrieved */
+    retrievalCount: number;
+    /** Number of successful task completions where this memory was used */
+    successCount: number;
+    /** Number of failed task completions where this memory was used */
+    failureCount: number;
+    /** Timestamp of last reward update */
+    lastRewardAt: Date;
+    /** How the Q-value was initially set */
+    initializedFrom: QValueInitSource;
+}
+/**
+ * Default utility subdocument values
+ */
+export declare const DEFAULT_UTILITY_SUBDOCUMENT: MemoryUtilitySubdocument;
+/**
+ * Options for utility-aware memory retrieval
+ */
+export interface UtilityRetrievalOptions {
+    /** Query string for semantic search */
+    query: string;
+    /** ORPAR phase for phase-specific lambda */
+    phase?: OrparPhase;
+    /** Agent ID for scoping */
+    agentId?: AgentId;
+    /** Channel ID for scoping */
+    channelId?: ChannelId;
+    /** Override default lambda */
+    lambda?: number;
+    /** Maximum candidates in Phase A */
+    maxCandidates?: number;
+    /** Maximum results to return */
+    maxResults?: number;
+    /** Similarity threshold */
+    similarityThreshold?: number;
+    /** Include score breakdown */
+    includeBreakdown?: boolean;
+}
+/**
+ * Retrieved memory with utility scoring information
+ */
+export interface RetrievedMemoryWithUtility {
+    /** The memory ID */
+    memoryId: string;
+    /** Memory content */
+    content: any;
+    /** Final composite score */
+    score: number;
+    /** Score breakdown (if requested) */
+    breakdown?: ScoredMemory['breakdown'];
+    /** Original memory metadata */
+    metadata?: Record<string, any>;
+}
+/**
+ * Result of utility-aware retrieval
+ */
+export interface UtilityRetrievalResult {
+    /** Retrieved memories */
+    memories: RetrievedMemoryWithUtility[];
+    /** Retrieval metadata */
+    metadata: {
+        /** Query used */
+        query: string;
+        /** Phase used for lambda */
+        phase?: OrparPhase;
+        /** Lambda value used */
+        lambda: number;
+        /** Total candidates before scoring */
+        totalCandidates: number;
+        /** Time for semantic search (ms) */
+        semanticSearchTimeMs: number;
+        /** Time for utility scoring (ms) */
+        utilityScoringTimeMs: number;
+        /** Total retrieval time (ms) */
+        totalTimeMs: number;
+    };
+}
+/**
+ * Q-value analytics for an agent or globally
+ */
+export interface QValueAnalytics {
+    /** Overall statistics */
+    statistics: QValueStatistics;
+    /** Top performing memories by Q-value */
+    topPerformers: Array<{
+        memoryId: string;
+        qValue: number;
+        successRate: number;
+        retrievalCount: number;
+    }>;
+    /** Convergence metrics */
+    convergence: {
+        /** Whether Q-values appear to be converging */
+        isConverging: boolean;
+        /** Average change in Q-values over recent updates */
+        averageRecentChange: number;
+        /** Number of memories with stable Q-values (low variance) */
+        stableMemoryCount: number;
+    };
+    /** Reward distribution */
+    rewardDistribution: {
+        successCount: number;
+        failureCount: number;
+        partialCount: number;
+        timeoutCount: number;
+    };
+}
+/**
+ * Environment variable names for MULS configuration
+ */
+export declare const MULS_ENV_VARS: {
+    readonly ENABLED: "MEMORY_UTILITY_LEARNING_ENABLED";
+    readonly DEFAULT_QVALUE: "QVALUE_DEFAULT";
+    readonly LEARNING_RATE: "QVALUE_LEARNING_RATE";
+    readonly LAMBDA_DEFAULT: "RETRIEVAL_LAMBDA_DEFAULT";
+    readonly LAMBDA_OBSERVATION: "RETRIEVAL_LAMBDA_OBSERVATION";
+    readonly LAMBDA_REASONING: "RETRIEVAL_LAMBDA_REASONING";
+    readonly LAMBDA_PLANNING: "RETRIEVAL_LAMBDA_PLANNING";
+    readonly LAMBDA_ACTION: "RETRIEVAL_LAMBDA_ACTION";
+    readonly LAMBDA_REFLECTION: "RETRIEVAL_LAMBDA_REFLECTION";
+};
+/**
+ * Get MULS config from environment variables
+ */
+export declare function getMulsConfigFromEnv(): Partial<MemoryUtilityConfig>;
+//# sourceMappingURL=MemoryUtilityTypes.d.ts.map

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

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

package/dist/types/MemoryUtilityTypes.js

@@ -0,0 +1,122 @@
+/**
+ * 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/
+ */
+/**
+ * Default reward mapping values
+ */
+export const DEFAULT_REWARD_MAPPING = {
+    success: 1.0,
+    failure: -1.0,
+    partial: 0.3,
+    timeout: -0.5
+};
+/**
+ * Default phase-specific lambda values
+ * Rationale:
+ * - OBSERVATION (0.2): Prioritize semantic accuracy for gathering context
+ * - REASONING (0.5): Balance explore/exploit for analysis
+ * - PLANNING (0.7): Exploit proven patterns for strategy
+ * - ACTION (0.3): Stay grounded for tool execution
+ * - REFLECTION (0.6): Favor memories that led to good assessments
+ */
+export const DEFAULT_PHASE_LAMBDAS = {
+    observation: 0.2,
+    reasoning: 0.5,
+    planning: 0.7,
+    action: 0.3,
+    reflection: 0.6
+};
+/**
+ * Default MULS configuration
+ */
+export const DEFAULT_MEMORY_UTILITY_CONFIG = {
+    enabled: false,
+    lambda: 0.5,
+    phaseLambdas: DEFAULT_PHASE_LAMBDAS,
+    defaultQValue: 0.5,
+    learningRate: 0.1,
+    maxCandidates: 20,
+    maxResults: 5,
+    similarityThreshold: 0.3,
+    normalizationMethod: 'z-score',
+    rewardMapping: DEFAULT_REWARD_MAPPING,
+    qValueHistoryLimit: 100,
+    trackMemoryUsage: true,
+    cache: {
+        enabled: true,
+        maxSize: 1000,
+        ttlMs: 60000
+    }
+};
+/**
+ * Default utility subdocument values
+ */
+export const DEFAULT_UTILITY_SUBDOCUMENT = {
+    qValue: 0.5,
+    qValueHistory: [],
+    retrievalCount: 0,
+    successCount: 0,
+    failureCount: 0,
+    lastRewardAt: new Date(),
+    initializedFrom: 'default'
+};
+// ============================================================================
+// Environment Variable Defaults
+// ============================================================================
+/**
+ * Environment variable names for MULS configuration
+ */
+export const MULS_ENV_VARS = {
+    ENABLED: 'MEMORY_UTILITY_LEARNING_ENABLED',
+    DEFAULT_QVALUE: 'QVALUE_DEFAULT',
+    LEARNING_RATE: 'QVALUE_LEARNING_RATE',
+    LAMBDA_DEFAULT: 'RETRIEVAL_LAMBDA_DEFAULT',
+    LAMBDA_OBSERVATION: 'RETRIEVAL_LAMBDA_OBSERVATION',
+    LAMBDA_REASONING: 'RETRIEVAL_LAMBDA_REASONING',
+    LAMBDA_PLANNING: 'RETRIEVAL_LAMBDA_PLANNING',
+    LAMBDA_ACTION: 'RETRIEVAL_LAMBDA_ACTION',
+    LAMBDA_REFLECTION: 'RETRIEVAL_LAMBDA_REFLECTION'
+};
+/**
+ * Get MULS config from environment variables
+ */
+export function getMulsConfigFromEnv() {
+    const getNum = (key, defaultVal) => {
+        const val = process.env[key];
+        return val ? parseFloat(val) : defaultVal;
+    };
+    const getBool = (key, defaultVal) => {
+        const val = process.env[key];
+        return val ? val.toLowerCase() === 'true' : defaultVal;
+    };
+    return {
+        enabled: getBool(MULS_ENV_VARS.ENABLED, false),
+        defaultQValue: getNum(MULS_ENV_VARS.DEFAULT_QVALUE, 0.5),
+        learningRate: getNum(MULS_ENV_VARS.LEARNING_RATE, 0.1),
+        lambda: getNum(MULS_ENV_VARS.LAMBDA_DEFAULT, 0.5),
+        phaseLambdas: {
+            observation: getNum(MULS_ENV_VARS.LAMBDA_OBSERVATION, 0.2),
+            reasoning: getNum(MULS_ENV_VARS.LAMBDA_REASONING, 0.5),
+            planning: getNum(MULS_ENV_VARS.LAMBDA_PLANNING, 0.7),
+            action: getNum(MULS_ENV_VARS.LAMBDA_ACTION, 0.3),
+            reflection: getNum(MULS_ENV_VARS.LAMBDA_REFLECTION, 0.6)
+        }
+    };
+}
+//# sourceMappingURL=MemoryUtilityTypes.js.map

package/dist/types/MemoryUtilityTypes.js.map

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