@elizaos/plugin-memory 1.0.5 → 2.0.1

package/dist/prompts/consolidation.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Memory Consolidation Prompts
+ *
+ * Research: Section 2.2.2 "Proposed Extraction Prompt Structure"
+ *
+ * This module contains all prompts used for memory consolidation.
+ * Prompts are structured to use Chain-of-Thought (CoT) reasoning to
+ * distinguish transient events from persistent facts.
+ *
+ * Key Principles:
+ * - Clear mission statement
+ * - Explicit definitions (transient vs persistent)
+ * - Strict extraction rules
+ * - Structured XML output (more reliable than JSON for LLMs)
+ * - CoT examples for few-shot learning
+ */
+/**
+ * System prompt for the consolidation engine
+ *
+ * This replaces runtime.character.system temporarily during consolidation
+ */
+export declare const CONSOLIDATION_SYSTEM_PROMPT = "You are the \"Cortex\" \u2014 an advanced Memory Extraction Engine.\nYour function is to parse conversation logs and extract persistent facts into a structured database format.\n\n# CORE DIRECTIVE: \"Subject-First\" Extraction\nYou must rephrase memories to focus on the *topic*, not the user. This optimizes vector retrieval.\n- BAD: \"User likes to trade Bitcoin.\" (Too generic)\n- GOOD: \"Bitcoin (BTC) is a preferred trading asset.\" (Topic-focused)\n\n# COMPRESSION RULES (CRITICAL)\n1. **Aggressive Filtering**: Most user chatter is noise. If it won't be relevant in 30 days, DO NOT extract it.\n2. **Merge & Dedupe**: Do not create three separate memories for one topic. Combine them.\n   - *Input:* \"I like Red. I also like Blue. And Green.\"\n   - *Output:* \"Red, Blue, and Green are the preferred colors.\"\n3. **Conflict Resolution**: If a new fact contradicts an old one, mark 'isContradiction' as true.\n\n# OUTPUT FORMAT\nPhase 1: [ANALYSIS]\n- List extracted points.\n- MARK items as [TRANSIENT] (Ignore) or [MERGE] (Combine).\n- Refine the final wording.\n\nPhase 2: [MEMORIES]\nFormat: `MEM|TYPE|CATEGORY|CONFIDENCE|IS_CONTRADICTION|CONTENT`\n\nTypes: EPISODIC, SEMANTIC, PROCEDURAL\nCategories: bio, health, finance, preferences, relationships, skills, work\n";
+export declare function buildExtractionPrompt(conversationLog: string): string;
+/**
+ * Contradiction detection prompt
+ *
+ * Research: Section 4.3.1 "Detection Logic"
+ *
+ * Used to determine if a new memory contradicts existing memories
+ */
+export declare function buildContradictionPrompt(newMemoryContent: string, existingMemories: Array<{
+    content: string;
+    confidence: number;
+    createdAt: string;
+}>): string;

