@framers/agentos 0.1.125 → 0.1.127

package/dist/memory/retrieval/store/SqliteKnowledgeGraph.d.ts

@@ -0,0 +1,263 @@
+/**
+ * @fileoverview SQLite-backed implementation of IKnowledgeGraph.
+ *
+ * Persists knowledge entities (nodes), relations (edges), and episodic memories
+ * to the `knowledge_nodes` and `knowledge_edges` tables managed by SqliteBrain.
+ *
+ * Uses the async StorageAdapter API exposed by SqliteBrain (run/get/all/exec/
+ * transaction) rather than direct better-sqlite3 access.
+ *
+ * Episodic memories are stored as knowledge_nodes with `type = 'memory'` and
+ * their memory-specific fields packed into the `properties` JSON column.
+ *
+ * Graph traversal (BFS/DFS, shortest path, neighbourhood) is implemented via
+ * SQLite recursive Common Table Expressions (CTEs).
+ *
+ * Semantic search loads embeddings from BLOB columns and computes cosine
+ * similarity in-process — no external vector DB needed for the SQLite path.
+ *
+ * @module memory/store/SqliteKnowledgeGraph
+ */
+import type { IKnowledgeGraph, KnowledgeEntity, KnowledgeRelation, EpisodicMemory, EntityId, RelationId, EntityType, RelationType, KnowledgeQueryOptions, TraversalOptions, TraversalResult, SemanticSearchOptions, SemanticSearchResult, KnowledgeGraphStats } from '../graph/knowledge/IKnowledgeGraph.js';
+import type { SqliteBrain } from './SqliteBrain.js';
+/**
+ * Persistent knowledge graph backed by SQLite via SqliteBrain.
+ *
+ * Implements the full `IKnowledgeGraph` interface using the `knowledge_nodes`
+ * and `knowledge_edges` tables. Extended entity/relation fields that don't
+ * have dedicated columns are serialized into the JSON `properties` / `metadata`
+ * columns.
+ *
+ * @example
+ * ```ts
+ * const brain = await SqliteBrain.open('/tmp/agent-brain.sqlite');
+ * const graph = new SqliteKnowledgeGraph(brain);
+ * await graph.initialize();
+ *
+ * const entity = await graph.upsertEntity({
+ *   type: 'person',
+ *   label: 'Alice',
+ *   properties: { role: 'engineer' },
+ *   confidence: 0.95,
+ *   source: { type: 'user_input', timestamp: new Date().toISOString() },
+ * });
+ * ```
+ */
+export declare class SqliteKnowledgeGraph implements IKnowledgeGraph {
+    /** The shared SQLite brain instance. */
+    private readonly brain;
+    /**
+     * @param brain - A SqliteBrain instance whose async StorageAdapter methods
+     *                are used for all queries.
+     */
+    constructor(brain: SqliteBrain);
+    /**
+     * Initialize the knowledge graph.
+     *
+     * The schema is already created by SqliteBrain's constructor, so this is
+     * effectively a no-op. Provided to satisfy the IKnowledgeGraph contract.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Insert or update a knowledge entity.
+     *
+     * If `entity.id` is provided and exists, the row is updated (INSERT OR REPLACE).
+     * If omitted, a new UUID is generated.
+     *
+     * Extended fields (ownerId, tags, metadata, updatedAt) are packed into the
+     * `properties` JSON column as underscore-prefixed keys to avoid collisions
+     * with user-supplied properties.
+     */
+    upsertEntity(entity: Omit<KnowledgeEntity, 'id' | 'createdAt' | 'updatedAt'> & {
+        id?: EntityId;
+    }): Promise<KnowledgeEntity>;
+    /**
+     * Retrieve a single entity by its ID.
+     * Returns `undefined` if the entity does not exist.
+     */
+    getEntity(id: EntityId): Promise<KnowledgeEntity | undefined>;
+    /**
+     * Query entities with optional filters.
+     *
+     * Supports filtering by entity type, tags, owner, minimum confidence,
+     * full-text search, pagination (limit/offset), and time ranges.
+     */
+    queryEntities(options?: KnowledgeQueryOptions): Promise<KnowledgeEntity[]>;
+    /**
+     * Delete an entity and all its associated relations (incoming and outgoing).
+     * Returns `true` if the entity existed and was deleted.
+     */
+    deleteEntity(id: EntityId): Promise<boolean>;
+    /**
+     * Insert or update a knowledge relation (edge).
+     *
+     * Extended edge fields (label, properties, confidence, source, validFrom,
+     * validTo) are packed into the `metadata` JSON column.
+     */
+    upsertRelation(relation: Omit<KnowledgeRelation, 'id' | 'createdAt'> & {
+        id?: RelationId;
+    }): Promise<KnowledgeRelation>;
+    /**
+     * Get all relations for a given entity.
+     *
+     * @param entityId - The entity whose relations to retrieve.
+     * @param options  - Optional filters: direction ('outgoing'|'incoming'|'both'), types.
+     */
+    getRelations(entityId: EntityId, options?: {
+        direction?: 'outgoing' | 'incoming' | 'both';
+        types?: RelationType[];
+    }): Promise<KnowledgeRelation[]>;
+    /**
+     * Delete a single relation by its ID.
+     * Returns `true` if the relation existed and was deleted.
+     */
+    deleteRelation(id: RelationId): Promise<boolean>;
+    /**
+     * Record an episodic memory.
+     *
+     * Memories are stored as knowledge_nodes with `type = 'memory'`. The
+     * memory-specific fields are packed into the `properties` JSON column.
+     */
+    recordMemory(memory: Omit<EpisodicMemory, 'id' | 'createdAt' | 'accessCount' | 'lastAccessedAt'>): Promise<EpisodicMemory>;
+    /**
+     * Get an episodic memory by ID.
+     *
+     * Looks up the knowledge_node with the given ID and `type = 'memory'`,
+     * then unpacks the memory-specific fields from the `properties` JSON.
+     */
+    getMemory(id: string): Promise<EpisodicMemory | undefined>;
+    /**
+     * Query episodic memories with optional filters.
+     *
+     * Supports filtering by memory sub-type, participants, minimum importance,
+     * time range, and result limit.
+     */
+    queryMemories(options?: {
+        types?: EpisodicMemory['type'][];
+        participants?: string[];
+        minImportance?: number;
+        timeRange?: {
+            from?: string;
+            to?: string;
+        };
+        limit?: number;
+    }): Promise<EpisodicMemory[]>;
+    /**
+     * Recall relevant memories via keyword search against summaries.
+     *
+     * Performs a case-insensitive substring match on the label (which contains
+     * the summary text). Increments accessCount and updates lastAccessedAt for
+     * each returned memory (Hebbian reinforcement).
+     *
+     * Full semantic (embedding-based) recall requires the Memory facade.
+     */
+    recallMemories(query: string, topK?: number): Promise<EpisodicMemory[]>;
+    /**
+     * Traverse the graph from a starting entity using BFS.
+     *
+     * Uses a recursive CTE (Common Table Expression) to walk the graph up to
+     * `maxDepth` hops from the start node. Results are grouped by depth level.
+     *
+     * @param startEntityId - ID of the entity to start traversal from.
+     * @param options       - Optional: maxDepth, relationTypes, direction, minWeight, maxNodes.
+     */
+    traverse(startEntityId: EntityId, options?: TraversalOptions): Promise<TraversalResult>;
+    /**
+     * Find the shortest path between two entities using a bidirectional BFS
+     * implemented via a recursive CTE.
+     *
+     * Returns an ordered array of `{ entity, relation? }` steps from source to
+     * target, or `null` if no path exists within `maxDepth` hops.
+     */
+    findPath(sourceId: EntityId, targetId: EntityId, maxDepth?: number): Promise<Array<{
+        entity: KnowledgeEntity;
+        relation?: KnowledgeRelation;
+    }> | null>;
+    /**
+     * Get the neighbourhood of an entity — all entities and relations within
+     * `depth` hops.
+     *
+     * @param entityId - Centre entity.
+     * @param depth    - Maximum number of hops (default 1).
+     */
+    getNeighborhood(entityId: EntityId, depth?: number): Promise<{
+        entities: KnowledgeEntity[];
+        relations: KnowledgeRelation[];
+    }>;
+    /**
+     * Semantic search across entities and/or memories.
+     *
+     * Loads all embeddings from `knowledge_nodes`, computes cosine similarity
+     * against the query embedding (if present in `options`), and returns the
+     * top-K results above the minimum similarity threshold.
+     *
+     * NOTE: This implementation requires the caller to provide a query embedding
+     * via a pre-processing step. If no nodes have embeddings, an empty array is
+     * returned. For full text-to-embedding semantic search, use the Memory facade.
+     */
+    semanticSearch(options: SemanticSearchOptions): Promise<SemanticSearchResult[]>;
+    /**
+     * Extract entities and relations from text.
+     *
+     * This operation requires an LLM and is not supported at the store level.
+     * Use the Memory facade for LLM-powered extraction.
+     *
+     * @throws {Error} Always — extraction requires an LLM.
+     */
+    extractFromText(_text: string, _options?: {
+        extractRelations?: boolean;
+        entityTypes?: EntityType[];
+    }): Promise<{
+        entities: KnowledgeEntity[];
+        relations: KnowledgeRelation[];
+    }>;
+    /**
+     * Merge multiple entities into one primary entity.
+     *
+     * All relations (edges) pointing to or from the non-primary entities are
+     * re-linked to the primary entity. The non-primary entities are then deleted.
+     *
+     * @param entityIds - All entity IDs involved in the merge.
+     * @param primaryId - The ID that survives the merge.
+     */
+    mergeEntities(entityIds: EntityId[], primaryId: EntityId): Promise<KnowledgeEntity>;
+    /**
+     * Decay the confidence of all memory-type nodes by a multiplicative factor.
+     *
+     * This simulates the Ebbinghaus forgetting curve — memories that are not
+     * accessed (reinforced) gradually fade.
+     *
+     * @param decayFactor - Multiplicative factor in (0, 1). Default 0.95.
+     * @returns The number of memory nodes whose confidence was reduced.
+     */
+    decayMemories(decayFactor?: number): Promise<number>;
+    /**
+     * Get aggregate statistics about the knowledge graph.
+     *
+     * Returns counts of entities, relations, memories, breakdowns by type,
+     * average confidence, and oldest/newest entry timestamps.
+     */
+    getStats(): Promise<KnowledgeGraphStats>;
+    /**
+     * Delete all rows from knowledge_nodes and knowledge_edges.
+     * Wipes the knowledge graph completely.
+     */
+    clear(): Promise<void>;
+    /**
+     * Convert a raw `knowledge_nodes` row into a `KnowledgeEntity` domain object.
+     * Unpacks extended fields from the `properties` JSON column.
+     */
+    private _rowToEntity;
+    /**
+     * Convert a raw `knowledge_edges` row into a `KnowledgeRelation` domain object.
+     * Unpacks extended fields from the `metadata` JSON column.
+     */
+    private _rowToRelation;
+    /**
+     * Convert a raw `knowledge_nodes` row (with `type = 'memory'`) into an
+     * `EpisodicMemory` domain object. Unpacks memory-specific fields from the
+     * `properties` JSON column.
+     */
+    private _rowToMemory;
+}
+//# sourceMappingURL=SqliteKnowledgeGraph.d.ts.map

package/dist/memory/retrieval/store/SqliteKnowledgeGraph.d.ts.map

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