@framers/agentos 0.1.125 → 0.1.127

package/dist/memory/store/SqliteKnowledgeGraph.js

@@ -1,1036 +0,0 @@
-/**
- * @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 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 = 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 class SqliteKnowledgeGraph {
-    /**
-     * @param brain - A SqliteBrain instance whose async StorageAdapter methods
-     *                are 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 = await this.brain.get('SELECT * FROM knowledge_nodes WHERE id = ?', [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;
-        await this.brain.run(`INSERT OR REPLACE INTO knowledge_nodes
-         (id, type, label, properties, embedding, confidence, source, created_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, [
-            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 = await this.brain.get('SELECT * FROM knowledge_nodes WHERE id = ?', [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 = await this.brain.all(sql, 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) {
-        return await this.brain.transaction(async (trx) => {
-            // Delete all edges touching this entity.
-            await trx.run('DELETE FROM knowledge_edges WHERE source_id = ? OR target_id = ?', [id, id]);
-            // Delete the node itself.
-            const result = await trx.run('DELETE FROM knowledge_nodes WHERE id = ?', [id]);
-            return result.changes > 0;
-        });
-    }
-    // =========================================================================
-    // 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 = await this.brain.get('SELECT * FROM knowledge_edges WHERE id = ?', [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,
-        };
-        await this.brain.run(`INSERT OR REPLACE INTO knowledge_edges
-         (id, source_id, target_id, type, weight, bidirectional, metadata, created_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, [
-            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 = await this.brain.all(sql, 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 = await this.brain.run('DELETE FROM knowledge_edges WHERE id = ?', [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,
-        };
-        await this.brain.run(`INSERT INTO knowledge_nodes
-         (id, type, label, properties, embedding, confidence, source, created_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, [
-            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 = await this.brain.get(`SELECT * FROM knowledge_nodes WHERE id = ? AND type = 'memory'`, [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 = await this.brain.all(sql, 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 = await this.brain.all(`SELECT * FROM knowledge_nodes
-       WHERE type = 'memory' AND (label LIKE ? OR properties LIKE ?)
-       ORDER BY created_at DESC
-       LIMIT ?`, [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 = await this.brain.get('SELECT * FROM knowledge_nodes WHERE id = ?', [mem.id]);
-            if (row) {
-                const fields = JSON.parse(row.properties);
-                fields._accessCount = (fields._accessCount ?? 0) + 1;
-                fields._lastAccessedAt = now;
-                await this.brain.run('UPDATE knowledge_nodes SET properties = ? WHERE id = ?', [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 = await this.brain.all(sql, 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 = await this.brain.get('SELECT * FROM knowledge_edges WHERE id = ?', [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 = await this.brain.get(sql, [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 = await this.brain.get('SELECT * FROM knowledge_edges WHERE id = ?', [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 = await this.brain.all(sql, [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 = await this.brain.all('SELECT * FROM knowledge_edges');
-        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 = await this.brain.all(sql, 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 = await this.brain.all(allNodesSql);
-            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);
-        await this.brain.transaction(async (trx) => {
-            for (const otherId of othersIds) {
-                // Re-link outgoing edges: source_id = otherId -> primaryId.
-                await trx.run('UPDATE knowledge_edges SET source_id = ? WHERE source_id = ?', [primaryId, otherId]);
-                // Re-link incoming edges: target_id = otherId -> primaryId.
-                await trx.run('UPDATE knowledge_edges SET target_id = ? WHERE target_id = ?', [primaryId, otherId]);
-                // Delete the non-primary entity node.
-                await trx.run('DELETE FROM knowledge_nodes WHERE id = ?', [otherId]);
-            }
-            // Remove any self-referential edges that may have resulted from the merge.
-            await trx.run('DELETE FROM knowledge_edges WHERE source_id = target_id');
-        });
-        // 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 = await this.brain.run(`UPDATE knowledge_nodes
-       SET confidence = confidence * ?
-       WHERE type = 'memory'`, [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 entityCountRow = await this.brain.get("SELECT COUNT(*) AS cnt FROM knowledge_nodes WHERE type != 'memory'");
-        const entityCount = entityCountRow?.cnt ?? 0;
-        // Total relations.
-        const relationCountRow = await this.brain.get('SELECT COUNT(*) AS cnt FROM knowledge_edges');
-        const relationCount = relationCountRow?.cnt ?? 0;
-        // Total memories.
-        const memoryCountRow = await this.brain.get("SELECT COUNT(*) AS cnt FROM knowledge_nodes WHERE type = 'memory'");
-        const memoryCount = memoryCountRow?.cnt ?? 0;
-        // Entity types breakdown (exclude memories).
-        const entityTypeRows = await this.brain.all("SELECT type, COUNT(*) AS cnt FROM knowledge_nodes WHERE type != 'memory' GROUP BY type");
-        const entitiesByType = {};
-        for (const row of entityTypeRows) {
-            entitiesByType[row.type] = row.cnt;
-        }
-        // Relation types breakdown.
-        const relTypeRows = await this.brain.all('SELECT type, COUNT(*) AS cnt FROM knowledge_edges GROUP BY type');
-        const relationsByType = {};
-        for (const row of relTypeRows) {
-            relationsByType[row.type] = row.cnt;
-        }
-        // Average confidence across all nodes.
-        const avgConfRow = await this.brain.get('SELECT AVG(confidence) AS avg_conf FROM knowledge_nodes');
-        const avgConf = avgConfRow?.avg_conf ?? 0;
-        // Oldest and newest entries.
-        const oldest = await this.brain.get('SELECT created_at FROM knowledge_nodes ORDER BY created_at ASC LIMIT 1');
-        const newest = await this.brain.get('SELECT created_at FROM knowledge_nodes ORDER BY created_at DESC LIMIT 1');
-        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() {
-        await this.brain.transaction(async (trx) => {
-            // Edges first (FK constraint on source_id / target_id -> knowledge_nodes).
-            await trx.exec('DELETE FROM knowledge_edges');
-            await trx.exec('DELETE FROM knowledge_nodes');
-        });
-    }
-    // =========================================================================
-    // 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