Skip to main content

Class: SqliteMemoryGraph

Defined in: packages/agentos/src/memory/store/SqliteMemoryGraph.ts:115

SQLite-backed implementation of IMemoryGraph.

Thread safety: inherits better-sqlite3's single-writer model. All synchronous operations (reads) are safe to call from multiple places concurrently; writes serialise automatically through the WAL.

Usage:

const brain = new SqliteBrain('/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​

Constructors​

Constructor​

new SqliteMemoryGraph(brain): SqliteMemoryGraph

Defined in: packages/agentos/src/memory/store/SqliteMemoryGraph.ts:144

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

Methods​

addEdge()​

addEdge(edge): Promise<void>

Defined in: packages/agentos/src/memory/store/SqliteMemoryGraph.ts:310

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

addNode()​

addNode(memoryId, metadata): Promise<void>

Defined in: packages/agentos/src/memory/store/SqliteMemoryGraph.ts:226

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

clear()​

clear(): void

Defined in: packages/agentos/src/memory/store/SqliteMemoryGraph.ts:740

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​

void

Implementation of​

IMemoryGraph.clear

detectClusters()​

detectClusters(minSize?): Promise<MemoryCluster[]>

Defined in: packages/agentos/src/memory/store/SqliteMemoryGraph.ts:602

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

edgeCount()​

edgeCount(): number

Defined in: packages/agentos/src/memory/store/SqliteMemoryGraph.ts:730

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

Returns​

number

Implementation of​

IMemoryGraph.edgeCount

getConflicts()​

getConflicts(memoryId): MemoryEdge[]

Defined in: packages/agentos/src/memory/store/SqliteMemoryGraph.ts:577

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

getEdges()​

getEdges(memoryId, type?): MemoryEdge[]

Defined in: packages/agentos/src/memory/store/SqliteMemoryGraph.ts:338

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.

type?​

MemoryEdgeType

Optional edge type filter.

Returns​

MemoryEdge[]

Array of matching MemoryEdge objects.

Implementation of​

IMemoryGraph.getEdges

hasNode()​

hasNode(memoryId): boolean

Defined in: packages/agentos/src/memory/store/SqliteMemoryGraph.ts:292

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

initialize()​

initialize(): Promise<void>

Defined in: packages/agentos/src/memory/store/SqliteMemoryGraph.ts:156

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

nodeCount()​

nodeCount(): number

Defined in: packages/agentos/src/memory/store/SqliteMemoryGraph.ts:722

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

Returns​

number

Implementation of​

IMemoryGraph.nodeCount

recordCoActivation()​

recordCoActivation(memoryIds, learningRate?): Promise<void>

Defined in: packages/agentos/src/memory/store/SqliteMemoryGraph.ts:526

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

removeEdge()​

removeEdge(sourceId, targetId): Promise<void>

Defined in: packages/agentos/src/memory/store/SqliteMemoryGraph.ts:356

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

removeNode()​

removeNode(memoryId): Promise<void>

Defined in: packages/agentos/src/memory/store/SqliteMemoryGraph.ts:256

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

shutdown()​

shutdown(): Promise<void>

Defined in: packages/agentos/src/memory/store/SqliteMemoryGraph.ts:208

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

spreadingActivation()​

spreadingActivation(seedIds, config?): Promise<ActivatedNode[]>

Defined in: packages/agentos/src/memory/store/SqliteMemoryGraph.ts:389

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.

config?​

SpreadingActivationConfig

Optional tuning parameters.

Returns​

Promise<ActivatedNode[]>

Activated nodes sorted by activation descending, capped at maxResults.

Implementation of​

IMemoryGraph.spreadingActivation