Code-Graph & Graph-RAG — HeliosDB Nano

The Composition

Four services collapse into one engine

A retrieval-augmented generation pipeline is conventionally a vector store, a graph database, an entity linker, and a re-ranker — four services to deploy and keep in sync. HeliosDB Nano puts all four behind a single SQL surface.

Vector store

VECTOR(n) column with HNSW index. code-embed feature ships fastembed-rs in-process — no external embedding API.

Graph database

_hdb_graph_nodes + _hdb_graph_edges are ordinary, queryable, joinable tables, and WITH CONTEXT expands seed rows over them by BFS. Graph traversal and shortest-path functions callable from SQL are planned.

Entity linker

String-match (graph_rag_link_exact) and vector-similar (graph_rag_link_vector) linkers in the Rust API. 100% precision on a hand-labelled fixture (internal tests, Nano 3.19 vs the 80% acceptance target, see benchmarks.html).

Re-ranker

centrality_rerank in the Rust API boosts hits by (1 + α·centrality). RERANK BY in WITH CONTEXT is parsed today; applying it in SQL is planned.

Code-Graph

Your source as a queryable AST

The AST is a table. Symbols are rows. Edges are rows. CREATE AST INDEX backfills your repo into the schema; auto_reparse + a git-hook CLI keeps it current. The familiar LSP operations surface as SQL table functions and push down through the existing FilteredScan path — bloom-filter / zone-map / SIMD selection accelerates them automatically.

SQL-callable LSP — lsp_definition, lsp_references, lsp_call_hierarchy, lsp_hover, lsp_document_symbols, helios_lsp_rename_preview / helios_lsp_rename_apply.
Eight languages built-in — Rust, Python, TypeScript, TSX, JavaScript, Go, Markdown, SQL. Plus a runtime grammar registry for adding any tree-sitter grammar.
ON BRANCH + AS OF on every call — code intelligence is time-travel- and branch-aware on the same query.
Diff helpers — helios_lsp_references_diff, helios_lsp_body_diff, helios_ast_diff.

Code-Graph deep-dive →

SQL

CREATE EXTENSION hdb_code;
CREATE AST INDEX src_ast ON repo (content)
  USING tree_sitter(lang);

-- Where is this defined?
SELECT path, line FROM lsp_definition('execute_query');

-- ...as it was on a feature branch last Tuesday
SELECT *
FROM lsp_definition('execute_query')
  ON BRANCH 'feat/refactor'
  AS OF TIMESTAMP '2026-04-15T00:00:00Z';

-- Rename refactor with sha256 conflict check
SELECT applied, conflicts, files_changed
FROM helios_lsp_rename_apply(
  'old_name', 'new_name',
  dry_run := false
);

Graph-RAG

Grounded retrieval in a single SQL clause

WITH CONTEXT takes the rows of a seed query (its first column is node_id) and expands the subgraph by BFS over typed edges; applying RERANK BY in SQL is planned, and centrality_rerank is available in the Rust API. Eight ingestion adapters, called from the Rust API, cover doc pages, email threads, issues, Q&A, PDFs, Office docs, audio, and images; code symbols are projected as they are indexed — all into the same node/edge tables.

Cross-modal graph — one schema covers all modalities. JOIN code symbols against docs, emails, and issue comments naturally.
Eight ingestion adapters (Rust API) — graph_rag_ingest_docs, _email, _issues, _qa, plus Docling-backed _pdf / _office / _audio / _image. They are EmbeddedDatabase methods, not SQL functions.
Semantic-Merkle invalidation — CREATE SEMANTIC HASH INDEX. Re-embed only what changed at the document-subtree level.
Acceptance benchmark — 100-query mean of 62 ms on a 10k-node fixture (target was 500 ms); entity-linker precision 100% (target 80%) (internal tests, Nano 3.19 built with --features code-graph,graph-rag vs the acceptance targets, see benchmarks.html).

Graph-RAG architecture →

Rust API + SQL

// Rust API: ingest a Markdown table, then link
db.graph_rag_ingest_docs(&IngestDocsOptions {
    source_table: "docs".into(),
    id_col: "id".into(),
    text_col: "body".into(),
    title_col: Some("title".into()),
    chunk_by: ChunkStrategy::Headings,
})?;
db.graph_rag_link_exact(&[])?; // MENTIONS edges

