@elizaos/plugin-memory 1.0.5 → 2.0.1

package/dist/schemas/long-term-memories.d.ts

@@ -1,6 +1,17 @@
 /**
- * Long-term memory storage table
- * Stores persistent facts about users across all conversations
+ * Long-term Memory Storage Table
+ *
+ * Research: Section 4.1 "The SOTA Memory Schema"
+ *
+ * This table stores ALL persistent memories (episodic, semantic, procedural) with:
+ * - Memory type taxonomy (3-tier cognitive hierarchy)
+ * - Decay parameters for exponential forgetting
+ * - Confidence and provenance tracking
+ * - Contextual embeddings for superior retrieval
+ * - Soft delete for contradiction handling
+ *
+ * Design Decision: Single unified table vs separate tables per type
+ * Rationale: Easier to query across types, unified retrieval logic, flexible type reassignment
  */
 export declare const longTermMemories: import("drizzle-orm/pg-core").PgTableWithColumns<{
     name: "long_term_memories";
@@ -63,8 +74,27 @@ export declare const longTermMemories: import("drizzle-orm/pg-core").PgTableWith
         }, {}, {
             length: 36;
         }>;
-        category: import("drizzle-orm/pg-core").PgColumn<{
-            name: "category";
+        roomId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "room_id";
+            tableName: "long_term_memories";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 36;
+        }>;
+        type: import("drizzle-orm/pg-core").PgColumn<{
+            name: "type";
             tableName: "long_term_memories";
             dataType: "string";
             columnType: "PgText";
@@ -97,74 +127,48 @@ export declare const longTermMemories: import("drizzle-orm/pg-core").PgTableWith
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-        metadata: import("drizzle-orm/pg-core").PgColumn<{
-            name: "metadata";
+        embeddingContext: import("drizzle-orm/pg-core").PgColumn<{
+            name: "embedding_context";
             tableName: "long_term_memories";
-            dataType: "json";
-            columnType: "PgJsonb";
-            data: unknown;
-            driverParam: unknown;
-            notNull: false;
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
             hasDefault: false;
             isPrimaryKey: false;
             isAutoincrement: false;
             hasRuntimeDefault: false;
-            enumValues: undefined;
+            enumValues: [string, ...string[]];
             baseColumn: never;
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-        embedding: import("drizzle-orm/pg-core").PgColumn<{
-            name: "embedding";
+        confidence: import("drizzle-orm/pg-core").PgColumn<{
+            name: "confidence";
             tableName: "long_term_memories";
-            dataType: "array";
-            columnType: "PgArray";
-            data: number[];
-            driverParam: string | (string | number)[];
-            notNull: false;
-            hasDefault: false;
+            dataType: "number";
+            columnType: "PgReal";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
             isPrimaryKey: false;
             isAutoincrement: false;
             hasRuntimeDefault: false;
             enumValues: undefined;
-            baseColumn: import("drizzle-orm").Column<{
-                name: "embedding";
-                tableName: "long_term_memories";
-                dataType: "number";
-                columnType: "PgReal";
-                data: number;
-                driverParam: string | number;
-                notNull: false;
-                hasDefault: false;
-                isPrimaryKey: false;
-                isAutoincrement: false;
-                hasRuntimeDefault: false;
-                enumValues: undefined;
-                baseColumn: never;
-                identity: undefined;
-                generated: undefined;
-            }, {}, {}>;
+            baseColumn: never;
             identity: undefined;
             generated: undefined;
-        }, {}, {
-            baseBuilder: import("drizzle-orm/pg-core").PgColumnBuilder<{
-                name: "embedding";
-                dataType: "number";
-                columnType: "PgReal";
-                data: number;
-                driverParam: string | number;
-                enumValues: undefined;
-            }, {}, {}, import("drizzle-orm").ColumnBuilderExtraConfig>;
-            size: undefined;
-        }>;
-        confidence: import("drizzle-orm/pg-core").PgColumn<{
-            name: "confidence";
+        }, {}, {}>;
+        decayRate: import("drizzle-orm/pg-core").PgColumn<{
+            name: "decay_rate";
             tableName: "long_term_memories";
             dataType: "number";
             columnType: "PgReal";
             data: number;
             driverParam: string | number;
-            notNull: false;
+            notNull: true;
             hasDefault: true;
             isPrimaryKey: false;
             isAutoincrement: false;
@@ -174,15 +178,15 @@ export declare const longTermMemories: import("drizzle-orm/pg-core").PgTableWith
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-        source: import("drizzle-orm/pg-core").PgColumn<{
-            name: "source";
+        decayFunction: import("drizzle-orm/pg-core").PgColumn<{
+            name: "decay_function";
             tableName: "long_term_memories";
             dataType: "string";
             columnType: "PgText";
             data: string;
             driverParam: string;
-            notNull: false;
-            hasDefault: false;
+            notNull: true;
+            hasDefault: true;
             isPrimaryKey: false;
             isAutoincrement: false;
             hasRuntimeDefault: false;
@@ -208,13 +212,30 @@ export declare const longTermMemories: import("drizzle-orm/pg-core").PgTableWith
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-        updatedAt: import("drizzle-orm/pg-core").PgColumn<{
-            name: "updated_at";
+        lastAccessedAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "last_accessed_at";
             tableName: "long_term_memories";
             dataType: "date";
             columnType: "PgTimestamp";
             data: Date;
             driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        accessCount: import("drizzle-orm/pg-core").PgColumn<{
+            name: "access_count";
+            tableName: "long_term_memories";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
             notNull: true;
             hasDefault: true;
             isPrimaryKey: false;
@@ -225,12 +246,132 @@ export declare const longTermMemories: import("drizzle-orm/pg-core").PgTableWith
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-        lastAccessedAt: import("drizzle-orm/pg-core").PgColumn<{
-            name: "last_accessed_at";
+        isActive: import("drizzle-orm/pg-core").PgColumn<{
+            name: "is_active";
             tableName: "long_term_memories";
-            dataType: "date";
-            columnType: "PgTimestamp";
-            data: Date;
+            dataType: "boolean";
+            columnType: "PgBoolean";
+            data: boolean;
+            driverParam: boolean;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        source: import("drizzle-orm/pg-core").PgColumn<{
+            name: "source";
+            tableName: "long_term_memories";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: unknown;
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        metadata: import("drizzle-orm/pg-core").PgColumn<{
+            name: "metadata";
+            tableName: "long_term_memories";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: unknown;
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        supersedesId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "supersedes_id";
+            tableName: "long_term_memories";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 36;
+        }>;
+    };
+    dialect: "pg";
+}>;
+/**
+ * Long-term Memory Embeddings Table
+ * Stores vector embeddings for semantic search with dynamic dimension support
+ * Research: Section 3 "RAG Strategy"
+ */
+export declare const longTermMemoryEmbeddings: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "long_term_memory_embeddings";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "id";
+            tableName: "long_term_memory_embeddings";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 36;
+        }>;
+        memoryId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "memory_id";
+            tableName: "long_term_memory_embeddings";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 36;
+        }>;
+        dim384: import("drizzle-orm/pg-core").PgColumn<{
+            name: "dim_384";
+            tableName: "long_term_memory_embeddings";
+            dataType: "array";
+            columnType: "PgVector";
+            data: number[];
             driverParam: string;
             notNull: false;
             hasDefault: false;
@@ -241,15 +382,112 @@ export declare const longTermMemories: import("drizzle-orm/pg-core").PgTableWith
             baseColumn: never;
             identity: undefined;
             generated: undefined;
-        }, {}, {}>;
-        accessCount: import("drizzle-orm/pg-core").PgColumn<{
-            name: "access_count";
-            tableName: "long_term_memories";
-            dataType: "number";
-            columnType: "PgInteger";
-            data: number;
-            driverParam: string | number;
+        }, {}, {
+            dimensions: 384;
+        }>;
+        dim512: import("drizzle-orm/pg-core").PgColumn<{
+            name: "dim_512";
+            tableName: "long_term_memory_embeddings";
+            dataType: "array";
+            columnType: "PgVector";
+            data: number[];
+            driverParam: string;
             notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            dimensions: 512;
+        }>;
+        dim768: import("drizzle-orm/pg-core").PgColumn<{
+            name: "dim_768";
+            tableName: "long_term_memory_embeddings";
+            dataType: "array";
+            columnType: "PgVector";
+            data: number[];
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            dimensions: 768;
+        }>;
+        dim1024: import("drizzle-orm/pg-core").PgColumn<{
+            name: "dim_1024";
+            tableName: "long_term_memory_embeddings";
+            dataType: "array";
+            columnType: "PgVector";
+            data: number[];
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            dimensions: 1024;
+        }>;
+        dim1536: import("drizzle-orm/pg-core").PgColumn<{
+            name: "dim_1536";
+            tableName: "long_term_memory_embeddings";
+            dataType: "array";
+            columnType: "PgVector";
+            data: number[];
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            dimensions: 1536;
+        }>;
+        dim3072: import("drizzle-orm/pg-core").PgColumn<{
+            name: "dim_3072";
+            tableName: "long_term_memory_embeddings";
+            dataType: "array";
+            columnType: "PgVector";
+            data: number[];
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            dimensions: 3072;
+        }>;
+        createdAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "created_at";
+            tableName: "long_term_memory_embeddings";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
             hasDefault: true;
             isPrimaryKey: false;
             isAutoincrement: false;

package/dist/services/memory-service.d.ts

@@ -1,102 +1,146 @@
 import { type IAgentRuntime, Service, type UUID, type ServiceTypeName } from '@elizaos/core';
-import { type LongTermMemory, type SessionSummary, type MemoryConfig, LongTermMemoryCategory } from '../types/index';
+import type { Metadata } from '@elizaos/core';
+import { type LongTermMemory, type LongTermMemoryConfig, type LongTermMemorySearchParams, type LongTermMemoryRetrievalResult, type ConversationSummary, MemoryType } from '../types/index';
 /**
- * Memory Service
- * Manages both short-term (session summaries) and long-term (persistent facts) memory
+ * Long-Term Memory Service - State-of-the-Art Cognitive Memory System
+ *
+ * Research: Based on comprehensive analysis in refactor.md
+ *
+ * This service implements:
+ * 1. Three-tier long-term memory taxonomy (Episodic, Semantic, Procedural)
+ * 2. Memory consolidation pipeline (transient filtering)
+ * 3. Hybrid retrieval (Vector + BM25 + Graph)
+ * 4. Exponential decay for long-term memory forgetting
+ * 5. Contextual embeddings for superior retrieval
+ * 6. Contradiction detection and resolution
+ *
+ * Architecture Philosophy:
+ * - Async consolidation: Don't block the conversation loop
+ * - Decay-weighted scoring: Recent and frequently accessed long-term memories score higher
+ * - Graph-guided retrieval: Use relations for context
+ * - Confidence-based filtering: Only store high-quality extractions
  */
 export declare class MemoryService extends Service {
     static serviceType: ServiceTypeName;
-    private sessionMessageCounts;
-    private memoryConfig;
-    private lastExtractionCheckpoints;
+    config: LongTermMemoryConfig & Metadata;
+    private bm25Index;
+    private embeddingDimension?;
+    private isInitialized;
+    private longTermMemoryRepo;
+    private conversationSummaryRepo;
     capabilityDescription: string;
+    /**
+     * Default configuration based on research recommendations
+     * Research: Section 6 "Implementation Strategy"
+     */
+    private static defaultConfig;
     constructor(runtime?: IAgentRuntime);
     static start(runtime: IAgentRuntime): Promise<Service>;
     stop(): Promise<void>;
     initialize(runtime: IAgentRuntime): Promise<void>;
     /**
-     * Get the Drizzle database instance
+     * Load configuration from runtime settings
      */
-    private getDb;
+    private loadConfiguration;
     /**
-     * Get configuration
+     * Ensure embedding dimension is set dynamically based on the model
      */
-    getConfig(): MemoryConfig;
+    private ensureEmbeddingDimension;
     /**
-     * Update configuration
+     * Get current configuration
      */
-    updateConfig(updates: Partial<MemoryConfig>): void;
+    getConfig(): LongTermMemoryConfig;
     /**
-     * Track message count for a room
+     * Update configuration
      */
-    incrementMessageCount(roomId: UUID): number;
+    updateConfig(updates: Partial<LongTermMemoryConfig>): void;
     /**
-     * Reset message count for a room
+     * Store a new long-term memory
+     *
+     * Research: Section 3.2.1 "Contextual Embeddings"
      */
-    resetMessageCount(roomId: UUID): void;
+    storeLongTermMemory(memory: Omit<LongTermMemory, 'id' | 'createdAt' | 'lastAccessedAt' | 'accessCount' | 'isActive' | 'embedding'>): Promise<LongTermMemory>;
     /**
-     * Check if summarization is needed for a room
+     * Retrieve long-term memory by ID
      */
-    shouldSummarize(roomId: UUID): Promise<boolean>;
+    getLongTermMemory(id: UUID): Promise<LongTermMemory | null>;
     /**
-     * Generate cache key for tracking extraction checkpoints per entity-room pair
+     * Update an existing long-term memory
+     *
+     * Research: Section 4.3.2 "Resolution Strategies"
      */
-    private getExtractionKey;
+    updateLongTermMemory(id: UUID, updates: Partial<Omit<LongTermMemory, 'id' | 'agentId' | 'createdAt'>>): Promise<void>;
     /**
-     * Get the last extraction checkpoint for an entity in a room
-     * Uses the cache table via adapter
+     * Delete a long-term memory (hard delete)
      */
-    getLastExtractionCheckpoint(entityId: UUID, roomId: UUID): Promise<number>;
+    deleteLongTermMemory(id: UUID): Promise<void>;
     /**
-     * Set the last extraction checkpoint for an entity in a room
-     * Uses the cache table via adapter
+     * Get all long-term memories for an entity (with basic filtering)
      */
-    setLastExtractionCheckpoint(entityId: UUID, roomId: UUID, messageCount: number): Promise<void>;
+    getLongTermMemories(entityId: UUID, type?: MemoryType, limit?: number, includeInactive?: boolean): Promise<LongTermMemory[]>;
     /**
-     * Check if long-term extraction should run based on message count and interval
+     * Handle contradictory long-term memory
+     *
+     * Research: Section 4.3 "Handling Contradictions"
      */
-    shouldRunExtraction(entityId: UUID, roomId: UUID, currentMessageCount: number): Promise<boolean>;
+    handleContradiction(entityId: UUID, newMemory: Omit<LongTermMemory, 'id' | 'createdAt' | 'lastAccessedAt' | 'accessCount' | 'isActive' | 'embedding'>): Promise<void>;
     /**
-     * Store a long-term memory
+     * Detect if new memory contradicts any existing memory
+     *
+     * Research: Section 4.3.1 "Detection Logic"
      */
-    storeLongTermMemory(memory: Omit<LongTermMemory, 'id' | 'createdAt' | 'updatedAt'>): Promise<LongTermMemory>;
+    detectContradiction(newMemory: Omit<LongTermMemory, 'id' | 'createdAt' | 'lastAccessedAt' | 'accessCount' | 'isActive' | 'embedding'>, existingMemories: LongTermMemoryRetrievalResult[]): Promise<LongTermMemory | null>;
     /**
-     * Retrieve long-term memories for an entity
+     * Search long-term memories with hybrid retrieval
+     *
+     * Research: Section 3 "Retrieval Augmented Generation Strategy"
      */
-    getLongTermMemories(entityId: UUID, category?: LongTermMemoryCategory, limit?: number): Promise<LongTermMemory[]>;
+    searchLongTermMemories(params: LongTermMemorySearchParams): Promise<LongTermMemoryRetrievalResult[]>;
     /**
-     * Update a long-term memory
-     * Enforces multi-tenancy by verifying agentId and entityId
+     * Vector search implementation
      */
-    updateLongTermMemory(id: UUID, entityId: UUID, updates: Partial<Omit<LongTermMemory, 'id' | 'agentId' | 'entityId' | 'createdAt'>>): Promise<void>;
+    private vectorSearch;
     /**
-     * Delete a long-term memory
-     * Enforces multi-tenancy by verifying agentId and entityId
+     * BM25 search implementation
      */
-    deleteLongTermMemory(id: UUID, entityId: UUID): Promise<void>;
+    private bm25Search;
     /**
-     * Get the current session summary for a room (latest one)
+     * Rebuild BM25 index from database
      */
-    getCurrentSessionSummary(roomId: UUID): Promise<SessionSummary | null>;
+    private rebuildBM25Index;
     /**
-     * Store a session summary (initial creation)
+     * Get formatted memories for context injection
+     *
+     * Research: Section 5.1.3 "Tier 3: Just-In-Time Injection"
      */
-    storeSessionSummary(summary: Omit<SessionSummary, 'id' | 'createdAt' | 'updatedAt'>): Promise<SessionSummary>;
+    getFormattedLongTermMemoriesForContext(entityId: UUID, query: string, roomId?: UUID): Promise<string>;
     /**
-     * Update an existing session summary
-     * Enforces multi-tenancy by verifying agentId
+     * Store a conversation summary
+     *
+     * Research: Section 5.1.2 "Hierarchical Conversation Summarization"
      */
-    updateSessionSummary(id: UUID, roomId: UUID, updates: Partial<Omit<SessionSummary, 'id' | 'agentId' | 'roomId' | 'createdAt' | 'updatedAt'>>): Promise<void>;
+    storeSummary(summary: Omit<ConversationSummary, 'id' | 'createdAt' | 'lastAccessedAt' | 'accessCount'>): Promise<ConversationSummary>;
     /**
-     * Get session summaries for a room
+     * Get summaries at a specific level for a room
      */
-    getSessionSummaries(roomId: UUID, limit?: number): Promise<SessionSummary[]>;
+    getSummariesByLevel(roomId: UUID, level: number): Promise<ConversationSummary[]>;
     /**
-     * Search long-term memories by semantic similarity (if embeddings are available)
+     * Search summaries by semantic similarity
+     *
+     * Research: Section 5.1.2 "Tier 2: The Conversation Summary"
      */
-    searchLongTermMemories(entityId: UUID, queryEmbedding: number[], limit?: number, matchThreshold?: number): Promise<LongTermMemory[]>;
+    searchSummaries(params: {
+        entityId: UUID;
+        roomId: UUID;
+        query: string;
+        limit?: number;
+        tokenBudget?: number;
+    }): Promise<ConversationSummary[]>;
     /**
-     * Get all long-term memories formatted for context
+     * Get the most recent Level 1 summary for a room and entity
+     * Used to determine which messages have already been summarized
+     *
+     * @returns The most recent Level 1 summary, or null if none exist
      */
-    getFormattedLongTermMemories(entityId: UUID): Promise<string>;
+    getMostRecentLevel1Summary(roomId: UUID, entityId: UUID): Promise<ConversationSummary | null>;
 }