Skip to main content

Class: SqlMemoryGraph

Defined in: packages/agentos/src/cognition/memory/retrieval/store/SqlMemoryGraph.ts:118

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 Brain.openSqlite('/path/to/brain.sqlite');
const graph = new SqlMemoryGraph(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 SqlMemoryGraph(brain): SqlMemoryGraph

Defined in: packages/agentos/src/cognition/memory/retrieval/store/SqlMemoryGraph.ts:147

Parameters​

brain​

Brain

The shared Brain connection for this agent. The knowledge_nodes and knowledge_edges tables must already exist (Brain creates them in its constructor).

Returns​

SqlMemoryGraph

Methods​

addEdge()​

addEdge(edge): Promise<void>

Defined in: packages/agentos/src/cognition/memory/retrieval/store/SqlMemoryGraph.ts:317

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/cognition/memory/retrieval/store/SqlMemoryGraph.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(): Promise<void>

Defined in: packages/agentos/src/cognition/memory/retrieval/store/SqlMemoryGraph.ts:752

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

detectClusters()​

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

Defined in: packages/agentos/src/cognition/memory/retrieval/store/SqlMemoryGraph.ts:614

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/cognition/memory/retrieval/store/SqlMemoryGraph.ts:742

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/cognition/memory/retrieval/store/SqlMemoryGraph.ts:589

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/cognition/memory/retrieval/store/SqlMemoryGraph.ts:348

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/cognition/memory/retrieval/store/SqlMemoryGraph.ts:299

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/cognition/memory/retrieval/store/SqlMemoryGraph.ts:159

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/cognition/memory/retrieval/store/SqlMemoryGraph.ts:734

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/cognition/memory/retrieval/store/SqlMemoryGraph.ts:537

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/cognition/memory/retrieval/store/SqlMemoryGraph.ts:366

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/cognition/memory/retrieval/store/SqlMemoryGraph.ts:266

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. The SQL delete takes every edge that names the node, those another graph instance on the same Brain wrote after this one loaded included, and a relation a host made to the node through the knowledge graph (upsertRelation), so the node's own delete meets no edge that still references it. For an id that names no node of this graph (a knowledge-graph entity of the same id), only memory-graph edges go, and the entity keeps its relations.

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/cognition/memory/retrieval/store/SqlMemoryGraph.ts:208

Shut down the memory graph.

Currently a no-op because Brain 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/cognition/memory/retrieval/store/SqlMemoryGraph.ts:400

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