The knowledge graph

Tree-sitter chunking

Retrieval is only as good as the units it retrieves. ContextBrain uses tree-sitter to parse source files structurally rather than splitting them on arbitrary line counts — so chunks are symbol-level (functions, classes, methods) instead of fixed-size windows that slice a function in half. Documents are chunked heading-aware, following their structure. The result is chunks that mean something on their own: an agent that retrieves one gets a whole, coherent unit, with a cite field so a synthesizing model can quote the source verbatim.

Nodes & relationships

Chunking produces a graph, not a flat list. Each connected repository contributes nodes — files, symbols, and refs — and the edges between them are typed relationships:

• calls — this symbol invokes that one.
• imports — this file depends on that module.
• defines — this file declares that symbol.

Because the relationships are explicit, the graph supports questions that pure text similarity can't — tracing callers and callees, following an import chain, or mapping the blast radius of a change. Memory entries also link into the graph (memory ↔ chunk, memory ↔ ticket, memory ↔ memory), so a team's decisions attach to the exact code they govern.

Storage: Postgres-native

A deliberate architectural choice: the graph lives in Postgres, not a separate graph database. Vector similarity runs on pgvector, and graph traversal uses recursive CTEs — so the same database holds the chunks, the embeddings, the relationships, the memory, and the audit trail. One system to operate, one transactional boundary, and no cross-store consistency problems. That keeps self-hosting tractable: the codebase never has to leave your perimeter and you aren't running a graph-DB cluster alongside it.

Hybrid retrieval

When a task needs context, ContextBrain doesn't rely on a single signal. It runs hybrid search that fuses three:

• Semantic— embedding similarity, for “find code that means this.”
• BM25 keyword — lexical match, for exact identifiers and rare terms.
• Entity — matches against known symbols and graph entities.

The three are combined with Reciprocal Rank Fusion (RRF) into one ranked result, and the ranking can be reranked — off, a local bge reranker, or Cohere with a per-org key. Signal weights, the RRF constant, the reranker, and the threshold are all per-org dials, and a 5-minute Redis cache (auto-invalidated on re-index) keeps repeat queries fast. The exact same engine powers the UI, the REST /api/v1/search/code endpoint, and the MCP search_codebase tool — so every surface ranks results identically.

Impact analysis & release risk

The relationships pay off most at decision time. Because the graph knows what calls what, ContextBrain exposes two graph-powered tools — over MCP and in the product:

• Impact analysis (get_impact_analysis) — the call / import blast radius for a symbol: everything that would be affected if you changed it.
• Release risk (get_release_risk) — a pre-merge risk surface, so an agent or reviewer can see what a change endangers before it ships.

This is the difference between search and structure. Keyword search tells you where a name appears; the graph tells you what depends on it — which is exactly what an agent (or a human) needs to avoid editing the wrong thing.

Where to go next

The graph and its retrieval feed the bundles agents actually consume — see context packs for how retrieval output is scored, budgeted, and hash-signed, and chat with your codebase for grounded, cited answers over the graph and over MCP to any agent.