Docs/Recall & memory injection

Guide

Recall & memory injection

Choose the correct read path for retrieving atomic facts, assembling broader topic context, or letting invoke() handle memory automatically.

Estimated time: 8 minutes

Level: Intermediate

Prerequisites:Installation·Quick Start

Overview

Recall and grafting both turn stored graph memory into useful context, but they operate at different levels. Recall ranks atomic memory facts; grafting assembles broader topic context and can expand through graph neighbours.

When to use this

Build your own LLM request instead of using invoke().

Inspect the evidence behind a response.

Choose explicit topics for a prompt.

Decide whether memory should only be read or copied into another session.

Choose the right operation

Use invoke() to recall, answer, and learn in one high-level chat operation.

Use recall() for ranked atomic facts and prompt-ready context without an assistant completion.

Use graft() when the application already knows the topic IDs to assemble.

Use graftByRelevance() when a query should select topic seeds before assembly.

Use absorbFromAgent() only when selected memory should be copied into another agent session.

Read-path decision flow

Choose intent

Recall facts

Assemble topics

Copy when needed

Step 1: Recall structured facts

Recall is side-effect free. It embeds the query, searches active memories, ranks facts, loads parent topics, and formats fact blocks until the token budget is reached.

recall.ts

const result = await agent.recall("deployment preferences", {
  limit: 8,
  minSimilarity: 0.55,
  tokenBudget: 1000,
  scoring: { similarityWeight: 0.7, confidenceWeight: 0.3 },
});

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

Step 2: Use recalled context in your LLM call

Keep application policy separate and higher priority than recalled content. Memory is evidence, not trusted instruction text.

custom-chat.ts

const memory = await agent.recall(userMessage);
const answer = await llm.complete(
  [{ role: "user", content: userMessage }],
  memory.systemPrompt,
);

Step 3: Assemble topic context

Explicit grafting preserves broader topic summaries and nearby source context. It is useful when a user or application has already selected topics.

graft.ts

const topics = await agent.getActiveNodes();
const context = await agent.graft([topics[0]!.id]);

console.log(context.nodes);
console.log(context.systemPrompt);

Full example

manual-memory-loop.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.remember("Deploy production services to the eu-west-1 region.");
  const memory = await agent.recall("Where should production be deployed?", {
    limit: 5,
    tokenBudget: 800,
  });

  const answer = await llm.complete(
    [{ role: "user", content: "Where should production be deployed?" }],
    memory.systemPrompt,
  );
  console.log(answer);
} finally {
  await agent.close();
}

How filtering and ranking work

Normal recall excludes decayed, superseded, forgotten, and suppressed-topic memories.

minSimilarity is the vector-search floor.

Returned facts are ranked using configured similarity and confidence weights.

Facts are grouped by parent topic and stopped at the token budget.

Tag scope can keep recall session-local or intentionally search tagged memory across sessions.

Common mistakes

Using grafting when only a few atomic facts are required.

Copying memory into another session when a read-only preview is enough.

Treating systemPrompt as application policy rather than untrusted memory context.

Increasing limit without checking the token budget.

Debugging thresholds before confirming ingestion and lifecycle state.