Graph Brain
Graph Hacks · FalkorDB

Your outage is
a graph.

It's 3 a.m. and auth-service is down. The answers you need are spread across five tools and one engineer's memory. We put them all in one FalkorDB graph and let two AI agents take it from there.

TL;DR

  1. The problem: incident context is scattered, so agents (and people) guess.
  2. The fix: model the whole company as a graph in FalkorDB: services, owners, customers, decisions, runbooks and memory.
  3. The result: two Gemini agents with no shared context triage, plan and pick the fix that hits 0 VIP customers instead of 3, all through 13 MCP tools that are each one Cypher query.

01 — THE PROBLEMContext is scattered. Agents guess.

Every incident asks the same four questions. What breaks if this breaks? Who has fixed this before? Which customers feel it? What did we decide last time?

The answers exist, but they live in a chat thread, a wiki page, a ticket queue, a pager log and the head of whoever was on call in March. An LLM handed a pile of documents can't follow a dependency three hops out. It guesses, and the guesses sound confident.

Fig. 1 — Before / after
Same facts, different shape. On the left each tool knows one thing. On the right the edges are the knowledge: who owns what, who fixed what, who depends on what.
Operational questions are traversal questions. They were never search questions.The idea the whole project rests on

02 — THE MODELSo we drew the company as one graph.

Graph Brain seeds a realistic company: 5 teams, 15 engineers, 30 services, 5 customers (three of them VIP), plus tickets, docs, design decisions and runbooks. Every fact is a node or an edge in FalkorDB, so it can be queried with OpenCypher.

Fig. 2 — The schema. Service sits in the middle. Click a node to highlight its edges. Multi-tenancy is one graph per tenant: select_graph(f"tenant_{tenant}").
13MCP tools
14relationship types
1Cypher query per tool
0shared LLM context

Every agent capability is a Model Context Protocol tool, and every tool is one parameterized Cypher query in tools.py. The LLM decides what to ask; FalkorDB does the reasoning over structure. That boundary is the reason the answers are right.

03 — BLAST RADIUSWhat breaks if auth-service breaks?

This is the question a dashboard can't answer and a graph answers in one line. Drag the slider to walk the DEPENDS_ON edges outward. The query underneath changes as you go.

Fig. 3 — Interactive · real seed datared = down · amber = customer feels it · ★ = VIP
13services impacted
5customers hit
3VIPs hit
Three hops, fourteen services, every customer. One shared identity service sits under checkout, mobile, reporting and SSO. Nobody's dashboard shows that. The graph does.
tools.py · get_blast_radiusOpenCypher
MATCH p = (up:Service)-[:DEPENDS_ON*1..3]->(s:Service {id: $id}) WITH up, min(length(p)) AS hops OPTIONAL MATCH (t:Team)-[:OWNS]->(up) RETURN up.id, up.tier, hops, t.id ORDER BY hops, up.tier

Then we rank what we found. FalkorDB ships graph algorithms in the engine, so "how critical is this service?" is a single procedure call, not a pipeline:

tools.py · criticalitybuilt-in algorithm
CALL algo.pageRank('Service', 'DEPENDS_ON') YIELD node, score RETURN node.id, score

And customers are just one more hop: (c:Customer)-[:USES]->(:Service)-[:DEPENDS_ON*0..4]->(down). That path is how the agent can say "Globex feels this through checkout → payment-gateway → auth-service" and show its work.

04 — COORDINATIONTwo agents. Zero shared context. One node.

We split the work between a Triage agent and a Remediation agent. They never see each other's prompts or outputs. The only thing they share is an (:Incident) node in FalkorDB, which acts as a tiny state machine.

AGENT 1 · GEMINITriage blast_radius · find_expertrecall_memory · lineage AGENT 2 · GEMINIRemediation get_runbook · compare_actionsassign · log_episode (:Incident) INC-4f2a triaged CREATE MATCH status='triaged' SET status='assigned' auth-serviceAFFECTS DecisionReceiptFOR Gus MorenoASSIGNED_TO
Fig. 4 — The handoff. Triage writes the incident. Remediation finds it by status, plans, and flips it to assigned. Any human can open the graph and see exactly where things stand.
tools.py · assign_incidentstate transition
MATCH (i:Incident {id: $iid}), (p:Person {id: $pid}) OPTIONAL MATCH (:Person)-[old:ASSIGNED_TO]->(i) DELETE old WITH DISTINCT i, p SET i.status = 'assigned', i.plan = $plan CREATE (p)-[:ASSIGNED_TO {at: $now}]->(i)

Why not just pass a message between the agents? Because a message disappears. A node persists, is auditable, and can be read by a third agent we haven't written yet. The graph becomes the coordination protocol.

