Your README explains your architecture. Your docs folder explains your decisions. And until today, none of that existed in Octocode's knowledge graph.

0.20.0 closes that gap: Markdown files are now nodes in the GraphRAG knowledge graph, and links between documents become typed references relationships an AI assistant can actually traverse.

This one has bothered me for a while. Octocode could always find your docs — semantic search indexed Markdown from early on. But finding a doc by keyword and discovering it by following the structure of the project are two different things. An assistant asking "what depends on the payment module?" could walk the code graph beautifully — and stay completely blind to the architecture note sitting three directories away that explains why the module looks like that.

Code told half the story. The graph now knows the other half.

What Actually Changed

Here's the short version: Markdown documents now flow through the same GraphRAG pipeline as source code during indexing. Graph queries, relationship expansion, and the graphrag MCP tool can surface documentation alongside code — not as a separate search, but as part of the same traversal.

The mechanics that make it useful rather than noisy:

Cross-document links become references relationships. When one Markdown file links to another — [see the guide](guide.md) — Octocode records a typed edge between them. Relative links resolve against the linking file's location, anchor fragments (#section) get stripped, and external http:///https:// URLs are ignored. Your docs' link structure was always a map. Now the graph reads it.

The weighting is deliberate. In graph traversal, references carries an importance weight of 0.6 — below structural code relationships like imports and calls (0.7), above organizational ones like same-directory grouping (0.3). Document links meaningfully shape expansion without drowning out code structure. A link between two docs is a human saying "these belong together" — that's a real signal, but it's not the same as an actual call edge, and the weights reflect that.

.markdown files are supported everywhere .md is. Both semantic search and the new graph integration. Small thing, but it was an inconsistency that bit people with older repos.

And the upgrade path is the part I'm happiest about: you don't need to re-index from scratch. Markdown content is already stored in your index's document blocks, so rebuilding the graph picks it up from the existing database. Run octocode index or rebuild the graph, and your docs appear.

The Bug That Silently Hid Relationships

This fix matters more than the feature for some of you.

When reading relationships back from LanceDB, only part of the stored result set was being returned — subsequent batches were dropped instead of concatenated. On small projects you'd never notice. On larger ones, graph queries could silently miss connections you expected to exist.

Silent is the key word. No error, no warning — just an incomplete graph that looked complete. If you ever ran a graph query on a big repo and thought "huh, I expected more edges here," this was the likely cause. Rebuilding or reloading the graph now returns the full relationship set.

Two related fixes landed alongside it:

  • Markdown headings no longer pollute the code symbol index. Document headings were being indexed as "symbols," and import resolution was matching against them — producing spurious relationship candidates. Markdown nodes are excluded from symbol indexing now, while still participating in the graph through path-based links.
  • Markdown nodes resolve by path, not by symbol. In the efficient relationship-discovery pass, docs are routed through path-based resolution — which is how document links actually work — instead of the symbol-matching path used for code. Document-to-document edges are now accurate rather than coincidental.

Half the Memory on Relationship Loading

Incremental indexing flushes could write the same relationship more than once across batches. On a real-world large project, that meant the loader was pulling in 575K rows to represent 288K unique relationships — nearly half the set was duplicates.

Relationships are now deduplicated by their (source, target, type) triple when the graph loads. That roughly halves the memory footprint and speeds up every graph operation that iterates over the full set. The loader reports the dedup count when it removes duplicates, so you can see what it did.

No config change. It just loads leaner.

Everything Else

MCP server upgraded to rmcp 3.0.0. The underlying Model Context Protocol SDK moved to the new major version, keeping Octocode current with the MCP ecosystem and its streamable-HTTP transport. Both stdin and HTTP server modes work as before — no configuration changes required.

Config handling moved into octolib. The generic machinery for config file management and version-to-version migration — the version walk, guards, table merging — now lives in the shared octolib library. Octocode keeps only its own v1→v2 migration steps. Transparent to you: existing configs migrate exactly as before. The win is that config-handling fixes now land once for every tool built on octolib instead of being ported repo by repo.

Docs got some love too. The README now documents the full MCP tool surface — including the LSP-backed tools (lsp_goto_definition, lsp_find_references, lsp_hover, lsp_document_symbols, lsp_workspace_symbols, lsp_completion) and how to enable them with --with-lsp. And there are new vendor-neutral guides for pointing Octocode at any OpenAI-compatible LLM or embedding endpoint — local model servers and alternative hosted providers alike.

Upgrade

# Homebrew
brew upgrade muvon/tap/octocode

# Universal installer
curl -fsSL https://raw.githubusercontent.com/Muvon/octocode/master/install.sh | sh

# Cargo
cargo install octocode --version 0.20.0

It's a drop-in upgrade — no config changes, and existing configuration files migrate automatically. One thing to do after upgrading:

Rebuild the graph (or just run octocode index) on a project with real documentation. Then ask your assistant a question that used to require a human to connect the code to the docs — "where is authentication handled, and what does the security guide say about it?" — and watch it traverse both.

Octocode is open source (Apache 2.0) at github.com/Muvon/octocode, and it's the code-search engine behind Octomind. The graph knew how your code fit together. Now it knows what you wrote about it, too.