-- SQL: seed rows (node_id first), then expand the graph
SELECT node_id, node_kind, title
FROM _hdb_graph_nodes
WHERE title LIKE '%auth%'
WITH CONTEXT (
    HOPS 3,
    EDGES IMPORTS|REFERENCES|MENTIONS,
    DIRECTION both,
    LIMIT 50
);

-- Pass the returned rows to your LLM client as context

Native MCP Server

The agent's tool provider

Every modern coding agent — Claude Code, Cursor, Continue, Codex, Aider — speaks Model Context Protocol. HeliosDB Nano speaks it natively. Three transports (HTTP / WebSocket / SSE), bearer-token auth and public-bind hardening; stdio is available through the separate HeliosDB CodeKB MCP binary. 16 core tools, plus 10 LSP and AST tools with code-graph and helios_graphrag_search with graph-rag, surface via the mcp_tool! macro and the inventory crate.

Three transports — POST /mcp, /mcp/ws, /mcp/sse. For stdio, use the separate HeliosDB CodeKB MCP binary.
Streaming progress — notifications/progress events flow to agents that opt in via _meta.progressToken.
One-shot discovery — helios/info, tools/list?verbose=true, GET /mcp/info.
Hardened defaults — loopback bind out of the box; a non-loopback MCP listener requires --mcp-token or --allow-remote-mcp.

MCP server platform →

MCP config

# Claude Code, Cursor, Continue, etc.
{
  "mcpServers": {
    "heliosdb-nano": {
      "url":  "http://localhost:8080/mcp",
      "auth": {
        "type":  "bearer",
        "token": "$HDB_TOKEN"
      }
    }
  }
}

# Some of the auto-registered tools
heliosdb_bm25_index
heliosdb_hybrid_search
heliosdb_graph_add_edge
heliosdb_graph_traverse
heliosdb_graph_path
heliosdb_embed_and_store
helios_graphrag_search       # streaming
helios_lsp_document_symbols
helios_lsp_rename_preview
helios_lsp_references_diff
helios_lsp_body_diff
helios_ast_diff

Compared to bolt-on stacks

Why a database extension beats glue

Capability	Pinecone + Neo4j + Cohere-rerank	Sourcegraph Cody	HeliosDB Nano
Code-aware AST queries	—		SQL-callable
Vector store	Pinecone	internal	`VECTOR(n)` column
Graph store	Neo4j	—	tables
In-process embedder	external	external	fastembed-rs (BGESmallENV15)
Time-travel + branching	—	—	`ON BRANCH` + `AS OF`
Native MCP server	—	—	WS + SSE + HTTP (stdio via CodeKB MCP)
Operational footprint	3 services + reranker API	indexing daemon	1 binary

Quickstart

From zero to grounded RAG in 60 seconds

Shell + SQL

# 1. Install Nano 4.41.1 with all AI-retrieval features, then start it
#    (these features are compiled in from source: the prebuilt release binaries and
#    the ghcr.io/heliosdatabase/heliosdb-nano image ship without them)
cargo install heliosdb-nano \
  --features "code-graph,graph-rag,mcp-endpoint,code-embed"
heliosdb-nano start --data-dir ./helios-data

# 2. Connect via psql
psql -h localhost -d postgres

-- 3. Index your codebase
CREATE EXTENSION hdb_code;
CREATE AST INDEX src_ast ON repo (content)
  USING tree_sitter(lang);

-- 4. Ingest your docs from an app that embeds Nano: the ingest
--    adapters are Rust API methods, e.g. db.graph_rag_ingest_docs(...)

-- 5. Expand seed rows over the graph for grounding
SELECT node_id, node_kind, title
FROM _hdb_graph_nodes
WHERE title LIKE '%auth%'
WITH CONTEXT (HOPS 3, EDGES IMPORTS|REFERENCES|MENTIONS, LIMIT 25);

# 6. Connect Claude Code / Cursor (MCP)
# Add to .claude/mcp.json or .cursor/mcp.json:
# "heliosdb-nano": { "url": "http://localhost:8080/mcp" }

Code intelligence as a database extension