And who gets assigned? Not whoever is on the rota. find_expert_path walks (Person)-[:RESOLVED]->(Ticket)-[:AFFECTS]->(Service) on the broken service and its neighbours. For auth-service that's Gus Moreno, who fixed a vault token expiry here in 25 minutes. The graph remembers that, even though nobody wrote it on a wiki.

05 — COUNTERFACTUALSPick the fix that hurts no one.

Most incident bots stop at "here's a runbook." We wanted the agent to test a fix before anyone runs it. compare_actions takes two candidate actions, takes the affected services down in the graph, and counts who would feel it.

Fig. 5 — Counterfactual sandbox
REJECTED
A · Rotate the signing key
takes_down: [auth-service]
Services
14Customers
5PageRank risk
high
★ Globex★ Initech★ Umbrella Health
CHOSEN
B · Reroute to fallback region
takes_down: []
Services
0Customers
0PageRank risk
0.0
✓ no VIP impact
(:DecisionReceipt)-[:FOR]->(:Incident)
chosen: "Reroute to fallback region" · rejected: "Rotate the signing key"
why: B hits 0 VIP / 0 customers; A would hit 3 VIP (Globex, Initech, Umbrella Health)
The score is a tuple: (VIPs hit, customers hit, PageRank risk), lowest wins. The verdict is written back as a DecisionReceipt node, so "why did the bot do that?" always has an answer.
✦

"Safe" is a graph question. You can't tell whether an action is safe from the action alone. It depends on who sits downstream, and that's a traversal.

06 — PROCEDURAL MEMORYRunbooks that rewrite themselves.

A runbook is a linked list: (Playbook)-[:FIRST]->(ActionRule)-[:NEXT]->…, with IF_FAILS branches for when a step doesn't work. Because it's a graph, the agent (or you, from chat) can edit it, and the next incident gets the better version.

Fig. 6 — auth_failure runbook
Inserting a step is pointer surgery. Create the new node, point the old step at it, move the old NEXT edge to the new node. Get the order wrong and the runbook silently loses its tail.
tools.py · update_runbook (insert_after)rewire NEXT
// 1. hang the new step off the current one MATCH (s:ActionRule {id: $sid}) CREATE (s)-[:NEXT]->(:ActionRule {id: $nid, text: $text, reason: $why}) // 2. move the old NEXT so the chain stays unbroken MATCH (:ActionRule {id: $sid})-[r:NEXT]->(old:ActionRule {id: $old}), (n:ActionRule {id: $nid}) DELETE r CREATE (n)-[:NEXT]->(old)

07 — MEMORYMemory you can actually look at.

Agent memory is usually a vector store you can't inspect. We stored all three tiers as plain nodes, so you can open FalkorDB and read what the agent knows, edit it, or delete it.

Fig. 7 — Three tiers, one database. Conversational memory lets chat pick up where it left off. Episodic memory is what happened last time. Procedural memory is how to do it next time.

Bonus: the rate limiter lives in FalkorDB too

FalkorDB speaks the Redis protocol, so the Gemini quota guard didn't need a new service. It's two counters with a TTL next to the graph:

app.py · _over_limitRedis protocol
INCR ratelimit:ip:{ip} // EXPIRE 3600 → cap 10 / hour / visitor INCR ratelimit:global // EXPIRE 86400 → cap 300 / day

And if the database is unreachable, the app doesn't crash. It serves a read-only snapshot with a clear "DB unreachable" banner. A demo that dies when the network blinks isn't much of a demo.

08 — WHAT WAS HARDFour walls we hit.

🤝

Agents with no shared memory still have to agree

Fixed by making the Incident node an explicit triaged → assigned state machine.

🧭

"Safe" isn't a property of an action

It's a property of what's downstream. That's how the counterfactual sandbox came about.

🔗

Editing a linked list in Cypher

Insert and remove both mean re-pointing NEXT and FIRST without dropping the chain.

🛟

Staying up when the DB is down

A 503 handler plus a read-only snapshot, so the UI explains itself instead of erroring.

We also wrote test_graph.py, which exercises every Cypher operation without spending a single LLM token. That made it cheap to break things on purpose.

09 — WHAT WE LEARNEDThree things we'd tell our past selves.

i.

Match the database to the shape of the question.

"What breaks?", "who knows?" and "who feels it?" are all paths. In a graph they're one query each. In tables they're a week of joins.

ii.

MCP is the right seam between LLM and data.

Thirteen small tools, each one Cypher query, is easy to test, easy to audit and hard for the model to misuse.

iii.

Memory you can inspect beats memory that merely persists.

When memory is nodes and edges, a human can read it, fix it and trust it.

What's next

  • Ingest real sources: PagerDuty, GitHub and Slack, straight into the graph.
  • Human-in-the-loop approval before any action leaves the sandbox.
  • Learn DEPENDS_ON edge weights from real incident outcomes.
  • Swap our substring search for FalkorDB's full-text and vector indexes.

Break auth-service yourself.

Open the demo, start an incident, and watch the two agents work it out through the graph.