Class 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

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() },
});

Implements

IKnowledgeGraph

Constructors

constructor

new SqliteKnowledgeGraph(brain): SqliteKnowledgeGraph
Parameters
- brain: SqliteBrain
  A SqliteBrain instance whose async StorageAdapter methods are used for all queries.
Returns SqliteKnowledgeGraph
- Defined in src/memory/retrieval/store/SqliteKnowledgeGraph.ts:182

Methods

initialize

initialize(): Promise<void>
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.

Returns Promise<void>
Implementation of IKnowledgeGraph.initialize
- Defined in src/memory/retrieval/store/SqliteKnowledgeGraph.ts:196

upsertEntity

upsertEntity(entity): Promise<KnowledgeEntity>
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.
Parameters
- entity: Omit<KnowledgeEntity, "updatedAt" | "id" | "createdAt"> & {
  id?: string;
  }
Returns Promise<KnowledgeEntity>
Implementation of IKnowledgeGraph.upsertEntity
- Defined in src/memory/retrieval/store/SqliteKnowledgeGraph.ts:215

getEntity

getEntity(id): Promise<undefined | KnowledgeEntity>
Retrieve a single entity by its ID. Returns undefined if the entity does not exist.
Parameters
- id: string
Returns Promise<undefined | KnowledgeEntity>
Implementation of IKnowledgeGraph.getEntity
- Defined in src/memory/retrieval/store/SqliteKnowledgeGraph.ts:280

queryEntities

queryEntities(options?): Promise<KnowledgeEntity[]>
Query entities with optional filters.

Supports filtering by entity type, tags, owner, minimum confidence, full-text search, pagination (limit/offset), and time ranges.
Parameters
- Optional options: KnowledgeQueryOptions
Returns Promise<KnowledgeEntity[]>
Implementation of IKnowledgeGraph.queryEntities
- Defined in src/memory/retrieval/store/SqliteKnowledgeGraph.ts:296

deleteEntity

deleteEntity(id): Promise<boolean>
Delete an entity and all its associated relations (incoming and outgoing). Returns true if the entity existed and was deleted.
Parameters
- id: string
Returns Promise<boolean>
Implementation of IKnowledgeGraph.deleteEntity
- Defined in src/memory/retrieval/store/SqliteKnowledgeGraph.ts:363

upsertRelation

upsertRelation(relation): Promise<KnowledgeRelation>
Insert or update a knowledge relation (edge).

Extended edge fields (label, properties, confidence, source, validFrom, validTo) are packed into the metadata JSON column.
Parameters
- relation: Omit<KnowledgeRelation, "id" | "createdAt"> & {
  id?: string;
  }
Returns Promise<KnowledgeRelation>
Implementation of IKnowledgeGraph.upsertRelation
- Defined in src/memory/retrieval/store/SqliteKnowledgeGraph.ts:391

getRelations

getRelations(entityId, options?): Promise<KnowledgeRelation[]>
Get all relations for a given entity.
Parameters
- entityId: string
  The entity whose relations to retrieve.
- Optional options: {
  direction?: "both" | "outgoing" | "incoming";
  types?: RelationType[];
  }
  Optional filters: direction ('outgoing'|'incoming'|'both'), types.
  - Optional direction?: "both" | "outgoing" | "incoming"
  - Optional types?: RelationType[]
Returns Promise<KnowledgeRelation[]>
Implementation of IKnowledgeGraph.getRelations
- Defined in src/memory/retrieval/store/SqliteKnowledgeGraph.ts:455

deleteRelation

deleteRelation(id): Promise<boolean>
Delete a single relation by its ID. Returns true if the relation existed and was deleted.
Parameters
- id: string
Returns Promise<boolean>
Implementation of IKnowledgeGraph.deleteRelation
- Defined in src/memory/retrieval/store/SqliteKnowledgeGraph.ts:491

recordMemory

recordMemory(memory): Promise<EpisodicMemory>
Record an episodic memory.

Memories are stored as knowledge_nodes with type = 'memory'. The memory-specific fields are packed into the properties JSON column.
Parameters
- memory: Omit<EpisodicMemory, "id" | "createdAt" | "accessCount" | "lastAccessedAt">
Returns Promise<EpisodicMemory>
Implementation of IKnowledgeGraph.recordMemory
- Defined in src/memory/retrieval/store/SqliteKnowledgeGraph.ts:509

getMemory

