@elizaos/plugin-memory 1.1.0 → 1.1.2

package/dist/evaluators/long-term-extraction.d.ts

@@ -0,0 +1,8 @@
+import { type Evaluator } from "@elizaos/core";
+/**
+ * Long-term Memory Extraction Evaluator
+ *
+ * Analyzes conversations to extract persistent facts about users that should be remembered
+ * across all future conversations.
+ */
+export declare const longTermExtractionEvaluator: Evaluator;

package/dist/evaluators/summarization.d.ts

@@ -1,11 +1,30 @@
-import { type Evaluator } from '@elizaos/core';
+import { type Evaluator } from "@elizaos/core";
 /**
- * Hierarchical Summarization Evaluator
+ * Short-term Memory Summarization Evaluator
  *
- * Research: Section 5.1.2 "Hierarchical Episodic Summarization"
+ * Automatically generates and updates conversation summaries when conversations
+ * exceed the configured threshold (default: 16 messages).
  *
- * 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
+ * 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.
  */
 export declare const summarizationEvaluator: Evaluator;

package/dist/index.d.ts

@@ -1,160 +1,40 @@
 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 };
+export { contextSummaryProvider } from './providers/context-summary';
+export { longTermMemoryProvider } from './providers/long-term-memory';
 /**
- * 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)
- *
+ * 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
  */
 export declare const memoryPlugin: Plugin;
 export default memoryPlugin;