Agentic Architectures

Catalogue / Memory

Graph Memory

Turn documents into connected facts and answer by walking them

Shape
memory-loop
Model calls
Ingestion: 1 per document chunk. Question: 2, + 1 per extra hop (at most 2)
Latency
medium
Complexity
high

Also known as Knowledge-graph memory, Triple store memory

1

How do I answer questions that need several facts linked together?

Documents are boiled down to short facts that link two things, such as "Plant Lyon, supplied by, Norden Steel". The facts form a graph. A question is answered by finding the things it names, walking the links around them, and answering only from the facts reached.

You may need it if

  • Questions sound like "which customers depend on a supplier that is late?".
  • The answer is spread over several documents, and no single passage contains it.
  • Search returns relevant pages but the assistant still misses the connection between them.
2

When is a graph more structure than I need?

Use it when

  • Your domain is made of named things and relations, such as accounts, contracts, suppliers or systems.
  • Questions need two or three hops between facts to answer.
  • The same facts are queried many times, so the cost of extraction pays back.

Avoid it when

What it costs

Model calls
Ingestion: 1 per document chunk. Question: 2, + 1 per extra hop (at most 2)
Latency
medium
Complexity
high
3

How do documents become a graph, and how does a question travel through it?

Two entry points share one store. Documents go to an extractor that writes facts into the graph. A question goes to an entity finder, a graph walk collects the facts around the entities, and an answerer replies only from those facts, asking for one more hop when they fall short.

link missing,hops leftanswered or hoplimit reachedQuestion: The question to answer from the graph.QuestionDocuments: New documents, passages or facts to add to the graph.DocumentsFact extractor: Reads documents and writes facts as subject, relation, object, merging names with entities already in the graph.FactextractorEntity finder: Finds the people, companies and things the question names and matches them to graph entities.Entity finderFact graph: Entities linked by typed relations, each fact with the document it came from.Fact graphGraph walk: Collects every fact within a set number of hops of the matched entities.Graph walkAnswerer: Answers strictly from the collected facts, or asks for one more hop when a link is missing.AnswererAnswer: The answer, the chain of facts that supports it, and their source documents.Answer
  1. Step 1 of 6

    Documents become facts

    The extractor reads each new document and writes short facts that link two named things. Before writing, it checks the graph so "Norden Steel AB" joins the existing "Norden Steel" node.

  2. Step 2 of 6

    Questions wait for a current graph

    When documents and a question arrive together, ingestion finishes first, so the question is answered against the latest facts. A run with only documents ends once they are written.

  3. Step 3 of 6

    Find what the question names

    The entity finder picks out the things the question mentions and matches each one to a node in the graph, using names and known aliases.

  4. Step 4 of 6

    Walk the neighbourhood

    A plain graph query, not a model, collects every fact within two hops of the matched entities. This is cheap and returns exactly what is connected.

  5. Step 5 of 6

    Answer from the facts only

    The answerer sees only the collected facts. If the chain breaks one link short, it names the entity to expand and the walk goes one hop further, up to four hops in total.

  6. Step 6 of 6

    Release with the chain

    The answer leaves with the facts it rests on and their source documents. If the graph does not hold the answer, it says so instead of filling the gap.

What each part does
Question
The question to answer from the graph.
Documents
New documents, passages or facts to add to the graph.
Fact extractor
Reads documents and writes facts as subject, relation, object, merging names with entities already in the graph.
Entity finder
Finds the people, companies and things the question names and matches them to graph entities.
Fact graph
Entities linked by typed relations, each fact with the document it came from.
Graph walk
Collects every fact within a set number of hops of the matched entities.
Answerer
Answers strictly from the collected facts, or asks for one more hop when a link is missing.
Answer
The answer, the chain of facts that supports it, and their source documents.
  • Fact extractor → Fact graph: new facts
  • Fact graph → Fact extractor: existing entities
  • Fact extractor → Entity finder: graph up to date
  • Fact graph → Entity finder: entity names
  • Entity finder → Graph walk: matched entities
  • Graph walk → Answerer: connected facts
  • Answerer → Graph walk: link missing, hops left
  • Answerer → Answer: answered or hop limit reached

