Building a Company Brain with a Graph Database: HandsOnRepo's Practice with FalkorDB

When Your Codebase Becomes the Company's Only Memory

Every engineering organization holds a vast amount of knowledge that "nobody wrote down": who truly owns a piece of code (not the person listed in CODEOWNERS, but the one who actually changes it most), who should review this PR, why a particular change was rolled back, and what risks would arise if a certain person left. This information is scattered across commit history, review threads, merge events, and revert messages—newcomers often spend six months asking around before they grasp it.

According to a sharing by the HandsOnRepo team on dev.to, they ran an experiment with the graph database FalkorDB: turning FalkorDB's own GitHub organization into a "company brain" graph, then asking it questions that exist only in relationship paths. The project was built for the Graph Hacks hackathon co-hosted by WeMakeDevs and FalkorDB, and entered three tracks: Company Brain, Agents That Act on Connected Data, and Agent Memory and Coordination.

A Real, Verifiable Answer

The opening question posed in the article is: "Why was the SQL Server loader documentation in QueryWeaver rolled back, and who decided it?"

The answer: commit 819b96a reverted 6cc5a67, executed by Anchel135, in PR #719, merged by Gal Shubeli. The reason comes from the revert message: this file should have belonged to the SQL Server branch, and on the current branch it would break spellcheck.

This is not fabricated demo data—every link is clickable and verifiable, and the graph query takes tens of milliseconds. The answer exists only as a "path": a file, a commit that changed it, a commit that reverted that commit, the PR they belong to, the author and merger, and a revert message two hops away from the question.

Why Document Retrieval Can't Solve This Problem

The team's core insight: these questions are multi-hop—from file to commit, to person, to review, to PR, to comment, to who merged, to what reverted it. A text chunk cannot carry a path; a graph can.

This explains the ceiling of many RAG solutions in enterprise knowledge management. Vector retrieval excels at "finding similar content," but when the essence of a question is "who is connected to whom through what relationship," the granularity of document chunks is wrong.

Scale and Composition of the Graph

Data comes from two sources: the GitHub GraphQL API pulls PRs, issues, reviews, comments, and releases; a bare git clone fetches commit history and the files each commit touches. Repositories are pulled in parallel, and a mid-sized organization completes in about three minutes on a laptop.

FalkorDB's organization graph ultimately contains 8 repositories, 21,181 nodes, and 73,700 edges. Among them, REVERTS edges are parsed from commit messages and PR bodies, TOUCHES aggregates all commits by a person on a file, and REVIEWED_FOR points from reviewer to author and serves as input to PageRank. Owner Fact nodes carry SUPERSEDES history—when ownership changes, the old answer is retained rather than overwritten.

Multi-hop reasoning refers to question types where the answer cannot be obtained directly from a single text fragment but requires chaining multiple entities and their relationships. In the context of knowledge graphs, a hop is an edge; starting from "file," it takes four hops—"modified by commit," "commit submitted by person," "commit's PR," "PR merged by person"—to reach the answer of "who decided the rollback." The underlying assumption of vector retrieval is semantic similarity: split documents into chunks, encode them as vectors, and recall the closest chunks by cosine distance. It inherently loses the topological structure between entities, so when a question requires "walking N steps along relationships," the recalled content either lacks key intermediate links or mixes contexts from different PRs. The advantage of a graph database is precisely that it stores relationships as first-class citizens, making multi-hop queries an indexed traversal rather than repeated guessing over text chunks.

The Answer Is Computed by the Graph, Not Guessed by the Model

The chat agent is a tool-calling loop over 18 graph tools, using the model gpt-5-mini. The key design: the model does not answer the question—it only selects tools; tools execute Cypher or FalkorDB algorithms, and the model only handles wording. Each question costs about half a cent, and the graph computation takes 2 to 90 milliseconds.

Taking "Who should review changes under lib in falkordb-browser, and why" as an example, the agent calls the who_knows tool, matches files, follows TOUCHES and REVIEWED edges to find people, then ranks them:

commits_on_topic + 2 * reviews_on_topic + 40 * PageRank(reviewer -> author)

Ultimately Anchel135 ranks first: 210 commits touching 64 files under lib, and 26 reviews involving PRs for these files. The ranking is the graph's conclusion, not the model's guess.

The team emphasizes: without FalkorDB, the entire system doesn't work—no cache, no fallback storage, the graph is the product itself.

PageRank is a graph algorithm used by Google in its early days for web page ranking. The core idea: a node's importance is recursively determined by the importance of nodes pointing to it, with a damping factor (usually 0.85) handling random jumps. In this project, PageRank is applied to the graph formed by "reviewer → author" relationships, meaning: if a person frequently reviews authors who themselves are reviewed by many people, their weight is higher. This makes ranking no longer rely on coarse-grained counts like commit numbers, but distinguishes "high-frequency but peripheral" from "low-frequency but core" participants. Notably, PageRank's input is the direction and weight design of REVIEWED_FOR edges; reversing the direction or failing to filter bot nodes will systematically skew results—which is why the team stresses that "without handling bots, rankings are entirely distorted."

Four Real Findings About FalkorDB

All findings come from public data, and each can be linked to evidence.

1. One person solely owns 145 files no one else has touched. Guy Korland touched 283 files across the organization, of which 145 were never committed by any other human, plus 10 open PRs and 18 assigned issues. The graph also lists potential successors for each directory, so this is a to-do list, not a scare tactic.

