@elizaos/plugin-memory 1.0.5 → 2.0.1

package/dist/types/index.d.ts

@@ -1,86 +1,330 @@
 import type { UUID } from '@elizaos/core';
 /**
- * Categories of long-term memory
+ * Embedding dimension column type mapping
  */
-export declare enum LongTermMemoryCategory {
-    IDENTITY = "identity",// User identity, name, roles
-    EXPERTISE = "expertise",// Domain knowledge and familiarity
-    PROJECTS = "projects",// Past interactions and recurring topics
-    PREFERENCES = "preferences",// User preferences for interaction style
-    DATA_SOURCES = "data_sources",// Frequently used files, databases, APIs
-    GOALS = "goals",// User's broader intentions and objectives
-    CONSTRAINTS = "constraints",// User-defined rules and limitations
-    DEFINITIONS = "definitions",// Custom terms, acronyms, glossaries
-    BEHAVIORAL_PATTERNS = "behavioral_patterns"
+export type EmbeddingDimensionColumn = 'dim384' | 'dim512' | 'dim768' | 'dim1024' | 'dim1536' | 'dim3072';
+/**
+ * Dimension map for dynamic embedding support
+ */
+export declare const MEMORY_DIMENSION_MAP: Record<number, EmbeddingDimensionColumn>;
+/**
+ * Memory Type Taxonomy (Based on Cognitive Science)
+ *
+ * Research: Section 1.1 "The Cognitive Hierarchy of Agent Memory"
+ * - EPISODIC: Specific events anchored in time and place (conversation logs)
+ * - SEMANTIC: Facts and knowledge detached from specific episodes (user preferences, identity)
+ * - PROCEDURAL: "How-to" knowledge and successful tool execution patterns
+ */
+export declare enum MemoryType {
+    EPISODIC = "EPISODIC",
+    SEMANTIC = "SEMANTIC",
+    PROCEDURAL = "PROCEDURAL"
 }
 /**
- * Long-term memory entry
+ * Decay Function Types
+ *
+ * Research: Section 4.2 "Mathematical Model for Memory Decay"
+ * - EXPONENTIAL: Standard forgetting curve (Ebbinghaus)
+ * - LINEAR: Simple time-based decay
+ * - NONE: Core facts that never decay (identity, core preferences)
  */
-export interface LongTermMemory {
+export declare enum DecayFunction {
+    EXPONENTIAL = "EXPONENTIAL",
+    LINEAR = "LINEAR",
+    NONE = "NONE"
+}
+/**
+ * Conversation Summary - Hierarchical Conversation Summarization
+ *
+ * Research: Section 5.1.2 "Hierarchical Conversation Summarization"
+ *
+ * This implements recursive, multi-level summarization for long conversations:
+ * - Level 1: Summary of 50-100 messages
+ * - Level 2+: Summary of lower-level summaries (recursive)
+ *
+ * Benefits:
+ * - 10x token compression for very long conversations
+ * - Maintains narrative flow without exploding context window
+ * - Enables efficient retrieval of past conversation context
+ */
+export interface ConversationSummary {
+    /** Unique identifier */
     id: UUID;
+    /** Agent this summary belongs to */
     agentId: UUID;
+    /** Entity (user) this summary is about */
     entityId: UUID;
-    category: LongTermMemoryCategory;
+    /** Room this summary belongs to */
+    roomId: UUID;
+    /**
+     * Hierarchical level
+     * - 1: Direct summarization of messages
+     * - 2+: Summarization of lower-level summaries
+     */
+    level: number;
+    /**
+     * Parent summary ID (for tree structure)
+     * - null for Level 1 (summarizes messages)
+     * - UUID for Level 2+ (summarizes summaries)
+     */
+    parentSummaryId?: UUID;
+    /** The summary content (human-readable paragraph) */
     content: string;
-    metadata?: Record<string, unknown>;
+    /** Vector embedding for semantic search */
     embedding?: number[];
-    confidence?: number;
-    source?: string;
+    /** Estimated token count of this summary */
+    tokenCount: number;
+    /** Time range this summary covers */
+    startTime: Date;
+    endTime: Date;
+    /**
+     * Number of source items summarized
+     * - Level 1: message count
+     * - Level 2+: summary count
+     */
+    sourceCount: number;
+    /** IDs of source items (messages or summaries) */
+    sourceIds: UUID[];
+    /** When this summary was created */
     createdAt: Date;
-    updatedAt: Date;
-    lastAccessedAt?: Date;
-    accessCount?: number;
-    similarity?: number;
+    /** Last time this summary was accessed */
+    lastAccessedAt: Date | null;
+    /** How many times retrieved */
+    accessCount: number;
+    /** Flexible metadata (topics, sentiment, etc.) */
+    metadata: Record<string, unknown>;
 }
 /**
- * Short-term memory session summary
+ * Long-Term Memory Entry (The "Engram")
+ *
+ * Research: Section 4.1 "The SOTA Memory Schema"
+ * This interface represents a single unit of long-term memory with all necessary metadata
+ * for cognitive processing, including decay, confidence, and provenance tracking.
  */
-export interface SessionSummary {
+export interface LongTermMemory {
+    /** Unique identifier for this memory */
     id: UUID;
+    /** Agent this memory belongs to */
     agentId: UUID;
-    roomId: UUID;
-    entityId?: UUID;
-    summary: string;
-    messageCount: number;
-    lastMessageOffset: number;
-    startTime: Date;
-    endTime: Date;
-    topics?: string[];
-    metadata?: Record<string, unknown>;
-    embedding?: number[];
+    /** Entity (user/agent) this memory is about */
+    entityId: UUID;
+    /** Room/context where this memory was created */
+    roomId?: UUID;
+    /** Memory taxonomy type */
+    type: MemoryType;
+    /** The actual memory content (the fact or event) */
+    content: string;
+    /**
+     * Contextualized content for embedding
+     * Research: Section 3.2.1 "Contextual Embeddings"
+     * Example: "[User preference regarding programming]: I prefer Python over JavaScript"
+     */
+    embeddingContext: string;
+    /** Vector embedding of embeddingContext */
+    embedding: number[];
+    /**
+     * Confidence score (0.0 to 1.0)
+     * Research: Section 4.1 - Track certainty of extracted facts
+     * - 1.0: User explicitly stated or verified
+     * - < 1.0: LLM inferred or uncertain
+     */
+    confidence: number;
+    /**
+     * Decay rate (lambda λ) for exponential decay
+     * Research: Section 4.2.2 "Implementation Strategy"
+     * - ~0: Core facts (name, identity) - very slow decay
+     * - 0.01: Mid-term facts (current projects) - fade over weeks
+     * - 0.5+: Transient facts (lunch plans) - fade over days
+     */
+    decayRate: number;
+    /** Type of decay function to use */
+    decayFunction: DecayFunction;
+    /** When this memory was created */
     createdAt: Date;
-    updatedAt: Date;
+    /** When this memory was last accessed/retrieved */
+    lastAccessedAt: Date | null;
+    /**
+     * How many times this memory has been retrieved
+     * Research: Section 4.2.2 - High count = stronger memory (slower decay)
+     */
+    accessCount: number;
+    /**
+     * Soft delete flag for contradiction handling
+     * Research: Section 4.3 "Handling Contradictions"
+     * When a contradiction is found, old memory is marked inactive
+     */
+    isActive: boolean;
+    /**
+     * Provenance: Source tracking
+     * Research: Section 4.1 "Provenance / Lineage"
+     */
+    source: {
+        /** ID of the session where this was extracted */
+        sessionId?: string;
+        /** ID of the specific message that generated this fact */
+        messageId?: string;
+        /** Raw text snippet that triggered extraction */
+        textSnippet?: string;
+        /** Who provided the info (user ID or agent ID) */
+        authorId?: string;
+        /** Extraction model used (e.g., "gpt-4-turbo") */
+        extractionModel?: string;
+    };
+    /**
+     * Flexible metadata for future extensions
+     * Can store: tags, categories, relationships, etc.
+     */
+    metadata: Record<string, unknown>;
+    /**
+     * Optional: ID of memory this one supersedes (for contradiction resolution)
+     * Research: Section 4.3.1 "Resolution Strategies"
+     */
+    supersedesId?: UUID;
 }
 /**
- * Configuration for memory plugin
+ * Memory Configuration
+ *
+ * Research: Section 6 "Implementation Strategy"
+ * Simplified configuration focusing on key parameters
  */
-export interface MemoryConfig {
-    shortTermSummarizationThreshold: number;
-    shortTermRetainRecent: number;
-    shortTermSummarizationInterval: number;
-    longTermExtractionEnabled: boolean;
-    longTermVectorSearchEnabled: boolean;
-    longTermConfidenceThreshold: number;
-    longTermExtractionThreshold: number;
-    longTermExtractionInterval: number;
-    summaryModelType?: string;
-    summaryMaxTokens?: number;
-    summaryMaxNewMessages?: number;
+export interface LongTermMemoryConfig {
+    /**
+     * Number of messages before triggering consolidation
+     * Research: Section 2.3 "Consolidation Pipeline"
+     * Recommended: 10-20 messages
+     */
+    consolidationThreshold: number;
+    /**
+     * Minimum confidence to store a memory
+     * Research: Section 2.2 "Extraction Prompt Structure"
+     * Recommended: 0.7
+     */
+    minConfidence: number;
+    /**
+     * Enable vector search (requires embedding model)
+     * Research: Section 3 "RAG Strategy"
+     */
+    enableVectorSearch: boolean;
+    /**
+     * Enable BM25 keyword search
+     * Research: Section 3.2.1 - Combines with vector for Contextual Retrieval
+     */
+    enableBM25: boolean;
+    /**
+     * Number of memories to retrieve during RAG
+     * Research: Section 5.1.3 "Tier 3: Just-In-Time Injection"
+     */
+    retrievalLimit: number;
+    /**
+     * Token budget for memory context injection
+     * Research: Section 5.1.3 - Only highest-scoring memories within budget
+     */
+    tokenBudget: number;
+    /**
+     * Default decay rates for different memory types
+     * Research: Section 4.2.2 "Implementation Strategy"
+     */
+    defaultDecayRates: {
+        [MemoryType.EPISODIC]: number;
+        [MemoryType.SEMANTIC]: number;
+        [MemoryType.PROCEDURAL]: number;
+    };
+    /**
+     * Enable contradiction detection and resolution
+     * Research: Section 4.3 "Handling Contradictions"
+     */
+    enableContradictionDetection: boolean;
+    /**
+     * Hierarchical Summarization Configuration (GAP 3 fix)
+     * Research: Section 5.1.2 "Hierarchical Episodic Summarization"
+     */
+    summarization?: {
+        /** Enable hierarchical summarization */
+        enabled: boolean;
+        /** Number of messages before triggering Level 1 summary */
+        messagesPerSummary: number;
+        /** Number of Level N summaries before creating Level N+1 summary */
+        summariesPerLevel: number;
+        /** Maximum hierarchical depth (prevents infinite recursion) */
+        maxDepth: number;
+        /** Token budget for summary retrieval */
+        summaryTokenBudget: number;
+    };
 }
 /**
- * Memory extraction result from evaluator
+ * Extracted Long-Term Memory Result (from consolidation)
+ *
+ * Research: Section 2.2.2 "Proposed Extraction Prompt Structure"
  */
-export interface MemoryExtraction {
-    category: LongTermMemoryCategory;
+export interface ExtractedLongTermMemory {
+    /** The memory type classification */
+    type: MemoryType;
+    /** The extracted content */
     content: string;
+    /** Confidence score (0-1) */
     confidence: number;
+    /** Whether this contradicts an existing memory */
+    isContradiction: boolean;
+    /** ID of the source message */
+    sourceMessageId?: string;
+    /**
+     * Optional: Entity extraction for graph
+     * Research: Section 3.1.2 "Graph Advantages"
+     */
+    entities?: {
+        subject: string;
+        predicate: string;
+        object: string;
+    };
+    /** Additional metadata */
     metadata?: Record<string, unknown>;
 }
 /**
- * Summary generation result
+ * Consolidation Result
+ *
+ * Research: Section 2.2.2 "OUTPUT FORMAT"
  */
-export interface SummaryResult {
-    summary: string;
-    topics: string[];
-    keyPoints: string[];
+export interface ConsolidationResult {
+    /** Reasoning trace for debugging */
+    reasoningTrace: string;
+    /** Brief summary of transient events (for episodic log) */
+    transientSummary: string;
+    /** Extracted persistent long-term memories */
+    extractedMemories: ExtractedLongTermMemory[];
+}
+/**
+ * Long-Term Memory Retrieval Result (with decay-adjusted scoring)
+ *
+ * Research: Section 4.2 "Mathematical Model for Memory Decay"
+ */
+export interface LongTermMemoryRetrievalResult extends LongTermMemory {
+    /** Relevance score (vector similarity or BM25 score) */
+    relevanceScore: number;
+    /** Time-decayed activation score */
+    activationScore: number;
+    /** Final composite score (relevance * decay * confidence) */
+    finalScore: number;
+}
+/**
+ * Long-Term Memory Search Query Parameters
+ */
+export interface LongTermMemorySearchParams {
+    /** Entity to search memories for */
+    entityId: UUID;
+    /** Optional room context filter */
+    roomId?: UUID;
+    /** Query text */
+    query: string;
+    /** Optional memory type filter */
+    type?: MemoryType;
+    /** Maximum results to return */
+    limit?: number;
+    /** Minimum confidence threshold (default: 0.7) */
+    minConfidence?: number;
+    /** Minimum similarity threshold for vector search (default: 0.3) */
+    similarityThreshold?: number;
+    /** Whether to include inactive (superseded) memories */
+    includeInactive?: boolean;
+    /** Token budget for this retrieval (overrides config default) */
+    tokenBudget?: number;
 }

package/dist/utils/db-mapping.d.ts

@@ -0,0 +1,20 @@
+import { type LongTermMemory, type ConversationSummary } from '../types/index';
+/**
+ * Database Row Mapping Utilities
+ *
+ * Maps raw database rows to strongly-typed domain objects
+ */
+/**
+ * Map database row to LongTermMemory object
+ *
+ * @param row - Raw database row
+ * @returns Typed LongTermMemory object
+ */
+export declare function mapDbRowToLongTermMemory(row: any): LongTermMemory;
+/**
+ * Map database row to ConversationSummary object
+ *
+ * @param row - Raw database row
+ * @returns Typed ConversationSummary object
+ */
+export declare function mapDbRowToConversationSummary(row: any): ConversationSummary;

package/dist/utils/decay-scoring.d.ts

@@ -0,0 +1,41 @@
+import { DecayFunction, type LongTermMemoryRetrievalResult } from '../types/index';
+/**
+ * Decay Scoring Utilities
+ *
+ * Research: Section 4.2 "Mathematical Model for Memory Decay"
+ *
+ * Implements exponential and linear decay functions to model natural
+ * forgetting curves inspired by cognitive science research (Ebbinghaus forgetting curve)
+ */
+/**
+ * Calculate decay factor based on decay function type
+ *
+ * Research: Section 4.2 "Mathematical Model for Memory Decay"
+ * Formula: Score = Relevance * Confidence * exp(-λ * (t_now - t_last))
+ *
+ * @param decayFunction - Type of decay function (EXPONENTIAL, LINEAR, NONE)
+ * @param decayRate - Decay rate (lambda λ)
+ * @param timeDeltaDays - Time since last access in days
+ * @returns Decay factor (0.0 to 1.0)
+ */
+export declare function calculateDecayFactor(decayFunction: DecayFunction, decayRate: number, timeDeltaDays: number): number;
+/**
+ * Calculate access boost factor from access count
+ *
+ * Research: Section 4.2.2 "Reinforcement"
+ * More accesses = stronger memory
+ *
+ * @param accessCount - Number of times memory has been accessed
+ * @returns Boost factor (>= 1.0)
+ */
+export declare function calculateAccessBoost(accessCount: number): number;
+/**
+ * Apply decay scoring to a set of memories
+ *
+ * Research: Section 4.2 "Mathematical Model for Memory Decay"
+ * Calculates activation score and final score for each memory
+ *
+ * @param memories - Array of memory retrieval results
+ * @returns Array with decay scores applied
+ */
+export declare function applyDecayScoring(memories: LongTermMemoryRetrievalResult[]): LongTermMemoryRetrievalResult[];

package/dist/utils/embedding.d.ts

@@ -0,0 +1,21 @@
+import { type IAgentRuntime } from '@elizaos/core';
+/**
+ * Embedding Generation Utility
+ *
+ * Research: Section 3.2.1 "Contextual Embeddings"
+ */
+/**
+ * Generate embedding for text using the runtime's embedding model
+ *
+ * @param runtime - Agent runtime instance
+ * @param text - Text to generate embedding for
+ * @returns Embedding vector
+ */
+export declare function generateEmbedding(runtime: IAgentRuntime, text: string): Promise<number[]>;
+/**
+ * Clean and normalize an embedding vector
+ *
+ * @param embedding - Raw embedding vector
+ * @returns Cleaned vector with finite numbers and fixed precision
+ */
+export declare function cleanEmbedding(embedding: number[]): number[];

package/dist/utils/formatting.d.ts

@@ -0,0 +1,17 @@
+import { type LongTermMemoryRetrievalResult } from '../types/index';
+/**
+ * Memory Formatting Utilities
+ *
+ * Research: Section 5.1.3 "Tier 3: Just-In-Time Injection"
+ * Formats memories for LLM context in a human-readable format
+ */
+/**
+ * Format memories for context injection
+ *
+ * Research: Section 5.1.3 "Tier 3: Just-In-Time Injection"
+ * Groups by type and formats in a human-readable markdown format
+ *
+ * @param memories - Array of memories to format
+ * @returns Formatted string for LLM context
+ */
+export declare function formatMemoriesForContext(memories: LongTermMemoryRetrievalResult[]): string;

package/dist/utils/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Utility Functions for Memory Plugin
+ *
+ * This module exports reusable utility functions for:
+ * - Embedding generation and cleaning
+ * - Decay scoring calculations
+ * - Search result merging
+ * - Memory formatting
+ * - Database row mapping
+ * - Token counting and budget enforcement
+ */
+export * from './embedding';
+export * from './decay-scoring';
+export * from './search-merging';
+export * from './formatting';
+export * from './db-mapping';
+export * from './token-counter';

package/dist/utils/search-merging.d.ts

@@ -0,0 +1,18 @@
+import type { LongTermMemoryRetrievalResult } from '../types/index';
+/**
+ * Search Result Merging Utilities
+ *
+ * Research: Section 3.2.1 "Contextual Retrieval"
+ * Combines multiple ranking methods (Vector + BM25) for superior retrieval
+ */
+/**
+ * Merge vector and BM25 search results
+ *
+ * Research: Section 3.2.1 "Contextual Retrieval"
+ * When a memory appears in both result sets, average their scores
+ *
+ * @param vectorResults - Results from vector search
+ * @param bm25Results - Results from BM25 search
+ * @returns Merged results with combined scores
+ */
+export declare function mergeSearchResults(vectorResults: LongTermMemoryRetrievalResult[], bm25Results: LongTermMemoryRetrievalResult[]): LongTermMemoryRetrievalResult[];

package/dist/utils/token-counter.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Token Counter Utility
+ *
+ * Research: Section 5.1.3 "Token Budget Enforcement"
+ *
+ * This utility provides token counting for memory content to enforce
+ * token budgets during retrieval. Uses a simplified estimation based on
+ * GPT tokenization rules (1 token ≈ 4 characters for English text).
+ *
+ * For more precise counting, this can be replaced with a full tokenizer
+ * library (e.g., tiktoken), but the estimation is sufficient for budget
+ * enforcement in most cases.
+ */
+/**
+ * Estimate token count for a given text
+ *
+ * This is a simplified heuristic that works well for most content:
+ * - 1 token ≈ 4 characters for English text
+ * - Punctuation and whitespace are included
+ * - Non-English text may have different ratios
+ *
+ * @param text - The text to count tokens for
+ * @returns Estimated token count
+ */
+export declare function estimateTokenCount(text: string): number;
+/**
+ * Calculate token count for multiple text segments
+ *
+ * @param texts - Array of text strings
+ * @returns Total estimated token count
+ */
+export declare function estimateTokenCountForArray(texts: string[]): number;
+/**
+ * Trim an array of items to fit within a token budget
+ *
+ * This function takes an array of items with text content and trims it
+ * to fit within the specified token budget. Items are assumed to be
+ * already sorted by priority/score (highest first).
+ *
+ * @param items - Array of items (with getText function)
+ * @param budget - Maximum token budget
+ * @param getText - Function to extract text from an item
+ * @param includeOverhead - Additional tokens per item (formatting overhead)
+ * @returns Trimmed array of items that fit within budget
+ */
+export declare function trimToTokenBudget<T>(items: T[], budget: number, getText: (item: T) => string, includeOverhead?: number): T[];
+/**
+ * Format token count for human-readable display
+ *
+ * @param count - Token count
+ * @returns Formatted string (e.g., "1.2K tokens")
+ */
+export declare function formatTokenCount(count: number): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elizaos/plugin-memory",
-  "version": "1.0.5",
+  "version": "2.0.1",
   "description": "Advanced memory management plugin with short-term summarization and long-term persistent memory",
   "type": "module",
   "main": "dist/cjs/index.node.cjs",
@@ -66,5 +66,87 @@
   "license": "MIT",
   "publishConfig": {
     "access": "public"
+  },
+  "agentConfig": {
+    "pluginType": "elizaos:plugin:1.0.0",
+    "pluginParameters": {
+      "MEMORY_CONSOLIDATION_THRESHOLD": {
+        "type": "number",
+        "description": "Number of messages to buffer before triggering memory consolidation.",
+        "required": false,
+        "default": 10,
+        "sensitive": false
+      },
+      "MEMORY_MIN_CONFIDENCE": {
+        "type": "number",
+        "description": "Minimum confidence score (0-1) required to store extracted facts.",
+        "required": false,
+        "default": 0.7,
+        "sensitive": false
+      },
+      "MEMORY_ENABLE_VECTOR_SEARCH": {
+        "type": "boolean",
+        "description": "Enable semantic similarity search using embeddings.",
+        "required": false,
+        "default": true,
+        "sensitive": false
+      },
+      "MEMORY_ENABLE_BM25": {
+        "type": "boolean",
+        "description": "Enable keyword-based search with stemming for exact term matching.",
+        "required": false,
+        "default": true,
+        "sensitive": false
+      },
+      "MEMORY_RETRIEVAL_LIMIT": {
+        "type": "number",
+        "description": "Maximum number of memories to retrieve per query.",
+        "required": false,
+        "default": 5,
+        "sensitive": false
+      },
+      "MEMORY_TOKEN_BUDGET": {
+        "type": "number",
+        "description": "Maximum tokens to use for memory context in prompts.",
+        "required": false,
+        "default": 1000,
+        "sensitive": false
+      },
+      "MEMORY_SUMMARY_ENABLED": {
+        "type": "boolean",
+        "description": "Enable hierarchical conversation summarization to reduce token usage.",
+        "required": false,
+        "default": true,
+        "sensitive": false
+      },
+      "MEMORY_MESSAGES_PER_SUMMARY": {
+        "type": "number",
+        "description": "How many messages to include in each Level 1 summary.",
+        "required": false,
+        "default": 15,
+        "sensitive": false
+      },
+      "MEMORY_SUMMARIES_PER_LEVEL": {
+        "type": "number",
+        "description": "How many summaries to accumulate before creating the next level.",
+        "required": false,
+        "default": 5,
+        "sensitive": false
+      },
+      "MEMORY_SUMMARY_MAX_DEPTH": {
+        "type": "number",
+        "description": "Maximum depth of the summary hierarchy (1=direct summaries, 2=summaries of summaries, etc).",
+        "required": false,
+        "default": 3,
+        "sensitive": false
+      },
+      "MEMORY_SUMMARY_TOKEN_BUDGET": {
+        "type": "number",
+        "description": "Maximum tokens to use for conversation summaries in context.",
+        "required": false,
+        "default": 500,
+        "sensitive": false
+      }
+    }
   }
 }