Design the structures your agents work through — not just the prompts you feed them.
Graph engineering is the discipline behind every agent system that survives contact with production. It has two halves:
- Knowledge graphs — what agents remember. Entities and facts as nodes, typed relationships as edges, with time and provenance on every one.
- Task graphs — how agents work. Jobs as nodes, execution dependencies as edges: parallel fan-out, separated verification, one owner of every merge.
Most teams tune the model and the prompt — the two things that matter least once you're past the demo. This repo is about the part that compounds: the structure.
| Path | What it is |
|---|---|
references/methodology.md |
The end-to-end method: value test → ontology → extraction → fusion → serving |
references/task-graphs.md |
Orchestration patterns: the diamond, fake edges, the stop rule, convergent cycles, human gates, loops watching loops |
references/landscape.md |
Curated map of the open-source ecosystem — frameworks, memory engines, papers, courses |
skill/graph-engineering-playbook/SKILL.md |
An agent-loadable skill version of this playbook (Claude Code / Cowork compatible) |
pipeline/ |
A minimal runnable reference pipeline — extract → fuse → serve, stdlib-only Python |
No dependencies. Python 3.10+.
git clone https://github.com/PO-VINCENT/graph-engineering-playbook
cd graph-engineering-playbook/pipeline
# keyless demo (uses pre-extracted fixtures so you can see the full flow)
python run_demo.py --mock
# live extraction (set one of these)
export ANTHROPIC_API_KEY=... # or OPENAI_API_KEY
python run_demo.pyThe demo walks three sample documents through the whole discipline:
[1/4] extract 3 docs → 15 entity mentions, 13 relation candidates (each with an evidence quote)
[2/4] validate 2 relations rejected in code — endpoints violate the ontology's domain/range
[3/4] fuse 15 mentions → 7 canonical entities ("Acme Inc" = "Acme", "Bob Smith" = "Robert Smith")
[4/4] serve "How is Maya Chen connected to Acme?" → 4 paths, serialized as triples with provenance
Every stage is a single readable file (extract.py, fuse.py, serve.py) designed to be
forked into your own stack — not imported as a black box.
- Run the value test first. A graph pays off when queries are multi-hop, entities recur across sources, or relationships are the data. Single-hop lookups → use a table, stop.
- Schema before extraction. Extraction without an ontology produces a word cloud with
arrows. 5–15 entity types, precise verb relations (
ACQUIRED, neverRELATED_TO), domain/range validated in code. - No fact without evidence. Every node and edge carries a verbatim source quote, timestamp, and confidence. Co-occurrence is not assertion.
- Fuse before you trust. Entity resolution is where graph projects die. Block → match (string, attributes, neighborhood) → merge deterministically, with undo.
- The shape of the work decides the team. Parallelize only what's independent; verify in a separate context; give every merge one owner; gate the irreversible.
Rules 1–4 are the knowledge half. Rule 5 is the task half. The references unpack each with the research behind it.
Builders adding memory to agents, teams orchestrating multi-agent systems, and anyone who has watched a "just use RAG" project quietly fail on the first multi-hop question.
This playbook stands on public work it gratefully credits: Southeast University's graduate
Knowledge Graph course by Prof. Peng Wang (npubird/KnowledgeGraphCourse),
the English distillation in codejunkie99/graph-engineering,
the DeepMind × MIT study Towards a Science of Scaling Agent Systems, and the open-source
projects catalogued in references/landscape.md. All prose and
code here are original; errors are ours.
Maintained by Vincent Po Li — building WorkfxAI, growth AI agents for the AI-discovery layer. PRs welcome; see CONTRIBUTING.md.
MIT