Code-Graph &amp; Graph-RAG &mdash; 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 queryable, joinable, branch-aware tables. BFS / shortest-path / centrality functions in SQL.

Entity linker

String-match and vector-similar (graph_rag_link_vector) on insert. 100% precision on hand-labelled fixture.

Re-ranker

Centrality-biased + prefilter-aware HNSW wrapper. (1−α)·distance − α·centrality in the planner.

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 ON repo (path, lang, content);

-- 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 a seed, expands the subgraph by BFS, and ranks the result with centrality + vector distance. Eight ingestion adapters cover code symbols, doc pages, email threads, issues, Q&A, PDFs, Office docs, audio, and images — all projecting 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 — including Docling-backed graph_rag_ingest_pdf / _office / _audio / _image.
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%).

Graph-RAG architecture →

SQL

-- Ingest enterprise documents (v3.19)
SELECT graph_rag_ingest_pdf('/docs/handbook.pdf');
SELECT graph_rag_ingest_office('/contracts/2026-Q1.docx');
SELECT graph_rag_ingest_audio('/calls/standup.m4a');

-- Ground an LLM query with subgraph context
SELECT answer
FROM ask_llm('What changed in the auth flow last quarter?')
WITH CONTEXT (
    seed_text   = 'auth flow',
    seed_kinds  = ['function', 'doc', 'issue'],
    edge_kinds  = ['IMPORTS', 'REFERENCES', 'MENTIONS'],
    hops        = 3,
    rerank      = 'centrality',
    alpha       = 0.3,
    limit       = 25
);

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), JWT auth, Unix-socket, public-bind hardening. Twelve auto-registered tools surface via the mcp_tool! macro and the inventory crate — including helios_graphrag_search with streaming progress events.

Three transports — POST /mcp, /mcp/ws, /mcp/sse. Plus stdio for sandboxed agents.
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 — localhost + Unix-socket out of the box; public-bind opt-in only.

MCP server platform →

MCP config

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

# Available tools (12, auto-registered)
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
Operational footprint	3 services + reranker API	indexing daemon	1 binary, 35 MB

Quickstart

From zero to grounded RAG in 60 seconds

Shell + SQL

# 1. Run Nano with all AI-retrieval features
docker run -d --name helios-nano \
  -p 8080:8080 -p 5432:5432 \
  -e HELIOS_FEATURES="code-graph,graph-rag,mcp-endpoint,code-embed" \
  dimensigon/heliosdb-nano:3.19.1

# 2. Connect via psql
psql -h localhost -U helios -d main

-- 3. Index your codebase
CREATE EXTENSION hdb_code;
CREATE AST INDEX ON repo (path, lang, content);

-- 4. Ingest your docs
SELECT graph_rag_ingest_docs('/docs/');
SELECT graph_rag_ingest_pdf('/docs/handbook.pdf');

-- 5. Query with grounding
SELECT *
FROM ask_llm('How does our auth flow work?')
WITH CONTEXT (
  seed_text  = 'auth flow',
  hops       = 3,
  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