Decision Brain: Using a Graph Database to Recover the "Why" for AI Coding

When code only remembers "what to do" and forgets "why"

Nearly every team has run into this scenario: during review, someone spots a line of code that looks obviously "wrong" and fixes it on the spot—quietly breaking a deliberate design decision from years ago. Code records what the program does, but never why it was done that way. That "why" is usually scattered across decision logs, old commit history, and someone's memory—and those three places are exactly the ones nobody opens when editing code.

AI coding agents make this problem worse. They change code quickly and confidently, yet know nothing about its history. Decision Brain, submitted by developer Peter Green at the Graph Hacks hackathon (FalkorDB × WeMakeDevs), takes direct aim at this problem: turn a repository's decision records and git history into a FalkorDB graph, so that every change can see the decisions, evidence, and knowledgeable people behind it before it merges.

A counterintuitive real-world case

In Peter's own project, a router prompt contained a factual error: it said the memory expert "can only read," but the memory module can actually save facts. Any reviewer or coding agent would want to fix it. They did change it once, and then measured—with the corrected text, the smallest model routed "remember this…" to the memory module 0 out of 20 times; with the "wrong" old text, 16 out of 20.

So the erroneous line stayed, with the reasoning buried in a paragraph of a 1,900-line decision log. The next person to open that file sees nothing. This is precisely the gap Decision Brain aims to close: bring the "why" into view at the moment a change happens.

ADR (Architecture Decision Record) is a lightweight documentation convention: each major technical decision becomes a standalone short file, typically recording the context, alternatives, final decision, and consequences, and lives in the version control system alongside the code. It differs from a centralized decision log like DECISIONS.md in granularity—ADRs are usually one decision per file, numbered, with a status that can be marked proposed/accepted/superseded. The GOV.UK content-publisher and log4brains mentioned in this article are both repositories that adopt the ADR ecosystem, which is why Decision Brain needs to support both "section-based logs" and "one decision per file" formats.

What exactly goes into the graph

Decision Brain's ingestion has two tracks, and this division of labor is itself part of the design.

Code handles deterministic extraction—no model involved

Git history is converted into Commit, File, and Person nodes (AI co-authors are marked as agents). Each decision log entry—a section of DECISIONS.md, or an ADR file—becomes a Decision node with a date, status, and precise source line numbers, linked via git blame to the commit that recorded it. Every historical version of the repository's AI agent instruction files (CLAUDE.md, AGENTS.md, .cursorrules) is also saved as a dated snippet, so "what the agent was instructed to do at the time of this commit" becomes a queryable question.

A local agent team does the reading, collaborating via Cypher

Four workers claim entries from a shared "kanban graph" and extract metrics, experiments (including conclusions), the files and concepts involved, and relationships between entries. The kanban itself is also a FalkorDB graph, with claiming, discovery, and handoffs all done through Cypher. Because FalkorDB serializes writes to a single graph, the claim operation is naturally atomic:

MATCH (s:Section)
WHERE (s.status = 'pending' OR (s.status = 'claimed' AND s.expiresAt < $now))
  AND s.attempts < $max AND coalesce(s.waiting, 0) = 0
WITH s ORDER BY s.order LIMIT 1
MATCH (a:Agent {name: $agent})
SET s.status = 'claimed', s.claimedBy = $agent, s.expiresAt = $now + $ttl, s.attempts = s.attempts + 1
CREATE (a)-[:CLAIMED {at: $now}]->(s)

Claims expire, so entries from a crashed worker can be taken over; the waiting field makes a directory summary wait for the files beneath it to finish first. When one agent believes entry A supersedes entry B, it initiates a "handoff"—which only counts once another agent confirms it by each quoting a passage from the source. On Invarail's 151 entries, the team initiated 15 handoffs, confirmed 9, and the rest were rejected by the second agent with reasons visible on the kanban.

Cypher is the graph query language introduced by Neo4j, describing nodes and edges with ASCII-art-style patterns, e.g. (a:Agent)-[:CLAIMED]->(s:Section) represents a CLAIMED edge from Agent to Section. Its core is the declarative MATCH … WHERE … SET/CREATE style, combined with expressions like coalesce, collect, and list comprehensions for conditional filtering and aggregation. FalkorDB is compatible with a subset of OpenCypher, so the claim statement in this article can perform the compound "filter—sort—lock—write" operation under the same transactional semantics—which is exactly the key reason to use a graph database as a kanban rather than a relational table.

Anything the model writes goes through checks first

Every quote must appear verbatim in the entry, every number must appear within its cited source, every filename must exist in git; a file summary that mentions a function or class not in the file is rejected. Peter also admits this checker has its own bugs: it once rejected 13 good summaries because no file contained the full string TaskStore.add, and now requires each part of a qualified name to appear as an identifier—but this still can't prove that add belongs to TaskStore.

Finally, a derived RATIONALE edge links a decision to the files it was based on, and FalkorDB's built-in algorithms answer structural questions directly: which files carry the most reasoning (algo.pageRank), how two things are connected (algo.SPpaths).

Asking and verifying: the answer is only the beginning

