Neat idea. The biggest problem I've had with code knowledge graphs is they go stale immediately -- someone renames a package and nobody updates the graph. Having it as Markdown in the repo is clever because it just goes through normal PR review like everything else, and you get git blame for free. My concern is scale though. Once you have thousands of nodes the Markdown files themselves become a mess to navigate, and at that point you're basically recreating a database with extra steps. Would love to see how this compares to just pointing an agent at LSP output.
I found having smaller structured markdowns in each folder explaining the space and classes within keeps Claude and Codex grounded even in a 10M+ LOC codebase of c/c++
I have a vitepress package in most of my repos. It is a knowledge graph that also just happens to produce heat looking docs for humans when served over http. Agents are very happy to read the raw .md.
Neat idea. The biggest problem I've had with code knowledge graphs is they go stale immediately -- someone renames a package and nobody updates the graph. Having it as Markdown in the repo is clever because it just goes through normal PR review like everything else, and you get git blame for free. My concern is scale though. Once you have thousands of nodes the Markdown files themselves become a mess to navigate, and at that point you're basically recreating a database with extra steps. Would love to see how this compares to just pointing an agent at LSP output.
We all know this isn't for humans. It's for LLMs.
So better question is why there isn't a bootstrap to get your LLM to scaffold it out and assist in detailing it.
You’re replying to an LLM, too, fwiw.
I found having smaller structured markdowns in each folder explaining the space and classes within keeps Claude and Codex grounded even in a 10M+ LOC codebase of c/c++
> "chalk": "^5.6.2",
security.md ist missing apparently.
I have a vitepress package in most of my repos. It is a knowledge graph that also just happens to produce heat looking docs for humans when served over http. Agents are very happy to read the raw .md.
So we are reinventing the docs /*/*.md directory? /s I think this is a good idea just don’t really get why would you need a tool around it
tl;dr: One file, bad (gets too big for context)
So give you agent a whole obsidian
I am skeptical how that helps. Agents cant just grep in one big file if reading entire file is the problem.