2. A rollback whose reason lies three hops away. In the QueryWeaver example above, the context (SQL Server branch, spellcheck failure, who merged PR #719) is scattered across commits, PRs, and comment threads. No single page on GitHub shows this path.

3. The vector index has a clear owner and backup. For graph/src/index, Dvir Dukhan has 186 commits touching 30 matching files and 22 related PR reviews; Avi Avni has 93 commits touching 51 files. Codex, via MCP and without being prompted, arrived at the same two candidates.

4. Without handling bots, rankings are entirely distorted. In the FalkorDB organization, 225 accounts are bots or shared automation identities. Dependabot, Copilot, CodeRabbit, and release bots commit and comment more than most humans. Flagging them is the watershed for whether answers are trustworthy.

Building a Brain for an Unfamiliar Organization from Scratch: A Validation

The most common skepticism about demo projects is: does it only work on data you prepared? So the team entered an organization they had never opened, google-ai-edge, and clicked Build brain.

212 seconds later: 36,514 nodes, 112,095 edges, covering its eight most active repositories. The suggested questions on the empty chat interface were generated from that organization's own graph, not preset: its busiest area, most active people, a traceable real PR.

Asking "Who should review changes to the Gallery app" yielded Kangning Chen (382 commits, 104 Gallery files, last touch two days ago), followed by Zichuan Wei (311 commits, 84 files). Asking "What happens if Sebastian Schmidt leaves" yielded 877 touched files, of which 695 were touched only by him—and this was an organization opened just four minutes earlier.

Agent Memory: One Graph, Three Clients

Every answer is stored back into FalkorDB as an Episode node, referencing its source. Before the next question, the agent does a full-text query over memory, and matches are shown as "Remembered from earlier." Because memory lives in the graph rather than the process, it survives restarts.

Three agents share this memory without messaging each other: the chat agent in the web app, a triage agent launched when a GitHub webhook triggers an issue (finds likely owners via the graph, comments with evidence, leaves an Action node), and any MCP client.

The MCP server exposes the same 18 tools, supporting Claude Desktop, Claude Code, Cursor, Codex, VS Code, Gemini CLI, and Cline. The team's first real task for Codex was: "I want to change the vector index code under graph/src/index"—Codex called who_knows, reverts, decision_trail, and remember, wrote PR_NOTES.md, designated Dvir Dukhan as primary reviewer and Avi Avni as backup, and stored the decision as an Episode. Then the web app's chat agent displayed "Remembered from earlier." One graph, two clients, shared state, zero glue code.

MCP (Model Context Protocol) is an open protocol proposed and open-sourced by Anthropic for connecting AI applications to external tools and data sources in a unified way. It uses a client-server architecture: an MCP server declares a set of tools and their JSON Schemas, and clients (such as Claude Desktop, Cursor, Codex) call them as needed during conversations. Compared to writing a separate plugin for each IDE or chat interface, MCP decouples "what can be done" from "who calls it," so the same 18 graph tools can be reused by the web app, the webhook-triggered triage agent, and any MCP-compatible client. In this project, MCP also handles shared state: once an Episode node is written to the graph, any client's next query can read it, eliminating the need for a message bus between agents.

Pitfalls: Engineering Lessons Worth Borrowing

The team candidly listed several technical lessons:

Free-text-to-Cypher is not reliable enough. Early on, letting the model write Cypher from scratch led it to invent relationship names, forget to filter bots, and generate different queries for the same question each time. The final solution is 18 parameterized, tested Cypher tools; the model only selects and phrases, with a read-only run_cypher as a last resort that rejects write operations.

FalkorDB has no undirected shortestPath. find_path needs to traverse bidirectional edges connecting people and PRs; the team switched to algo.SPpaths with relDirection: 'both' covering 15 relationship types.

Subqueries with EXISTS are not supported. The original "files touched only by this person" query used it, later rewritten as WITH f, collect(p) AS ps WHERE size(ps) = 1, which is actually clearer.

A 100 MB free instance can hold a 21k-node organization (about 83 MB). The memory hogs are indexes and comment bodies, not nodes and edges. To fit two organizations on a small instance, trim comment text and design full-text indexes carefully.

Git identity is not GitHub user. Commit authors appear as names and emails, often noreply addresses. The team collapsed them to GitHub login names by email, name, and noreply patterns, keeping uncollapsible ones as names without handles, never displayed as mentions.

Text-to-Cypher refers to letting a large model directly translate natural language questions into Cypher query statements. It looks impressive in demos but has three systematic risks in production: first, hallucinated relationship or property names—queries pass syntax but are semantically wrong; second, missing business constraints, such as forgetting to filter bot nodes or deleted repositories, causing statistical drift; third, inconsistent results across multiple generations for the same question, making answers non-reproducible and hard to audit. The parameterized-tool approach solidifies "query intent" into tested templates, with the model only selecting from a tool list and filling parameters, converging uncertainty into a controllable range. A read-only run_cypher as a fallback preserves exploratory capability while rejecting write operations to avoid accidental data changes—a common defensive design in such systems.

Performance and Cost Data

Measured on a laptop: full ingestion takes about 3 minutes (repositories pulled in parallel), incremental sync about 7 seconds, graph time per tool call 2 to 90 milliseconds, cost per answer about half a cent, and GitHub API quota consumed per organization under 100 points out of 5,000 per hour.

Try It

Running locally requires Docker, Python 3.12+, Node 20+, a GitHub token with public_repo permission, and an OpenAI key—three commands to start. The online demo is at handsonrepo.vercel.app; the free FalkorDB Cloud instance is 100 MB, and two brains already occupy about 95%, so the public demo is limited to 150 questions per day to control the OpenAI bill. The code is open-sourced under the MIT license at github.com/mithuna2357/FalkorDB.

The most valuable aspect of this project is not "yet another RAG demo," but that it clearly delineates the capability boundary between document retrieval and graph retrieval: when the answer to a question is a path rather than a passage of text, a graph database is not an optimization—it's a necessity.