@elizaos/plugin-memory 1.0.5 → 2.0.1

package/dist/evaluators/consolidation.d.ts

@@ -0,0 +1,19 @@
+import { type Evaluator } from '@elizaos/core';
+/**
+ * Memory Consolidation Evaluator
+ *
+ * Research: Section 2.3 "Consolidation Pipeline"
+ *
+ * This evaluator implements the full consolidation flow:
+ * 1. Buffers conversation messages
+ * 2. Validates when threshold is reached
+ * 3. Extracts persistent facts using LLM
+ * 4. Stores memories via service
+ *
+ * Architecture Design:
+ * - Evaluator owns the consolidation logic and prompts
+ * - Service handles storage/retrieval only
+ * - System prompt is temporarily swapped during consolidation
+ * - Non-blocking: Doesn't wait for consolidation to complete
+ */
+export declare const consolidationEvaluator: Evaluator;

package/dist/evaluators/summarization.d.ts

@@ -1,30 +1,11 @@
 import { type Evaluator } from '@elizaos/core';
 /**
- * Short-term Memory Summarization Evaluator
+ * Hierarchical Summarization Evaluator
  *
- * Automatically generates and updates conversation summaries when conversations
- * exceed the configured threshold (default: 16 messages).
+ * Research: Section 5.1.2 "Hierarchical Episodic Summarization"
  *
- * BEHAVIOR:
- * - Monitors message count per room
- * - Creates initial summary when count >= threshold (e.g., 16 messages)
- * - Updates summary at regular intervals (e.g., every 10 new messages)
- * - Condenses existing summary with new messages to stay under token limit
- * - Tracks offset to avoid re-processing messages
- * - Caps new messages per update to prevent context bloat (default: 20)
- *
- * OPTIMIZATION:
- * - Only triggers LLM when crossing threshold or interval boundaries
- * - Processes only NEW messages since last update
- * - Maintains rolling summary (fixed size, not ever-growing)
- * - LLM is instructed to merge and condense, keeping under 2500 tokens
- *
- * INTEGRATION:
- * Works with shortTermMemoryProvider which:
- * - Shows full conversation when < threshold (no summarization needed)
- * - Shows summaries + recent messages when >= threshold (optimized context)
- *
- * This creates an adaptive system that starts with full context and seamlessly
- * transitions to efficient summarization as conversations grow.
+ * Implements recursive, multi-level summarization for token-efficient conversation history:
+ * - Level 1: Summarizes 50-100 messages into narrative paragraphs
+ * - Level 2+: Summarizes lower-level summaries into higher-level abstractions
  */
 export declare const summarizationEvaluator: Evaluator;

package/dist/index.d.ts

@@ -1,38 +1,160 @@
 import type { Plugin } from '@elizaos/core';
+import { longTermMemoryProvider } from './providers/long-term-memory';
+import { recentContextProvider } from './providers/recent-conversation-summary';
+import { actionResultsProvider } from './providers/action-results';
 export * from './types/index';
 export * from './schemas/index';
+export * from './prompts/consolidation';
+export * from './prompts/summarization';
+export * from './utils/index';
+export * from './repositories/index';
 export { MemoryService } from './services/memory-service';
