@mce-bt/microagents-memory 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { ShortTermMemory, type STMConfig } from './stm.js';
+export { MidTermMemory, type MTMConfig, type EpisodicMemory } from './mtm.js';
+export { LongTermMemory, type LTMConfig, type KnowledgeFact } from './ltm.js';
+export { MemoryManager, type MemoryManagerConfig, type ContextBlock } from './manager.js';
+export { KnowledgeGraph, type KGConfig, type Entity, type Relation, type SearchEntitiesOptions, type GraphSnapshot, } from './knowledge-graph.js';
+export { MemoryExtractor, createExtractionAdapter, type ExtractionLLMAdapter, type ExtractionResult, type ExtractionStats, type ExtractedEntity, type ExtractedRelation, } from './memory-extractor.js';
+export { createMemoryTools } from './memory-tools.js';
+export { SummarizationPipeline, type SummarizationPipelineConfig, type PipelineResult, } from './summarization-pipeline.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,KAAK,SAAS,EAAE,MAAM,UAAU,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,KAAK,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,UAAU,CAAC;AAC9E,OAAO,EAAE,cAAc,EAAE,KAAK,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9E,OAAO,EAAE,aAAa,EAAE,KAAK,mBAAmB,EAAE,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAC1F,OAAO,EACL,cAAc,EACd,KAAK,QAAQ,EACb,KAAK,MAAM,EACX,KAAK,QAAQ,EACb,KAAK,qBAAqB,EAC1B,KAAK,aAAa,GACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,iBAAiB,GACvB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EACL,qBAAqB,EACrB,KAAK,2BAA2B,EAChC,KAAK,cAAc,GACpB,MAAM,6BAA6B,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+export { ShortTermMemory } from './stm.js';
+export { MidTermMemory } from './mtm.js';
+export { LongTermMemory } from './ltm.js';
+export { MemoryManager } from './manager.js';
+export { KnowledgeGraph, } from './knowledge-graph.js';
+export { MemoryExtractor, createExtractionAdapter, } from './memory-extractor.js';
+export { createMemoryTools } from './memory-tools.js';
+export { SummarizationPipeline, } from './summarization-pipeline.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAkB,MAAM,UAAU,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAuC,MAAM,UAAU,CAAC;AAC9E,OAAO,EAAE,cAAc,EAAsC,MAAM,UAAU,CAAC;AAC9E,OAAO,EAAE,aAAa,EAA+C,MAAM,cAAc,CAAC;AAC1F,OAAO,EACL,cAAc,GAMf,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,eAAe,EACf,uBAAuB,GAMxB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EACL,qBAAqB,GAGtB,MAAM,6BAA6B,CAAC"}

package/dist/knowledge-graph.d.ts

