Docs/Ingesting & extracting memory

Guide

Ingesting & extracting memory

Turn conversations, documents, notes, and explicit natural-language facts into incremental topic and memory graphs.

Estimated time: 8 minutes

Level: Beginner

Overview

MemoGrafter uses one write-side pipeline for conversational turns and raw text. It segments new material by topic, creates topic summaries, extracts atomic memories, embeds them, and appends graph edges without rebuilding prior memory.

When to use this

Import notes, articles, handbooks, or journal entries without generating a chat response.

Store an explicit preference through natural language.

Understand when invoke() has already handled ingestion.

Choose between appending content and intentionally replacing a session graph.

What you’ll build

A document-memory flow that imports a handbook section, records source metadata and tags, waits for ingestion, and recalls a policy fact later.

Memory construction pipeline

Raw text is split into internal chunks. Topic drift detection can create several segments from one input, and each segment can produce one topic node and multiple atomic memory nodes.

Raw text

Segment

Embed

Store

Link graph

Step 1: Choose the write path

Use invoke() for a user/assistant exchange; it schedules ingestion automatically.

Use ingestText() for documents or notes without a generated response.

Use remember() for a concise natural-language fact or preference.

Step 2: Ingest source text

Text ingestion does not add material to getHistory() and does not call the response-generation path. The extraction LLM still summarizes segments and extracts structured memories.

import-handbook.ts

import {
  MemoGrafterAgent,
  OpenAIEmbedAdapter,
  OpenAILLMAdapter,
} from "memo-grafter";

const llm = new OpenAILLMAdapter("gpt-4o");
const embedder = new OpenAIEmbedAdapter("text-embedding-3-small");

const agent = new MemoGrafterAgent({
  db: { connectionString: process.env.DATABASE_URL! },
  llm,
  embedder,
});

await agent.initialize();

await agent.setSessionTags(["project:support", "policy"]);
await agent.ingestText(handbookSection, {
  label: "Refund policy",
  source: "support-handbook:v3",
});

Step 3: Store an explicit fact

remember() is a convenience wrapper around text ingestion. It is suitable for natural-language facts, not exact row-level inserts.

remember.ts

await agent.remember("Refund requests are accepted within 30 days.", {
  label: "Refund window",
  source: "policy-settings",
});

Step 4: Verify the result

verify.ts

const result = await agent.recall("How long can a customer request a refund?", {
  tags: ["policy"],
  scope: "session-and-tags",
});

console.log(result.facts);
console.log(result.systemPrompt);

Full example

document-memory.ts

import {
  MemoGrafterAgent,
  OpenAIEmbedAdapter,
  OpenAILLMAdapter,
} from "memo-grafter";

const llm = new OpenAILLMAdapter("gpt-4o");
const embedder = new OpenAIEmbedAdapter("text-embedding-3-small");

const agent = new MemoGrafterAgent({
  db: { connectionString: process.env.DATABASE_URL! },
  llm,
  embedder,
});

await agent.initialize();

try {
  await agent.setSessionTags(["project:support", "policy"]);
  await agent.ingestText(handbookSection, {
    label: "Support handbook",
    source: "handbook:v3",
  });

  const memory = await agent.recall("refund eligibility", {
    tags: ["policy"],
    scope: "session-and-tags",
    limit: 5,
  });
  console.log(memory.facts);
} finally {
  await agent.close();
}

How incremental ingestion works

The session ingest cursor records the last processed message index.

Repeated ingestion of an unchanged history is a graph no-op.

New ranges use a small overlap window for topic context, then append nodes and edges.

The cursor advances only after graph writes succeed.

Normal ingestion preserves existing topics, memories, grafts, and provenance.

Replace versus append

ingestText() appends by default. Use replace: true only when the input represents the complete current document and the stored session graph should be rebuilt.

Replacement removes stored messages, graph records, segments, grafts, and ingest state for the session.

It does not change the generated agent session ID or clear public conversational history.

Do not use replacement as a routine autosave shortcut without accepting its destructive scope.

Best practices

Preserve a stable source value for provenance.

Use normalized tags for project and document grouping.

Split extremely large imports into meaningful bounded sources.

Review extraction quality in Studio before changing drift settings.

Wait for queue workers before expecting asynchronously ingested memory to appear.

Common mistakes

Manually ingesting an exchange already processed through invoke().

Using replace: true when content should be appended.

Expecting raw text to appear in public chat history.

Treating remember() as a deterministic database insert.

Changing embedding dimensions without migrating the vector schema.