@mce-bt/microagents-memory 0.1.0

package/dist/memory-extractor.js

@@ -0,0 +1,321 @@
+/**
+ * Simple extraction adapter that uses a completion function.
+ * Wraps any LLM completion call into the ExtractionLLMAdapter interface.
+ */
+export function createExtractionAdapter(completeFn) {
+    return {
+        async extract(systemPrompt, text) {
+            const raw = await completeFn([
+                { role: 'system', content: systemPrompt },
+                { role: 'user', content: text },
+            ]);
+            // Try to parse JSON from the response (handle markdown code blocks)
+            const jsonMatch = raw.match(/```(?:json)?\s*([\s\S]*?)```/) ?? [null, raw];
+            const jsonStr = (jsonMatch[1] ?? raw).trim();
+            try {
+                const parsed = JSON.parse(jsonStr);
+                return {
+                    entities: Array.isArray(parsed.entities) ? parsed.entities : [],
+                    relations: Array.isArray(parsed.relations) ? parsed.relations : [],
+                };
+            }
+            catch {
+                // If parsing fails, return empty result
+                return { entities: [], relations: [] };
+            }
+        },
+    };
+}
+// ─── Extraction Prompt ───
+const EXTRACTION_SYSTEM_PROMPT = `You are a memory extraction system. Your job is to extract structured knowledge from conversation logs.
+
+Extract:
+1. **Entities**: People, tools, concepts, organizations, projects, preferences, or any other notable noun mentioned.
+2. **Relations**: Directed connections between entities in active voice (e.g., "uses", "prefers", "works_on", "is_part_of").
+
+Rules:
+- Entity names should be normalized (e.g., "John Smith" not "john" or "John"). Use underscores for multi-word names.
+- Observations should be atomic — one fact per observation.
+- Relations should be in active voice (e.g., "works_at", "prefers", "created").
+- Only extract facts that are explicitly stated or strongly implied.
+- Do NOT infer facts that are speculative.
+- Entity types should be lowercase (e.g., "person", "tool", "concept", "project", "preference").
+- If an entity was mentioned before with different info, include all observations — deduplication happens downstream.
+
+Respond ONLY with valid JSON matching this schema:
+{
+  "entities": [
+    {
+      "name": "Entity_Name",
+      "entityType": "type",
+      "observations": ["fact 1", "fact 2"]
+    }
+  ],
+  "relations": [
+    {
+      "from": "Entity_A",
+      "to": "Entity_B",
+      "relationType": "relation_type"
+    }
+  ]
+}
+
+If there is nothing worth extracting, return: {"entities": [], "relations": []}`;
+/**
+ * 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 class MemoryExtractor {
+    kg;
+    llm;
+    logger;
+    constructor(kg, llm, logger) {
+        this.kg = kg;
+        this.llm = llm;
+        this.logger = 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.
+     */
+    async extractFromEntries(entries) {
+        const start = performance.now();
+        const stats = {
+            entitiesCreated: 0,
+            entitiesUpdated: 0,
+            relationsCreated: 0,
+            relationsSuperseded: 0,
+            durationMs: 0,
+        };
+        if (entries.length === 0) {
+            stats.durationMs = performance.now() - start;
+            return stats;
+        }
+        // Format entries into readable text
+        const text = this.formatEntries(entries);
+        // Extract via LLM
+        const result = await this.llm.extract(EXTRACTION_SYSTEM_PROMPT, text);
+        this.logger?.debug('Extraction result', {
+            entityCount: result.entities.length,
+            relationCount: result.relations.length,
+        });
+        // Store extracted entities
+        for (const entity of result.entities) {
+            try {
+                const existing = await this.kg.getEntityByName(entity.name);
+                await this.kg.upsertEntity({
+                    name: entity.name,
+                    entityType: entity.entityType,
+                    observations: entity.observations,
+                });
+                if (existing) {
+                    stats.entitiesUpdated++;
+                }
+                else {
+                    stats.entitiesCreated++;
+                }
+            }
+            catch (err) {
+                this.logger?.warn('Failed to store entity', {
+                    name: entity.name,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        // Store extracted relations
+        for (const relation of result.relations) {
+            try {
+                const created = await this.kg.createRelation({
+                    from: relation.from,
+                    to: relation.to,
+                    relationType: relation.relationType,
+                });
+                if (created) {
+                    stats.relationsCreated++;
+                }
+            }
+            catch (err) {
+                this.logger?.warn('Failed to store relation', {
+                    from: relation.from,
+                    to: relation.to,
+                    type: relation.relationType,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        stats.durationMs = performance.now() - start;
+        this.logger?.info('Memory extraction complete', {
+            entitiesCreated: stats.entitiesCreated,
+            entitiesUpdated: stats.entitiesUpdated,
+            relationsCreated: stats.relationsCreated,
+            durationMs: Math.round(stats.durationMs),
+        });
+        return stats;
+    }
+    /**
+     * Extract knowledge from raw text (e.g., a document or summary).
+     */
+    async extractFromText(text) {
+        const start = performance.now();
+        const stats = {
+            entitiesCreated: 0,
+            entitiesUpdated: 0,
+            relationsCreated: 0,
+            relationsSuperseded: 0,
+            durationMs: 0,
+        };
+        if (!text.trim()) {
+            stats.durationMs = performance.now() - start;
+            return stats;
+        }
+        const result = await this.llm.extract(EXTRACTION_SYSTEM_PROMPT, text);
+        for (const entity of result.entities) {
+            try {
+                const existing = await this.kg.getEntityByName(entity.name);
+                await this.kg.upsertEntity({
+                    name: entity.name,
+                    entityType: entity.entityType,
+                    observations: entity.observations,
+                });
+                if (existing)
+                    stats.entitiesUpdated++;
+                else
+                    stats.entitiesCreated++;
+            }
+            catch (err) {
+                this.logger?.warn('Failed to store entity', {
+                    name: entity.name,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        for (const relation of result.relations) {
+            try {
+                const created = await this.kg.createRelation({
+                    from: relation.from,
+                    to: relation.to,
+                    relationType: relation.relationType,
+                });
+                if (created)
+                    stats.relationsCreated++;
+            }
+            catch (err) {
+                this.logger?.warn('Failed to store relation', {
+                    from: relation.from,
+                    to: relation.to,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        stats.durationMs = performance.now() - start;
+        return stats;
+    }
+    /**
+     * Extract with contradiction handling — supersedes existing relations
+     * when the LLM finds conflicting facts.
+     */
+    async extractWithContradictions(entries, existingContext) {
+        const start = performance.now();
+        const stats = {
+            entitiesCreated: 0,
+            entitiesUpdated: 0,
+            relationsCreated: 0,
+            relationsSuperseded: 0,
+            durationMs: 0,
+        };
+        if (entries.length === 0) {
+            stats.durationMs = performance.now() - start;
+            return stats;
+        }
+        const text = this.formatEntries(entries);
+        const contextualPrompt = existingContext
+            ? `${EXTRACTION_SYSTEM_PROMPT}\n\n## Existing Knowledge\nThe following is what is currently known. If anything in the conversation contradicts or updates these facts, extract the NEW information (the old will be automatically superseded):\n\n${existingContext}`
+            : EXTRACTION_SYSTEM_PROMPT;
+        const result = await this.llm.extract(contextualPrompt, text);
+        // Store entities (same as normal extraction)
+        for (const entity of result.entities) {
+            try {
+                const existing = await this.kg.getEntityByName(entity.name);
+                await this.kg.upsertEntity({
+                    name: entity.name,
+                    entityType: entity.entityType,
+                    observations: entity.observations,
+                });
+                if (existing)
+                    stats.entitiesUpdated++;
+                else
+                    stats.entitiesCreated++;
+            }
+            catch (err) {
+                this.logger?.warn('Failed to store entity', {
+                    name: entity.name,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        // Store relations with contradiction detection
+        for (const relation of result.relations) {
+            try {
+                // Use supersede to handle contradictions
+                const created = await this.kg.supersedRelation({
+                    from: relation.from,
+                    to: relation.to,
+                    relationType: relation.relationType,
+                });
+                if (created) {
+                    // Check if a previous relation was invalidated
+                    const history = await this.kg.getRelationHistory(relation.from, relation.to, relation.relationType);
+                    if (history.length > 1) {
+                        stats.relationsSuperseded++;
+                    }
+                    stats.relationsCreated++;
+                }
+            }
+            catch (err) {
+                this.logger?.warn('Failed to store relation', {
+                    from: relation.from,
+                    to: relation.to,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        stats.durationMs = performance.now() - start;
+        return stats;
+    }
+    // ─── Helpers ───
+    formatEntries(entries) {
+        return entries
+            .filter((e) => e.type === 'message' || e.type === 'tool_result')
+            .map((e) => {
+            const role = e.metadata?.role ?? e.type;
+            const ts = new Date(e.timestamp).toISOString();
+            return `[${ts}] ${role}: ${e.content}`;
+        })
+            .join('\n');
+    }
+    /**
+     * Build a text summary of existing knowledge for contradiction detection context.
+     */
+    async buildExistingContext(entityNames) {
+        const lines = [];
+        for (const name of entityNames) {
+            const entity = await this.kg.getEntityByName(name);
+            if (!entity)
+                continue;
+            lines.push(`Entity: ${entity.name} (${entity.entityType})`);
+            for (const obs of entity.observations) {
+                lines.push(`  - ${obs}`);
+            }
+            const relations = await this.kg.getEntityRelations(name);
+            for (const rel of relations) {
+                lines.push(`  ${rel.fromName} --[${rel.relationType}]--> ${rel.toName}`);
+            }
+            lines.push('');
+        }
+        return lines.join('\n');
+    }
+}
+//# sourceMappingURL=memory-extractor.js.map

package/dist/memory-extractor.js.map

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

package/dist/memory-tools.d.ts

@@ -0,0 +1,10 @@
+import type { RegisteredTool } from '@mce-bt/microagents-core';
+import type { MemoryManager } from './manager.js';
+/**
+ * Create memory tools that agents can use during conversations.
+ * Inspired by Letta's approach of giving agents explicit memory control.
+ *
+ * Returns an array of RegisteredTool objects ready for the tool registry.
+ */
+export declare function createMemoryTools(manager: MemoryManager): RegisteredTool[];
+//# sourceMappingURL=memory-tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memory-tools.d.ts","sourceRoot":"","sources":["../src/memory-tools.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,aAAa,GACrB,cAAc,EAAE,CAYlB"}

package/dist/memory-tools.js

@@ -0,0 +1,239 @@
+import { z } from 'zod';
+/**
+ * Create memory tools that agents can use during conversations.
+ * Inspired by Letta's approach of giving agents explicit memory control.
+ *
+ * Returns an array of RegisteredTool objects ready for the tool registry.
+ */
+export function createMemoryTools(manager) {
+    const kg = manager.kg;
+    if (!kg)
+        return [];
+    return [
+        searchKnowledgeTool(kg),
+        storFactTool(kg),
+        recallEntityTool(kg),
+        relateEntitiesTool(kg),
+        listEntitiesTool(kg),
+        recallRecentEpisodesTool(manager),
+    ];
+}
+// ─── Tool Definitions ───
+function searchKnowledgeTool(kg) {
+    return {
+        name: 'search_knowledge',
+        description: 'Search the knowledge graph for entities, facts, and relationships. ' +
+            'Use this when you need to recall information about people, concepts, tools, ' +
+            'or any previously learned knowledge.',
+        parameters: z.object({
+            query: z.string().describe('Search query — matches entity names, types, and observations'),
+            entityType: z.string().optional().describe('Filter by entity type (e.g., "person", "tool", "concept")'),
+            limit: z.number().optional().describe('Max results to return (default: 10)'),
+        }),
+        visibility: 'internal',
+        handler: async (params) => {
+            const { query, entityType, limit } = params;
+            const entities = await kg.searchEntities({
+                query,
+                entityType,
+                limit: limit ?? 10,
+            });
+            if (entities.length === 0) {
+                return { found: false, message: 'No matching knowledge found.' };
+            }
+            // For each entity, also fetch its relations
+            const results = await Promise.all(entities.map(async (entity) => {
+                const relations = await kg.getEntityRelations(entity.name);
+                return {
+                    name: entity.name,
+                    type: entity.entityType,
+                    observations: entity.observations,
+                    relations: relations.map((r) => ({
+                        from: r.fromName,
+                        to: r.toName,
+                        type: r.relationType,
+                    })),
+                };
+            }));
+            return { found: true, count: results.length, results };
+        },
+    };
+}
+function storFactTool(kg) {
+    return {
+        name: 'store_fact',
+        description: 'Store a new fact or observation about an entity in long-term memory. ' +
+            'Use this when you learn something important that should be remembered ' +
+            'across conversations (e.g., user preferences, project details, key decisions).',
+        parameters: z.object({
+            entityName: z.string().describe('Name of the entity (e.g., "user", "Project_Alpha", "Redis")'),
+            entityType: z.string().describe('Type of entity (e.g., "person", "project", "tool", "concept", "preference")'),
+            observations: z.array(z.string()).describe('List of atomic facts to store (one fact per item)'),
+        }),
+        visibility: 'internal',
+        handler: async (params) => {
+            const { entityName, entityType, observations } = params;
+            const entity = await kg.upsertEntity({
+                name: entityName,
+                entityType,
+                observations,
+            });
+            return {
+                stored: true,
+                entity: entity.name,
+                totalObservations: entity.observations.length,
+            };
+        },
+    };
+}
+function recallEntityTool(kg) {
+    return {
+        name: 'recall_entity',
+        description: 'Recall everything known about a specific entity — its observations, ' +
+            'relationships, and history. Use this when you need detailed context ' +
+            'about a person, project, tool, or concept.',
+        parameters: z.object({
+            name: z.string().describe('Exact name of the entity to recall'),
+            includeHistory: z.boolean().optional().describe('Include expired/superseded relations (default: false)'),
+        }),
+        visibility: 'internal',
+        handler: async (params) => {
+            const { name, includeHistory } = params;
+            const entity = await kg.getEntityByName(name);
+            if (!entity) {
+                return { found: false, message: `No entity named "${name}" found.` };
+            }
+            const relations = await kg.getEntityRelations(name, {
+                includeExpired: includeHistory ?? false,
+            });
+            return {
+                found: true,
+                entity: {
+                    name: entity.name,
+                    type: entity.entityType,
+                    observations: entity.observations,
+                    createdAt: entity.createdAt.toISOString(),
+                    updatedAt: entity.updatedAt.toISOString(),
+                },
+                relations: relations.map((r) => ({
+                    from: r.fromName,
+                    to: r.toName,
+                    type: r.relationType,
+                    validFrom: r.validFrom.toISOString(),
+                    validUntil: r.validUntil?.toISOString() ?? null,
+                    active: r.validUntil === null,
+                })),
+            };
+        },
+    };
+}
+function relateEntitiesTool(kg) {
+    return {
+        name: 'relate_entities',
+        description: 'Create a relationship between two entities in the knowledge graph. ' +
+            'Use this to capture connections like "user works_on Project_Alpha" or ' +
+            '"Redis is_used_by Coordinator_Agent". If the relationship already exists, ' +
+            'it will be updated (old one preserved in history).',
+        parameters: z.object({
+            from: z.string().describe('Source entity name'),
+            to: z.string().describe('Target entity name'),
+            relationType: z.string().describe('Relationship type in active voice (e.g., "works_on", "uses", "prefers")'),
+            supersede: z.boolean().optional().describe('If true, replaces any existing relation of same type (default: false)'),
+        }),
+        visibility: 'internal',
+        handler: async (params) => {
+            const { from, to, relationType, supersede } = params;
+            try {
+                let relation;
+                if (supersede) {
+                    relation = await kg.supersedRelation({ from, to, relationType });
+                }
+                else {
+                    relation = await kg.createRelation({ from, to, relationType });
+                }
+                if (relation) {
+                    return {
+                        created: true,
+                        relation: {
+                            from,
+                            to,
+                            type: relationType,
+                            validFrom: relation.validFrom.toISOString(),
+                        },
+                    };
+                }
+                return { created: false, message: 'Relation already exists.' };
+            }
+            catch (err) {
+                return {
+                    created: false,
+                    error: err instanceof Error ? err.message : String(err),
+                };
+            }
+        },
+    };
+}
+function listEntitiesTool(kg) {
+    return {
+        name: 'list_entities',
+        description: 'List all known entities, optionally filtered by type. ' +
+            'Use this to see what knowledge is available in memory.',
+        parameters: z.object({
+            entityType: z.string().optional().describe('Filter by type (e.g., "person", "tool")'),
+            limit: z.number().optional().describe('Max results (default: 20)'),
+        }),
+        visibility: 'internal',
+        handler: async (params) => {
+            const { entityType, limit } = params;
+            const entities = await kg.searchEntities({
+                entityType,
+                limit: limit ?? 20,
+            });
+            return {
+                count: entities.length,
+                entities: entities.map((e) => ({
+                    name: e.name,
+                    type: e.entityType,
+                    observationCount: e.observations.length,
+                })),
+            };
+        },
+    };
+}
+function recallRecentEpisodesTool(manager) {
+    return {
+        name: 'recall_recent_episodes',
+        description: 'Recall recent conversation episodes (session summaries). ' +
+            'Use this to remember what happened in past conversations.',
+        parameters: z.object({
+            domain: z.string().optional().describe('Filter by domain/topic'),
+            tags: z.array(z.string()).optional().describe('Filter by tags'),
+            limit: z.number().optional().describe('Max episodes to return (default: 5)'),
+        }),
+        visibility: 'internal',
+        handler: async (params) => {
+            const { domain, tags, limit } = params;
+            const episodes = await manager.mtm.getRecent({
+                domain,
+                tags,
+                limit: limit ?? 5,
+            });
+            if (episodes.length === 0) {
+                return { found: false, message: 'No recent episodes found.' };
+            }
+            return {
+                found: true,
+                count: episodes.length,
+                episodes: episodes.map((ep) => ({
+                    id: ep.id,
+                    summary: ep.summary,
+                    domain: ep.domain,
+                    tags: ep.tags,
+                    startedAt: ep.startedAt.toISOString(),
+                    endedAt: ep.endedAt?.toISOString() ?? null,
+                })),
+            };
+        },
+    };
+}
+//# sourceMappingURL=memory-tools.js.map

package/dist/memory-tools.js.map

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

package/dist/mtm.d.ts

@@ -0,0 +1,55 @@
+export interface MTMConfig {
+    connectionString: string;
+}
+export interface EpisodicMemory {
+    id: string;
+    agentId: string;
+    sessionId: string;
+    summary: string;
+    tags: string[];
+    domain: string | null;
+    startedAt: Date;
+    endedAt: Date | null;
+    metadata: Record<string, unknown>;
+    createdAt: Date;
+}
+/**
+ * Mid-Term Memory (MTM) — PostgreSQL-backed episodic summaries.
+ *
+ * Stores session summaries and recent episode timeline.
+ * Tagged by domain/topic for efficient querying.
+ * "What happened recently regarding X?"
+ */
+export declare class MidTermMemory {
+    private pool;
+    private config;
+    private agentId;
+    constructor(config: MTMConfig);
+    start(agentId: string): Promise<void>;
+    stop(): Promise<void>;
+    private ensureSchema;
+    /**
+     * Store a session summary as an episodic memory.
+     */
+    storeSummary(episode: Omit<EpisodicMemory, 'id' | 'createdAt'>): Promise<string>;
+    /**
+     * Get recent episodes, optionally filtered by domain or tags.
+     */
+    getRecent(options?: {
+        domain?: string;
+        tags?: string[];
+        agentId?: string;
+        limit?: number;
+        sinceDate?: Date;
+    }): Promise<EpisodicMemory[]>;
+    /**
+     * Get a specific episode by ID.
+     */
+    getById(id: string): Promise<EpisodicMemory | null>;
+    /**
+     * Delete an episode.
+     */
+    delete(id: string): Promise<void>;
+    private rowToEpisode;
+}
+//# sourceMappingURL=mtm.d.ts.map

package/dist/mtm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mtm.d.ts","sourceRoot":"","sources":["../src/mtm.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,SAAS;IACxB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,EAAE,IAAI,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,SAAS,EAAE,IAAI,CAAC;CACjB;AAED;;;;;;GAMG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,IAAI,CAAwB;IACpC,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,OAAO,CAAc;gBAEjB,MAAM,EAAE,SAAS;IAIvB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOrC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAOb,YAAY;IAwB1B;;OAEG;IACG,YAAY,CAAC,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,IAAI,GAAG,WAAW,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IAwBtF;;OAEG;IACG,SAAS,CAAC,OAAO,GAAE;QACvB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,SAAS,CAAC,EAAE,IAAI,CAAC;KACb,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAyClC;;OAEG;IACG,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAYzD;;OAEG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKvC,OAAO,CAAC,YAAY;CAcrB"}