Class SqlKnowledgeGraph

Initialize the knowledge graph.

The schema is already created by Brain's constructor, so this is effectively a no-op. Provided to satisfy the IKnowledgeGraph contract.

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.

Retrieve a single entity by its ID. Returns undefined if the entity does not exist.

Query entities with optional filters.

Supports filtering by entity type, tags, owner, minimum confidence, full-text search, pagination (limit/offset), and time ranges.

Delete an entity and all its associated relations (incoming and outgoing). Returns true if the entity existed and was deleted.

Insert or update a knowledge relation (edge).

Extended edge fields (label, properties, confidence, source, validFrom, validTo) are packed into the metadata JSON column.

Get all relations for a given entity.

Delete a single relation by its ID. Returns true if the relation existed and was deleted.

Record an episodic memory.

Memories are stored as knowledge_nodes with type = 'memory'. The memory-specific fields are packed into the properties JSON column. A memory trace's copy (a context that names the trace, memoryTraceId) is keyed by the trace (trace:<traceId>): recording the trace again replaces the copy, and a delete by trace id finds it by key.

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.

Delete the memory nodes that copy the filter's traces or scopes, with the relations that name them, as deleteEntity deletes an entity's. A trace's copy is deleted by its key; the first delete by trace id of this instance first gives the copies an older release recorded their key (rekeyOlderCopies), and a copy whose move failed in that pass is deleted by its node id. While that pass fails as a whole, a delete by trace id reads the trace's copies held under another node id by the text their stored JSON holds (olderCopyIds) and deletes them too. A scope's copies are read by the text their stored JSON holds (LIKE with an escape clause, which on SQLite also matches the text in other letter cases) and matched exactly in code, so a malformed properties value is skipped rather than failing the delete.

Query episodic memories with optional filters.

Supports filtering by memory sub-type, participants, minimum importance, time range, and result limit.

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.

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.

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.

Get the neighbourhood of an entity — all entities and relations within depth hops.

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.

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

Always — extraction requires an LLM.

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.

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.

Get aggregate statistics about the knowledge graph.

Returns counts of entities, relations, memories, breakdowns by type, average confidence, and oldest/newest entry timestamps.

Delete all rows from knowledge_nodes and knowledge_edges. Wipes the knowledge graph completely.