getActiveNodes()

Read topic objects for the agent session, or tagged topics across sessions when explicitly requested.

What it does

Read topic objects for the agent session, or tagged topics across sessions when explicitly requested.

When to use it

Use to inspect detected topic objects, obtain IDs for explicit grafting, or build a topic browser.

Signature

TypeScript

getActiveNodes(options?: TagFilterOptions): Promise<TopicNode[]>

Parameters

options? (TagFilterOptions) — A typed options object. The applicable fields and defaults are documented below.

TagFilterOptions fields

tags? (string[]) — Tags to match. Omit this field to avoid tag filtering.

tagMode? ("all" | "any", default "all") — Require every supplied tag or at least one supplied tag.

scope? ("session" | "session-and-tags" | "tagged", default "session") — Keep reads in the selected session, combine the session with tagged sessions, or search tagged sessions across session boundaries.

sessionIds? (string[]) — Explicitly constrain cross-session operations. It has no effect on APIs that are strictly current-session scoped.

includeSuppressed? (boolean, default false) — Include suppressed topic nodes.

includeForgotten? (boolean, default false) — Include forgotten memories where the operation returns or evaluates memories.

TopicNode fields

id, sessionId, and segmentId identify the topic and its owning session/segment.

label is the short extracted topic name; summary is its generated description.

messageRange is the inclusive source-message index range; topicOrder is its position in the session.

driftScore records the topic-boundary signal. embedding is the stored semantic vector and can be large.

tags and source preserve caller metadata.

suppressed and suppressedAt describe topic lifecycle state.

agentColor, fleetId, and agentId are populated for fleet-owned topics and otherwise are null.

createdAt is a JavaScript Date when read through the package API.

Result

A TopicNode[] ordered by session ID, topic order, and creation time. An empty array means that no topic matched. Each object includes its ID, label, summary, source message range, drift score, tags, lifecycle state, fleet metadata, and creation time.

Behavior

Reads existing topic rows; it does not return the structured MemoryNode facts attached to them. Use recall() for ranked facts or getGraphSnapshot() for the complete inspection model.

Side effects and completion

Read-only.

Example

example.ts

const topics = await agent.getActiveNodes({
  tags: ["project:a"],
  tagMode: "all",
});

for (const topic of topics) {
  console.log(topic.id, topic.label, topic.summary);
}

Important behavior

This operation is read-only and waits for the agent's local pending-ingest chain before reading.

With BullMQ queue mode, waiting only guarantees that submission settled; the worker may not have persisted newly queued topics yet.

Suppressed topics are excluded unless includeSuppressed is true.

scope: "tagged" with non-empty tags searches matching topics across sessions. sessionIds and includeForgotten do not affect this topic-node read.