@framers/agentos 0.1.101 → 0.1.103

package/dist/memory/store/SqliteKnowledgeGraph.js

@@ -0,0 +1,1062 @@
+/**
+ * @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.
+ *
+ * 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 crypto from 'node:crypto';
+// ---------------------------------------------------------------------------
+// Embedding helpers
+// ---------------------------------------------------------------------------
+/**
+ * Serialize a number[] embedding into a Buffer (Float32 little-endian)
+ * for storage in an SQLite BLOB column.
+ */
+function embeddingToBlob(vec) {
+    const buf = Buffer.alloc(vec.length * 4);
+    for (let i = 0; i < vec.length; i++) {
+        buf.writeFloatLE(vec[i], i * 4);
+    }
+    return buf;
+}
+/**
+ * Deserialize a BLOB (Float32 little-endian) back into a number[] embedding.
+ */
+function blobToEmbedding(blob) {
+    const count = blob.length / 4;
+    const vec = new Array(count);
+    for (let i = 0; i < count; i++) {
+        vec[i] = blob.readFloatLE(i * 4);
+    }
+    return vec;
+}
+/**
+ * Compute cosine similarity between two equal-length vectors.
+ * Returns 0 if either vector has zero magnitude.
+ */
+function cosineSimilarity(a, b) {
+    let dot = 0;
+    let magA = 0;
+    let magB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        magA += a[i] * a[i];
+        magB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(magA) * Math.sqrt(magB);
+    return denom === 0 ? 0 : dot / denom;
+}
+// ---------------------------------------------------------------------------
+// SqliteKnowledgeGraph
+// ---------------------------------------------------------------------------
+/**
+ * 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 = new SqliteBrain('/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 class SqliteKnowledgeGraph {
+    /**
+     * @param brain - A SqliteBrain instance whose `db` handle is used for all queries.
+     */
+    constructor(brain) {
+        this.brain = brain;
+    }
+    // =========================================================================
+    // Initialization
+    // =========================================================================
+    /**
+     * 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.
+     */
+    async initialize() {
+        // Schema already exists via SqliteBrain._initSchema().
+        // Nothing additional to do.
+    }
+    // =========================================================================
+    // Entity Operations
+    // =========================================================================
+    /**
+     * 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.
+     */
+    async upsertEntity(entity) {
+        const now = new Date().toISOString();
+        const id = entity.id ?? crypto.randomUUID();
+        // Check if the entity already exists to preserve createdAt.
+        const existing = this.brain.db
+            .prepare('SELECT * FROM knowledge_nodes WHERE id = ?')
+            .get(id);
+        const createdAt = existing
+            ? new Date(existing.created_at).toISOString()
+            : now;
+        // Pack extended fields into the properties JSON envelope.
+        const extended = {
+            _props: entity.properties,
+            _ownerId: entity.ownerId,
+            _tags: entity.tags,
+            _metadata: entity.metadata,
+            _updatedAt: now,
+        };
+        const embeddingBlob = entity.embedding
+            ? embeddingToBlob(entity.embedding)
+            : null;
+        this.brain.db
+            .prepare(`INSERT OR REPLACE INTO knowledge_nodes
+           (id, type, label, properties, embedding, confidence, source, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(id, entity.type, entity.label, JSON.stringify(extended), embeddingBlob, entity.confidence, JSON.stringify(entity.source), new Date(createdAt).getTime());
+        return this._rowToEntity({
+            id,
+            type: entity.type,
+            label: entity.label,
+            properties: JSON.stringify(extended),
+            embedding: embeddingBlob,
+            confidence: entity.confidence,
+            source: JSON.stringify(entity.source),
+            created_at: new Date(createdAt).getTime(),
+        });
+    }
+    /**
+     * Retrieve a single entity by its ID.
+     * Returns `undefined` if the entity does not exist.
+     */
+    async getEntity(id) {
+        const row = this.brain.db
+            .prepare('SELECT * FROM knowledge_nodes WHERE id = ?')
+            .get(id);
+        if (!row)
+            return undefined;
+        return this._rowToEntity(row);
+    }
+    /**
+     * Query entities with optional filters.
+     *
+     * Supports filtering by entity type, tags, owner, minimum confidence,
+     * full-text search, pagination (limit/offset), and time ranges.
+     */
+    async queryEntities(options) {
+        const clauses = [];
+        const params = [];
+        // Filter: entity types (only non-memory types for queryEntities).
+        if (options?.entityTypes && options.entityTypes.length > 0) {
+            const placeholders = options.entityTypes.map(() => '?').join(', ');
+            clauses.push(`type IN (${placeholders})`);
+            params.push(...options.entityTypes);
+        }
+        // Filter: minimum confidence.
+        if (options?.minConfidence !== undefined) {
+            clauses.push('confidence >= ?');
+            params.push(options.minConfidence);
+        }
+        // Filter: time range.
+        if (options?.timeRange?.from) {
+            clauses.push('created_at >= ?');
+            params.push(new Date(options.timeRange.from).getTime());
+        }
+        if (options?.timeRange?.to) {
+            clauses.push('created_at <= ?');
+            params.push(new Date(options.timeRange.to).getTime());
+        }
+        const whereClause = clauses.length > 0 ? `WHERE ${clauses.join(' AND ')}` : '';
+        const limit = options?.limit ?? 100;
+        const offset = options?.offset ?? 0;
+        const sql = `SELECT * FROM knowledge_nodes ${whereClause} ORDER BY created_at DESC LIMIT ? OFFSET ?`;
+        params.push(limit, offset);
+        const rows = this.brain.db.prepare(sql).all(...params);
+        let entities = rows.map((r) => this._rowToEntity(r));
+        // Post-filter by ownerId (stored inside properties JSON).
+        if (options?.ownerId) {
+            entities = entities.filter((e) => e.ownerId === options.ownerId);
+        }
+        // Post-filter by tags (stored inside properties JSON).
+        if (options?.tags && options.tags.length > 0) {
+            entities = entities.filter((e) => options.tags.some((tag) => e.tags?.includes(tag)));
+        }
+        // Post-filter by textSearch (label + properties text match, case-insensitive).
+        if (options?.textSearch) {
+            const search = options.textSearch.toLowerCase();
+            entities = entities.filter((e) => e.label.toLowerCase().includes(search) ||
+                JSON.stringify(e.properties).toLowerCase().includes(search));
+        }
+        return entities;
+    }
+    /**
+     * Delete an entity and all its associated relations (incoming and outgoing).
+     * Returns `true` if the entity existed and was deleted.
+     */
+    async deleteEntity(id) {
+        const deleteOp = this.brain.db.transaction(() => {
+            // Delete all edges touching this entity.
+            this.brain.db
+                .prepare('DELETE FROM knowledge_edges WHERE source_id = ? OR target_id = ?')
+                .run(id, id);
+            // Delete the node itself.
+            const result = this.brain.db
+                .prepare('DELETE FROM knowledge_nodes WHERE id = ?')
+                .run(id);
+            return result.changes > 0;
+        });
+        return deleteOp();
+    }
+    // =========================================================================
+    // Relation Operations
+    // =========================================================================
+    /**
+     * Insert or update a knowledge relation (edge).
+     *
+     * Extended edge fields (label, properties, confidence, source, validFrom,
+     * validTo) are packed into the `metadata` JSON column.
+     */
+    async upsertRelation(relation) {
+        const now = new Date().toISOString();
+        const id = relation.id ?? crypto.randomUUID();
+        // Preserve createdAt if edge already exists.
+        const existing = this.brain.db
+            .prepare('SELECT * FROM knowledge_edges WHERE id = ?')
+            .get(id);
+        const createdAt = existing
+            ? new Date(existing.created_at).toISOString()
+            : now;
+        // Pack extended edge fields into the metadata JSON column.
+        const extended = {
+            _label: relation.label,
+            _properties: relation.properties,
+            _confidence: relation.confidence,
+            _source: relation.source,
+            _validFrom: relation.validFrom,
+            _validTo: relation.validTo,
+        };
+        this.brain.db
+            .prepare(`INSERT OR REPLACE INTO knowledge_edges
+           (id, source_id, target_id, type, weight, bidirectional, metadata, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(id, relation.sourceId, relation.targetId, relation.type, relation.weight, relation.bidirectional ? 1 : 0, JSON.stringify(extended), new Date(createdAt).getTime());
+        return this._rowToRelation({
+            id,
+            source_id: relation.sourceId,
+            target_id: relation.targetId,
+            type: relation.type,
+            weight: relation.weight,
+            bidirectional: relation.bidirectional ? 1 : 0,
+            metadata: JSON.stringify(extended),
+            created_at: new Date(createdAt).getTime(),
+        });
+    }
+    /**
+     * Get all relations for a given entity.
+     *
+     * @param entityId - The entity whose relations to retrieve.
+     * @param options  - Optional filters: direction ('outgoing'|'incoming'|'both'), types.
+     */
+    async getRelations(entityId, options) {
+        const direction = options?.direction ?? 'both';
+        const clauses = [];
+        const params = [];
+        if (direction === 'outgoing') {
+            clauses.push('(source_id = ?)');
+            params.push(entityId);
+        }
+        else if (direction === 'incoming') {
+            clauses.push('(target_id = ?)');
+            params.push(entityId);
+        }
+        else {
+            clauses.push('(source_id = ? OR target_id = ?)');
+            params.push(entityId, entityId);
+        }
+        if (options?.types && options.types.length > 0) {
+            const placeholders = options.types.map(() => '?').join(', ');
+            clauses.push(`type IN (${placeholders})`);
+            params.push(...options.types);
+        }
+        const sql = `SELECT * FROM knowledge_edges WHERE ${clauses.join(' AND ')}`;
+        const rows = this.brain.db.prepare(sql).all(...params);
+        return rows.map((r) => this._rowToRelation(r));
+    }
+    /**
+     * Delete a single relation by its ID.
+     * Returns `true` if the relation existed and was deleted.
+     */
+    async deleteRelation(id) {
+        const result = this.brain.db
+            .prepare('DELETE FROM knowledge_edges WHERE id = ?')
+            .run(id);
+        return result.changes > 0;
+    }
+    // =========================================================================
+    // Episodic Memory Operations
+    // =========================================================================
+    /**
+     * Record an episodic memory.
+     *
+     * Memories are stored as knowledge_nodes with `type = 'memory'`. The
+     * memory-specific fields are packed into the `properties` JSON column.
+     */
+    async recordMemory(memory) {
+        const now = new Date().toISOString();
+        const id = crypto.randomUUID();
+        const memFields = {
+            _props: {},
+            _updatedAt: now,
+            _memoryType: memory.type,
+            _summary: memory.summary,
+            _description: memory.description,
+            _participants: memory.participants,
+            _valence: memory.valence,
+            _importance: memory.importance,
+            _entityIds: memory.entityIds,
+            _occurredAt: memory.occurredAt,
+            _durationMs: memory.durationMs,
+            _outcome: memory.outcome,
+            _insights: memory.insights,
+            _context: memory.context,
+            _accessCount: 0,
+            _lastAccessedAt: now,
+        };
+        const embeddingBlob = memory.embedding
+            ? embeddingToBlob(memory.embedding)
+            : null;
+        const source = {
+            type: 'conversation',
+            timestamp: now,
+        };
+        this.brain.db
+            .prepare(`INSERT INTO knowledge_nodes
+           (id, type, label, properties, embedding, confidence, source, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(id, 'memory', memory.summary.slice(0, 200), JSON.stringify(memFields), embeddingBlob, memory.importance, JSON.stringify(source), new Date(now).getTime());
+        return {
+            id,
+            type: memory.type,
+            summary: memory.summary,
+            description: memory.description,
+            participants: memory.participants,
+            valence: memory.valence,
+            importance: memory.importance,
+            entityIds: memory.entityIds,
+            embedding: memory.embedding,
+            occurredAt: memory.occurredAt,
+            durationMs: memory.durationMs,
+            outcome: memory.outcome,
+            insights: memory.insights,
+            context: memory.context,
+            createdAt: now,
+            accessCount: 0,
+            lastAccessedAt: now,
+        };
+    }
+    /**
+     * 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.
+     */
+    async getMemory(id) {
+        const row = this.brain.db
+            .prepare(`SELECT * FROM knowledge_nodes WHERE id = ? AND type = 'memory'`)
+            .get(id);
+        if (!row)
+            return undefined;
+        return this._rowToMemory(row);
+    }
+    /**
+     * Query episodic memories with optional filters.
+     *
+     * Supports filtering by memory sub-type, participants, minimum importance,
+     * time range, and result limit.
+     */
+    async queryMemories(options) {
+        const clauses = ["type = 'memory'"];
+        const params = [];
+        // Filter by minimum importance (stored as confidence).
+        if (options?.minImportance !== undefined) {
+            clauses.push('confidence >= ?');
+            params.push(options.minImportance);
+        }
+        // Filter by time range on created_at.
+        if (options?.timeRange?.from) {
+            clauses.push('created_at >= ?');
+            params.push(new Date(options.timeRange.from).getTime());
+        }
+        if (options?.timeRange?.to) {
+            clauses.push('created_at <= ?');
+            params.push(new Date(options.timeRange.to).getTime());
+        }
+        const limit = options?.limit ?? 100;
+        const sql = `SELECT * FROM knowledge_nodes WHERE ${clauses.join(' AND ')} ORDER BY created_at DESC LIMIT ?`;
+        params.push(limit);
+        const rows = this.brain.db.prepare(sql).all(...params);
+        let memories = rows.map((r) => this._rowToMemory(r));
+        // Post-filter by memory sub-type (stored in properties JSON).
+        if (options?.types && options.types.length > 0) {
+            const typeSet = new Set(options.types);
+            memories = memories.filter((m) => typeSet.has(m.type));
+        }
+        // Post-filter by participants (stored in properties JSON).
+        if (options?.participants && options.participants.length > 0) {
+            memories = memories.filter((m) => options.participants.some((p) => m.participants.includes(p)));
+        }
+        return memories;
+    }
+    /**
+     * 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.
+     */
+    async recallMemories(query, topK) {
+        const limit = topK ?? 10;
+        const searchTerm = `%${query}%`;
+        const rows = this.brain.db
+            .prepare(`SELECT * FROM knowledge_nodes
+         WHERE type = 'memory' AND (label LIKE ? OR properties LIKE ?)
+         ORDER BY created_at DESC
+         LIMIT ?`)
+            .all(searchTerm, searchTerm, limit);
+        const memories = rows.map((r) => this._rowToMemory(r));
+        // Update access count and last accessed for each recalled memory.
+        const now = new Date().toISOString();
+        for (const mem of memories) {
+            const row = this.brain.db
+                .prepare('SELECT * FROM knowledge_nodes WHERE id = ?')
+                .get(mem.id);
+            if (row) {
+                const fields = JSON.parse(row.properties);
+                fields._accessCount = (fields._accessCount ?? 0) + 1;
+                fields._lastAccessedAt = now;
+                this.brain.db
+                    .prepare('UPDATE knowledge_nodes SET properties = ? WHERE id = ?')
+                    .run(JSON.stringify(fields), mem.id);
+                mem.accessCount = fields._accessCount;
+                mem.lastAccessedAt = now;
+            }
+        }
+        return memories;
+    }
+    // =========================================================================
+    // Graph Traversal
+    // =========================================================================
+    /**
+     * 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.
+     */
+    async traverse(startEntityId, options) {
+        const root = await this.getEntity(startEntityId);
+        if (!root) {
+            throw new Error(`Entity not found: ${startEntityId}`);
+        }
+        const maxDepth = options?.maxDepth ?? 3;
+        const direction = options?.direction ?? 'both';
+        const minWeight = options?.minWeight ?? 0;
+        const maxNodes = options?.maxNodes ?? 1000;
+        // Build the edge direction clause for the recursive step.
+        let edgeJoin;
+        if (direction === 'outgoing') {
+            edgeJoin = 'knowledge_edges e ON e.source_id = t.entity_id';
+        }
+        else if (direction === 'incoming') {
+            edgeJoin = 'knowledge_edges e ON e.target_id = t.entity_id';
+        }
+        else {
+            edgeJoin = 'knowledge_edges e ON (e.source_id = t.entity_id OR e.target_id = t.entity_id)';
+        }
+        // Build optional relation type filter.
+        let typeFilter = '';
+        const typeParams = [];
+        if (options?.relationTypes && options.relationTypes.length > 0) {
+            const placeholders = options.relationTypes.map(() => '?').join(', ');
+            typeFilter = `AND e.type IN (${placeholders})`;
+            typeParams.push(...options.relationTypes);
+        }
+        // Next entity ID expression depends on direction.
+        let nextEntityExpr;
+        if (direction === 'outgoing') {
+            nextEntityExpr = 'e.target_id';
+        }
+        else if (direction === 'incoming') {
+            nextEntityExpr = 'e.source_id';
+        }
+        else {
+            nextEntityExpr = "CASE WHEN e.source_id = t.entity_id THEN e.target_id ELSE e.source_id END";
+        }
+        const sql = `
+      WITH RECURSIVE traverse AS (
+        SELECT
+          ? AS entity_id,
+          0 AS depth,
+          CAST(? AS TEXT) AS edge_id
+        UNION ALL
+        SELECT
+          ${nextEntityExpr},
+          t.depth + 1,
+          e.id
+        FROM traverse t
+        JOIN ${edgeJoin}
+        WHERE t.depth < ?
+          AND e.weight >= ?
+          ${typeFilter}
+          AND ${nextEntityExpr} != t.entity_id
+      )
+      SELECT DISTINCT entity_id, depth, edge_id
+      FROM traverse
+      LIMIT ?
+    `;
+        const params = [
+            startEntityId,
+            '', // placeholder edge_id for root
+            maxDepth,
+            minWeight,
+            ...typeParams,
+            maxNodes,
+        ];
+        const traversalRows = this.brain.db.prepare(sql).all(...params);
+        // Group by depth. Collect unique entity IDs per level.
+        const levelMap = new Map();
+        const visitedEntities = new Set();
+        for (const row of traversalRows) {
+            if (visitedEntities.has(row.entity_id))
+                continue;
+            visitedEntities.add(row.entity_id);
+            if (!levelMap.has(row.depth)) {
+                levelMap.set(row.depth, { entityIds: new Set(), edgeIds: new Set() });
+            }
+            const level = levelMap.get(row.depth);
+            level.entityIds.add(row.entity_id);
+            if (row.edge_id) {
+                level.edgeIds.add(row.edge_id);
+            }
+        }
+        // Resolve entities and relations for each level.
+        const levels = [];
+        let totalEntities = 0;
+        let totalRelations = 0;
+        for (const [depth, data] of [...levelMap.entries()].sort((a, b) => a[0] - b[0])) {
+            const entities = [];
+            for (const eid of data.entityIds) {
+                const entity = await this.getEntity(eid);
+                if (entity)
+                    entities.push(entity);
+            }
+            const relations = [];
+            for (const rid of data.edgeIds) {
+                const row = this.brain.db
+                    .prepare('SELECT * FROM knowledge_edges WHERE id = ?')
+                    .get(rid);
+                if (row)
+                    relations.push(this._rowToRelation(row));
+            }
+            levels.push({ depth, entities, relations });
+            totalEntities += entities.length;
+            totalRelations += relations.length;
+        }
+        return {
+            root,
+            levels,
+            totalEntities,
+            totalRelations,
+        };
+    }
+    /**
+     * 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.
+     */
+    async findPath(sourceId, targetId, maxDepth) {
+        const depth = maxDepth ?? 10;
+        // Use a recursive CTE that tracks the path as a comma-separated list of
+        // "entityId:edgeId" pairs. Stops when targetId is reached.
+        const sql = `
+      WITH RECURSIVE path_search AS (
+        SELECT
+          ? AS current_id,
+          CAST(? AS TEXT) AS path_entities,
+          CAST('' AS TEXT) AS path_edges,
+          0 AS depth
+        UNION ALL
+        SELECT
+          CASE
+            WHEN e.source_id = p.current_id THEN e.target_id
+            ELSE e.source_id
+          END,
+          p.path_entities || ',' ||
+            CASE WHEN e.source_id = p.current_id THEN e.target_id ELSE e.source_id END,
+          CASE WHEN p.path_edges = '' THEN e.id ELSE p.path_edges || ',' || e.id END,
+          p.depth + 1
+        FROM path_search p
+        JOIN knowledge_edges e ON (e.source_id = p.current_id OR e.target_id = p.current_id)
+        WHERE p.depth < ?
+          AND p.path_entities NOT LIKE '%' ||
+            CASE WHEN e.source_id = p.current_id THEN e.target_id ELSE e.source_id END || '%'
+      )
+      SELECT path_entities, path_edges, depth
+      FROM path_search
+      WHERE current_id = ?
+      ORDER BY depth ASC
+      LIMIT 1
+    `;
+        const row = this.brain.db.prepare(sql).get(sourceId, sourceId, depth, targetId);
+        if (!row)
+            return null;
+        const entityIds = row.path_entities.split(',').filter(Boolean);
+        const edgeIds = row.path_edges.split(',').filter(Boolean);
+        const result = [];
+        for (let i = 0; i < entityIds.length; i++) {
+            const entity = await this.getEntity(entityIds[i]);
+            if (!entity)
+                return null;
+            let relation;
+            if (i > 0 && edgeIds[i - 1]) {
+                const edgeRow = this.brain.db
+                    .prepare('SELECT * FROM knowledge_edges WHERE id = ?')
+                    .get(edgeIds[i - 1]);
+                if (edgeRow)
+                    relation = this._rowToRelation(edgeRow);
+            }
+            result.push({ entity, relation });
+        }
+        return result;
+    }
+    /**
+     * 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).
+     */
+    async getNeighborhood(entityId, depth) {
+        const maxDepth = depth ?? 1;
+        const sql = `
+      WITH RECURSIVE neighborhood AS (
+        SELECT ? AS entity_id, 0 AS depth
+        UNION ALL
+        SELECT
+          CASE
+            WHEN e.source_id = n.entity_id THEN e.target_id
+            ELSE e.source_id
+          END,
+          n.depth + 1
+        FROM neighborhood n
+        JOIN knowledge_edges e ON (e.source_id = n.entity_id OR e.target_id = n.entity_id)
+        WHERE n.depth < ?
+      )
+      SELECT DISTINCT entity_id FROM neighborhood
+    `;
+        const rows = this.brain.db.prepare(sql).all(entityId, maxDepth);
+        const entityIds = new Set(rows.map((r) => r.entity_id));
+        const entities = [];
+        for (const eid of entityIds) {
+            const entity = await this.getEntity(eid);
+            if (entity)
+                entities.push(entity);
+        }
+        // Collect all edges where both endpoints are in the neighbourhood.
+        const allEdges = this.brain.db
+            .prepare('SELECT * FROM knowledge_edges')
+            .all();
+        const relations = allEdges
+            .filter((e) => entityIds.has(e.source_id) && entityIds.has(e.target_id))
+            .map((r) => this._rowToRelation(r));
+        return { entities, relations };
+    }
+    // =========================================================================
+    // Semantic Search
+    // =========================================================================
+    /**
+     * 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.
+     */
+    async semanticSearch(options) {
+        const scope = options.scope ?? 'all';
+        const topK = options.topK ?? 10;
+        const minSimilarity = options.minSimilarity ?? 0;
+        // Build WHERE clause based on scope.
+        const clauses = ['embedding IS NOT NULL'];
+        if (scope === 'entities') {
+            clauses.push("type != 'memory'");
+        }
+        else if (scope === 'memories') {
+            clauses.push("type = 'memory'");
+        }
+        if (options.entityTypes && options.entityTypes.length > 0) {
+            const placeholders = options.entityTypes.map(() => '?').join(', ');
+            clauses.push(`type IN (${placeholders})`);
+        }
+        const sql = `SELECT * FROM knowledge_nodes WHERE ${clauses.join(' AND ')}`;
+        const params = [];
+        if (options.entityTypes && options.entityTypes.length > 0) {
+            params.push(...options.entityTypes);
+        }
+        const rows = this.brain.db.prepare(sql).all(...params);
+        // We need a query embedding. For keyword-based fallback, we match by text.
+        // Here we do keyword search since we don't have an embedding model.
+        const queryLower = options.query.toLowerCase();
+        const results = [];
+        for (const row of rows) {
+            // If the row has an embedding, we'd need a query embedding for cosine sim.
+            // As a fallback, do keyword matching and assign a pseudo-similarity.
+            const label = row.label.toLowerCase();
+            const propsStr = row.properties.toLowerCase();
+            let similarity = 0;
+            if (label.includes(queryLower)) {
+                similarity = 0.9; // Strong match on label.
+            }
+            else if (propsStr.includes(queryLower)) {
+                similarity = 0.7; // Weaker match in properties.
+            }
+            if (similarity < minSimilarity)
+                continue;
+            const isMemory = row.type === 'memory';
+            // Post-filter by ownerId if specified.
+            if (options.ownerId) {
+                const entity = this._rowToEntity(row);
+                if (entity.ownerId !== options.ownerId)
+                    continue;
+            }
+            if (isMemory) {
+                results.push({
+                    item: this._rowToMemory(row),
+                    type: 'memory',
+                    similarity,
+                });
+            }
+            else {
+                results.push({
+                    item: this._rowToEntity(row),
+                    type: 'entity',
+                    similarity,
+                });
+            }
+        }
+        // Also search nodes WITHOUT embeddings by keyword when no embedding vectors
+        // are available (pure keyword fallback).
+        if (results.length === 0) {
+            const allNodesSql = `SELECT * FROM knowledge_nodes WHERE ${scope === 'entities' ? "type != 'memory'" :
+                scope === 'memories' ? "type = 'memory'" : '1=1'}`;
+            const allRows = this.brain.db.prepare(allNodesSql).all();
+            for (const row of allRows) {
+                const label = row.label.toLowerCase();
+                const propsStr = row.properties.toLowerCase();
+                let similarity = 0;
+                if (label.includes(queryLower)) {
+                    similarity = 0.9;
+                }
+                else if (propsStr.includes(queryLower)) {
+                    similarity = 0.7;
+                }
+                if (similarity < minSimilarity)
+                    continue;
+                if (options.ownerId) {
+                    const entity = this._rowToEntity(row);
+                    if (entity.ownerId !== options.ownerId)
+                        continue;
+                }
+                const isMemory = row.type === 'memory';
+                results.push({
+                    item: isMemory ? this._rowToMemory(row) : this._rowToEntity(row),
+                    type: isMemory ? 'memory' : 'entity',
+                    similarity,
+                });
+            }
+        }
+        // Sort by similarity descending, take top-K.
+        results.sort((a, b) => b.similarity - a.similarity);
+        return results.slice(0, topK);
+    }
+    // =========================================================================
+    // Knowledge Extraction
+    // =========================================================================
+    /**
+     * 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.
+     */
+    async extractFromText(_text, _options) {
+        throw new Error('extractFromText requires an LLM — use the Memory facade for LLM-powered extraction');
+    }
+    // =========================================================================
+    // Maintenance
+    // =========================================================================
+    /**
+     * 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.
+     */
+    async mergeEntities(entityIds, primaryId) {
+        const primary = await this.getEntity(primaryId);
+        if (!primary) {
+            throw new Error(`Primary entity not found: ${primaryId}`);
+        }
+        const othersIds = entityIds.filter((id) => id !== primaryId);
+        const mergeTx = this.brain.db.transaction(() => {
+            for (const otherId of othersIds) {
+                // Re-link outgoing edges: source_id = otherId → primaryId.
+                this.brain.db
+                    .prepare('UPDATE knowledge_edges SET source_id = ? WHERE source_id = ?')
+                    .run(primaryId, otherId);
+                // Re-link incoming edges: target_id = otherId → primaryId.
+                this.brain.db
+                    .prepare('UPDATE knowledge_edges SET target_id = ? WHERE target_id = ?')
+                    .run(primaryId, otherId);
+                // Delete the non-primary entity node.
+                this.brain.db
+                    .prepare('DELETE FROM knowledge_nodes WHERE id = ?')
+                    .run(otherId);
+            }
+            // Remove any self-referential edges that may have resulted from the merge.
+            this.brain.db
+                .prepare('DELETE FROM knowledge_edges WHERE source_id = target_id')
+                .run();
+        });
+        mergeTx();
+        // Return the surviving primary entity (re-fetch to reflect current state).
+        return (await this.getEntity(primaryId));
+    }
+    /**
+     * 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.
+     */
+    async decayMemories(decayFactor) {
+        const factor = decayFactor ?? 0.95;
+        const result = this.brain.db
+            .prepare(`UPDATE knowledge_nodes
+         SET confidence = confidence * ?
+         WHERE type = 'memory'`)
+            .run(factor);
+        return result.changes;
+    }
+    /**
+     * Get aggregate statistics about the knowledge graph.
+     *
+     * Returns counts of entities, relations, memories, breakdowns by type,
+     * average confidence, and oldest/newest entry timestamps.
+     */
+    async getStats() {
+        // Total non-memory entities.
+        const entityCount = (this.brain.db
+            .prepare("SELECT COUNT(*) AS cnt FROM knowledge_nodes WHERE type != 'memory'")
+            .get())?.cnt ?? 0;
+        // Total relations.
+        const relationCount = (this.brain.db
+            .prepare('SELECT COUNT(*) AS cnt FROM knowledge_edges')
+            .get())?.cnt ?? 0;
+        // Total memories.
+        const memoryCount = (this.brain.db
+            .prepare("SELECT COUNT(*) AS cnt FROM knowledge_nodes WHERE type = 'memory'")
+            .get())?.cnt ?? 0;
+        // Entity types breakdown (exclude memories).
+        const entityTypeRows = this.brain.db
+            .prepare("SELECT type, COUNT(*) AS cnt FROM knowledge_nodes WHERE type != 'memory' GROUP BY type")
+            .all();
+        const entitiesByType = {};
+        for (const row of entityTypeRows) {
+            entitiesByType[row.type] = row.cnt;
+        }
+        // Relation types breakdown.
+        const relTypeRows = this.brain.db
+            .prepare('SELECT type, COUNT(*) AS cnt FROM knowledge_edges GROUP BY type')
+            .all();
+        const relationsByType = {};
+        for (const row of relTypeRows) {
+            relationsByType[row.type] = row.cnt;
+        }
+        // Average confidence across all nodes.
+        const avgConf = (this.brain.db
+            .prepare('SELECT AVG(confidence) AS avg_conf FROM knowledge_nodes')
+            .get())?.avg_conf ?? 0;
+        // Oldest and newest entries.
+        const oldest = (this.brain.db
+            .prepare('SELECT created_at FROM knowledge_nodes ORDER BY created_at ASC LIMIT 1')
+            .get());
+        const newest = (this.brain.db
+            .prepare('SELECT created_at FROM knowledge_nodes ORDER BY created_at DESC LIMIT 1')
+            .get());
+        return {
+            totalEntities: entityCount,
+            totalRelations: relationCount,
+            totalMemories: memoryCount,
+            entitiesByType,
+            relationsByType,
+            avgConfidence: avgConf,
+            oldestEntry: oldest ? new Date(oldest.created_at).toISOString() : '',
+            newestEntry: newest ? new Date(newest.created_at).toISOString() : '',
+        };
+    }
+    /**
+     * Delete all rows from knowledge_nodes and knowledge_edges.
+     * Wipes the knowledge graph completely.
+     */
+    async clear() {
+        const clearTx = this.brain.db.transaction(() => {
+            // Edges first (FK constraint on source_id / target_id → knowledge_nodes).
+            this.brain.db.exec('DELETE FROM knowledge_edges');
+            this.brain.db.exec('DELETE FROM knowledge_nodes');
+        });
+        clearTx();
+    }
+    // =========================================================================
+    // Private: Row ↔ Domain Object Converters
+    // =========================================================================
+    /**
+     * Convert a raw `knowledge_nodes` row into a `KnowledgeEntity` domain object.
+     * Unpacks extended fields from the `properties` JSON column.
+     */
+    _rowToEntity(row) {
+        let extended;
+        try {
+            extended = JSON.parse(row.properties);
+        }
+        catch {
+            extended = { _props: {} };
+        }
+        const source = (() => {
+            try {
+                return JSON.parse(row.source);
+            }
+            catch {
+                return { type: 'system', timestamp: new Date(row.created_at).toISOString() };
+            }
+        })();
+        return {
+            id: row.id,
+            type: row.type,
+            label: row.label,
+            properties: extended._props ?? {},
+            embedding: row.embedding ? blobToEmbedding(row.embedding) : undefined,
+            confidence: row.confidence,
+            source,
+            createdAt: new Date(row.created_at).toISOString(),
+            updatedAt: extended._updatedAt ?? new Date(row.created_at).toISOString(),
+            ownerId: extended._ownerId,
+            tags: extended._tags,
+            metadata: extended._metadata,
+        };
+    }
+    /**
+     * Convert a raw `knowledge_edges` row into a `KnowledgeRelation` domain object.
+     * Unpacks extended fields from the `metadata` JSON column.
+     */
+    _rowToRelation(row) {
+        let extended;
+        try {
+            extended = JSON.parse(row.metadata);
+        }
+        catch {
+            extended = {};
+        }
+        return {
+            id: row.id,
+            sourceId: row.source_id,
+            targetId: row.target_id,
+            type: row.type,
+            label: extended._label ?? row.type,
+            properties: extended._properties,
+            weight: row.weight,
+            bidirectional: row.bidirectional === 1,
+            confidence: extended._confidence ?? 1,
+            source: extended._source ?? { type: 'system', timestamp: new Date(row.created_at).toISOString() },
+            createdAt: new Date(row.created_at).toISOString(),
+            validFrom: extended._validFrom,
+            validTo: extended._validTo,
+        };
+    }
+    /**
+     * Convert a raw `knowledge_nodes` row (with `type = 'memory'`) into an
+     * `EpisodicMemory` domain object. Unpacks memory-specific fields from the
+     * `properties` JSON column.
+     */
+    _rowToMemory(row) {
+        let fields;
+        try {
+            fields = JSON.parse(row.properties);
+        }
+        catch {
+            fields = {};
+        }
+        return {
+            id: row.id,
+            type: (fields._memoryType ?? 'interaction'),
+            summary: fields._summary ?? row.label,
+            description: fields._description,
+            participants: fields._participants ?? [],
+            valence: fields._valence,
+            importance: row.confidence,
+            entityIds: fields._entityIds ?? [],
+            embedding: row.embedding ? blobToEmbedding(row.embedding) : undefined,
+            occurredAt: fields._occurredAt ?? new Date(row.created_at).toISOString(),
+            durationMs: fields._durationMs,
+            outcome: fields._outcome,
+            insights: fields._insights,
+            context: fields._context,
+            createdAt: new Date(row.created_at).toISOString(),
+            accessCount: fields._accessCount ?? 0,
+            lastAccessedAt: fields._lastAccessedAt ?? new Date(row.created_at).toISOString(),
+        };
+    }
+}
+//# sourceMappingURL=SqliteKnowledgeGraph.js.map