+export { longTermMemoryProvider, recentContextProvider, actionResultsProvider };
 /**
- * Memory Plugin
- *
- * Advanced memory management plugin that provides:
- *
- * **Short-term Memory (Conversation Summarization)**:
- * - Automatically summarizes long conversations to reduce context size
- * - Retains recent messages while archiving older ones as summaries
- * - Configurable thresholds for when to summarize
- *
- * **Long-term Memory (Persistent Facts)**:
- * - Extracts and stores persistent facts about users
- * - Categorizes information (identity, expertise, preferences, etc.)
- * - Provides context-aware user profiles across all conversations
- *
- * **Components**:
- * - `MemoryService`: Manages all memory operations
- * - Evaluators: Process conversations to create summaries and extract facts
- * - Providers: Inject memory context into conversations
- * - Actions: Allow manual memory storage via user commands
- *
- * **Configuration** (via environment variables):
- * - `MEMORY_SUMMARIZATION_THRESHOLD`: Messages before summarization (default: 50)
- * - `MEMORY_RETAIN_RECENT`: Recent messages to keep (default: 10)
- * - `MEMORY_LONG_TERM_ENABLED`: Enable long-term extraction (default: true)
- * - `MEMORY_CONFIDENCE_THRESHOLD`: Minimum confidence to store (default: 0.7)
- *
- * **Database Tables**:
- * - `long_term_memories`: Persistent user facts
- * - `session_summaries`: Conversation summaries
- * - `memory_access_logs`: Optional usage tracking
+ * Memory Plugin - State-of-the-Art Cognitive Memory System
+ *
+ * Based on comprehensive research analysis (refactor.md), this plugin implements
+ * a sophisticated memory architecture that mirrors human cognitive processes.
+ *
+ * ## Core Concepts (Research-Based)
+ *
+ * ### 1. Three-Tier Memory Taxonomy
+ * Research: Section 1.1 "The Cognitive Hierarchy"
+ * - **EPISODIC**: Specific events anchored in time and place (conversation logs)
+ * - **SEMANTIC**: Facts and knowledge detached from episodes (user preferences, identity)
+ * - **PROCEDURAL**: Skills and successful tool execution patterns ("know-how")
+ *
+ * ### 2. Memory Consolidation Pipeline
+ * Research: Section 2 "Architecture for Extraction & Taxonomy"
+ * - Buffers conversation messages asynchronously
+ * - Triggers consolidation every N messages (configurable)
+ * - Extracts persistent facts using LLM with specialized prompts
+ * - Filters transient intents (e.g., "draw a cat") from persistent facts (e.g., "user likes cats")
+ *
+ * ### 3. Hybrid Retrieval (Vector + BM25)
+ * Research: Section 3 "Retrieval Augmented Generation Strategy"
+ * - **Vector Search**: Semantic similarity using embeddings
+ * - **BM25**: Keyword-based search for exact matches
+ * - Combined with exponential decay for time-weighted scoring
+ *
+ * ### 4. Exponential Decay & Forgetting
+ * Research: Section 4.2 "Mathematical Model for Memory Decay"
+ * - Memories fade over time using Ebbinghaus forgetting curve
+ * - Reinforcement: Frequently accessed memories decay slower
+ * - Configurable decay rates per memory type
+ *
+ * ### 5. Contextual Embeddings
+ * Research: Section 3.2.1 "Solving the Pronoun Problem"
+ * - Enriches content with context before embedding
+ * - Example: "It was terrible" → "[User movie preference]: The movie Inception was terrible"
+ * - Enables superior retrieval accuracy
+ *
+ * ### 6. Contradiction Detection & Resolution
+ * Research: Section 4.3 "Handling Contradictions"
+ * - Detects when new facts contradict existing ones
+ * - Uses soft-delete (isActive flag) to supersede old memories
+ * - Maintains provenance chain (supersedesId)
+ *
+ * ## Components
+ *
+ * - **MemoryService**: Core service managing all memory operations
+ * - **consolidationEvaluator**: Buffers messages and triggers fact extraction
+ * - **summarizationEvaluator**: Creates hierarchical conversation summaries
+ * - **longTermMemoryProvider** (LONG_TERM_MEMORY): User knowledge and facts
+ * - **recentContextProvider** (RECENT_CONVERSATION_SUMMARY): Conversational history with summaries
+ * - **actionResultsProvider** (ACTION_RESULTS): Recent action executions and tool memory
+ *
+ * ## Configuration (Environment Variables)
+ *
+ * All settings use `runtime.getSetting()` pattern:
+ *
+ * - `MEMORY_CONSOLIDATION_THRESHOLD`: Messages before consolidation (default: 12)
+ * - `MEMORY_MIN_CONFIDENCE`: Minimum confidence to store (default: 0.7)
+ * - `MEMORY_ENABLE_VECTOR_SEARCH`: Enable semantic search (default: true)
+ * - `MEMORY_ENABLE_BM25`: Enable keyword search (default: true)
+ * - `MEMORY_RETRIEVAL_LIMIT`: Max memories to retrieve (default: 5)
+ * - `MEMORY_TOKEN_BUDGET`: Token budget for memory context (default: 1000)
+ *
+ * ### Hierarchical Summarization
+ *
+ * - `MEMORY_SUMMARY_ENABLED`: Enable hierarchical summarization (default: true)
+ * - `MEMORY_MESSAGES_PER_SUMMARY`: Messages per Level 1 summary (default: 7)
+ * - `MEMORY_SUMMARIES_PER_LEVEL`: Summaries before next level (default: 5)
+ * - `MEMORY_SUMMARY_MAX_DEPTH`: Maximum hierarchy depth (default: 3)
+ * - `MEMORY_SUMMARY_TOKEN_BUDGET`: Token budget for summaries (default: 500)
+ * - `CONTEXT_OVERLAP_USER_MESSAGES`: User messages overlap after summary (default: 2)
+ *
+ * ## Database Tables
+ *
+ * - `long_term_memories`: Unified storage for all memory types
+ * - `conversation_summaries`: Hierarchical conversation summaries
+ *
+ * ## Design Decisions
+ *
+ * ### Why Single Unified Table?
+ * Research: Section 4.1 "Data Structure & Schema"
+ * - Easier cross-type queries
+ * - Unified retrieval logic
+ * - Flexible type reassignment (episodic can become semantic over time)
+ * - Simpler codebase
+ *
+ * ### Why Async Consolidation?
+ * Research: Section 2.3 "Consolidation Pipeline"
+ * - Doesn't block conversation flow
+ * - Allows for deeper analysis without latency
+ * - Mirrors biological "sleep" consolidation
+ *
+ * ### Why Contextual Embeddings?
+ * Research: Section 3.2.1 "Contextual Retrieval"
+ * - Solves pronoun ambiguity ("it", "that")
+ * - Improves retrieval accuracy by 49% (Anthropic research)
+ * - Self-contained memory chunks
+ *
+ * ## Usage Examples
+ *
+ * ### Accessing the Service
+ * ```typescript
+ * const memoryService = runtime.getService<MemoryService>('memory');
+ * ```
+ *
+ * ### Searching Memories
+ * ```typescript
+ * const memories = await memoryService.searchLongTermMemories({
+ *   entityId: userId,
+ *   query: "What does the user like?",
+ *   type: MemoryType.SEMANTIC,
+ *   limit: 5
+ * });
+ * ```
+ *
+ * ### Storing a Memory Manually
+ * ```typescript
+ * await memoryService.storeLongTermMemory({
+ *   agentId: runtime.agentId,
+ *   entityId: userId,
+ *   type: MemoryType.SEMANTIC,
+ *   content: "User is allergic to peanuts",
+ *   embeddingContext: "[User health information]: User is allergic to peanuts",
+ *   confidence: 1.0,
+ *   decayRate: 0.0, // Core fact, never decays
+ *   decayFunction: DecayFunction.NONE,
+ *   source: { authorId: userId },
+ *   metadata: { category: "health" }
+ * });
+ * ```
+ *
+ * ## Research References
+ *
+ * This implementation is based on the comprehensive research document (refactor.md)
+ * which analyzed 40+ academic papers and industry implementations to identify
+ * state-of-the-art techniques for agentic memory systems.
+ *
+ * Key research areas:
+ * - Cognitive science (memory hierarchies, consolidation)
+ * - RAG optimization (vector search, BM25, contextual retrieval)
+ * - Forgetting curves (Ebbinghaus, exponential decay)
+ * - LLM prompting (Chain-of-Thought, extraction patterns)
+ *
  */
 export declare const memoryPlugin: Plugin;
 export default memoryPlugin;