FalkorDB graph engine as an opt-in query backend for the skills

[galshubeli]

Hi! Really like this project.
I ran /understand on your own repo to see how it works from the inside.
Disclosure, I work at FalkorDB, so I obviously have a horse in this race.

The idea: an opt-in query backend behind persistence/index.ts. JSON stays the default and stays the source of truth. Loading it into a graph store is just a script, no LLM tokens involved. When it's enabled, the skills query the graph instead of grepping the file.

Why I think it's worth it: chat, explain, diff and onboard all follow the same instruction, "for each matched node ID, Grep for that ID in the edges section". That's a multi-hop traversal being done as repeated text search, so the cost grows with the size of the graph rather than the size of the answer. On a big monorepo, a question like "what breaks if this file changes?" pulls a large slice of the context window before the model reasons about any of it. That question is more or less what understand-diff exists to do.

A few other things a query backend would help with:

• Incremental saves. Right now all of knowledge-graph.json gets rewritten on every update, even though fingerprints.json already knows exactly which files changed. A store can upsert just those nodes.
• Multi-repo ([Feature Request] Multi-repo workspace support and cross-repo knowledge graph #219). Many graphs in one instance that can be queried across, instead of scoping to a subdirectory.
• Vector plus graph in one query. embedding-search.ts is currently a linear scan with hand written cosine similarity. With vector indexing you could find nodes semantically similar to X and traverse their dependency closure in a single query.

A bit of context on FalkorDB itself, in case it's unfamiliar: it's open source, it's built to be multi-tenant so a single instance can hold many graphs at once (which is what makes the multi-repo case natural), and it's fast because queries run on sparse matrix linear algebra rather than pointer chasing.

Worth saying clearly, because "add a database" usually means "ask every user to run a server": it doesn't have to here. There's an embedded build, FalkorDBLite, that's a pip install falkordblite and runs in process with no server and no configuration. Your pipeline already runs Python scripts (merge-batch-graphs.py and friends), so this wouldn't be a new kind of dependency. Anyone who wants the server version for multi-repo or a shared team setup can still run one, but nobody has to.

To be clear about scope: this doesn't touch the analysis phase, which is where the real token cost lives, and it doesn't touch the dashboard, which needs the whole graph in memory to render anyway. Both stay exactly as they are.

@Lum1104, going by your note on #298, we'd build and maintain the adapter on our side. Would an opt-in path like this be welcome? Happy to work to whatever contract makes sense for you.

[Lum1104]

Sure, feel free to open a PR!