Where it connects

Entry
question
Question

A question about the entities and relations covered by the graph.

Side input
documents
DocumentEvidenceKnowledge

Documents, sourced passages or ready-made facts to add, each with an identifier of its source.

Exit
answer
Answer

When: The collected facts answer the question, or the hop limit is reached.

The answer, the chain of facts used with their sources, and a clear statement when the graph lacks the answer.

Memory kept between runs
graph
Knowledge

Subject, relation, object facts with one node per real-world entity, a list of aliases, and the source of every fact.

4

What do I ask my assistant to set up?

The agents to launch

Fact extractor

Read the document and list every durable fact as subject, relation, object, with the source. Use a short fixed list of relation names. Before writing, match each subject and object to an existing entity or its aliases, and only create a new entity when none matches.

Sees: One document at a time, the list of relation names and the existing entities with their aliases. Not the questions.

Entity finder

List the entities the question names and match each to a graph entity using names and aliases. Report any name you could not match. Do not answer the question.

Sees: The question and the list of entities with aliases. Not the facts.

Answerer

Answer the question using only the facts given, and cite the facts you used. If a link is missing, name the entity to expand instead of answering. If the facts cannot answer the question, say so plainly.

Sees: The question and the facts collected by the walk. Not the documents and not the rest of the graph.

A prompt you can paste

Works with any assistant that can launch sub-agents. It contains the agents, the procedure and the stop rule above.

Framework-agnostic prompt
You are the orchestrator of a multi-agent workflow that follows the "Graph Memory" architecture.
Launch every agent listed below as a separate sub-agent with its own context. Give each agent only the context stated for it. Do not do an agent's work yourself. If you cannot launch sub-agents, play each agent in a clearly separated turn and never let it use what is withheld from it.

# Task
[Describe your task here]

# Graph Memory
Turn documents into connected facts and answer by walking them.
Input: the task above. It must provide: A question about the entities and relations covered by the graph. If something essential is missing, ask for it before starting.

Agents to launch:
- Fact extractor: Read the document and list every durable fact as subject, relation, object, with the source. Use a short fixed list of relation names. Before writing, match each subject and object to an existing entity or its aliases, and only create a new entity when none matches.
  Context for this agent: One document at a time, the list of relation names and the existing entities with their aliases. Not the questions.
- Entity finder: List the entities the question names and match each to a graph entity using names and aliases. Report any name you could not match. Do not answer the question.
  Context for this agent: The question and the list of entities with aliases. Not the facts.
- Answerer: Answer the question using only the facts given, and cite the facts you used. If a link is missing, name the entity to expand instead of answering. If the facts cannot answer the question, say so plainly.
  Context for this agent: The question and the facts collected by the walk. Not the documents and not the rest of the graph.

Procedure:
1. Set up a graph store with entities, aliases and typed relations, and agree on a list of ten to twenty relation names for your domain.
2. For each new document, launch the fact extractor and write its facts, merging entities as it indicates.
3. When a question arrives, finish any pending ingestion first, then launch the entity finder.
4. Query the graph for every fact within two hops of the matched entities.
5. Launch the answerer on the question and those facts. If it names an entity to expand, add one more hop around it and launch it again, up to four hops in total.

Stop rule: Stop when the answerer answers or declares the graph insufficient, or when the walk reaches four hops, whichever comes first.

Exit:
- `answer`, when: The collected facts answer the question, or the hop limit is reached. Deliver: The answer, the chain of facts used with their sources, and a clear statement when the graph lacks the answer.

# Final deliverable
The answer, the numbered chain of facts used with their source documents, and any entity names that could not be matched.

The same thing in code

LangGraph, python, package langgraph
from typing import Literal, TypeVar

from langchain.chat_models import init_chat_model
from langgraph.graph import END, START, StateGraph
from pydantic import BaseModel

