How I built GraphLens for the Graph Hacks hackathon, the FalkorDB limitation that broke my live demo at the worst possible moment, and the three things every developer building graph-powered agents should know.
There's a question every developer asks when they open a codebase they haven't touched in a few weeks:
"What breaks if I change this?"
And every time, the answer is the same ritual: open twenty files, grep for half an hour, follow imports with your eyes, and still — guess.
AI coding assistants are brilliant at writing code. They're terrible at explaining systems. Because they read files one at a time — like someone studying a city one building at a time, trying to infer the road network.
What if the agent could see the road network?
That question became GraphLens — my submission for the Graph Hacks hackathon by WeMakeDevs × FalkorDB. And the story of how it almost failed on stage is more useful than the story of how I built it.
What GraphLens does
GraphLens turns any Python codebase into a knowledge graph, stores it in FalkorDB, and deploys an AI agent that answers questions by walking the graph — not by guessing from training data.
Codebase → AST parser → FalkorDB graph → AI agent → Explained answer
The architecture in three parts:
1. Deterministic extraction. The parser uses Python's built-in ast module — no embeddings, no vector store, no nondeterminism. Modules, classes, functions, imports, calls, inheritance. Same input, same graph, every time.
2. FalkorDB as the reasoning substrate. The code becomes nodes and edges:
(parser.py:Module) -[:CONTAINS]-> (parse_codebase:Function)
(parse_codebase:Function) -[:CALLS]-> (scan_directory:Call)
(cli.py:Module) -[:IMPORTS]-> (src.parser:ExternalModule)
3. An agent with graph tools. The LLM doesn't "know" the code — it queries it. Seven tools: PageRank, impact analysis, shortest path, community detection, dependency chains, decision tracing, and raw Cypher. Every answer ships with a reasoning trace: which tool ran, with what arguments, what came back. If the agent says parser.py is critical, you can see the exact PageRank query that proved it.
I also added an MCP server so any MCP-compatible assistant can call the same graph tools, and a memory layer where the agent persists facts between sessions.
The demo that broke at the worst possible moment
Here's the part most hackathon write-ups skip.
I built everything over a few days. Parser, graph store, agent loop, a dark glassmorphism dashboard with a D3.js force graph. 44 tests, all passing. I was confident.
Then I deployed to Render, opened the live demo, and typed my showcase query — the one I'd planned to demo to judges:
Shortest path from
parse_codebasetoGraphStore
The two most connected symbols in my entire codebase. My own product answered:
❌ No path found between 'parse_codebase' and 'GraphStore'.
I want to sit with that for a second, because this is the kind of moment that separates projects that ship from projects that get abandoned at 3 AM.
I spent the next hour debugging against the live database, and found three bugs stacked on top of each other:
Bug #1: Synthetic nodes were islands
When cmd_ingest calls parse_codebase(), my parser created a synthetic Call node:
cmd_ingest -[:CALLS]-> call:parse_codebase
But the actual function definition — function:parser.py:parse_codebase — was a completely separate node. Nobody ever linked them. Same for GraphStore. My graph had two parallel worlds: the "real code" world and the "call sites" world, with no bridges between them.
25 call sites were affected. Every function in the project was effectively double-booked.
Bug #2: Every import pointed at a ghost
from src.parser import parse_codebase created an ExternalModule node called src.parser. The actual module node was called parser.py. Different nodes. Zero edges between them.
32 imports in the project — all dead ends. The graph's connective tissue was an illusion.
Bug #3: FalkorDB can't walk backwards
This one I found by accident, querying the live playground directly:
FalkorDB does not currently support undirected shortestPath traversals
My shortest-path query only walked edges forward, then tried backward as a fallback. But between these two nodes, no one-way path existed in either direction — because of bugs #1 and #2. Three bugs, one broken demo.
The fix: three parts, one evening
Part 1 — Link the islands. I wrote a link_definitions() method that runs idempotently on every server start and after every ingest:
MERGE (c:Call)-[:RESOLVES_TO]->(def) // link call sites to real definitions
MERGE (e:ExternalModule)-[:ALIAS_OF]->(m) // src.parser → parser.py
On the live graph: 25 call-site links, 32 import aliases. The two worlds became one.
Part 2 — Route around the engine. Since FalkorDB won't do undirected shortest paths, my find_shortest_path() tries native directed Cypher first, then falls back to a Python BFS over an adjacency list fetched in a single round trip. ~660 edges — trivial to walk. The BFS tracks direction per hop, so the UI renders honest arrows:
parse_codebase ←[CALLS]- ingest -[CALLS]-> GraphStore
2 hops. Real path. Honest directions.
Part 3 — Tell the truth when you fail. The error messages now distinguish three cases: "No node named X — did you mean Y?", "Both exist but are disconnected", and "Query error." A tool that lies about why it failed is worse than one that fails silently — because it sends you debugging the wrong thing.
I pushed. Render rebuilt. 90 seconds later:
✅
parse_codebase ←[CALLS]- ingest -[CALLS]-> GraphStore— 2 hops
I screenshotted it. Obviously.
What I learned building this
Graphs are honest in a way other stores aren't. With a vector database, a wrong answer just looks like a wrong answer. With a graph, you can see the missing edge. The bug wasn't in my algorithm — it was in my data model. I had drawn a distinction (real definition vs. call site) that mattered deeply to my parser and meant absolutely nothing to someone querying the graph. If your schema encodes concepts your users don't share, they will find every edge case you accidentally built.
Work with your engine's grain. I burned an hour fighting Cypher syntax when the right answer was "this engine doesn't support this operation — take the data into Python." A single round-trip BFS was the correct tool. It felt like cheating for ten minutes. Then I remembered that every system I admire — every database, every distributed service — routes around limitations exactly like this.
The demo is the product. Everything the judges will actually see — the reasoning trace, the direction-aware arrows, the did-you-mean errors — got built in the last stretch, after the "real work" was done. My 44 tests gave me confidence. The 90 seconds of live verification gave me the story. Budget your time accordingly.
AI assistants saved me time. They didn't save me from debugging. (Disclosure: I used AI coding assistants throughout, per the hackathon rules.) They wrote boilerplate, test scaffolding, and boilerplate-adjacent code while I spent my attention on the data model. But the bug that broke my demo was a systems bug — an engine limitation, disconnected components, the difference between a schema that's correct and a schema that's useful. You only catch those by running the thing and staring at the failure.
Try it yourself
-
Live demo — hit Run Demo in the header for a guided walkthrough, or press
Ctrl+Kto search nodes - Source code — MIT licensed
- Self-host in 4 commands:
docker run -p 6379:6379 falkordb/falkordb:latest
pip install -r requirements.txt
python -m src.cli ingest ./src
python -m src.cli serve
The hackathon brief said: "Give your agent a graph. Make decisions you can trace."
GraphLens traces every decision to the exact edge it walked. And after this weekend, I'd trust it — not because it's perfect, but because when it broke, it told me exactly where.
Built for Graph Hacks 2026 · Powered by FalkorDB · Submit your own project
If you've ever debugged a database limitation at 2 AM and found something better on the other side — I'd love to hear it in the comments. 👇
Top comments (0)