Skip to content

Architecture

A high-level tour of how Super-Brain turns raw code into a queryable knowledge graph.

The five layers

Super-Brain is organized as five cooperating layers. Each has a single job and a clean contract with the next.

┌──────────────────────────────────────────────────┐ │ 5. Interface CLI · MCP server · Reports │ ├──────────────────────────────────────────────────┤ │ 4. Intelligence Hybrid retriever · LLM · Tools│ ├──────────────────────────────────────────────────┤ │ 3. Storage KùzuDB graph + Qdrant vectors │ ├──────────────────────────────────────────────────┤ │ 2. Extraction Deterministic AST parsers │ ├──────────────────────────────────────────────────┤ │ 1. Preprocessing Tree-sitter · MarkItDown │ │ · faster-whisper · yt-dlp │ └──────────────────────────────────────────────────┘

Everything below layer 4 is deterministic. No LLM calls happen during ingestion.

Layer 1 — Preprocessing

Job: turn raw inputs (code files, documents, audio) into parsed intermediate representations.

  • Code — tree-sitter with the full language pack. 306 languages, one consistent AST interface.
  • Documents — MarkItDown converts PDF, DOCX, PPTX, MD, TXT, HTML into normalized markdown with headings preserved.
  • Audio / video — yt-dlp fetches remote sources; FFmpeg normalizes to WAV; faster-whisper transcribes locally with word-level timestamps.

No network calls happen here unless the user explicitly asks for a YouTube URL. Transcription runs entirely on-device.

Layer 2 — Extraction

Job: turn parsed trees and transcripts into graph-ready entities and edges.

  • Rule-based AST queries produce Function, Method, and Class nodes along with their call edges. Rules are language-specific for tier-1 languages and generic for the other 290+.
  • Import resolution links symbols across files by resolving relative and absolute imports.
  • Document extraction breaks markdown into Section nodes, one per heading, preserving the heading hierarchy.
  • Audio extraction chunks transcripts into Transcript nodes with start/end timestamps.

Every extraction rule is deterministic. Given the same input, you get identical output every run — which means you can commit the graph, diff it, and trust it.

Layer 3 — Storage

Job: persist extracted nodes and edges; serve them to the query layer with low latency.

Two stores work together:

KùzuDB — the graph

Embedded graph database. No server, no daemon. The whole database is a file (or a directory of files) in your project. Supports Cypher, ACID transactions, and multi-gigabyte graphs on commodity hardware.

Node types: Module, Function, Class, Document, Section, Concept, Audio, Transcript.

Edge types: CALLS, DEFINES, IMPORTS, CONTAINS, REFERENCES, TRANSCRIBES, LINKED_TO.

Qdrant — the vector store

Local-mode Qdrant, same story: embedded, file-backed, no server required. Holds 384-dimensional embeddings produced by a local sentence-transformer model (default: all-MiniLM-L6-v2).

Every node that has meaningful text (function body, doc section, transcript) is embedded and cross-indexed by node_id with the graph.

Layer 4 — Intelligence

Job: answer questions by combining semantic similarity with structural traversal.

Hybrid retrieval

  1. Semantic seed: vector-search the query against Qdrant. Returns top-K candidates ranked by cosine similarity.
  2. Graph expansion: for each seed, walk the graph outward (CALLS, LINKED_TO, REFERENCES) to a configurable depth. Each hop applies a decay factor so structurally-distant nodes don't swamp the result.
  3. Filter and rank: exclude external stubs, merge duplicates, sort by decayed score.

The result is a ranked list of nodes with source paths, line numbers, and confidence — enough evidence to cite exactly why the answer is what it is.

Optional local LLM

For rich natural-language answers, an optional llama.cpp integration runs Llama-3.2-1B locally (~700 MB model file, downloaded once). The LLM receives only the ranked evidence bundle — never the whole codebase — and composes the prose.

Turning the LLM off gives you pure deterministic evidence. Turning it on adds phrasing, not facts.

Layer 5 — Interface

Job: expose the intelligence layer to humans and other tools.

Three entry points:

  • CLI — agsuperbrain ask, search-vectors, query, inspect-function, and everything else in the CLI Reference.
  • MCP server — agsuperbrain mcp-serve over stdio JSON-RPC. Ten tools: search_code, find_callers, find_callees, get_function_body, path_between, closure, get_subgraph, stats, list_modules, list_functions.
  • Reports — agsuperbrain report writes a GRAPH_REPORT.md with god-nodes, cross-module dependencies, orphans, and suggested follow-up questions.

All three read from the same graph and vector store. There is no second copy of anything.

Data flow end to end

Source files ──► tree-sitter ──► Function/Call nodes ──┐ ├──► KùzuDB ──┐ PDFs / docs ──► MarkItDown ──► Section nodes ──┤ │ │ ├──► Hybrid retriever ──► MCP / CLI Audio / video ─► Whisper ──► Transcript nodes ──┘ │ │ Node text ──► sentence-transformers ──► 384-dim vectors ──► Qdrant ┘

Ingestion is one-way and additive. Query-time reads are cheap. The file watcher re-runs the ingestion pipeline only against changed files, keeping the graph fresh without a full rebuild.

Determinism guarantees

The architecture is built to keep surprises out:

  • No LLM in ingestion. Call edges, class hierarchies, imports — all come from AST walks. An LLM cannot invent a relationship that isn't in the code.
  • Stable node IDs. IDs are derived from source path + qualified name, so re-ingesting the same code produces the same graph.
  • Transactional writes. KùzuDB is ACID. A crash mid-ingest leaves the previous graph intact.
  • Idempotent upserts. Re-running ingest on the same files updates changed bodies and leaves everything else alone.

Performance characteristics

Rough ballpark numbers on a 2024-era laptop:

Operation Speed
Parse + ingest source code 500–2,000 files / minute
Build vector index ~200 nodes / second
Semantic search query < 50 ms
Graph expansion (depth 2) < 100 ms
End-to-end ask < 1 s (deterministic) or 2–5 s (with local LLM)

Numbers vary with file size, language, and hardware. The file watcher keeps steady-state overhead to near zero — changed files re-parse in milliseconds.

What's intentionally out of scope

Super-Brain is not:

  • A code generator — it indexes code, it doesn't write code
  • A cloud service — there is no Super-Brain server to log into
  • A replacement for your assistant — it makes your assistant smarter, not redundant
  • A type checker — it extracts structural facts, not type correctness

Next steps

  • CLI Reference — commands built on this architecture
  • IDE Integration — how the architecture plugs into Claude Code / Cursor / Aider / etc.
  • Why Super-Brain — what this architecture solves that standalone assistants can't