llm = init_chat_model("anthropic:claude-sonnet-5-5")
M = TypeVar("M", bound=BaseModel)
RELATIONS = ["works_for", "owns", "supplies", "located_in", "part_of", "signed"]  # fixed in advance


class Fact(BaseModel):
    subject: str
    relation: str
    object: str
    source: str


class Facts(BaseModel):
    facts: list[Fact]
    aliases: dict[str, str] = {}  # alias or new name -> canonical entity


class Match(BaseModel):
    matched: list[str]
    unmatched: list[str]


class Reply(BaseModel):
    status: Literal["answered", "expand", "insufficient"]
    answer: str = ""
    used_facts: list[int] = []
    expand: str = ""


# the fact graph: an in-memory stand-in for your graph database
FACTS: list[Fact] = []
ALIASES: dict[str, str] = {}
INBOX: list[tuple[str, str]] = []  # (source id, text) waiting to be ingested


def walk(seeds: set[str], hops: int) -> list[Fact]:
    frontier, seen = set(seeds), set(seeds)
    for _ in range(hops):
        frontier = {n for f in FACTS if f.subject in frontier or f.object in frontier for n in (f.subject, f.object)} - seen
        seen |= frontier
    return [f for f in FACTS if f.subject in seen and f.object in seen]


async def ask(schema: type[M], prompt: str) -> M:
    return schema.model_validate(await llm.with_structured_output(schema).ainvoke(prompt))


class State(BaseModel):
    question: str
    seeds: list[str] = []
    unmatched: list[str] = []
    hops: int = 2
    reply: Reply | None = None


async def ingest(state: State) -> dict:
    while INBOX:  # finish pending ingestion before answering
        source, text = INBOX.pop(0)
        out = await ask(Facts, f"List every durable fact as subject, relation, object. Relations: {RELATIONS}. "
                        f"Reuse these entities, add aliases, create new ones only if none match: {ALIASES}\n"
                        f"Source: {source}\n\n{text}")
        ALIASES.update(out.aliases)
        FACTS.extend(f for f in out.facts if f.relation in RELATIONS)
        ALIASES.update({n: n for f in out.facts for n in (f.subject, f.object) if n not in ALIASES})
    return {}


async def finder(state: State) -> dict:
    # sees the entity names and aliases, never the facts
    m = await ask(Match, f"Match each entity the question names to one of these. Do not answer.\n{ALIASES}\n\n{state.question}")
    return {"seeds": [ALIASES.get(n, n) for n in m.matched], "unmatched": m.unmatched}


async def answerer(state: State) -> dict:
    facts = walk(set(state.seeds), state.hops)  # the graph walk; the answerer sees only these facts
    listing = "\n".join(f"{i}. {f.subject} {f.relation} {f.object} [{f.source}]" for i, f in enumerate(facts))
    reply = await ask(Reply, "Answer using only these facts and cite their numbers. If a link is missing, set status "
                      f"'expand' and name the entity. If they cannot answer, say 'insufficient'.\n{listing}\n\n{state.question}")
    if reply.status == "expand":
        return {"reply": reply, "seeds": state.seeds + [reply.expand], "hops": state.hops + 1}
    return {"reply": reply}


def more_hops(state: State) -> str:
    expand = state.reply is not None and state.reply.status == "expand"
    return "answerer" if expand and state.hops <= 4 else END  # the hop limit: four in total


graph = StateGraph(State).add_sequence([ingest, finder, answerer])
graph.add_edge(START, "ingest")
graph.add_conditional_edges("answerer", more_hops, ["answerer", END])
app = graph.compile()


async def run(task: str):
    final = State.model_validate(await app.ainvoke(State(question=task)))
    return final.reply, final.unmatched

Swap the in-memory lists for a real graph database and tune the relation list to your domain before ingesting anything.

Claude Agent SDK, python, package claude-agent-sdk
from typing import Literal, TypeVar

from claude_agent_sdk import AgentDefinition, ClaudeAgentOptions, ResultMessage, query
from pydantic import BaseModel

