<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Rehan Abdul Nayeem</title>
    <description>The latest articles on DEV Community by Rehan Abdul Nayeem (@rn_786).</description>
    <link>https://dev.to/rn_786</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4191758%2Fcd788e8e-cc85-4ebe-a9ab-fa6196d13153.png</url>
      <title>DEV Community: Rehan Abdul Nayeem</title>
      <link>https://dev.to/rn_786</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/rn_786"/>
    <language>en</language>
    <item>
      <title>I gave an AI agent a map of a codebase — and it stopped guessing</title>
      <dc:creator>Rehan Abdul Nayeem</dc:creator>
      <pubDate>Sun, 18 Oct 2026 09:04:32 +0000</pubDate>
      <link>https://dev.to/rn_786/i-gave-an-ai-agent-a-map-of-a-codebase-and-it-stopped-guessing-4024</link>
      <guid>https://dev.to/rn_786/i-gave-an-ai-agent-a-map-of-a-codebase-and-it-stopped-guessing-4024</guid>
      <description>&lt;p&gt;&lt;em&gt;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.&lt;/em&gt;&lt;/p&gt;




&lt;p&gt;There's a question every developer asks when they open a codebase they haven't touched in a few weeks:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;"What breaks if I change this?"&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;And every time, the answer is the same ritual: open twenty files, grep for half an hour, follow imports with your eyes, and still — &lt;em&gt;guess&lt;/em&gt;.&lt;/p&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;What if the agent could see the road network?&lt;/p&gt;

&lt;p&gt;That question became &lt;strong&gt;GraphLens&lt;/strong&gt; — my submission for the &lt;a href="https://www.wemakedevs.org/hackathons/falkordb" rel="noopener noreferrer"&gt;Graph Hacks hackathon&lt;/a&gt; by WeMakeDevs × FalkorDB. And the story of how it almost failed on stage is more useful than the story of how I built it.&lt;/p&gt;




&lt;h2&gt;
  
  
  What GraphLens does
&lt;/h2&gt;

