I stopped my AI agent from guessing: RepoBrain, an explainable team brain on FalkorDB

Ask an AI who knows a part of your codebase best and you get a confident answer. Ask it how it knows, and the confidence disappears. That gap is why I built RepoBrain for the Graph Hacks hackathon by FalkorDB and WeMakeDevs: an agent that answers by walking a knowledge graph, and shows its work every time.
The problem
Every team loses context: who owns this module, why it was designed this way, what breaks if I change this file. The answers are buried in commits, pull requests and design docs, and the useful part is the relationships between them. A chatbot that searches text can only guess at those, and you cannot see why it is wrong.
The idea
RepoBrain loads the real history of the Flask repository into FalkorDB (about 2,280 commits, 125 people, 596 files, 8 design decisions and roughly 10,500 edges) and lets agents answer by walking the graph. Every answer shows three things:
• the path it took, animated hop by hop in the UI
• the Cypher that was actually run
• the sources it is based on: commits, files, people, issues, PRs and design decisions
How it works
FalkorDB keeps three graphs side by side: repo (people, commits, files, modules, PRs, issues and design decisions), mem: (a private memory graph for each user) and agents (where two agents hand work to each other).
A question like "Who knows src/flask/app.py best?" becomes one traversal:
MATCH (f:File {path: $path})<-[t:TOUCHES]-(c:Commit)<-[:AUTHORED]-(p:Person)
RETURN p.name AS person, count(c) AS commits, sum(t.adds) AS adds,
max(c.date) AS last_touched
ORDER BY commits DESC LIMIT 10
The Investigator agent has seven graph tools, including blast radius (following import edges up to two hops), FalkorDB's native algo.pageRank for the most central files, and algo.SPpaths for shortest paths. The same tools are exposed as an MCP server. After each answer, the Investigator writes a Finding into the agents graph, and a Reviewer agent reads it from there and writes a review brief with risky files and suggested reviewers. Every question is also saved in the user's own memory graph and recalled next time.
Without an LLM key, RepoBrain falls back to template mode: the answer is composed straight from the graph results, still with path, Cypher and sources. The graph finds the facts, and the LLM only narrates them.
What I learned
• Let the graph hold the facts and the model narrate them. Template mode works because the answer is already in the query result, which makes every answer traceable.
• Put agent coordination in data, not in prompts. The two agents only share a Finding node, so the hand-off is easy to inspect and easy to show in the UI.
• Keep the agent loop small and strict. One JSON object per turn, at most six tool calls, and one nudge for a bad reply before falling back.
• Prefer two honest nodes over one guessed edge. Git authors and GitHub users stay separate Person nodes, because matching emails to logins would need a fuzzy guess.
How I built it
AI coding assistants helped me build RepoBrain, and I used OpenCode for that. I decided what to build and how the graph is structured, and the repo includes 22 tests that run against the real ingested graph.
Try it
You only need Docker:
cp .env.example .env
docker compose up --build
Open http://localhost:5173 and wait 2 to 4 minutes for the first ingest. Five one-click questions are built into the chat.
Code: https://github.com/Aakash9969/repobrain
Community detection with algo.WCC is the next step. Built for Graph Hacks by FalkorDB and WeMakeDevs, entering all three tracks: Agents That Act on Connected Data, Agent Memory and Coordination, and Company Brain.