The query agent is an ordinary tool-calling loop built around twelve MCP tools—why, what_breaks, disproven, who_knows, trace, origin, told, review, etc.—each corresponding to a short Cypher query, and the same tools can serve any MCP client.

What Peter cares most about is not how the model answers, but how the code checks the answer afterward: every [id] cited must have actually been returned by a tool in the current turn; every number must appear in the evidence of the cited entry (citing 0/20 against the wrong source is a failure); "I don't know" is only a valid abstention if the rest of the answer makes no claims. The page states "verified 2 citations · 8 numbers match the evidence" and labels the body text as "written by the model," because the wording itself is not verified by code.

Code review: the most convincing part of the demo

This demo wasn't originally planned, but it became the most valuable use case. The review page runs entirely in the browser: a contributor "fixes" the erroneous router rule, and before merging, the system reconstructs the decision log as of that commit's state (rebuilt from git, not today's files), then presents:

• R1: the "wrong" rule in the router prompt is load-bearing—measured 0/20 vs 16/20
• D1: "the corrected router prompt text fixes 7B's memory routing"—tried, and disproven
• P1: who knows this file

Then, in a clearly labeled simulated one-off copy, the team records a new decision: retire 7B and fix the rule on a supported model, measured at 20/20 vs 19/20. Click Sync, and Decision Brain picks up only the changed parts—one agent proposes the "supersession," a second confirms—and the resubmitted amendment is guided by the new decision, with the old decision listed as superseded, plus one line the script didn't arrange: "fixing the rule works for qwen2.5:7b" recorded as disproven under the new decision. The old constraint survives as a live warning, scoped to where it still applies. The new evidence doesn't simply "win."

Review the original proposal again, and it still shows the evidence of its time—a change judged by what was known when it was made.

Does graph retrieval actually help? A set of controlled data

Before running any experiments, Peter froze 24 questions spanning three repositories: Invarail (his own project), GOV.UK's content-publisher, and log4brains, which he had never seen before. The key comparison was the same local model using keyword search results instead of the graph tools. The experiment ran twice, with the second scored by a new agent that only saw an anonymized A/B table.

Metric	Decision Brain	Same model + keyword search
Required evidence found	20/20 · 20/20	15/20 · 15/20
Answers passing the rubric	17/20 · 16/20	11/20 · 10/20
Correcting false premises	4/4 · 4/4	2/4 · 2/4
Correct "I don't know"	4/4 · 4/4	4/4 · 4/4
Median latency	20.6s · 22.9s	7.9s · 7.8s

The gap comes almost entirely from retrieval: when keyword search misses the entry the answer depends on, the model has nothing to work from, whereas the graph tools find it. The cost is roughly 2.6–2.9× the latency. Peter is also honest about the margin: if every borderline judgment went against Decision Brain, the result would be 14 vs 12—still ahead, but the advantage in premise correction would disappear. All data is in eval/v2/.

MCP (Model Context Protocol) is an open protocol that lets models call external tools and data sources in a unified way: the server declares a set of tools with names, parameter schemas, and descriptions, and the client (such as Claude Desktop, IDE plugins, or a custom agent) makes calls as needed during a conversation and feeds the results back to the model. The twelve tools of the query agent in this article (why, what_breaks, who_knows, etc.) are an implementation of this protocol, so the same graph capabilities can plug into any MCP-compatible client without changes—the tools are the interface, and the model only decides which one to call.

Pitfalls, all written into the record

Every correction is dated in DECISIONS.md. A few worth remembering:

• The grounding checker over-asserted three times: treating "Not surprisingly…" as a premise with no numbers, treating any negation as an abstention, accepting numbers attributed to the wrong decision. Each was caught by an external reviewer, and each is now a test.
• A FalkorDB upgrade silently broke queries: on 6.x, a list comprehension after a nested comprehension returned []. CI ran a newer image than the local machine, causing intermittent failures; he first suspected the payload, then hash collisions, before finally pinpointing it. The fix was to switch to plain MATCH … collect and pin the image version.
• The first fresh clone on an unfamiliar repo failed in four ways: date-named ADRs, two records written on the same day conflicting, a function deleted while fixing a bug, and a commit written months before the merge time. All four got tests, followed by one clean, uninterrupted run.
• The demo itself found two bugs: an old experiment under a superseded decision still showed a "don't retry" warning; and the agent asked the user to revisit a decision the graph already knew was replaced. The demo is the test.

Getting started and next steps

The code, setup, and evaluation are on GitHub. You need Docker, Node 22.9+, and an OpenAI-compatible model service that supports tool calling (the author used glm-5.3-flash on vLLM; qwen3.8:27B on Ollama also works). Point it at any repository with a DECISIONS.md or an ADR directory.

The bigger idea goes beyond code: the same graph structure applies to any decision record, not just code—business documents, spreadsheets, policy files—where every change can be linked back to its rationale. Near-term plans include question memory (answered questions reused by the next agent), section-by-section reading of very long entries, and a GitHub Action that automatically posts reviews on every pull request.

For readers following AI coding tools, the most valuable takeaway from this project isn't a particular trick but an orientation: in an era where agents are increasingly capable of changing code, making the "why" into infrastructure is more reliable than leaving it in someone's head.