1How 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.
2When 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
- Answers sit in one passage of one document. Plain retrieval is cheaper and keeps the original wording.
Use Agentic RAG instead - Questions ask for themes or summaries across a whole corpus, not specific linked facts.
Use GraphRAG instead - What must be remembered is a conversation with one user, not a body of documents.
Use Episodic + Semantic Memory instead
What it costs
- Model calls
- Ingestion: 1 per document chunk. Question: 2, + 1 per extra hop (at most 2)
- Latency
- medium
- Complexity
- high
3How 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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
A question about the entities and relations covered by the graph.
Documents, sourced passages or ready-made facts to add, each with an identifier of its source.
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.
Subject, relation, object facts with one node per real-world entity, a list of aliases, and the source of every fact.
4What 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.
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
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.
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.
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.
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
- Reflection conditional
Condition: Use this link only when the question asks for an explanation or synthesis drawn from several facts, not when the answer is a single entity, value or 'not in the graph' statement.
- Chain of Verification direct
Treat the graph answer as an existing answer whose claims must be verified. Check each claim independently, then report it as confirmed, corrected or removed, keeping the source chain alongside.
- Debate conditional
Condition: Use this link only when the question requires inference or judgement across the facts (for example ranking, weighing risk, or choosing between options), not a direct lookup of a stated relation.
- Constitutional Critique direct
Check the graph answer against each rule in the constitution and fix only the failed rules. Preserve the fact chain, the sources and any statement that the graph lacks the answer.
- Textual Backpropagation conditional
Condition: Use the link only when the graph-memory payload contains an actual answer backed by a fact chain, not a statement that the graph lacks the answer.