@@ -0,0 +1,179 @@
+export interface KGConfig {
+    connectionString: string;
+    /** Embedding dimensions (default: 1536) */
+    embeddingDimensions?: number;
+}
+export interface Entity {
+    id: string;
+    agentId: string;
+    name: string;
+    entityType: string;
+    observations: string[];
+    embedding?: number[];
+    metadata: Record<string, unknown>;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface Relation {
+    id: string;
+    agentId: string;
+    fromEntity: string;
+    toEntity: string;
+    relationType: string;
+    weight: number;
+    validFrom: Date;
+    validUntil: Date | null;
+    metadata: Record<string, unknown>;
+    createdAt: Date;
+}
+export interface SearchEntitiesOptions {
+    query?: string;
+    entityType?: string;
+    limit?: number;
+    embedding?: number[];
+    threshold?: number;
+}
+export interface GraphSnapshot {
+    entities: Entity[];
+    relations: Relation[];
+}
+/**
+ * Knowledge Graph — Postgres-backed entity-relation graph with temporal validity.
+ *
+ * Combines the MCP memory server's entity-relation-observation model with
+ * Graphiti's temporal validity windows, all implemented in PostgreSQL.
+ *
+ * Entities have names, types, observations (atomic facts), and optional embeddings
+ * for semantic search. Relations connect entities with typed, directed edges that
+ * carry validity windows (valid_from / valid_until) for temporal reasoning.
+ */
+export declare class KnowledgeGraph {
+    private pool;
+    private config;
+    private agentId;
+    private embeddingDimensions;
+    constructor(config: KGConfig);
+    start(agentId: string): Promise<void>;
+    stop(): Promise<void>;
+    private ensureSchema;
+    /**
+     * Create or update an entity. If an entity with the same name already exists
+     * for this agent, merges new observations (deduplicates) and updates metadata.
+     */
+    upsertEntity(input: {
+        name: string;
+        entityType: string;
+        observations?: string[];
+        embedding?: number[];
+        metadata?: Record<string, unknown>;
+    }): Promise<Entity>;
+    /**
+     * Get an entity by name (scoped to this agent).
+     */
+    getEntityByName(name: string): Promise<Entity | null>;
+    /**
+     * Get an entity by ID.
+     */
+    getEntityById(id: string): Promise<Entity | null>;
+    /**
+     * Add observations to an existing entity. Deduplicates automatically.
+     */
+    addObservations(entityName: string, observations: string[]): Promise<string[]>;
+    /**
+     * Remove specific observations from an entity.
+     */
+    removeObservations(entityName: string, observations: string[]): Promise<void>;
+    /**
+     * Delete an entity and all its relations (cascading).
+     */
+    deleteEntity(name: string): Promise<void>;
+    /**
+     * Create a relation between two entities. Skips if an identical active relation exists.
+     * If a contradicting relation exists (same from/to/type but different validity),
+     * the old one is invalidated (valid_until set to now).
+     */
+    createRelation(input: {
+        from: string;
+        to: string;
+        relationType: string;
+        weight?: number;
+        metadata?: Record<string, unknown>;
+        validFrom?: Date;
+    }): Promise<Relation | null>;
+    /**
+     * Invalidate a relation by setting valid_until to now.
+     * Preserves history — the relation is never deleted.
+     */
+    invalidateRelation(id: string): Promise<void>;
+    /**
+     * Delete a relation permanently (use invalidate for temporal preservation).
+     */
+    deleteRelation(input: {
+        from: string;
+        to: string;
+        relationType: string;
+    }): Promise<void>;
+    /**
+     * Get all active relations for an entity (as source or target).
+     * Only returns relations where valid_until IS NULL (currently active).
+     */
+    getEntityRelations(entityName: string, options?: {
+        includeExpired?: boolean;
+    }): Promise<(Relation & {
+        fromName: string;
+        toName: string;
+    })[]>;
+    /**
+     * Search entities by text query (matches name, type, and observations).
+     */
+    searchEntities(options?: SearchEntitiesOptions): Promise<Entity[]>;
+    /**
+     * Semantic search entities by embedding similarity.
+     */
+    searchEntitiesByEmbedding(queryEmbedding: number[], options?: {
+        entityType?: string;
+        limit?: number;
+        threshold?: number;
+    }): Promise<(Entity & {
+        similarity: number;
+    })[]>;
+    /**
+     * Open specific entities by name and return them with their relations.
+     * Similar to MCP memory server's open_nodes.
+     */
+    openEntities(names: string[]): Promise<GraphSnapshot>;
+    /**
+     * Read the full graph for this agent (active relations only).
+     */
+    readGraph(options?: {
+        includeExpired?: boolean;
+    }): Promise<GraphSnapshot>;
+    /**
+     * Get the state of relations at a specific point in time.
+     */
+    getRelationsAt(date: Date, options?: {
+        entityName?: string;
+    }): Promise<Relation[]>;
+    /**
+     * Get the history of changes to a specific relation type between two entities.
+     */
+    getRelationHistory(from: string, to: string, relationType: string): Promise<Relation[]>;
+    /**
+     * Update a relation: invalidates the existing one and creates a new one.
+     * This preserves temporal history (Graphiti pattern).
+     */
+    supersedRelation(input: {
+        from: string;
+        to: string;
+        relationType: string;
+        weight?: number;
+        metadata?: Record<string, unknown>;
+    }): Promise<Relation | null>;
+    /**
+     * Get entity counts grouped by type.
+     */
+    getEntityTypeCounts(): Promise<Record<string, number>>;
+    private rowToEntity;
+    private rowToRelation;
+}
+//# sourceMappingURL=knowledge-graph.d.ts.map

package/dist/knowledge-graph.d.ts.map

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