Class SqliteMemoryGraph

SQLite-backed implementation of IMemoryGraph.

Thread safety: inherits the underlying adapter's concurrency model. Writes serialise automatically through WAL when using SQLite-backed adapters.

Usage:

const brain = await SqliteBrain.open('/path/to/brain.sqlite');
const graph = new SqliteMemoryGraph(brain);
await graph.initialize();

await graph.addNode('mem-1', { type: 'episodic', scope: 'session', scopeId: 's1', strength: 1.0, createdAt: Date.now() });
await graph.addEdge({ sourceId: 'mem-1', targetId: 'mem-2', type: 'SAME_TOPIC', weight: 0.8, createdAt: Date.now() });

const activated = await graph.spreadingActivation(['mem-1']);

Implements

IMemoryGraph

Index

Constructors

constructor

Methods

initialize shutdown addNode removeNode hasNode addEdge getEdges removeEdge spreadingActivation recordCoActivation getConflicts detectClusters nodeCount edgeCount clear

Constructors

constructor

new SqliteMemoryGraph(brain): SqliteMemoryGraph
Parameters
- brain: SqliteBrain
  The shared SqliteBrain connection for this agent. The knowledge_nodes and knowledge_edges tables must already exist (SqliteBrain creates them in its constructor).
Returns SqliteMemoryGraph
- Defined in src/memory/retrieval/store/SqliteMemoryGraph.ts:143

Methods

initialize

initialize(): Promise<void>
Hydrate the in-memory node and edge caches from the SQLite database.

Must be called once before any other method. Safe to call multiple times (idempotent — fully replaces in-memory state each time).

Returns Promise<void>
Implementation of IMemoryGraph.initialize
- Defined in src/memory/retrieval/store/SqliteMemoryGraph.ts:155

shutdown

shutdown(): Promise<void>
Shut down the memory graph.

Currently a no-op because SqliteBrain owns the DB connection lifetime. Provided for interface compliance and forward compatibility.

Returns Promise<void>
Implementation of IMemoryGraph.shutdown
- Defined in src/memory/retrieval/store/SqliteMemoryGraph.ts:206

addNode

addNode(memoryId, metadata): Promise<void>
Add a memory node to the graph.

The node is persisted to knowledge_nodes (type = 'memory_graph') with the metadata serialised into the properties JSON column. If a node with the same memoryId already exists it is silently replaced (upsert).
Parameters
- memoryId: string
  Unique identifier for the memory trace this node represents.
- metadata: MemoryGraphNodeMeta
  Structural metadata describing the memory.
Returns Promise<void>
Implementation of IMemoryGraph.addNode
- Defined in src/memory/retrieval/store/SqliteMemoryGraph.ts:224

removeNode

removeNode(memoryId): Promise<void>
Remove a node and all its incident edges from the graph.

Edges referencing the removed node are deleted from both SQLite and the in-memory cache to keep the graph consistent.
Parameters
- memoryId: string
  ID of the node to remove.
Returns Promise<void>
Implementation of IMemoryGraph.removeNode
- Defined in src/memory/retrieval/store/SqliteMemoryGraph.ts:257

hasNode

hasNode(memoryId): boolean
Check whether a node exists in the graph.

O(1) in-memory lookup — does not touch SQLite.
Parameters
- memoryId: string
  ID to check.
Returns boolean
true if the node is present, false otherwise.
Implementation of IMemoryGraph.hasNode
- Defined in src/memory/retrieval/store/SqliteMemoryGraph.ts:294

addEdge

addEdge(edge): Promise<void>
Add a directed edge between two memory nodes.

If an edge with the same (sourceId, targetId) pair already exists it is replaced (upsert by composite key). The underlying SQLite row is identified by a deterministic UUID derived from the source/target pair so that repeated upserts land on the same row.
Parameters
- edge: MemoryEdge
  Edge descriptor including type, weight, and timestamp.
Returns Promise<void>
Implementation of IMemoryGraph.addEdge
- Defined in src/memory/retrieval/store/SqliteMemoryGraph.ts:312

getEdges

getEdges(memoryId, type?): MemoryEdge[]
Retrieve all edges incident to a memory node.

Returns edges where memoryId appears as either source or target. Optionally filters by edge type.

O(E) scan over the in-memory edge map — acceptable for typical graph sizes (< 10k edges).
Parameters
- memoryId: string
  Node ID to query.
- Optional type: MemoryEdgeType
  Optional edge type filter.
Returns MemoryEdge[]
Array of matching MemoryEdge objects.
Implementation of IMemoryGraph.getEdges
- Defined in src/memory/retrieval/store/SqliteMemoryGraph.ts:343

removeEdge

removeEdge(sourceId, targetId): Promise<void>
Remove a directed edge from the graph.
Parameters
- sourceId: string
  Source node ID.
- targetId: string
  Target node ID.
Returns Promise<void>
Implementation of IMemoryGraph.removeEdge
- Defined in src/memory/retrieval/store/SqliteMemoryGraph.ts:361