getMemory(id): Promise<undefined | EpisodicMemory>
Get an episodic memory by ID.

Looks up the knowledge_node with the given ID and type = 'memory', then unpacks the memory-specific fields from the properties JSON.
Parameters
- id: string
Returns Promise<undefined | EpisodicMemory>
Implementation of IKnowledgeGraph.getMemory
- Defined in src/memory/retrieval/store/SqliteKnowledgeGraph.ts:586

queryMemories

queryMemories(options?): Promise<EpisodicMemory[]>
Query episodic memories with optional filters.

Supports filtering by memory sub-type, participants, minimum importance, time range, and result limit.
Parameters
- Optional options: {
      types?: ("error" | "success" | "discovery" | "conversation" | "task" | "interaction")[];
      participants?: string[];
      minImportance?: number;
      timeRange?: {
          from?: string;
          to?: string;
      };
      limit?: number;
  }
  - Optional types?: ("error" | "success" | "discovery" | "conversation" | "task" | "interaction")[]
  - Optional participants?: string[]
  - Optional minImportance?: number
  - Optional timeRange?: {
    from?: string;
    to?: string;
    }
    - Optional from?: string
    - Optional to?: string
  - Optional limit?: number
Returns Promise<EpisodicMemory[]>
Implementation of IKnowledgeGraph.queryMemories
- Defined in src/memory/retrieval/store/SqliteKnowledgeGraph.ts:602

recallMemories

recallMemories(query, topK?): Promise<EpisodicMemory[]>
Recall relevant memories via keyword search against summaries.

Performs a case-insensitive substring match on the label (which contains the summary text). Increments accessCount and updates lastAccessedAt for each returned memory (Hebbian reinforcement).

Full semantic (embedding-based) recall requires the Memory facade.
Parameters
- query: string
- Optional topK: number
Returns Promise<EpisodicMemory[]>
Implementation of IKnowledgeGraph.recallMemories
- Defined in src/memory/retrieval/store/SqliteKnowledgeGraph.ts:660

traverse

traverse(startEntityId, options?): Promise<TraversalResult>
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.
Parameters
- startEntityId: string
  ID of the entity to start traversal from.
- Optional options: TraversalOptions
  Optional: maxDepth, relationTypes, direction, minWeight, maxNodes.
Returns Promise<TraversalResult>
Implementation of IKnowledgeGraph.traverse
- Defined in src/memory/retrieval/store/SqliteKnowledgeGraph.ts:713

findPath

findPath(sourceId, targetId, maxDepth?): Promise<null | {
entity: KnowledgeEntity;
relation?: KnowledgeRelation;
}[]>
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.
Parameters
- sourceId: string
- targetId: string
- Optional maxDepth: number
Returns Promise<null | {
entity: KnowledgeEntity;
relation?: KnowledgeRelation;
}[]>
Implementation of IKnowledgeGraph.findPath
- Defined in src/memory/retrieval/store/SqliteKnowledgeGraph.ts:853

getNeighborhood

getNeighborhood(entityId, depth?): Promise<{
entities: KnowledgeEntity[];
relations: KnowledgeRelation[];
}>
Get the neighbourhood of an entity — all entities and relations within depth hops.
Parameters
- entityId: string
  Centre entity.
- Optional depth: number
  Maximum number of hops (default 1).
Returns Promise<{
entities: KnowledgeEntity[];
relations: KnowledgeRelation[];
}>
Implementation of IKnowledgeGraph.getNeighborhood
- Defined in src/memory/retrieval/store/SqliteKnowledgeGraph.ts:930

semanticSearch

semanticSearch(options): Promise<SemanticSearchResult[]>
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.
Parameters
- options: SemanticSearchOptions
Returns Promise<SemanticSearchResult[]>
Implementation of IKnowledgeGraph.semanticSearch
- Defined in src/memory/retrieval/store/SqliteKnowledgeGraph.ts:990

extractFromText

extractFromText(_text, _options?): Promise<{
entities: KnowledgeEntity[];
relations: KnowledgeRelation[];
}>
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.
Parameters
- _text: string
- Optional _options: {
  extractRelations?: boolean;
  entityTypes?: EntityType[];
  }
  - Optional extractRelations?: boolean
  - Optional entityTypes?: EntityType[]
Returns Promise<{
entities: KnowledgeEntity[];
relations: KnowledgeRelation[];
}>
Throws
Always — extraction requires an LLM.
Implementation of IKnowledgeGraph.extractFromText
- Defined in src/memory/retrieval/store/SqliteKnowledgeGraph.ts:1113

