Moonkale

Spec 002 — HelixDB as an embedded graph source

3 min read

HelixDB has an embedded mode (docs) — open it like LadybugDB or DuckDB, without the helix daemon or an HTTP server. Moonkale should offer it as an opt-in source (moonkale-sources-graph, feature helix) on desktop and the server, same Source shape as LadybugDB; the browser build keeps the plain-HTTP server mode (POST /v2/query) only.

Findings (2026-09-19)

  • Embedded mode exists in the repo: sdks/rust (crate helix-db 3.0.0) has embedded = ["dep:db"]; with it Client::open(HelixDbSource::Disk { root, database }).await (also Memory, and S3-compatible object storage) opens storage in-process; queries use the same QueryRequest contract as server mode (HelixQL through helix-dsl-macros). No daemon, no CLI at runtime.
  • Not on crates.io yet: the published helix-db 3.0.0 (2026-08-04) has features = { default = [] } and no db dependency — the engine (crates/db 0.1.0) is an unpublished workspace crate. Embedded Helix therefore means a git dependency on HelixDB/helix-db, and crates/db pulls a git fork of slatedb (pinned rev) plus tantivy, foyer, object_store (aws), rkyv, rayon, … — a heavy tree that follows main. Storage is SlateDB (LSM over disk/object storage), not LMDB as in Helix 1.x/2.x.
  • Where it would pay off beyond “another graph engine”: graph + vector in one store for the RAG index (moonkale-index::embed).

What “done” looks like

  1. sources-graph/src/helix.rs implements Source for the embedded client behind helix (git dep, pinned rev; desktop + server only; never the web client), with the server mode (HTTP) as the second backend of the same file.
  2. Explorer: a .helix/ folder (or a configured path) opens as a graph source; the graph editor draws query results as it does for LadybugDB (Cypher → HelixQL dialect in dialect.rs).
  3. One unit test against HelixDbSource::Memory; an E2E step only if the server build enables the feature by default (it should not until the crate is published).
  4. Crate note + Problem Log entry with the measured clean-build cost.

Decision

Wait until crates/db is published on crates.io (or the git tree stabilises), unless the RAG index needs Helix’s vectors first. Until then the stub stays as it is.

Done 2026-09-28 (Milestone 17)

Embedded HelixDB is a source: sources-graph feature helix (git dependency on HelixDB/helix-db, pinned to f0d1b554f4), HelixSource in src/helix.rs. A *.helix directory (the object-store root; its one database, or main) opens from the Sources tree, read-only (open_reader): node and edge labels as tables, vertices and edges as a graph (v:<Label>:<id>, EdgeKind::Custom), the helix dialect (nodes [<label>] [limit n], edges …) in the table editor, Show in Graph included. Tests: sources-graph/tests/helix.rs (a Disk store written through the SDK, then read through the source), E2E stores.mjs. The HTTP server mode is not done. Known: an open writes a manifest into the store (P-145). See Milestone 17 - Implementation Log.

Graph View

Backlinks