spreadingActivation

spreadingActivation(seedIds, config?): Promise<ActivatedNode[]>
Run spreading activation from a set of seed nodes.

Implements Anderson's ACT-R spreading activation model using BFS:
1. Each seed node starts with activation = 1.0.
2. When a node propagates to a neighbour, the neighbour's activation receives: parentActivation * (1 - decayPerHop) * edgeWeight.
3. If a node is reached by multiple paths, the maximum activation is kept.
4. Nodes below activationThreshold are not expanded further.
5. BFS stops at depth maxDepth.
Seed nodes are excluded from the returned list (they are the query, not the result).
Parameters
- seedIds: string[]
  IDs of the memory nodes that trigger the activation.
- Optional config: SpreadingActivationConfig
  Optional tuning parameters.
Returns Promise<ActivatedNode[]>
Activated nodes sorted by activation descending, capped at maxResults.
Implementation of IMemoryGraph.spreadingActivation
- Defined in src/memory/retrieval/store/SqliteMemoryGraph.ts:395

recordCoActivation

recordCoActivation(memoryIds, learningRate?): Promise<void>
Record that a set of memories were activated together (Hebbian learning).

For every unordered pair (A, B) in memoryIds, a CO_ACTIVATED edge is upserted:
- If no edge exists, it is created with weight = learningRate.
- If an edge already exists, its weight is incremented by learningRate and capped at 1.0.
This implements the Hebbian rule "neurons that fire together wire together" at the memory graph level, gradually strengthening associations between memories that are frequently retrieved in the same context.
Parameters
- memoryIds: string[]
  IDs of co-activated memories.
- learningRate: number = 0.1
  Weight increment per co-activation event.
Returns Promise<void>
Default
```
0.1
```
Implementation of IMemoryGraph.recordCoActivation
- Defined in src/memory/retrieval/store/SqliteMemoryGraph.ts:532

getConflicts

getConflicts(memoryId): MemoryEdge[]
Return all CONTRADICTS edges incident to a given memory node.

A CONTRADICTS edge signals that two memories express mutually incompatible beliefs or facts. The consolidation engine uses this to trigger conflict-resolution passes.
Parameters
- memoryId: string
  The memory node to check for contradictions.
Returns MemoryEdge[]
Array of CONTRADICTS edges (may be empty).
Implementation of IMemoryGraph.getConflicts
- Defined in src/memory/retrieval/store/SqliteMemoryGraph.ts:584

detectClusters

detectClusters(minSize?): Promise<MemoryCluster[]>
Detect connected components (clusters) in the memory graph.

Uses path-compressed Union-Find over all edges. Components are filtered to those with at least minSize members.

The centroidId of each cluster is the member with the highest total incident edge weight (most central node). If the cluster has only one member, centroidId equals that member.

The density of a cluster is computed as: actualEdges / maxPossibleEdges where maxPossibleEdges = n*(n-1). For single-member clusters, density = 0.
Parameters
- minSize: number = 2
  Minimum component size to include.
Returns Promise<MemoryCluster[]>
Array of MemoryCluster objects.
Default
```
2
```
Implementation of IMemoryGraph.detectClusters
- Defined in src/memory/retrieval/store/SqliteMemoryGraph.ts:609

nodeCount

nodeCount(): number
Return the number of nodes currently in the graph. O(1) — backed by the in-memory Map size.

Returns number
Implementation of IMemoryGraph.nodeCount
- Defined in src/memory/retrieval/store/SqliteMemoryGraph.ts:729

edgeCount

edgeCount(): number
Return the number of edges currently in the graph. O(1) — backed by the in-memory Map size.

Returns number
Implementation of IMemoryGraph.edgeCount
- Defined in src/memory/retrieval/store/SqliteMemoryGraph.ts:737

clear

clear(): Promise<void>
Remove all nodes and edges from the graph (both in-memory and SQLite).

This is a destructive, irreversible operation. Intended for tests and administrative resets only.

Returns Promise<void>
Implementation of IMemoryGraph.clear
- Defined in src/memory/retrieval/store/SqliteMemoryGraph.ts:747

Class SqliteMemoryGraph

Implements

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns SqliteMemoryGraph

Methods

initialize

Returns Promise<void>

shutdown

Returns Promise<void>

addNode

Parameters

Returns Promise<void>

removeNode

Parameters

Returns Promise<void>

hasNode

Parameters

Returns boolean

addEdge

Parameters

Returns Promise<void>

getEdges

Parameters

Returns MemoryEdge[]

removeEdge

Parameters

Returns Promise<void>

spreadingActivation

Parameters

Returns Promise<ActivatedNode[]>

recordCoActivation

Parameters

Returns Promise<void>

Default

getConflicts

Parameters

Returns MemoryEdge[]

detectClusters

Parameters

Returns Promise<MemoryCluster[]>

Default

nodeCount

Returns number

edgeCount

Returns number

clear

Returns Promise<void>

Settings

Member Visibility

Theme

On This Page