package/dist/prompts/summarization.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Hierarchical Summarization Prompts
+ *
+ * Research: Section 5.1.2 "Hierarchical Episodic Summarization"
+ *
+ * These prompts implement recursive, multi-level summarization:
+ * - Level 1: Summarize raw messages into narrative paragraphs
+ * - Level 2+: Summarize lower-level summaries into higher-level abstractions
+ *
+ * Goal: Achieve 10x token compression while preserving conversational narrative
+ */
+/**
+ * System prompt for Level 1 summarization (messages → summary)
+ */
+export declare const SUMMARIZATION_SYSTEM_PROMPT = "You are \"Chronos\", a master summarizer.\nYour function is to condense conversation logs into concise, subject-first narrative summaries.\n\n# CORE DIRECTIVE: \"Subject-First\" Summarization\nYou must rephrase the narrative to focus on the *topic*, not the user. This optimizes vector retrieval.\n- BAD: \"User asked about Python.\" (Too generic)\n- GOOD: \"Python programming inquiries were addressed.\" (Topic-focused)\n\n# COMPRESSION RULES\n1. **Be Concise**: Target 2-4 sentences. Maximum 100 words.\n2. **Be Factual**: No interpretation, no speculation. Only what actually happened.\n3. **Be Narrative**: Write as a story, not a bullet list.\n4. **Preserve Key Facts**: If the user revealed important information (preferences, identity, needs), include it.\n5. **Exclude Trivia**: Skip greetings, acknowledgments, and filler conversation.\n\n# OUTPUT FORMAT\nPhase 1: [ANALYSIS]\n- Identify key topics.\n- Draft the summary.\n- Refine wording to be subject-first.\n\nPhase 2: [RESULT]\nFormat: `SUMM|TAGS|CONTENT`\n- TAGS: Comma-separated list of key topics (lowercase)\n- CONTENT: The narrative summary text (must be a single line, no newlines)\n";
+export declare function buildLevel1SummaryPrompt(formattedMessages: string, previousSummary?: string): string;
+/**
+ * System prompt for Level 2+ summarization (summaries → meta-summary)
+ */
+export declare const HIGHER_LEVEL_SUMMARIZATION_SYSTEM_PROMPT = "You are \"Chronos\", a Meta-Summarization Agent.\nYour task is to compress multiple conversation summaries into a single, higher-level summary.\n\n# MISSION\nTransform a list of conversation summaries into one concise meta-summary that captures:\n1. **Overarching themes** across the summaries\n2. **Key events or milestones** (e.g., \"User onboarded\", \"Project completed\")\n3. **Evolving context** (e.g., \"User's preferences shifted from X to Y\")\n\n# RULES\n- **Subject-First**: Focus on the topic, not the user.\n- **Abstract Higher**: Don't repeat specifics from each summary. Find the pattern.\n- **Chronological Flow**: Maintain temporal order if it matters.\n- **Preserve Critical Facts**: If summaries mention important identity or preferences, keep them.\n\n# OUTPUT FORMAT\nPhase 1: [ANALYSIS]\n- Identify themes and milestones.\n- Combine related points.\n- Refine to subject-first.\n\nPhase 2: [RESULT]\nFormat: `SUMM|TAGS|CONTENT`\n- TAGS: Comma-separated list of key topics (lowercase)\n- CONTENT: The meta-summary text (must be a single line, no newlines)\n";
+export declare function buildHigherLevelSummaryPrompt(formattedSummaries: string): string;
+/**
+ * Estimate token count from text (used as fallback)
+ */
+export declare function estimateTokensInSummary(text: string): number;

package/dist/providers/action-results.d.ts

@@ -0,0 +1,2 @@
+import { type Provider } from '@elizaos/core';
+export declare const actionResultsProvider: Provider;

package/dist/providers/long-term-memory.d.ts

@@ -1,17 +1,24 @@
 import { type Provider } from '@elizaos/core';
 /**
- * Long-term Memory Provider
+ * Long-Term Memory Provider (Facts Only)
  *
- * Provides persistent facts about the user that have been learned across
- * all conversations. This includes:
- * - User identity and roles
- * - Domain expertise
- * - Preferences
- * - Goals and projects
- * - Custom definitions
- * - Behavioral patterns
+ * Research: Section 3 "RAG Strategy" - Semantic & Procedural Knowledge
  *
- * This provider enriches the context with relevant long-term information
- * to make the agent's responses more personalized and contextually aware.
+ * This provider focuses ONLY on persistent knowledge about the user:
+ * - **Semantic Facts**: Timeless information (preferences, identity, skills)
+ * - **Procedural Patterns**: How the user does things, tool preferences
+ *
+ * DOES NOT INCLUDE:
+ * - Recent messages (handled by RECENT_CONTEXT)
+ * - Conversation summaries (handled by RECENT_CONTEXT)
+ * - Current message (handled by RECENT_CONTEXT)
+ *
+ * Design Philosophy:
+ * - Pure knowledge retrieval (no conversational context)
+ * - Used in FINAL response phase (after planning)
+ * - Provides "who is this user" context
+ *
+ * Template Variables Provided:
+ * - `longTermMemories`: Formatted semantic/procedural facts
  */
 export declare const longTermMemoryProvider: Provider;

package/dist/providers/recent-conversation-summary.d.ts

@@ -0,0 +1,2 @@
+import { type Provider } from '@elizaos/core';
+export declare const recentContextProvider: Provider;