M = TypeVar("M", bound=BaseModel)
RELATIONS = ["works_for", "owns", "supplies", "located_in", "part_of", "signed"]  # fixed in advance


class Fact(BaseModel):
    subject: str
    relation: str
    object: str
    source: str


class Facts(BaseModel):
    facts: list[Fact]
    aliases: dict[str, str] = {}  # alias or new name -> canonical entity


class Match(BaseModel):
    matched: list[str]
    unmatched: list[str]


class Reply(BaseModel):
    status: Literal["answered", "expand", "insufficient"]
    answer: str = ""
    used_facts: list[int] = []
    expand: str = ""


AGENTS = {
    "fact-extractor": AgentDefinition(
        description="Turns one document into subject-relation-object facts.",
        prompt=f"List every durable fact as subject, relation, object with its source. Relations: {RELATIONS}. "
        "Match names to the existing entities and aliases; create an entity only when none matches.",
        tools=[],
    ),
    "entity-finder": AgentDefinition(
        description="Matches the entities a question names to graph entities.",
        prompt="Match each entity the question names to a graph entity by name or alias. "
        "Report names you could not match. Do not answer the question.",
        tools=[],
    ),
    "answerer": AgentDefinition(
        description="Answers strictly from the facts it is given.",
        prompt="Answer using only the facts given and cite their numbers. If a link is missing, set status "
        "'expand' and name the entity. If the facts cannot answer, set status 'insufficient'.",
        tools=[],
    ),
}

# the fact graph: an in-memory stand-in for your graph database
FACTS: list[Fact] = []
ALIASES: dict[str, str] = {}
INBOX: list[tuple[str, str]] = []  # (source id, text) waiting to be ingested


def walk(seeds: set[str], hops: int) -> list[Fact]:
    frontier, seen = set(seeds), set(seeds)
    for _ in range(hops):
        frontier = {n for f in FACTS if f.subject in frontier or f.object in frontier for n in (f.subject, f.object)} - seen
        seen |= frontier
    return [f for f in FACTS if f.subject in seen and f.object in seen]


async def delegate(agent: str, payload: str, schema: type[M]) -> M:
    # one query per launch, so the sub-agent sees only what it is handed
    options = ClaudeAgentOptions(
        agents={agent: AGENTS[agent]}, tools=["Agent"], allowed_tools=["Agent"], max_turns=4,
        output_format={"type": "json_schema", "schema": schema.model_json_schema()},
    )
    async for message in query(prompt=f"Hand this input unchanged to the {agent} agent and return its result:\n\n{payload}", options=options):
        if isinstance(message, ResultMessage):
            return schema.model_validate(message.structured_output)
    raise RuntimeError(f"{agent} returned nothing")


async def run(task: str):
    while INBOX:  # finish pending ingestion first; the extractor never sees questions
        source, text = INBOX.pop(0)
        out = await delegate("fact-extractor", f"Entities and aliases: {ALIASES}\nSource: {source}\n\n{text}", Facts)
        ALIASES.update(out.aliases)
        FACTS.extend(f for f in out.facts if f.relation in RELATIONS)
        ALIASES.update({n: n for f in out.facts for n in (f.subject, f.object) if n not in ALIASES})
    match = await delegate("entity-finder", f"Entities and aliases: {ALIASES}\n\nQuestion: {task}", Match)
    seeds, hops = {ALIASES.get(n, n) for n in match.matched}, 2
    while True:
        facts = walk(seeds, hops)
        listing = "\n".join(f"{i}. {f.subject} {f.relation} {f.object} [{f.source}]" for i, f in enumerate(facts))
        reply = await delegate("answerer", f"Facts:\n{listing}\n\nQuestion: {task}", Reply)
        if reply.status != "expand" or hops == 4:  # the stop rule: four hops at most
            return reply, [facts[i] for i in reply.used_facts if i < len(facts)], match.unmatched
        seeds.add(ALIASES.get(reply.expand, reply.expand))
        hops += 1

