Inspecting & reviewing memory

Trace what MemoGrafter retained, why a fact was recalled, its lifecycle state, and where transferred memory came from.

Estimated time: 7 minutes

Level: Beginner

Overview

Review combines application reads with Studio. Start from the query that produced unexpected behavior, then move from retrieved facts to parent topics, lifecycle state, history, and provenance before changing thresholds.

When to use this

Validate extraction before shipping a workflow.

Explain why a memory appeared in a prompt.

Debug a missing or stale result.

Review forgotten, suppressed, conflicting, or superseded records.

Trace memory copied from another session.

Step 1: Reproduce recall

recall-debug.ts

const result = await agent.recall("refund policy", {
  limit: 10,
  minSimilarity: 0.4,
});

console.table(result.facts.map((fact) => ({
  id: fact.id,
  value: fact.value,
  similarity: fact.similarity,
  confidence: fact.confidence,
})));

Step 2: Inspect the graph snapshot

Snapshots intentionally include inactive lifecycle rows so inspection tools can show what normal active reads omit.

snapshot.ts

const snapshot = await agent.getGraphSnapshot();
console.log(snapshot.snapshotNodes);
console.log(snapshot.snapshotMemories);
console.log(snapshot.memoryEdges);

Step 3: Inspect history and change

history.ts

const history = await agent.getMemoryHistory("user", "location");
const diff = await agent.getMemoryDiff(oldMemoryId, newMemoryId);

console.log(history.entries);
console.log(diff.changedFields);

Step 4: Review in Studio

Open the session in Graph View and select the parent topic.

Inspect memory confidence, source, tags, lifecycle flags, and edges.

Use Prompt Preview with the original query.

Compare the exact generated prompt before adjusting retrieval settings.

Apply supported lifecycle actions only after resolving the correct node.

Full review workflow

review.ts

const recall = await agent.recall(query, { limit: 10, minSimilarity: 0.4 });
const snapshot = await agent.getGraphSnapshot();

for (const fact of recall.facts) {
  const lifecycle = snapshot.snapshotMemories.find(
    ({ memory }) => memory.id === fact.id,
  )?.lifecycle;
  console.log({ fact, lifecycle });
}

Why memory may be missing

Ingestion has not completed yet.

Extraction created a topic summary but no matching atomic memory.

The query embedding falls below minSimilarity.

The fact was trimmed by limit or tokenBudget.

The memory is decayed, superseded, forgotten, or attached to a suppressed topic.

Tags or scope exclude the record.

Best practices

Debug with the exact production query and scope.

Record source metadata during ingestion.

Review both similarity and extraction confidence.

Use history and diff for changing facts rather than reading only the newest row.

Keep Studio local and do not expose its internal API publicly.