ingest()

Ingest messages inline or submit them through the configured queue.

What it does

Ingest messages inline or submit them through the configured queue.

When to use it

Use when the application owns ordered conversation history and session IDs and can accept configured queue semantics.

Signature

TypeScript

ingest(messages: Message[], sessionId: string, options?: IngestOptions): Promise<TopicNode[]>

Parameters

messages (Message[]) — Ordered conversation messages to extract memory from.

sessionId (string) — The application-owned session whose memory should be read or changed.

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

IngestOptions fields

tags? (string[]) — Normalized metadata copied to topics and memories created by this ingestion.

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

Newly created TopicNode[] during inline ingestion. With queue mode, this returns an empty array after accepting the job; use ingestNow() when the graph must be available immediately.

Behavior

Processes only the unprocessed suffix after the stored ingest cursor. Inline mode returns created topics; queue mode returns an empty array after job acceptance.

Side effects and completion

Persists or queues messages, topic segments, topics, structured memories, graph edges, and ingest-cursor progress.

Example

example.ts

const nodes = await memo.ingest(messages, "user-42", { tags: ["profile"] });

Important behavior

Ingestion is incremental and processes only the suffix after the stored ingest cursor.