Swap the in-memory lists for a real graph database, and run ingestion as a separate job so questions never wait on it.

OpenAI Agents SDK, python, package openai-agents
from typing import Literal

from agents import Agent, Runner
from pydantic import BaseModel

RELATIONS = ["works_for", "owns", "supplies", "located_in", "part_of", "signed"]  # fixed in advance


class Fact(BaseModel):
    subject: str
    relation: str
    object: str
    source: str


class Alias(BaseModel):
    name: str
    entity: str


class Facts(BaseModel):
    facts: list[Fact]
    aliases: list[Alias]


class Match(BaseModel):
    matched: list[str]
    unmatched: list[str]


class Reply(BaseModel):
    status: Literal["answered", "expand", "insufficient"]
    answer: str
    used_facts: list[int]
    expand: str


extractor = Agent(
    name="Fact extractor",
    instructions=f"List every durable fact as subject, relation, object with its source. Relations: {RELATIONS}. "
    "Match names to the existing entities and aliases; create an entity only when none matches.",
    output_type=Facts,
)
finder = Agent(
    name="Entity finder",
    instructions="Match each entity the question names to a graph entity by name or alias. "
    "Report names you could not match. Do not answer the question.",
    output_type=Match,
)
answerer = Agent(
    name="Answerer",
    instructions="Answer using only the facts given and cite their numbers. If a link is missing, set status "
    "'expand' and name the entity. If the facts cannot answer, set status 'insufficient'.",
    output_type=Reply,
)

# the fact graph: an in-memory stand-in for your graph database
FACTS: list[Fact] = []
ALIASES: dict[str, str] = {}
INBOX: list[tuple[str, str]] = []  # (source id, text) waiting to be ingested


def walk(seeds: set[str], hops: int) -> list[Fact]:
    frontier, seen = set(seeds), set(seeds)
    for _ in range(hops):
        frontier = {n for f in FACTS if f.subject in frontier or f.object in frontier for n in (f.subject, f.object)} - seen
        seen |= frontier
    return [f for f in FACTS if f.subject in seen and f.object in seen]


async def run(task: str):
    while INBOX:  # finish pending ingestion first; the extractor never sees questions
        source, text = INBOX.pop(0)
        out = (await Runner.run(extractor, f"Entities and aliases: {ALIASES}\nSource: {source}\n\n{text}")).final_output_as(Facts)
        ALIASES.update({a.name: a.entity for a in out.aliases})
        FACTS.extend(f for f in out.facts if f.relation in RELATIONS)
        ALIASES.update({n: n for f in out.facts for n in (f.subject, f.object) if n not in ALIASES})
    match = (await Runner.run(finder, f"Entities and aliases: {ALIASES}\n\nQuestion: {task}")).final_output_as(Match)
    seeds, hops = {ALIASES.get(n, n) for n in match.matched}, 2
    while True:
        facts = walk(seeds, hops)  # the answerer sees only the walked facts, never the documents
        listing = "\n".join(f"{i}. {f.subject} {f.relation} {f.object} [{f.source}]" for i, f in enumerate(facts))
        reply = (await Runner.run(answerer, f"Facts:\n{listing}\n\nQuestion: {task}")).final_output_as(Reply)
        if reply.status != "expand" or hops == 4:  # the stop rule: four hops at most
            return reply, [facts[i] for i in reply.used_facts if i < len(facts)], match.unmatched
        seeds.add(ALIASES.get(reply.expand, reply.expand))
        hops += 1

Swap the in-memory lists for a real graph database and tune the relation list to your domain before ingesting anything.

Vercel AI SDK, typescript, package ai
import { anthropic } from '@ai-sdk/anthropic';
import { generateText, Output } from 'ai';
import { z } from 'zod';

const model = anthropic('claude-sonnet-5-5');
const RELATIONS = ['works_for', 'owns', 'supplies', 'located_in', 'part_of', 'signed'] as const; // fixed in advance

