Most coding assistants see your project as a pile of text chunks. They guess which files matter, forget what you told them yesterday, and can't tell you why they answered the way they did.

We wanted the opposite: an agent whose working context is a graph. So we built ORBIT, a local-first personal AI agent that uses FalkorDB as its context layer. Every project you authorize becomes a code graph the agent traverses, every memory is a node linked to its concepts, and every answer shows the Cypher behind it.

Repo: https://github.com/SinghCharanjeet11/orbit

Demo video (2 min): https://youtu.be/jOIPAibwpO8

The problem with "chunk and retrieve"

Ask a typical assistant "What breaks if I change execute_tool?" and it searches for files that mention the name, reads a few, and guesses. It misses the file that imports the module that imports the function, because that file never says execute_tool at all.

That isn't a text-search question. It's a graph traversal: follow the IMPORTS and CALLS edges backwards, a few hops deep. So we put the code into a graph database and let the agent traverse it.

Step 1: Turn a project into a graph

When you authorize a folder, ORBIT parses it locally (Python with ast, JS/TS imports and definitions with patterns) and writes one isolated FalkorDB graph per project:

(:File {path, lang, lines})-[:DEFINES]->(:Symbol {name, qual, kind, line})
(:File)-[:IMPORTS]->(:File)
(:File)-[:USES_PACKAGE]->(:Package {name})
(:Symbol)-[:CALLS]->(:Symbol)

Only structure goes into the graph: paths, names, line numbers and links. File contents and secrets never do, and .env files aren't even read.

Building is a handful of batched writes, one per node or edge type:

UNWIND $rows AS e
MATCH (a:File {path: e[0]}), (b:File {path: e[1]})
CREATE (a)-[:IMPORTS]->(b)

On ORBIT's own backend this takes about a second: 52 files, 373 symbols, 107 imports, 433 resolved calls and 7 packages. FalkorDB keeps a separate graph per project (orbit_code_ID), so projects never bleed into each other.

Step 2: Questions become traversals

"What depends on this file, directly or indirectly?" is one query:

MATCH p = (d:File)-[:IMPORTS*1..4]->(f:File {path: $path})
WHERE d <> f
RETURN d.path AS path, min(length(p)) AS hops
ORDER BY hops, path

"How does a request get from the API route to the tool executor?" is a shortest path:

MATCH (a:Symbol {name: 'agent_loop'}), (b:Symbol {name: 'execute_tool'})
WITH shortestPath((a)-[:CALLS*1..8]->(b)) AS p
RETURN [n IN nodes(p) | n.file + '::' + n.qual] AS call_chain

It returns:

routes.py::agent_loop → loop.py::run_loop → loop.py::run_tool → registry.py::execute_tool

In our app most of these queries finish in 1 to 5 ms. That matters: it's fast enough to run on every step of the agent loop, not just once up front.

Step 3: Let the agent choose graph tools

The graph agent works in small steps. Each turn the model returns one JSON action, and ORBIT runs it. The tools are graph-first:

• find_symbol: where a function is defined, who calls it, what it calls

• impact_of: every file that depends on a file, up to 4 hops

• call_chain: the shortest call path between two functions

• file_context: a file's imports, importers, packages and impact

• package_users: which files use a third-party package

• cypher_query: the model writes its own read-only Cypher

It reads a file only when the graph says that file matters. Asked "What depends on execute_tool?", the model called find_symbol, then wrote its own variable-length CALLS query, and answered with the exact callers. No guessing, and every step in the UI shows the Cypher it ran.

Safety: model-written Cypher runs through FalkorDB's GRAPH.RO_QUERY, which rejects any query that would write, plus a timeout and a row cap. The agent has no write tool at all. Proposed file changes wait for the user's approval.

Step 4: Memory is a graph too

Personal agents need memory, but dumping everything into a vector store makes it impossible to say why something was recalled. In ORBIT, memories live in a graph:

(:Memory)-[:MENTIONS]->(:Concept)
(:Memory)-[:ABOUT]->(:Project)
(:Conversation)-[:HAS_TURN]->(:Turn)-[:RECALLED]->(:Memory)

Recall is a query: concepts in your message lead to confirmed memories, ranked higher when they are about the active project:

UNWIND $concepts AS c
MATCH (k:Concept {name: c})<-[:MENTIONS]-(m:Memory {confirmed: true})
WITH m, collect(k.name) AS via
OPTIONAL MATCH (m)-[:ABOUT]->(p:Project {id: $project})
RETURN m.id, size(via) + CASE WHEN p IS NULL THEN 0 ELSE 1 END AS score, via
ORDER BY score DESC

Save "I deploy my projects with Docker Compose on a Hetzner VPS", then ask "How should I deploy my next side project?". The answer builds on that memory and shows which memory it used. ORBIT also stores a (:Turn)-[:RECALLED]->(:Memory) edge, so later you can see which answers used which memory. That is provenance, not just retrieval.

Architecture

React UI --(local token proxy)--> FastAPI --> FalkorDB (code graphs + memory graph)
                                    |--> SQLite (chats, proposals, audit)
                                    |--> any OpenAI-compatible model (Groq gpt-oss-120b in our demo)

FalkorDB holds every relationship the agent reasons over. If it's down, ORBIT says "FalkorDB offline" and refuses graph features instead of quietly falling back to guessing. The graph isn't decoration. The product runs on it.

Things that surprised us

1. Reasoning models sometimes hide the answer. gpt-oss-120b occasionally returned an empty content field and put the final JSON at the end of its reasoning. We now recover the last valid JSON object from the reasoning text.

2. Free tiers limit tokens per minute, per model. A multi-step agent hits that quickly. Since the limit is per model, ORBIT switches to a fallback model on a 429 before waiting.

3. Store structure, not content. Keeping only names and edges in the graph made privacy simple and made queries fast. The agent reads actual file text only when it needs it, after redaction and after the user consents.

4. Showing the Cypher builds trust. Once every answer showed the query behind it, wrong answers became easy to debug. It's also the best demo of what the graph is doing.

Try it

git clone https://github.com/SinghCharanjeet11/orbit.git && cd orbit
cp .env.example .env        # add any OpenAI-compatible key (we used Groq)
docker compose up -d        # FalkorDB
python scripts/dev.py       # backend + frontend

Open http://localhost:5173, authorize a folder (ORBIT's own backend folder is a good first one), and ask the graph agent what depends on what.

Built by Charanjeet and Chirag. Thanks to the FalkorDB team for a graph database fast enough to sit inside an agent loop.