MemoGrafter
ingestText()
Convert raw text into topic and memory nodes, inline or through the configured queue.
What it does
Convert raw text into topic and memory nodes, inline or through the configured queue.
When to use it
Use for application-owned notes or documents associated with an explicit session ID.
Signature
TypeScript
ingestText(text: string, sessionId: string, options?: IngestTextOptions & IngestOptions): Promise<TopicNode[]>Parameters
text (string) — Raw text to analyze and convert into memories.sessionId (string) — The application-owned session whose memory should be read or changed.options? (IngestTextOptions & 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.IngestTextOptions fields
replace? (boolean, default false) — Clear the target session graph before processing this text.label? (string) — Supply a document/topic label instead of relying only on extraction.source? (string) — Preserve an application-defined provenance label.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, or an empty array after queue submission.
Behavior
Chunks and extracts text into the same graph model as conversations. Queue mode returns an empty array after submission.
Side effects and completion
replace: true clears the target session graph before new text is processed.Example
example.ts
const nodes = await memo.ingestText(note, "project-a", { label: "Roadmap" });Important behavior
Text is chunked internally and may produce multiple topics.
replace: true clears the existing session graph before processing the text.