const factSchema = z.object({ subject: z.string(), relation: z.enum(RELATIONS), object: z.string(), source: z.string() });
type Fact = z.infer<typeof factSchema>;

// the fact graph: an in-memory stand-in for your graph database
const facts: Fact[] = [];
const aliases = new Map<string, string>(); // alias or name -> canonical entity
const inbox: { source: string; text: string }[] = []; // documents waiting to be ingested

function walk(seeds: Set<string>, hops: number): Fact[] {
  const seen = new Set(seeds);
  let frontier = new Set(seeds);
  for (let i = 0; i < hops; i++) {
    const next = new Set<string>();
    for (const f of facts) {
      if (frontier.has(f.subject) || frontier.has(f.object)) [f.subject, f.object].forEach((n) => !seen.has(n) && next.add(n));
    }
    next.forEach((n) => seen.add(n));
    frontier = next;
  }
  return facts.filter((f) => seen.has(f.subject) && seen.has(f.object));
}

async function ask<T>(instructions: string, prompt: string, schema: z.ZodType<T>): Promise<T> {
  const { output } = await generateText({ model, instructions, prompt, output: Output.object({ schema }) });
  return output;
}

export async function run(task: string) {
  const known = () => JSON.stringify(Object.fromEntries(aliases));
  for (let doc = inbox.shift(); doc; doc = inbox.shift()) { // finish pending ingestion first
    const out = await ask(
      `List every durable fact as subject, relation, object with its source. Relations: ${RELATIONS.join(', ')}. ` +
        'Match names to the existing entities and aliases; create an entity only when none matches.',
      `Entities and aliases: ${known()}\nSource: ${doc.source}\n\n${doc.text}`,
      z.object({ facts: z.array(factSchema), aliases: z.array(z.object({ name: z.string(), entity: z.string() })) }),
    );
    out.aliases.forEach((a) => aliases.set(a.name, a.entity));
    for (const f of out.facts) {
      facts.push(f);
      [f.subject, f.object].forEach((n) => aliases.has(n) || aliases.set(n, n));
    }
  }
  // the entity finder sees names and aliases, never the facts
  const match = await ask(
    'Match each entity the question names to a graph entity by name or alias. Report names you could not match. Do not answer.',
    `Entities and aliases: ${known()}\n\nQuestion: ${task}`,
    z.object({ matched: z.array(z.string()), unmatched: z.array(z.string()) }),
  );
  const seeds = new Set(match.matched.map((n) => aliases.get(n) ?? n));
  for (let hops = 2; ; hops++) {
    const found = walk(seeds, hops); // the answerer sees only the walked facts
    const listing = found.map((f, i) => `${i}. ${f.subject} ${f.relation} ${f.object} [${f.source}]`).join('\n');
    const reply = await ask(
      "Answer using only the facts given and cite their numbers. If a link is missing, set status 'expand' " +
        "and name the entity. If the facts cannot answer, set status 'insufficient'.",
      `Facts:\n${listing}\n\nQuestion: ${task}`,
      z.object({ status: z.enum(['answered', 'expand', 'insufficient']), answer: z.string(), usedFacts: z.array(z.number().int()), expand: z.string() }),
    );
    if (reply.status !== 'expand' || hops === 4) { // the stop rule: four hops at most
      return { ...reply, chain: reply.usedFacts.map((i) => found[i]).filter(Boolean), unmatched: match.unmatched };
    }
    seeds.add(aliases.get(reply.expand) ?? reply.expand);
  }
}

Swap the in-memory arrays for a real graph database and tune the relation list to your domain before ingesting anything.

Snippets are generated when the site is built and type-checked against the SDK versions listed in the repository. Treat them as a starting skeleton.

What goes wrong

  • Free-form relation names fragment the graph into synonyms. Fix the list of relations in advance.
  • Without alias matching, one company becomes several nodes and walks miss most of its facts.
  • Walking too many hops floods the answerer with loosely related facts. Start at two and widen only on request.

Chain it

Its result can feed