mergeEntities

mergeEntities(entityIds, primaryId): Promise<KnowledgeEntity>
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.
Parameters
- entityIds: string[]
  All entity IDs involved in the merge.
- primaryId: string
  The ID that survives the merge.
Returns Promise<KnowledgeEntity>
Implementation of IKnowledgeGraph.mergeEntities
- Defined in src/memory/retrieval/store/SqliteKnowledgeGraph.ts:1135

decayMemories

decayMemories(decayFactor?): Promise<number>
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.
Parameters
- Optional decayFactor: number
  Multiplicative factor in (0, 1). Default 0.95.
Returns Promise<number>
The number of memory nodes whose confidence was reduced.
Implementation of IKnowledgeGraph.decayMemories
- Defined in src/memory/retrieval/store/SqliteKnowledgeGraph.ts:1186

getStats

getStats(): Promise<KnowledgeGraphStats>
Get aggregate statistics about the knowledge graph.

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

Returns Promise<KnowledgeGraphStats>
Implementation of IKnowledgeGraph.getStats
- Defined in src/memory/retrieval/store/SqliteKnowledgeGraph.ts:1205

clear

clear(): Promise<void>
Delete all rows from knowledge_nodes and knowledge_edges. Wipes the knowledge graph completely.

Returns Promise<void>
Implementation of IKnowledgeGraph.clear
- Defined in src/memory/retrieval/store/SqliteKnowledgeGraph.ts:1272

Class SqliteKnowledgeGraph

Example

Implements

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns SqliteKnowledgeGraph

Methods

initialize

Returns Promise<void>

upsertEntity

Parameters

Returns Promise<KnowledgeEntity>

getEntity

Parameters

Returns Promise<undefined | KnowledgeEntity>

queryEntities

Parameters

Returns Promise<KnowledgeEntity[]>

deleteEntity

Parameters

Returns Promise<boolean>

upsertRelation

Parameters

Returns Promise<KnowledgeRelation>

getRelations

Parameters

Optional direction?: "both" | "outgoing" | "incoming"

Optional types?: RelationType[]

Returns Promise<KnowledgeRelation[]>

deleteRelation

Parameters

Returns Promise<boolean>

recordMemory

Parameters

Returns Promise<EpisodicMemory>

getMemory

Parameters

Returns Promise<undefined | EpisodicMemory>

queryMemories

Parameters

Optional types?: ("error" | "success" | "discovery" | "conversation" | "task" | "interaction")[]

Optional participants?: string[]

Optional minImportance?: number

Optional timeRange?: { from?: string; to?: string; }

Optional from?: string

Optional to?: string

Optional limit?: number

Returns Promise<EpisodicMemory[]>

recallMemories

Parameters

Returns Promise<EpisodicMemory[]>

traverse

Parameters

Returns Promise<TraversalResult>

findPath

Parameters

Returns Promise<null | { entity: KnowledgeEntity; relation?: KnowledgeRelation; }[]>

getNeighborhood

Parameters

Returns Promise<{ entities: KnowledgeEntity[]; relations: KnowledgeRelation[]; }>

semanticSearch

Parameters

Returns Promise<SemanticSearchResult[]>

extractFromText

Parameters

Optional extractRelations?: boolean

Optional entityTypes?: EntityType[]

Returns Promise<{ entities: KnowledgeEntity[]; relations: KnowledgeRelation[]; }>

Throws

mergeEntities

Parameters

Returns Promise<KnowledgeEntity>

decayMemories

Parameters

Returns Promise<number>

getStats

`Optional` direction?: "both" | "outgoing" | "incoming"

`Optional` types?: RelationType[]

`Optional` types?: ("error" | "success" | "discovery" | "conversation" | "task" | "interaction")[]

`Optional` participants?: string[]

`Optional` minImportance?: number

`Optional` timeRange?: {
from?: string;
to?: string;
}

`Optional` from?: string

`Optional` to?: string

`Optional` limit?: number

Returns Promise<null | {
entity: KnowledgeEntity;
relation?: KnowledgeRelation;
}[]>

Returns Promise<{
entities: KnowledgeEntity[];
relations: KnowledgeRelation[];
}>

`Optional` extractRelations?: boolean

`Optional` entityTypes?: EntityType[]

Returns Promise<{
entities: KnowledgeEntity[];
relations: KnowledgeRelation[];
}>