@mce-bt/microagents-memory 0.1.0

package/dist/ltm.js

@@ -0,0 +1,223 @@
+import pg from 'pg';
+const { Pool } = pg;
+/**
+ * Long-Term Memory (LTM) — PostgreSQL + pgvector knowledge store.
+ *
+ * Stores persistent semantic knowledge with embeddings for RAG retrieval.
+ * Where durable learning lives. Categorized, tagged, searchable.
+ */
+export class LongTermMemory {
+    pool = null;
+    config;
+    agentId = '';
+    embeddingDimensions;
+    constructor(config) {
+        this.config = config;
+        this.embeddingDimensions = config.embeddingDimensions ?? 1536;
+    }
+    async start(agentId) {
+        this.agentId = agentId;
+        this.pool = new Pool({ connectionString: this.config.connectionString });
+        await this.ensureSchema();
+    }
+    async stop() {
+        if (this.pool) {
+            await this.pool.end();
+            this.pool = null;
+        }
+    }
+    async ensureSchema() {
+        if (!this.pool)
+            return;
+        // Enable pgvector extension
+        await this.pool.query('CREATE EXTENSION IF NOT EXISTS vector');
+        await this.pool.query(`
+      CREATE TABLE IF NOT EXISTS ltm_knowledge (
+        id TEXT PRIMARY KEY,
+        agent_id TEXT NOT NULL,
+        content TEXT NOT NULL,
+        category TEXT NOT NULL DEFAULT 'general',
+        tags TEXT[] DEFAULT '{}',
+        embedding vector(${this.embeddingDimensions}),
+        metadata JSONB DEFAULT '{}',
+        created_at TIMESTAMPTZ DEFAULT NOW(),
+        updated_at TIMESTAMPTZ DEFAULT NOW()
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_ltm_agent_id ON ltm_knowledge(agent_id);
+      CREATE INDEX IF NOT EXISTS idx_ltm_category ON ltm_knowledge(category);
+      CREATE INDEX IF NOT EXISTS idx_ltm_tags ON ltm_knowledge USING GIN(tags);
+    `);
+        // Create vector index for similarity search (IVFFlat for performance)
+        // Only create if enough rows exist; otherwise use default sequential scan
+        try {
+            await this.pool.query(`
+        CREATE INDEX IF NOT EXISTS idx_ltm_embedding
+        ON ltm_knowledge USING ivfflat (embedding vector_cosine_ops)
+        WITH (lists = 100)
+      `);
+        }
+        catch {
+            // IVFFlat index requires data to build; will be created later
+        }
+    }
+    /**
+     * Store a knowledge fact with optional embedding.
+     */
+    async store(fact) {
+        if (!this.pool)
+            throw new Error('LTM not started');
+        const id = `kf-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        const embeddingStr = fact.embedding
+            ? `[${fact.embedding.join(',')}]`
+            : null;
+        await this.pool.query(`INSERT INTO ltm_knowledge (id, agent_id, content, category, tags, embedding, metadata)
+       VALUES ($1, $2, $3, $4, $5, $6::vector, $7)`, [
+            id,
+            this.agentId,
+            fact.content,
+            fact.category ?? 'general',
+            fact.tags ?? [],
+            embeddingStr,
+            JSON.stringify(fact.metadata ?? {}),
+        ]);
+        return id;
+    }
+    /**
+     * Semantic similarity search using embedding vector.
+     */
+    async search(queryEmbedding, options = {}) {
+        if (!this.pool)
+            throw new Error('LTM not started');
+        const conditions = ['embedding IS NOT NULL'];
+        const params = [];
+        let idx = 1;
+        conditions.push(`agent_id = $${idx}`);
+        params.push(options.agentId ?? this.agentId);
+        idx++;
+        if (options.category) {
+            conditions.push(`category = $${idx}`);
+            params.push(options.category);
+            idx++;
+        }
+        if (options.tags && options.tags.length > 0) {
+            conditions.push(`tags && $${idx}`);
+            params.push(options.tags);
+            idx++;
+        }
+        const embeddingStr = `[${queryEmbedding.join(',')}]`;
+        const limit = options.limit ?? 10;
+        const threshold = options.threshold ?? 0.7;
+        const where = conditions.join(' AND ');
+        const result = await this.pool.query(`SELECT *,
+              1 - (embedding <=> $${idx}::vector) as similarity
+       FROM ltm_knowledge
+       WHERE ${where}
+         AND 1 - (embedding <=> $${idx}::vector) >= $${idx + 1}
+       ORDER BY embedding <=> $${idx}::vector
+       LIMIT $${idx + 2}`, [...params, embeddingStr, threshold, limit]);
+        return result.rows.map((row) => ({
+            ...this.rowToFact(row),
+            similarity: parseFloat(row.similarity),
+        }));
+    }
+    /**
+     * Full-text search (keyword-based, no embedding needed).
+     */
+    async searchByText(query, options = {}) {
+        if (!this.pool)
+            throw new Error('LTM not started');
+        const conditions = [];
+        const params = [];
+        let idx = 1;
+        conditions.push(`agent_id = $${idx}`);
+        params.push(this.agentId);
+        idx++;
+        conditions.push(`content ILIKE $${idx}`);
+        params.push(`%${query}%`);
+        idx++;
+        if (options.category) {
+            conditions.push(`category = $${idx}`);
+            params.push(options.category);
+            idx++;
+        }
+        if (options.tags && options.tags.length > 0) {
+            conditions.push(`tags && $${idx}`);
+            params.push(options.tags);
+            idx++;
+        }
+        const limit = options.limit ?? 10;
+        const where = conditions.join(' AND ');
+        const result = await this.pool.query(`SELECT * FROM ltm_knowledge WHERE ${where} ORDER BY updated_at DESC LIMIT $${idx}`, [...params, limit]);
+        return result.rows.map(this.rowToFact);
+    }
+    /**
+     * Get a fact by ID.
+     */
+    async getById(id) {
+        if (!this.pool)
+            throw new Error('LTM not started');
+        const result = await this.pool.query('SELECT * FROM ltm_knowledge WHERE id = $1', [id]);
+        if (result.rows.length === 0)
+            return null;
+        return this.rowToFact(result.rows[0]);
+    }
+    /**
+     * Update a fact's content and optionally its embedding.
+     */
+    async update(id, updates) {
+        if (!this.pool)
+            throw new Error('LTM not started');
+        const sets = ['updated_at = NOW()'];
+        const params = [];
+        let idx = 1;
+        if (updates.content !== undefined) {
+            sets.push(`content = $${idx}`);
+            params.push(updates.content);
+            idx++;
+        }
+        if (updates.category !== undefined) {
+            sets.push(`category = $${idx}`);
+            params.push(updates.category);
+            idx++;
+        }
+        if (updates.tags !== undefined) {
+            sets.push(`tags = $${idx}`);
+            params.push(updates.tags);
+            idx++;
+        }
+        if (updates.embedding !== undefined) {
+            sets.push(`embedding = $${idx}::vector`);
+            params.push(`[${updates.embedding.join(',')}]`);
+            idx++;
+        }
+        if (updates.metadata !== undefined) {
+            sets.push(`metadata = $${idx}`);
+            params.push(JSON.stringify(updates.metadata));
+            idx++;
+        }
+        params.push(id);
+        await this.pool.query(`UPDATE ltm_knowledge SET ${sets.join(', ')} WHERE id = $${idx}`, params);
+    }
+    /**
+     * Delete a fact.
+     */
+    async forget(id) {
+        if (!this.pool)
+            throw new Error('LTM not started');
+        await this.pool.query('DELETE FROM ltm_knowledge WHERE id = $1', [id]);
+    }
+    rowToFact(row) {
+        return {
+            id: row.id,
+            agentId: row.agent_id,
+            content: row.content,
+            category: row.category,
+            tags: row.tags,
+            metadata: (row.metadata ?? {}),
+            createdAt: new Date(row.created_at),
+            updatedAt: new Date(row.updated_at),
+        };
+    }
+}
+//# sourceMappingURL=ltm.js.map

package/dist/ltm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ltm.js","sourceRoot":"","sources":["../src/ltm.ts"],"names":[],"mappings":"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"}

package/dist/manager.d.ts

@@ -0,0 +1,80 @@
+import { ShortTermMemory, type STMConfig } from './stm.js';
+import { MidTermMemory, type MTMConfig } from './mtm.js';
+import { LongTermMemory, type LTMConfig } from './ltm.js';
+import { KnowledgeGraph, type KGConfig } from './knowledge-graph.js';
+import type { MemoryEntry } from '@mce-bt/microagents-core';
+export interface MemoryManagerConfig {
+    stm: STMConfig;
+    mtm: MTMConfig;
+    ltm: LTMConfig;
+    /** Optional knowledge graph config. When provided, enables KG features. */
+    kg?: KGConfig;
+}
+export interface ContextBlock {
+    source: 'system' | 'stm' | 'mtm' | 'ltm' | 'kg';
+    content: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Unified Memory Manager — orchestrates all 3 memory tiers.
+ *
+ * Provides a single API for agents to interact with memory,
+ * plus a buildContext() method that assembles LLM context from
+ * all relevant memory sources.
+ */
+export declare class MemoryManager {
+    readonly stm: ShortTermMemory;
+    readonly mtm: MidTermMemory;
+    readonly ltm: LongTermMemory;
+    readonly kg: KnowledgeGraph | null;
+    private agentId;
+    constructor(config: MemoryManagerConfig);
+    start(agentId: string): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * Log an entry to the session's short-term memory.
+     * Convenience method that delegates to STM.
+     */
+    log(sessionId: string, entry: Omit<MemoryEntry, 'id' | 'sessionId' | 'agentId' | 'timestamp'>): Promise<void>;
+    /**
+     * Build the full context for an LLM call by merging:
+     * 1. STM: current session messages
+     * 2. MTM: relevant recent episodes
+     * 3. LTM: semantically relevant knowledge (if embedder provided)
+     */
+    buildContext(options: {
+        sessionId: string;
+        queryEmbedding?: number[];
+        mtmOptions?: {
+            domain?: string;
+            tags?: string[];
+            limit?: number;
+        };
+        ltmOptions?: {
+            category?: string;
+            tags?: string[];
+            limit?: number;
+            threshold?: number;
+        };
+        kgOptions?: {
+            query?: string;
+            entityType?: string;
+            limit?: number;
+        };
+        maxStmEntries?: number;
+    }): Promise<ContextBlock[]>;
+    /**
+     * Summarize a session's STM into an MTM episode.
+     * Called on session close or by a background process.
+     */
+    summarizeSession(sessionId: string, summary: string, options?: {
+        tags?: string[];
+        domain?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<string>;
+    private formatStmEntries;
+    private formatMtmEpisodes;
+    private formatLtmFacts;
+    private formatKgEntities;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../src/manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,KAAK,SAAS,EAAE,MAAM,UAAU,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,KAAK,SAAS,EAAuB,MAAM,UAAU,CAAC;AAC9E,OAAO,EAAE,cAAc,EAAE,KAAK,SAAS,EAAsB,MAAM,UAAU,CAAC;AAC9E,OAAO,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,SAAS,CAAC;IACf,GAAG,EAAE,SAAS,CAAC;IACf,GAAG,EAAE,SAAS,CAAC;IACf,2EAA2E;IAC3E,EAAE,CAAC,EAAE,QAAQ,CAAC;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,QAAQ,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,IAAI,CAAC;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;;;;;GAMG;AACH,qBAAa,aAAa;IACxB,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;IAC7B,QAAQ,CAAC,EAAE,EAAE,cAAc,GAAG,IAAI,CAAC;IACnC,OAAO,CAAC,OAAO,CAAc;gBAEjB,MAAM,EAAE,mBAAmB;IAOjC,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWrC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAU3B;;;OAGG;IACG,GAAG,CACP,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,GAAG,WAAW,GAAG,SAAS,GAAG,WAAW,CAAC,GACrE,OAAO,CAAC,IAAI,CAAC;IAIhB;;;;;OAKG;IACG,YAAY,CAAC,OAAO,EAAE;QAC1B,SAAS,EAAE,MAAM,CAAC;QAClB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;QAC1B,UAAU,CAAC,EAAE;YACX,MAAM,CAAC,EAAE,MAAM,CAAC;YAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;YAChB,KAAK,CAAC,EAAE,MAAM,CAAC;SAChB,CAAC;QACF,UAAU,CAAC,EAAE;YACX,QAAQ,CAAC,EAAE,MAAM,CAAC;YAClB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;YAChB,KAAK,CAAC,EAAE,MAAM,CAAC;YACf,SAAS,CAAC,EAAE,MAAM,CAAC;SACpB,CAAC;QACF,SAAS,CAAC,EAAE;YACV,KAAK,CAAC,EAAE,MAAM,CAAC;YACf,UAAU,CAAC,EAAE,MAAM,CAAC;YACpB,KAAK,CAAC,EAAE,MAAM,CAAC;SAChB,CAAC;QACF,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IA2E3B;;;OAGG;IACG,gBAAgB,CACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QACP,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC/B,GACL,OAAO,CAAC,MAAM,CAAC;IAwBlB,OAAO,CAAC,gBAAgB;IASxB,OAAO,CAAC,iBAAiB;IAUzB,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,gBAAgB;CAmBzB"}

package/dist/manager.js

@@ -0,0 +1,182 @@
+import { ShortTermMemory } from './stm.js';
+import { MidTermMemory } from './mtm.js';
+import { LongTermMemory } from './ltm.js';
+import { KnowledgeGraph } from './knowledge-graph.js';
+/**
+ * Unified Memory Manager — orchestrates all 3 memory tiers.
+ *
+ * Provides a single API for agents to interact with memory,
+ * plus a buildContext() method that assembles LLM context from
+ * all relevant memory sources.
+ */
+export class MemoryManager {
+    stm;
+    mtm;
+    ltm;
+    kg;
+    agentId = '';
+    constructor(config) {
+        this.stm = new ShortTermMemory(config.stm);
+        this.mtm = new MidTermMemory(config.mtm);
+        this.ltm = new LongTermMemory(config.ltm);
+        this.kg = config.kg ? new KnowledgeGraph(config.kg) : null;
+    }
+    async start(agentId) {
+        this.agentId = agentId;
+        const inits = [
+            this.stm.start(agentId),
+            this.mtm.start(agentId),
+            this.ltm.start(agentId),
+        ];
+        if (this.kg)
+            inits.push(this.kg.start(agentId));
+        await Promise.all(inits);
+    }
+    async stop() {
+        const stops = [
+            this.stm.stop(),
+            this.mtm.stop(),
+            this.ltm.stop(),
+        ];
+        if (this.kg)
+            stops.push(this.kg.stop());
+        await Promise.all(stops);
+    }
+    /**
+     * Log an entry to the session's short-term memory.
+     * Convenience method that delegates to STM.
+     */
+    async log(sessionId, entry) {
+        await this.stm.log(sessionId, entry);
+    }
+    /**
+     * Build the full context for an LLM call by merging:
+     * 1. STM: current session messages
+     * 2. MTM: relevant recent episodes
+     * 3. LTM: semantically relevant knowledge (if embedder provided)
+     */
+    async buildContext(options) {
+        const blocks = [];
+        // STM: session log
+        const stmEntries = options.maxStmEntries
+            ? await this.stm.getRecentEntries(options.sessionId, options.maxStmEntries)
+            : await this.stm.getSessionLog(options.sessionId);
+        if (stmEntries.length > 0) {
+            blocks.push({
+                source: 'stm',
+                content: this.formatStmEntries(stmEntries),
+                metadata: { entryCount: stmEntries.length },
+            });
+        }
+        // MTM: recent episodes
+        const episodes = await this.mtm.getRecent({
+            domain: options.mtmOptions?.domain,
+            tags: options.mtmOptions?.tags,
+            limit: options.mtmOptions?.limit ?? 5,
+        });
+        if (episodes.length > 0) {
+            blocks.push({
+                source: 'mtm',
+                content: this.formatMtmEpisodes(episodes),
+                metadata: { episodeCount: episodes.length },
+            });
+        }
+        // LTM: semantic knowledge
+        if (options.queryEmbedding) {
+            const facts = await this.ltm.search(options.queryEmbedding, {
+                category: options.ltmOptions?.category,
+                tags: options.ltmOptions?.tags,
+                limit: options.ltmOptions?.limit ?? 5,
+                threshold: options.ltmOptions?.threshold ?? 0.7,
+            });
+            if (facts.length > 0) {
+                blocks.push({
+                    source: 'ltm',
+                    content: this.formatLtmFacts(facts),
+                    metadata: { factCount: facts.length },
+                });
+            }
+        }
+        // KG: knowledge graph entities & relations
+        if (this.kg && options.kgOptions?.query) {
+            const entities = await this.kg.searchEntities({
+                query: options.kgOptions.query,
+                entityType: options.kgOptions.entityType,
+                limit: options.kgOptions.limit ?? 5,
+            });
+            if (entities.length > 0) {
+                const entitiesWithRelations = await Promise.all(entities.map(async (entity) => {
+                    const relations = await this.kg.getEntityRelations(entity.name);
+                    return { entity, relations };
+                }));
+                blocks.push({
+                    source: 'kg',
+                    content: this.formatKgEntities(entitiesWithRelations),
+                    metadata: { entityCount: entities.length },
+                });
+            }
+        }
+        return blocks;
+    }
+    /**
+     * Summarize a session's STM into an MTM episode.
+     * Called on session close or by a background process.
+     */
+    async summarizeSession(sessionId, summary, options = {}) {
+        const stmEntries = await this.stm.getSessionLog(sessionId);
+        const startedAt = stmEntries.length > 0
+            ? new Date(stmEntries[0].timestamp)
+            : new Date();
+        const endedAt = stmEntries.length > 0
+            ? new Date(stmEntries[stmEntries.length - 1].timestamp)
+            : new Date();
+        return this.mtm.storeSummary({
+            agentId: this.agentId,
+            sessionId,
+            summary,
+            tags: options.tags ?? [],
+            domain: options.domain ?? null,
+            startedAt,
+            endedAt,
+            metadata: options.metadata ?? {},
+        });
+    }
+    // ─── Formatters ───
+    formatStmEntries(entries) {
+        return entries
+            .map((e) => {
+            const ts = new Date(e.timestamp).toISOString();
+            return `[${ts}] [${e.type}] ${e.content}`;
+        })
+            .join('\n');
+    }
+    formatMtmEpisodes(episodes) {
+        return episodes
+            .map((ep) => {
+            const date = ep.startedAt.toISOString().split('T')[0];
+            const tags = ep.tags.length > 0 ? ` [${ep.tags.join(', ')}]` : '';
+            return `[${date}]${tags} ${ep.summary}`;
+        })
+            .join('\n\n');
+    }
+    formatLtmFacts(facts) {
+        return facts
+            .map((f) => `[${f.category}] (relevance: ${(f.similarity * 100).toFixed(0)}%) ${f.content}`)
+            .join('\n\n');
+    }
+    formatKgEntities(items) {
+        return items
+            .map(({ entity, relations }) => {
+            const lines = [
+                `[${entity.entityType}] ${entity.name}`,
+                ...entity.observations.map((o) => `  - ${o}`),
+            ];
+            for (const r of relations) {
+                lines.push(`  → ${r.fromName} -[${r.relationType}]-> ${r.toName}`);
+            }
+            return lines.join('\n');
+        })
+            .join('\n\n');
+    }
+}
+//# sourceMappingURL=manager.js.map

package/dist/manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.js","sourceRoot":"","sources":["../src/manager.ts"],"names":[],"mappings":"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"}

package/dist/memory-extractor.d.ts

@@ -0,0 +1,75 @@
+import type { KnowledgeGraph } from './knowledge-graph.js';
+import type { MemoryEntry } from '@mce-bt/microagents-core';
+export interface ExtractedEntity {
+    name: string;
+    entityType: string;
+    observations: string[];
+}
+export interface ExtractedRelation {
+    from: string;
+    to: string;
+    relationType: string;
+}
+export interface ExtractionResult {
+    entities: ExtractedEntity[];
+    relations: ExtractedRelation[];
+}
+export interface ExtractionStats {
+    entitiesCreated: number;
+    entitiesUpdated: number;
+    relationsCreated: number;
+    relationsSuperseded: number;
+    durationMs: number;
+}
+/**
+ * LLM adapter interface for memory extraction.
+ * The extraction pipeline calls this to extract structured data from text.
+ */
+export interface ExtractionLLMAdapter {
+    /**
+     * Extract entities and relations from conversation text.
+     * Must return valid JSON matching ExtractionResult.
+     */
+    extract(systemPrompt: string, text: string): Promise<ExtractionResult>;
+}
+/**
+ * Simple extraction adapter that uses a completion function.
+ * Wraps any LLM completion call into the ExtractionLLMAdapter interface.
+ */
+export declare function createExtractionAdapter(completeFn: (messages: Array<{
+    role: string;
+    content: string;
+}>) => Promise<string>): ExtractionLLMAdapter;
+/**
+ * Memory Extraction Pipeline — Extracts structured knowledge from conversations.
+ *
+ * Inspired by Mem0's automatic extraction pattern. Uses an LLM to analyze
+ * conversation logs and extract entities, observations, and relations,
+ * then stores them in the knowledge graph with temporal validity.
+ */
+export declare class MemoryExtractor {
+    private kg;
+    private llm;
+    private logger?;
+    constructor(kg: KnowledgeGraph, llm: ExtractionLLMAdapter, logger?: MemoryExtractor['logger']);
+    /**
+     * Extract knowledge from a list of memory entries (e.g., a session log).
+     * Formats entries into text, sends to LLM for extraction, then stores results.
+     */
+    extractFromEntries(entries: MemoryEntry[]): Promise<ExtractionStats>;
+    /**
+     * Extract knowledge from raw text (e.g., a document or summary).
+     */
+    extractFromText(text: string): Promise<ExtractionStats>;
+    /**
+     * Extract with contradiction handling — supersedes existing relations
+     * when the LLM finds conflicting facts.
+     */
+    extractWithContradictions(entries: MemoryEntry[], existingContext?: string): Promise<ExtractionStats>;
+    private formatEntries;
+    /**
+     * Build a text summary of existing knowledge for contradiction detection context.
+     */
+    buildExistingContext(entityNames: string[]): Promise<string>;
+}
+//# sourceMappingURL=memory-extractor.d.ts.map

package/dist/memory-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-extractor.d.ts","sourceRoot":"","sources":["../src/memory-extractor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAU,MAAM,sBAAsB,CAAC;AACnE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAI5D,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,SAAS,EAAE,iBAAiB,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,eAAe;IAC9B,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,OAAO,CACL,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAC9B;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,CAAC,QAAQ,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,GAClF,oBAAoB,CAwBtB;AAuCD;;;;;;GAMG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,EAAE,CAAiB;IAC3B,OAAO,CAAC,GAAG,CAAuB;IAClC,OAAO,CAAC,MAAM,CAAC,CAKb;gBAGA,EAAE,EAAE,cAAc,EAClB,GAAG,EAAE,oBAAoB,EACzB,MAAM,CAAC,EAAE,eAAe,CAAC,QAAQ,CAAC;IAOpC;;;OAGG;IACG,kBAAkB,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,eAAe,CAAC;IAiF1E;;OAEG;IACG,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAwD7D;;;OAGG;IACG,yBAAyB,CAC7B,OAAO,EAAE,WAAW,EAAE,EACtB,eAAe,CAAC,EAAE,MAAM,GACvB,OAAO,CAAC,eAAe,CAAC;IA8E3B,OAAO,CAAC,aAAa;IAWrB;;OAEG;IACG,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;CAqBnE"}