&lt;p&gt;GraphLens turns any Python codebase into a &lt;strong&gt;knowledge graph&lt;/strong&gt;, stores it in &lt;strong&gt;FalkorDB&lt;/strong&gt;, and deploys an AI agent that answers questions by &lt;em&gt;walking the graph&lt;/em&gt; — not by guessing from training data.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Codebase → AST parser → FalkorDB graph → AI agent → Explained answer
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The architecture in three parts:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;1. Deterministic extraction.&lt;/strong&gt; The parser uses Python's built-in &lt;code&gt;ast&lt;/code&gt; module — no embeddings, no vector store, no nondeterminism. Modules, classes, functions, imports, calls, inheritance. Same input, same graph, every time.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;2. FalkorDB as the reasoning substrate.&lt;/strong&gt; The code becomes nodes and edges:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight cypher"&gt;&lt;code&gt;&lt;span class="ss"&gt;(&lt;/span&gt;&lt;span class="py"&gt;parser.py:&lt;/span&gt;&lt;span class="n"&gt;Module&lt;/span&gt;&lt;span class="ss"&gt;)&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="ss"&gt;[&lt;/span&gt;&lt;span class="nc"&gt;:CONTAINS&lt;/span&gt;&lt;span class="ss"&gt;]&lt;/span&gt;&lt;span class="o"&gt;-&amp;gt;&lt;/span&gt; &lt;span class="ss"&gt;(&lt;/span&gt;&lt;span class="py"&gt;parse_codebase:&lt;/span&gt;&lt;span class="n"&gt;Function&lt;/span&gt;&lt;span class="ss"&gt;)&lt;/span&gt;
&lt;span class="ss"&gt;(&lt;/span&gt;&lt;span class="py"&gt;parse_codebase:&lt;/span&gt;&lt;span class="n"&gt;Function&lt;/span&gt;&lt;span class="ss"&gt;)&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="ss"&gt;[&lt;/span&gt;&lt;span class="nc"&gt;:CALLS&lt;/span&gt;&lt;span class="ss"&gt;]&lt;/span&gt;&lt;span class="o"&gt;-&amp;gt;&lt;/span&gt; &lt;span class="ss"&gt;(&lt;/span&gt;&lt;span class="py"&gt;scan_directory:&lt;/span&gt;&lt;span class="k"&gt;Call&lt;/span&gt;&lt;span class="ss"&gt;)&lt;/span&gt;
&lt;span class="ss"&gt;(&lt;/span&gt;&lt;span class="py"&gt;cli.py:&lt;/span&gt;&lt;span class="n"&gt;Module&lt;/span&gt;&lt;span class="ss"&gt;)&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="ss"&gt;[&lt;/span&gt;&lt;span class="nc"&gt;:IMPORTS&lt;/span&gt;&lt;span class="ss"&gt;]&lt;/span&gt;&lt;span class="o"&gt;-&amp;gt;&lt;/span&gt; &lt;span class="ss"&gt;(&lt;/span&gt;&lt;span class="py"&gt;src.parser:&lt;/span&gt;&lt;span class="n"&gt;ExternalModule&lt;/span&gt;&lt;span class="ss"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;3. An agent with graph tools.&lt;/strong&gt; The LLM doesn't "know" the code — it &lt;em&gt;queries&lt;/em&gt; it. Seven tools: PageRank, impact analysis, shortest path, community detection, dependency chains, decision tracing, and raw Cypher. Every answer ships with a &lt;strong&gt;reasoning trace&lt;/strong&gt;: which tool ran, with what arguments, what came back. If the agent says &lt;code&gt;parser.py&lt;/code&gt; is critical, you can see the exact PageRank query that proved it.&lt;/p&gt;

&lt;p&gt;I also added an &lt;strong&gt;MCP server&lt;/strong&gt; so any MCP-compatible assistant can call the same graph tools, and a &lt;strong&gt;memory layer&lt;/strong&gt; where the agent persists facts between sessions.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;🔗 &lt;a href="https://graph-hacks-88hd.onrender.com/" rel="noopener noreferrer"&gt;Live Demo&lt;/a&gt; · &lt;a href="https://github.com/rehannayeem0786/Graph-Hacks" rel="noopener noreferrer"&gt;GitHub&lt;/a&gt;&lt;/strong&gt;&lt;/p&gt;




&lt;h2&gt;
  
  
  The demo that broke at the worst possible moment
&lt;/h2&gt;

&lt;p&gt;Here's the part most hackathon write-ups skip.&lt;/p&gt;

&lt;p&gt;I built everything over a few days. Parser, graph store, agent loop, a dark glassmorphism dashboard with a D3.js force graph. &lt;strong&gt;44 tests, all passing.&lt;/strong&gt; I was confident.&lt;/p&gt;

&lt;p&gt;Then I deployed to Render, opened the live demo, and typed my showcase query — the one I'd planned to demo to judges:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Shortest path from &lt;code&gt;parse_codebase&lt;/code&gt; to &lt;code&gt;GraphStore&lt;/code&gt;&lt;/strong&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;The two most connected symbols in my entire codebase. My own product answered:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;❌ No path found between 'parse_codebase' and 'GraphStore'.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;I spent the next hour debugging against the live database, and found &lt;strong&gt;three bugs stacked on top of each other&lt;/strong&gt;:&lt;/p&gt;

&lt;h3&gt;
  
  
  Bug #1: Synthetic nodes were islands
&lt;/h3&gt;

&lt;p&gt;When &lt;code&gt;cmd_ingest&lt;/code&gt; calls &lt;code&gt;parse_codebase()&lt;/code&gt;, my parser created a synthetic &lt;code&gt;Call&lt;/code&gt; node:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight cypher"&gt;&lt;code&gt;&lt;span class="n"&gt;cmd_ingest&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="ss"&gt;[&lt;/span&gt;&lt;span class="nc"&gt;:CALLS&lt;/span&gt;&lt;span class="ss"&gt;]&lt;/span&gt;&lt;span class="o"&gt;-&amp;gt;&lt;/span&gt; &lt;span class="py"&gt;call:&lt;/span&gt;&lt;span class="n"&gt;parse_codebase&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;But the &lt;em&gt;actual function definition&lt;/em&gt; — &lt;code&gt;function:parser.py:parse_codebase&lt;/code&gt; — was a completely separate node. Nobody ever linked them. Same for &lt;code&gt;GraphStore&lt;/code&gt;. My graph had two parallel worlds: the "real code" world and the "call sites" world, with no bridges between them.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;25 call sites&lt;/strong&gt; were affected. Every function in the project was effectively double-booked.&lt;/p&gt;

&lt;h3&gt;
  
  
  Bug #2: Every import pointed at a ghost
&lt;/h3&gt;

&lt;p&gt;&lt;code&gt;from src.parser import parse_codebase&lt;/code&gt; created an &lt;code&gt;ExternalModule&lt;/code&gt; node called &lt;code&gt;src.parser&lt;/code&gt;. The actual module node was called &lt;code&gt;parser.py&lt;/code&gt;. Different nodes. Zero edges between them.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;32 imports&lt;/strong&gt; in the project — all dead ends. The graph's connective tissue was an illusion.&lt;/p&gt;

&lt;h3&gt;
  
  
  Bug #3: FalkorDB can't walk backwards
&lt;/h3&gt;

&lt;p&gt;This one I found by accident, querying the live playground directly:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;FalkorDB does not currently support undirected shortestPath traversals
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;My shortest-path query only walked edges &lt;strong&gt;forward&lt;/strong&gt;, then tried &lt;strong&gt;backward&lt;/strong&gt; as a fallback. But between these two nodes, no one-way path existed in &lt;em&gt;either&lt;/em&gt; direction — because of bugs #1 and #2. Three bugs, one broken demo.&lt;/p&gt;




&lt;h2&gt;
  
  
  The fix: three parts, one evening
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Part 1 — Link the islands.&lt;/strong&gt; I wrote a &lt;code&gt;link_definitions()&lt;/code&gt; method that runs idempotently on every server start and after every ingest:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight cypher"&gt;&lt;code&gt;&lt;span class="k"&gt;MERGE&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="ss"&gt;(&lt;/span&gt;&lt;span class="py"&gt;c:&lt;/span&gt;&lt;span class="k"&gt;Call&lt;/span&gt;&lt;span class="ss"&gt;)&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="ss"&gt;[&lt;/span&gt;&lt;span class="nc"&gt;:RESOLVES_TO&lt;/span&gt;&lt;span class="ss"&gt;]&lt;/span&gt;&lt;span class="o"&gt;-&amp;gt;&lt;/span&gt;&lt;span class="ss"&gt;(&lt;/span&gt;&lt;span class="n"&gt;def&lt;/span&gt;&lt;span class="ss"&gt;)&lt;/span&gt;      &lt;span class="c1"&gt;// link call sites to real definitions&lt;/span&gt;
&lt;span class="k"&gt;MERGE&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="ss"&gt;(&lt;/span&gt;&lt;span class="py"&gt;e:&lt;/span&gt;&lt;span class="n"&gt;ExternalModule&lt;/span&gt;&lt;span class="ss"&gt;)&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="ss"&gt;[&lt;/span&gt;&lt;span class="nc"&gt;:ALIAS_OF&lt;/span&gt;&lt;span class="ss"&gt;]&lt;/span&gt;&lt;span class="o"&gt;-&amp;gt;&lt;/span&gt;&lt;span class="ss"&gt;(&lt;/span&gt;&lt;span class="n"&gt;m&lt;/span&gt;&lt;span class="ss"&gt;)&lt;/span&gt; &lt;span class="c1"&gt;// src.parser → parser.py&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;On the live graph: &lt;strong&gt;25 call-site links, 32 import aliases&lt;/strong&gt;. The two worlds became one.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Part 2 — Route around the engine.&lt;/strong&gt; Since FalkorDB won't do undirected shortest paths, my &lt;code&gt;find_shortest_path()&lt;/code&gt; tries native directed Cypher first, then falls back to a &lt;strong&gt;Python BFS&lt;/strong&gt; 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:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;parse_codebase ←[CALLS]- ingest -[CALLS]-&amp;gt; GraphStore
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;2 hops. Real path. Honest directions.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Part 3 — Tell the truth when you fail.&lt;/strong&gt; The error messages now distinguish three cases: &lt;em&gt;"No node named X — did you mean Y?"&lt;/em&gt;, &lt;em&gt;"Both exist but are disconnected"&lt;/em&gt;, and &lt;em&gt;"Query error."&lt;/em&gt; A tool that lies about &lt;em&gt;why&lt;/em&gt; it failed is worse than one that fails silently — because it sends you debugging the wrong thing.&lt;/p&gt;

&lt;p&gt;I pushed. Render rebuilt. 90 seconds later:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;✅ &lt;code&gt;parse_codebase ←[CALLS]- ingest -[CALLS]-&amp;gt; GraphStore&lt;/code&gt; — 2 hops&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;I screenshotted it. Obviously.&lt;/p&gt;




&lt;h2&gt;
  
  
  What I learned building this
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Graphs are honest in a way other stores aren't.&lt;/strong&gt; With a vector database, a wrong answer just looks like a wrong answer. With a graph, you can &lt;em&gt;see&lt;/em&gt; 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.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Work with your engine's grain.&lt;/strong&gt; 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.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The demo is the product.&lt;/strong&gt; Everything the judges will actually &lt;em&gt;see&lt;/em&gt; — 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 &lt;em&gt;story&lt;/em&gt;. Budget your time accordingly.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;AI assistants saved me time. They didn't save me from debugging.&lt;/strong&gt; (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 &lt;em&gt;systems&lt;/em&gt; bug — an engine limitation, disconnected components, the difference between a schema that's correct and a schema that's &lt;em&gt;useful&lt;/em&gt;. You only catch those by running the thing and staring at the failure.&lt;/p&gt;




&lt;h2&gt;
  
  
  Try it yourself
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;&lt;a href="https://graph-hacks-88hd.onrender.com/" rel="noopener noreferrer"&gt;Live demo&lt;/a&gt;&lt;/strong&gt; — hit &lt;strong&gt;Run Demo&lt;/strong&gt; in the header for a guided walkthrough, or press &lt;code&gt;Ctrl+K&lt;/code&gt; to search nodes&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;a href="https://github.com/rehannayeem0786/Graph-Hacks" rel="noopener noreferrer"&gt;Source code&lt;/a&gt;&lt;/strong&gt; — MIT licensed&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Self-host in 4 commands:&lt;/strong&gt;
&lt;/li&gt;
&lt;/ul&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;docker run &lt;span class="nt"&gt;-p&lt;/span&gt; 6379:6379 falkordb/falkordb:latest
pip &lt;span class="nb"&gt;install&lt;/span&gt; &lt;span class="nt"&gt;-r&lt;/span&gt; requirements.txt
python &lt;span class="nt"&gt;-m&lt;/span&gt; src.cli ingest ./src
python &lt;span class="nt"&gt;-m&lt;/span&gt; src.cli serve
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The hackathon brief said: &lt;em&gt;"Give your agent a graph. Make decisions you can trace."&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;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.&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Built for Graph Hacks 2026 · Powered by FalkorDB · &lt;a href="https://www.wemakedevs.org/hackathons/falkordb" rel="noopener noreferrer"&gt;Submit your own project&lt;/a&gt;&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;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. 👇&lt;/p&gt;

</description>
      <category>hackathon</category>
      <category>falkordb</category>
      <category>agents</category>
      <category>knowledgegraph</category>
    </item>
  </channel>
</rss>