package/dist/repositories/conversation-summary.d.ts

@@ -0,0 +1,33 @@
+import type { IAgentRuntime, UUID } from '@elizaos/core';
+import { type ConversationSummary, type EmbeddingDimensionColumn } from '../types/index';
+/**
+ * Conversation Summary Repository
+ *
+ * Research: Section 5.1.2 "Hierarchical Conversation Summarization"
+ * Handles database operations for conversation summaries
+ */
+export declare class ConversationSummaryRepository {
+    private runtime;
+    private embeddingDimension?;
+    constructor(runtime: IAgentRuntime, embeddingDimension?: EmbeddingDimensionColumn);
+    /**
+     * Get database instance with health check
+     */
+    private getDb;
+    /**
+     * Insert a new summary
+     */
+    insert(summary: Omit<ConversationSummary, 'id' | 'createdAt' | 'lastAccessedAt' | 'accessCount'>, embedding?: number[]): Promise<ConversationSummary>;
+    /**
+     * Find summaries by level
+     */
+    findByLevel(roomId: UUID, level: number): Promise<ConversationSummary[]>;
+    /**
+     * Vector search for summaries
+     */
+    vectorSearch(entityId: UUID, roomId: UUID, queryEmbedding: number[], limit?: number): Promise<ConversationSummary[]>;
+    /**
+     * Update access metadata for summaries
+     */
+    updateAccessMetadata(summaryIds: UUID[]): Promise<void>;
+}

package/dist/repositories/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Repository Layer for Memory Plugin
+ *
+ * This module provides data access repositories that encapsulate
+ * all database operations for the memory system.
+ *
+ * Repositories handle:
+ * - Database connection management
+ * - CRUD operations
+ * - Query building
+ * - Transaction management
+ * - Health checks for long-running operations
+ *
+ * Research: Clean Architecture - Separation of data access from business logic
+ */
+export * from './long-term-memory';
+export * from './conversation-summary';

package/dist/repositories/long-term-memory.d.ts

@@ -0,0 +1,53 @@
+import type { IAgentRuntime, UUID } from '@elizaos/core';
+import { type LongTermMemory, type LongTermMemoryRetrievalResult, type LongTermMemorySearchParams, type EmbeddingDimensionColumn, MemoryType } from '../types/index';
+/**
+ * Long-Term Memory Repository
+ *
+ * Handles all database operations for long-term memories
+ * Provides clean data access layer separated from business logic
+ */
+export declare class LongTermMemoryRepository {
+    private runtime;
+    private embeddingDimension?;
+    constructor(runtime: IAgentRuntime, embeddingDimension?: EmbeddingDimensionColumn);
+    /**
+     * Get database instance with health check
+     */
+    private getDb;
+    /**
+     * Insert a new memory into database
+     */
+    insert(memory: Omit<LongTermMemory, 'id' | 'createdAt' | 'lastAccessedAt' | 'accessCount' | 'isActive' | 'embedding'>, embedding?: number[]): Promise<LongTermMemory>;
+    /**
+     * Find memory by ID
+     */
+    findById(id: UUID): Promise<LongTermMemory | null>;
+    /**
+     * Update existing memory
+     */
+    update(id: UUID, updates: Partial<LongTermMemory>, newEmbedding?: number[]): Promise<void>;
+    /**
+     * Delete memory (hard delete)
+     */
+    delete(id: UUID): Promise<void>;
+    /**
+     * Find memories by entity with optional filters
+     */
+    findByEntity(entityId: UUID, type?: MemoryType, limit?: number, includeInactive?: boolean): Promise<LongTermMemory[]>;
+    /**
+     * Vector search for memories
+     */
+    vectorSearch(params: LongTermMemorySearchParams, queryEmbedding: number[], similarityThreshold?: number): Promise<LongTermMemoryRetrievalResult[]>;
+    /**
+     * Fetch all active memories for BM25 indexing
+     */
+    fetchAllActive(): Promise<Array<{
+        id: UUID;
+        content: string;
+        embeddingContext: string;
+    }>>;
+    /**
+     * Update access metadata (lastAccessedAt and accessCount)
+     */
+    updateAccessMetadata(memoryIds: UUID[]): Promise<void>;
+}