node id: 0
name: Alice"] bob["User node
node id: 1
name: Bob"] alice -->|"FOLLOWS
edge id: 0
since: 2026-07-24"| bob ``` Alice is the source of the `FOLLOWS` edge and Bob is its target. Direction belongs to the relationship: traversing out from Alice reaches Bob, while traversing in from Bob reaches Alice. Nodes and edges are numbered from separate sequences, which is why the edge above has ID `0` even though a node already holds ID `0`. An ID is only unique within its own space, so always keep track of whether an ID refers to a node or an edge. | Element | Meaning | | --- | --- | | Node | An entity such as a user, document, or product | | Edge | A directed relationship between two nodes | | Label | The single type or role of one node or edge | | Property | Typed data stored on a node or edge | | ID | The identity of one node or edge within its own ID space | Each node and each edge carries exactly one label, assigned when it is created. There is no multi-label set, so model a secondary role as a property or as a relationship to another node rather than as an extra label. ## Properties Nodes and edges can carry scalar values, arrays, and nested objects: | Family | Values | | --- | --- | | Scalar | Null, boolean, integer, float, date-time, string, bytes | | Collection | Typed arrays and heterogeneous arrays | | Object | Nested maps of any of the above | A nested value stays readable through a dotted path such as `metadata.score`, but only top-level properties can be indexed. Promote a nested field to the top level when you need to filter, order, or search on it. ## Multiple relationships HelixDB is a multigraph: the same source and target can be connected by more than one edge. ```mermaid flowchart LR alice["User node
Alice"] bob["User node
Bob"] alice -->|"SENT
edge id: 0
text: Hello"| bob alice -->|"SENT
edge id: 1
text: Thanks"| bob ``` Both `SENT` edges connect Alice to Bob, but each has its own ID and properties. Use separate edges when the relationships represent separate events or facts. An edge can also connect a node to itself, which is useful for relationships such as `MERGED_INTO` between records of the same kind. ## Indexes An index is an optional access path over a node or edge label and a top-level property. Its definition also contains family-specific settings such as uniqueness, sort direction, text analysis, or vector dimensions and distance metric. ```mermaid %%{init: {'flowchart': {'defaultRenderer': 'elk'}}}%% flowchart LR document["Document node
label: Document"] status["status
published"] body["body
Graph data..."] embedding["embedding
[0.12, 0.84, ...]"] secondary["Secondary index
exact, unique, and range lookup"] text["Text index
BM25-ranked search"] vector["Vector index
nearest-neighbor search"] document --> status document --> body document --> embedding status -. "indexed by" .-> secondary body -. "indexed by" .-> text embedding -. "indexed by" .-> vector ``` | Index | Use | | --- | --- | | Secondary | Equality, ordering, and range lookup, with optional uniqueness on node labels | | Text | BM25-ranked search over strings and string arrays | | Vector | Similarity search over fixed-dimension numeric arrays | Indexes may target nodes or edges and are scoped by label and property. They do not change the canonical graph data. Creating one starts an asynchronous backfill over existing data; the index becomes visible only after validation and atomic activation. See [Secondary indexes](/database/helix-db/query-guides/secondary-indexes), [Text indexes](/database/helix-db/query-guides/text-indexes), and [Vector indexes](/database/helix-db/query-guides/vector-indexes) for creation and query examples. ## Model data clearly - Use noun-like node labels such as `User`, `Document`, and `Product`. - Use relationship labels such as `FOLLOWS`, `AUTHORED`, and `PURCHASED`. - Store relationship-specific values on the edge. - Use separate edges for distinct events between the same entities. - Keep properties intended for indexing at the top level. - Node and edge IDs are unsigned 64-bit values from separate sequences that both start at zero. - `$id` and `$label` expose identity and label in queries. `$label` cannot be assigned through an ordinary property map. - A node label can be changed by a dedicated relabel operation, which also moves the node between label indexes. An edge label is fixed for the life of the edge. - Current secondary, text, and vector indexes require top-level properties, and object and heterogeneous-array values cannot be indexed. - Uniqueness is available on node equality indexes only; there is no unique edge index. ## Next steps
add_n User, name: Alice"] bob["Entry 2 — bob
add_n User, name: Bob"] follow["Entry 3 — follow
add_e FOLLOWS, since: 2026-07-24"] friends["Entry 4 — friends
out FOLLOWS, then value_map"] alice -->|"edge source, var alice"| follow bob -->|"edge target, var bob"| follow alice -->|"traversal source, var alice"| friends follow -.->|"new edge is visible to later entries"| friends ``` ## 1. Pick the batch type ```rust Rust write_batch() ``` ```ts TypeScript writeBatch(); ``` ```go Go helix.WriteQuery("write_users") ``` ```python Python write_batch() ``` ```json JSON { "write": { "entries": [], "returns": [] } } ``` A batch is a list of named entries plus the names to return. A write batch is the only batch that accepts a mutating traversal. Rust and TypeScript reject `addN` in a read batch at compile time, and Go and Python reject it while the request is being built, so a stray write in a read path never reaches the server. All entries in one batch commit or roll back together, which is what lets entry 4 read the edge that entry 3 has only just created. ## 2. Create the two nodes ```rust Rust .var_as("alice", g().add_n("User", vec![("name", "Alice")])) ``` ```ts TypeScript .varAs("alice", g().addN("User", { name: "Alice" })) ``` ```go Go VarAs("alice", helix.G().AddN("User", helix.Props{helix.Prop("name", "Alice")})) ``` ```python Python .var_as("alice", g().add_n("User", {"name": "Alice"})) ``` ```json JSON { "query": { "name": "alice", "root": { "add_n": { "label": "User", "properties": [ ["name", { "value": { "string": "Alice" } }] ] } } } } ``` `varAs` adds one entry and gives it a name. `g()` starts an empty traversal, so `addN` here is a source operation with no `input` and creates exactly one node. Given an input stream instead, `addN` creates one node per incoming row. Properties travel as ordered `[name, value]` pairs, and each value carries its type tag (`string`, `i64`, `f64`, `bool`, `date_time`, `bytes`, and the array and object variants). The `{ "value": … }` wrapper distinguishes a literal from an `{ "expr": … }` reference such as a [parameter](/database/helix-db/query-guides/parameters). The name `alice` is local to this transaction. It is not a stored variable, a route, or a server-side binding, and it is gone once the response is sent. ## 3. Connect them with a directed edge ```rust Rust .var_as( "follow", g() .n(NodeRef::var("alice")) .add_e("FOLLOWS", NodeRef::var("bob"), vec![("since", "2026-07-24")]), ) ``` ```ts TypeScript .varAs( "follow", g() .n(NodeRef.var("alice")) .addE("FOLLOWS", NodeRef.var("bob"), { since: "2026-07-24" }), ) ``` ```go Go VarAs( "follow", helix.G(). N(helix.NodeVar("alice")). AddE( "FOLLOWS", helix.NodeVar("bob"), helix.Props{helix.Prop("since", "2026-07-24")}, ), ) ``` ```python Python .var_as( "follow", g() .n(NodeRef.var("alice")) .add_e("FOLLOWS", NodeRef.var("bob"), {"since": "2026-07-24"}), ) ``` ```json JSON { "query": { "name": "follow", "root": { "add_e": { "input": { "nodes": { "reference": { "var": "alice" } } }, "label": "FOLLOWS", "to": { "var": "bob" }, "properties": [ ["since", { "value": { "string": "2026-07-24" } }] ] } } } } ``` Unlike `addN`, `addE` needs an input stream: the nodes in that stream become the edge sources, and `to` is the target. `n(NodeRef.var("alice"))` turns entry 1's result back into a stream, which is why `add_e` carries an `input` of `{ "nodes": { "reference": { "var": "alice" } } }`. Direction comes from the operation, not the label: Alice is the source and Bob is the target, so traversing out from Alice reaches Bob. If the input stream held several nodes, `addE` would create one edge per source node. `since` is stored as a plain string here because the value is written as a string. Use a date-time property when you need range comparisons or ordering on it. `follow` is not listed in `returning`, so it never appears in the response. The entry still runs. Leave write-only steps out of `returning` to keep the payload small. ## 4. Follow the new edge in the same transaction ```rust Rust .var_as( "friends", g() .n(NodeRef::var("alice")) .out(Some("FOLLOWS")) .value_map(Some(vec!["$id", "name"])), ) ``` ```ts TypeScript .varAs( "friends", g().n(NodeRef.var("alice")).out("FOLLOWS").valueMap(["$id", "name"]), ) ``` ```go Go VarAs( "friends", helix.G().N(helix.NodeVar("alice")).Out("FOLLOWS").ValueMap("$id", "name"), ) ``` ```python Python .var_as( "friends", g().n(NodeRef.var("alice")).out("FOLLOWS").value_map(["$id", "name"]), ) ``` ```json JSON { "query": { "name": "friends", "root": { "value_map": { "input": { "out": { "input": { "nodes": { "reference": { "var": "alice" } } }, "label": "FOLLOWS" } }, "properties": ["$id", "name"] } } } } ``` This entry is a read inside a write batch. It starts at Alice again, walks out along `FOLLOWS`, and projects two fields from whatever it lands on. The edge from entry 3 is uncommitted at this point but still visible, because the batch is one transaction. Each chained operation consumes the previous stream and wraps it as `input`, so the AST nests in the opposite order to the builder chain: the last operation you write is the outermost JSON object, and the source sits at the innermost position. ```mermaid flowchart LR vm["value_map
properties: $id, name"] out["out
label: FOLLOWS"] nodes["nodes
reference: var alice"] vm -->|input| out out -->|input| nodes ``` `out` returns the destination nodes of outgoing edges. Passing a label does more than filter the results — it narrows which edges are read in the first place, so always pass one when the schema provides it. | Operation | Result | | --- | --- | | `out(label)` | Destination nodes of outgoing edges | | `in(label)` | Source nodes of incoming edges | | `both(label)` | Adjacent nodes in either direction | | `outE(label)` / `inE(label)` | The edges themselves | `valueMap` is a terminal operation: it selects properties by name and ends the traversal, so nothing can be chained after it. `$id` and `$label` expose identity and label alongside ordinary properties, and omitting the property list returns every property. ## 5. Choose what comes back ```rust Rust .returning(["alice", "bob", "friends"]) ``` ```ts TypeScript .returning(["alice", "bob", "friends"]); ``` ```go Go Returning("alice", "bob", "friends") ``` ```python Python .returning(["alice", "bob", "friends"]) ``` ```json JSON { "returns": ["alice", "bob", "friends"] } ``` `returning` picks which named entries appear in the response body. Names it omits still execute; they are simply not serialized back to the client. ## 6. Name the request ```rust Rust let request = write_users()?; ``` ```ts TypeScript const request = query.toQueryRequest({ queryName: "write_users" }); ``` ```go Go request := helix.WriteQuery("write_users") // named before the entries are added ``` ```python Python request = query.to_query_request(query_name="write_users") ``` ```json JSON { "query_name": "write_users" } ``` Rust's `#[query]` macro rewrites the function to return `Result
", "msg": "" }`. Clients should branch on
`error` and treat `msg` as diagnostic text. An oversized Cloud request uses
`payload_too_large` as its stable error code. See
[Error handling](/database/helix-db/query-guides/error-handling) for local error
codes and retry guidance.
## Related resources
- [`helix query`](/cli/command-reference/query) builds and sends requests from JSON or the TypeScript DSL.
- [Build and run a query](/database/helix-db/core-concepts/overview) explains the operation tree.
- [Parameters](/database/helix-db/query-guides/parameters) defines typed and untyped runtime values.
# Handle query errors
Page type: Reference
Reference
Helix query failures expose a stable machine-readable code separately from the
human-readable diagnostic. Branch on the code; log or display the message.
Messages can gain context over time and are not a compatibility contract.
## HTTP error envelope
Every non-success response from `POST /v2/query` uses `error` for the static
code and `msg` for the readable message:
```json
{
"error": "index_not_found",
"msg": "planner error: missing text index for `Document.body`"
}
```
The response never adds a separate `code` field. HTTP status classifications
are unchanged, so use both the status and static code when deciding whether to
retry. A non-JSON response from an older proxy or intermediary is still exposed
by each SDK as readable details with no code.
## Access the code in an SDK
```rust Rust
match client.query::(request).send().await {
Err(error) if error.error_code() == Some("index_not_found") => {
// Create the index, wait for it to become active, then retry.
}
Err(error) => return Err(error),
Ok(response) => println!("{response}"),
}
```
```ts TypeScript
try {
await client.query(request).send();
} catch (cause) {
if (cause instanceof HelixError && cause.code === "index_not_found") {
// Create the index, wait for it to become active, then retry.
} else {
throw cause;
}
}
```
```go Go
if err := client.Exec(ctx, request, &response); err != nil {
var helixErr *helix.HelixError
if errors.As(err, &helixErr) && helixErr.Code == helix.QueryErrorCode("index_not_found") {
// Create the index, wait for it to become active, then retry.
} else {
return err
}
}
```
```python Python
try:
response = client.query(request)
except HelixError as error:
if error.code == "index_not_found":
# Create the index, wait for it to become active, then retry.
pass
else:
raise
```
```json JSON
{
"error": "index_not_found",
"msg": "planner error: missing text index for `Document.body`"
}
```
Known Rust codes can also be parsed as `QueryErrorCode`. SDK wire fields remain
open strings so a newer server's unknown future code is preserved rather than
being collapsed or rejected.
## Other query boundaries
For gRPC, the status message remains human-readable and the same static code is
attached as ASCII metadata under `helix-error-code`. Active-text mutation admission
failures use `InvalidArgument`, matching their HTTP 400 classification.
Embedded Rust errors expose `error_code()`. UniFFI errors carry two explicit
fields named `error` and `msg`; generated Python, Node, and Go bindings pass
that pair into their SDK error objects. Embedded callers never need to infer a
code from exception text.
## Stability and retry rules
- Existing code strings are frozen compatibility identifiers. New codes may be
added, so applications must preserve and safely handle unknown values.
- A code describes the failure, not whether replaying a particular mutation is
safe. Retry only idempotent work or work protected by an application-level
idempotency key.
- `transaction_conflict` is the only HTTP conflict classification and is
normally retryable with bounded backoff.
- Availability and lifecycle failures should be retried only after the named
condition changes. Validation and planning failures require a corrected
request or schema/index configuration.
- `internal_*`, `storage_error`, and `response_serialization_error` are opaque
by design. Retain the `msg` and server logs when escalating them.
## Error-code reference
“Correctable” means whether a caller can change its request or deployment state
to address the failure. Statuses list the current HTTP behavior; `400/503` and
`400/500` indicate that the same code can arise at more than one boundary.
### Request validation
| Code | Meaning | HTTP | Retry | Correctable |
| --- | --- | --- | --- | --- |
| `invalid_request` | The request is incompatible with the selected query mode. | 400 | After fixing the request | Yes |
| `invalid_query_json` | The query body cannot be decoded as query JSON. | 400 | After fixing the body | Yes |
| `invalid_request_body` | The transport cannot read the body or it exceeds the body limit. | 400 | After fixing the body | Yes |
| `invalid_request_option` | A header or transport option is invalid; writer routing can also be unavailable. | 400/503 | After fixing the option or routing | Yes |
| `invalid_query` | An embedded or encoded query payload is invalid. | 500 | After fixing the query | Yes |
### Planning
| Code | Meaning | HTTP | Retry | Correctable |
| --- | --- | --- | --- | --- |
| `invalid_index_operation_id` | An index lifecycle operation ID is invalid. | 400 | After fixing the ID | Yes |
| `unsupported_edge_all_target` | An all-edges reference was used as a finite mutation target. | 400 | After changing the traversal | Yes |
| `non_literal_index_expression` | An index operation expression is not a literal or parameter. | 400 | After changing the expression | Yes |
| `missing_planning_equality_parameter` | A parameter needed to plan an equality lookup is not bound. | 400 | After binding the parameter | Yes |
| `unsupported_planning_equality_parameter` | An equality parameter cannot be represented by the selected index. | 400 | After changing the parameter value | Yes |
| `invalid_search_tenant` | A tenant was supplied for an unscoped search index. | 400 | After fixing tenant usage | Yes |
| `invalid_search_tenant_value` | A search tenant value has the wrong shape. | 400 | After fixing the value | Yes |
| `invalid_search_result_count` | A search result count is zero. | 400 | After using a positive count | Yes |
| `invalid_search_result_count_expression` | A search result-count expression has the wrong shape. | 400 | After fixing the expression | Yes |
| `invalid_search_input` | A text or vector search input has the wrong shape. | 400 | After fixing the input | Yes |
| `invalid_batch_condition_min_size` | A batch condition has a zero minimum size. | 400 | After fixing the condition | Yes |
| `invalid_initial_batch_condition` | The first batch entry depends on a previous result. | 400 | After reordering the batch | Yes |
| `duplicate_property_assignment` | A mutation assigns the same property more than once. | 400 | After removing the duplicate | Yes |
| `duplicate_property_selection` | A projection selects the same property more than once. | 400 | After removing the duplicate | Yes |
| `duplicate_projection_alias` | A projection emits the same alias more than once. | 400 | After renaming an alias | Yes |
| `duplicate_return_variable` | A batch returns the same variable more than once. | 400 | After removing the duplicate | Yes |
| `duplicate_element_id` | A point lookup contains the same element ID more than once. | 400 | After deduplicating IDs | Yes |
| `duplicate_order_key` | A sort contains the same property more than once. | 400 | After deduplicating keys | Yes |
| `unbound_context` | A sub-traversal is missing its parent input. | 400 | After binding the context | Yes |
| `invalid_sub_traversal_operation` | An operation is invalid inside a branch or repeat sub-traversal. | 400 | After changing the traversal | Yes |
| `invalid_after_bind_operation` | An operation is invalid after a row-local bind. | 400 | After changing the traversal | Yes |
| `read_only_traversal_in_write_batch` | A write batch contains a read-only traversal. | 400 | After moving the read | Yes |
| `invalid_branch_arity` | A branch has too few traversals. | 400 | After adding a branch | Yes |
| `invalid_batch_arity` | A batch has too few entries. | 400 | After adding an entry | Yes |
| `invalid_repeat_emit` | A repeat emit predicate conflicts with its emit mode. | 400 | After fixing repeat options | Yes |
| `invalid_repeat_count` | A repeat count or depth is zero. | 400 | After using a positive count | Yes |
| `invalid_shortest_path_count` | A shortest-path count or depth is zero. | 400 | After using a positive count | Yes |
| `invalid_order_keys` | An order operation has no sort keys. | 400 | After adding a key | Yes |
| `invalid_projection_arity` | A projection has too few fields. | 400 | After adding a field | Yes |
| `invalid_stream_range` | A stream range is statically inverted. | 400 | After fixing the range | Yes |
| `invalid_stream_bound_expression` | A stream-bound expression has the wrong shape. | 400 | After fixing the expression | Yes |
| `invalid_empty_name` | A required query name is empty. | 400 | After supplying a name | Yes |
| `invalid_predicate_arity` | A predicate set has too few children. | 400 | After adding a predicate | Yes |
### Execution
| Code | Meaning | HTTP | Retry | Correctable |
| --- | --- | --- | --- | --- |
| `query_deadline_exceeded` | Execution exceeded its cooperative deadline. | 500 | With a larger deadline or less work | Sometimes |
| `invalid_node_id` | A supplied node ID is invalid. | 500 | After fixing the ID | Yes |
| `node_not_found` | A requested node does not exist. | 500 | After fixing state or ID | Yes |
| `edge_not_found` | A requested edge does not exist. | 500 | After fixing state or endpoints | Yes |
| `invalid_vector_configuration` | Vector index configuration is invalid. | 500 | After fixing configuration | Yes |
| `unique_constraint_violation` | A unique index already owns the requested value. | 500 | After choosing a unique value | Yes |
| `unsupported_unique_index_value_type` | A unique index does not support the value type. | 500 | After changing the value | Yes |
| `invalid_vector_dimension` | A vector has the wrong dimension. | 400 | After fixing the vector | Yes |
| `invalid_vector_component` | A vector contains a non-finite component. | 400 | After fixing the vector | Yes |
| `vector_component_magnitude_exceeded` | A component exceeds the score-safe magnitude. | 400 | After normalizing the vector | Yes |
| `zero_norm_cosine_vector` | A cosine vector has zero norm. | 400 | After supplying a nonzero vector | Yes |
### Active-text mutation limits
`active_text_mutation_limit_exceeded` reports a deterministic rejection before the
write transaction commits. The request's graph changes are not committed. The error
is caller-correctable and uses HTTP 400, gRPC `InvalidArgument`, or the embedded
`InvalidRequest` binding category. It is not a transient rate limit or an unknown
write outcome; retrying the identical mutation does not resolve the limit.
For example, the HTTP query service returns:
```json
{
"error": "active_text_mutation_limit_exceeded",
"msg": "db error: Active text mutation exceeds entities: observed 513, limit 512. This is a hard mutation-batch limit; reduce the number or size of mutations."
}
```
Branch on `error`, not the wording in `msg`. The diagnostic identifies the resource,
observed usage and configured limit. See [active-text admission limits](/database/helix-cloud/operate/limits#active-text-mutation-admission)
for the default bounds and how entities are counted. The same engine policy applies
to standalone databases; embedded configurations may override it.
### Index lifecycle
| Code | Meaning | HTTP | Retry | Correctable |
| --- | --- | --- | --- | --- |
| `index_lifecycle_unavailable` | The required lifecycle authority is unavailable. | 500 | After authority recovery | Operational |
| `secondary_lifecycle_stepping_requires_disabled_mode` | Explicit secondary stepping requires disabled worker mode. | 500 | After changing worker mode | Operational |
| `active_text_mutation_limit_exceeded` | An active text mutation exceeded a hard admission limit. | 400 | Reduce the mutation before retrying | Yes |
| `invalid_index_source_data` | Existing graph data violates an index source contract. | 500 | After correcting source data | Yes |
| `invalid_index_model` | A value violates the current index model. | 500 | After fixing model or value | Yes |
| `invalid_secondary_index_value` | A value violates a secondary-index contract. | 500 | After fixing the value | Yes |
| `identifier_exhausted` | A bounded non-index-specific identifier namespace is exhausted. | 500 | No immediate retry | Operational |
| `index_id_exhausted` | The logical index ID namespace is exhausted. | 500 | No immediate retry | Operational |
| `vector_physical_id_exhausted` | The vector physical index ID namespace is exhausted. | 500 | No immediate retry | Operational |
| `index_generation_exhausted` | The index generation namespace is exhausted. | 500 | No immediate retry | Operational |
| `index_revision_exhausted` | The index revision namespace is exhausted. | 500 | No immediate retry | Operational |
| `index_operation_revision_exhausted` | The index-operation revision namespace is exhausted. | 500 | No immediate retry | Operational |
| `index_already_exists` | An index with the requested identity already exists. | 500 | After using idempotent creation or a new name | Yes |
| `index_definition_conflict` | An existing index has a conflicting definition. | 500 | After reconciling definitions | Yes |
| `index_busy` | The index is already changing lifecycle state. | 500 | After the active operation completes | Yes |
| `index_operation_not_found` | The requested index operation does not exist. | 500 | After fixing the operation ID | Yes |
| `index_operation_not_abortable` | The requested operation can no longer be aborted. | 500 | No | No |
| `index_not_found` | The required logical or physical index does not exist. | 400/500 | After creating or selecting the index | Yes |
### Retryable conflicts
| Code | Meaning | HTTP | Retry | Correctable |
| --- | --- | --- | --- | --- |
| `transaction_conflict` | A concurrent transaction prevented commit. | 409 | Yes, bounded backoff | No request change required |
| `request_read_view_changed` | A standalone reader changed views during the request. | 500 | Yes, bounded retry | No request change required |
| `stale_index_generation` | A retained handle refers to a stale index generation. | 500 | Yes, reacquire state | No request change required |
| `writer_fenced_commit_outcome_unknown` | Writer fencing made the final commit outcome unknowable. | 500 | Only with idempotency protection | No |
### Availability and migration
| Code | Meaning | HTTP | Retry | Correctable |
| --- | --- | --- | --- | --- |
| `database_closed` | The database handle is closed. | 500 | After reopening | Operational |
| `invalid_configuration` | Database configuration is invalid. | 500 | After fixing configuration | Operational |
| `migration_stepping_requires_disabled_mode` | Explicit migration stepping requires disabled worker mode. | 500 | After changing worker mode | Operational |
| `migration_required` | Existing storage requires an explicit migration. | 500 | After migration | Operational |
| `writer_migration_required` | A writer must open and migrate existing storage. | 500 | After writer migration | Operational |
| `unsupported_index_storage_version` | Stored index data is newer than this binary supports. | 500 | After upgrading the binary | Operational |
| `writer_mode_required` | The operation requires a writer handle. | 503 | On a writer | Operational |
| `reader_mode_required` | The operation requires a standalone reader handle. | 500 | On a reader | Operational |
| `query_cancelled_by_reader_retirement` | Reader retirement cancelled the query before the reader closed. | 500 | After routing to another reader | Operational |
### Internal failures
| Code | Meaning | HTTP | Retry | Correctable |
| --- | --- | --- | --- | --- |
| `storage_error` | Storage failed outside a classified transaction conflict. | 500 | According to storage health | Operational |
| `internal_planner_error` | An internal planner contract failed. | 400 | No automatic retry | No |
| `response_serialization_error` | A successful result could not be serialized. | 500 | No automatic retry | No |
| `internal_error` | An invariant, persisted-data contract, or opaque internal operation failed. | 500 | No automatic retry | No |
## Migrate direct HTTP consumers
The field names changed while their roles stayed the same:
| Before | Now | Meaning |
| --- | --- | --- |
| `code` | `error` | Stable machine-readable code |
| `error` | `msg` | Human-readable diagnostic |
Old response:
```json
{
"error": "planner error: missing text index for `Document.body`",
"code": "index_not_found"
}
```
New response:
```json
{
"error": "index_not_found",
"msg": "planner error: missing text index for `Document.body`"
}
```
Current SDKs read both shapes during migration. Direct HTTP consumers must move
their code branch from `code` to `error` and their diagnostic read from `error`
to `msg`.
# Connect to Helix Cloud
Page type: Guide
Guide
Helix Cloud runs a dedicated writer and horizontally scalable readers behind a routing
gateway. Applications send the same dynamic operation-tree request used in local and
embedded modes.
## Request flow
```text
application
│ POST /v2/query
▼
gateway
├── read request ──► reader
└── write request ─► writer
│
▼
object storage
```
## Connect and send a request
```rust Rust
let client = helix_db::Client::new(Some("https://cluster.helix-db.com"))?
.with_api_key(Some("hx_your_api_key"));
```
```ts TypeScript
const client = Client
.server("https://cluster.helix-db.com")
.withApiKey("hx_your_api_key");
```
```go Go
client, err := helix.NewClient(
"https://cluster.helix-db.com",
helix.WithAPIKey("hx_your_api_key"),
)
```
```python Python
client = Client(
"https://cluster.helix-db.com",
api_key="hx_your_api_key",
)
```
These SDK examples target a database-specific cluster-mode gateway URL. Such an
endpoint authenticates the API key but rejects `X-Helix-Database-Id` and
`X-Helix-Tenant-Id`. A GA shared gateway instead requires
`X-Helix-Database-Id`; the current public SDK request builders do not expose
that selection header, so use the direct HTTP contract for GA shared-gateway
requests.
Each client sends the same operation-tree request body:
```json JSON
{
"request_type": "read",
"query_name": "user_by_username",
"query": {
"read": {
"entries": [
{
"query": {
"name": "user",
"root": {
"nodes_where": {
"predicate": {
"eq": {
"left": { "property": "username" },
"right": { "constant": { "string": "Alice" } }
}
}
}
}
}
}
],
"returns": ["user"]
}
}
}
```
Keep API keys in secrets management, not source control. The JSON example is the request
body sent to `POST /v2/query`.
`query_name` is optional diagnostic metadata. The query itself remains entirely inside
the request; there is no route deployment step.
## Routing controls
SDK request builders expose advanced server-only controls:
- Require execution on the writer.
- Require a warm read.
- Choose whether a write waits for durability.
Embedded clients reject these controls because they describe distributed routing.
## Query warming
Send an ordinary read request with `X-Helix-Warm: true` to execute it on every
eligible database backend without returning the query result. The gateway returns
`204 No Content` after at least one backend succeeds, including when another target
fails. If every target fails, the normal deterministic error response is returned.
Managed clusters target database pods that are ready, running, routable, and not
quarantined. Add `X-Helix-Require-Writer: true` to target only the authoritative
writer. Authentication, [request rate limits](/database/helix-cloud/operate/limits#helix-cloud-request-rate-limits),
retries, and the normal query timeout still apply before and during fanout.
Warming populates the storage, vector, and text caches touched by the read; it does
not create a separate result cache. `X-Helix-Warm: true` or `1` enables warming;
`false` or `0` leaves the request on the ordinary query path. Invalid values and
warm write requests return `400 Bad Request`; writes are rejected before backend
execution. A managed cluster with no eligible warming target returns
`503 Service Unavailable`.
## Next steps
Understand readers, the writer, storage, and routing.
Review transaction and durability behavior.
Handle authentication and tenant isolation.
Authenticate and connect a project.
# Using the Cloud
Page type: Tutorial
Tutorial
Use Helix Cloud to create a workspace, choose a monthly plan shared by its
databases, provision a database, and create API keys.
Enter a workspace name, choose a monthly plan, and select **Create
workspace**. The plan's read and write allowances are shared by every
database in the workspace. You can change the plan later from **Billing**.
Enter a database name and select **Create Database**. Helix Cloud generates
its URL slug. The database has isolated data and uses the workspace's shared
monthly allowance. Database creation creates a default read-write API key
and displays its token once. Save it immediately in the application's
secrets manager; Helix cannot show it again.
Wait for the database status to become **Active**, then open it. In
**Connect**, copy the endpoint and database ID. To connect an application
directly to the gateway, use **API Keys** to explicitly create a read-only
or read-write key and copy its value when it is shown once.
## Test the connection
Set the three values copied from the database page, then count the database's
nodes. A successful response, such as `{"node_count":0}`, confirms the connection.
```bash
export HELIX_ENDPOINT=""
export HELIX_DATABASE_ID=""
export HELIX_API_KEY=""
curl --fail-with-body \
"$HELIX_ENDPOINT/v2/query" \
--header "Authorization: Bearer $HELIX_API_KEY" \
--header "X-Helix-Database-Id: $HELIX_DATABASE_ID" \
--header "Content-Type: application/json" \
--data '{
"request_type": "read",
"query": {
"read": {
"entries": [
{
"query": {
"name": "node_count",
"root": {
"count": {
"input": {
"nodes": { "reference": "all" }
}
}
}
}
}
],
"returns": ["node_count"]
}
}
}'
```
Keep API keys in a secrets manager or environment variable. Do not commit them
to source control.
## Next steps
Connect from an SDK and understand Cloud request routing.
Review authentication, encryption, and API key handling.
Install the SDK and connect a Node.js application.
Build and run a query step by step.
# Architecture
Page type: Concept
Concept
Helix Cloud runs as a single writer node and multiple reader nodes behind a routing gateway. Reads
scale horizontally. Writes are serialized through a dedicated writer process to maintain a simple
consistency model.
Helix Cloud is a fundamentally different architecture and database compared to the open-source v1
version of HelixDB. That version used LMDB, which was limited to sequential writes and could only handle
a relatively small amount of data. Helix Cloud uses a new LSM-based storage engine backed by object
storage that can handle concurrent writes to the writer node and allows for virtually unlimited data storage.
## Gateway
The gateway is the entry point for all client traffic. It authenticates each request via Bearer
token, accepts the inline query payload, and routes it: mutations always go to the writer,
read-only queries are distributed across the readers and the writer.
For high availability, deploy at least three gateway instances per cluster. Smaller fleets work for
non-HA or test workloads but are not recommended for production.
## Writer
A single writer process handles all mutations. The writer supports concurrent write transactions
through MVCC (multi-version concurrency control), allowing multiple writes to execute in parallel
without blocking each other. Serializing the commit path through one process eliminates distributed
coordination and simplifies the consistency model. The writer batches mutations for throughput and
persists them durably to object storage before acknowledging.
The writer also serves read-only queries. It maintains its own SSD and in-memory cache, giving it
the most up-to-date view of the data. Reads routed to the writer see committed writes immediately,
with no snapshot refresh delay.
## Readers
Readers serve all read-only queries. They are stateless with respect to writes and can be added
or removed without coordination. Each reader maintains a local SSD and in-memory cache populated
from object storage.
Reader scaling is automatic. As query load increases, new readers are provisioned. As load
decreases, excess readers are removed. This keeps cost proportional to actual query volume.
## Object Storage
Object storage is the durable system of record. All graph data, vector indexes, text index
artifacts, and metadata persist here. No data lives exclusively on local disk. This means the
system can recover from a full cache loss by reading from object storage, and storage capacity is
effectively unbounded.
## Cache Hierarchy
Each process (writer and readers) maintains local cache tiers for the data and indexes it serves.
- **In-memory cache.** Fastest access. Holds the most frequently accessed graph data, vector
search state, and hot text-search generations. Bounded by available RAM.
- **SSD cache.** Larger capacity, lower cost per byte. Holds warm graph data, vector data, and
reusable text-search artifacts. Reads from SSD are significantly faster than reads from object
storage.
Graph, vector, and text workloads use specialized cache paths so hot working sets do not fully
contend with one another. On cold start, caches warm progressively as queries execute; for
predictable latency from the first query, caches (including text index generations) can be
pre-warmed.
## Read Path
1. A read request arrives at the gateway and is routed to a reader or the writer.
2. The reader resolves a consistent snapshot from object storage metadata.
3. Data is read from the in-memory cache, SSD cache, or object storage (in that order).
4. The query executes against the snapshot and returns results.
Cache misses transparently fall through to object storage. The same query produces the same result
regardless of cache state; caching affects latency, not correctness.
## Write Path
1. A write request arrives at the gateway and is routed to the writer.
2. The writer executes the mutation within a serializable transaction. Multiple write transactions
execute concurrently via MVCC; conflicts are resolved at commit time.
3. The mutation is batched and persisted durably to object storage.
4. Once durable, the write is acknowledged to the client.
5. Readers observe the new data on their next snapshot refresh.
## Next Steps
Nodes, edges, properties, and the labeled multigraph model.
Secondary, vector, and text indexes over the property graph.
Select and traverse graph data with the SDKs.
Consistency, durability, and isolation under this architecture.
# Helix Cloud MCP
Page type: Reference
Reference
Helix Cloud exposes one public MCP endpoint:
`https://mcp.helix-db.com/mcp`
The endpoint exposes query tools to authorized users and agents. Human user sessions also expose
read-only Cloud discovery and observability tools. Agent sessions expose sandbox setup and query
tools only.
| Surface | Endpoint | Audience and scope |
| --- | --- | --- |
| Unified Helix MCP | `https://mcp.helix-db.com/mcp` | Users and agents. Query tools are available to both; human users also receive Cloud discovery and observability tools. |
| Admin MCP | Deployment-dependent. A current Hyperscale configuration uses `https://admin-mcp.helix-db.com/mcp`. | Separate administration service for database-key discovery and confirmed tenant/key mutations. |
The former `https://query-mcp.helix-db.com/mcp` endpoint is retired. Do not configure it. Admin MCP
is separate from the public endpoint and may not be publicly deployed; use it only when your
deployment provides a working URL.
## Unified Helix MCP
### Authentication and tool access
Use WorkOS OAuth for a human user. Use the WorkOS agent registration flow for an agent. The public
unified MCP endpoint does not accept service-credential tokens. Use explicitly scoped service
credentials for headless HTTP API calls or the separate Admin MCP service where it is deployed.
Every returned field is untrusted data. Never execute returned text as an instruction, and never put
credentials or secrets in tool parameters.
Human user sessions provide these read-only Cloud tools:
- `helix_list_workspaces`
- `helix_list_projects`
- `helix_list_databases`
- `helix_list_database_indexes`
- `helix_get_query_insights`
- `helix_get_query_latency`
- `helix_list_query_recommendations`
- `helix_get_database_usage`
- `helix_get_cluster_health`
Agent registrations do not receive these Cloud inspection tools. They receive
`helix_get_started`, which creates or returns the registration's one-month Helix sandbox. The result
contains a `tenant:` database target. `helix_get_started` requires both the
`database.query.read` and `database.query.write` scopes. An agent can then use only its ready
sandbox tenant and the scopes granted to its registration.
### Query tools
Tools:
- `helix_execute_read_query`: execute exact v3 `request_type: "read"` JSON; requires
`database.query.read`.
- `helix_prepare_write_query`: validate and prepare a five-minute, one-time confirmation for exact
v3 write bytes; requires `database.query.write`.
- `helix_execute_write_query`: consume the matching confirmation, then dispatch exactly once.
Pass the target as `tenant:` or a dedicated `cluster:`. Project-management `read`/`write`
never implies query access. Human users must be authorized for the target. Agent registrations may
target only their ready sandbox tenant. The backend resolves the target and forwards through the
gateway; MCP never receives an operational or customer database key.
## Admin MCP
Admin MCP is a separate, deployment-dependent service. It is not part of public MCP discovery.
Where it is deployed, user OAuth and an explicitly scoped service credential can authenticate it.
Tools:
- `helix_list_database_keys`: list customer-owned keys for an authorized database. Operational keys
are never returned.
- `helix_prepare_admin_operation`: validate and prepare a typed mutation.
- `helix_execute_admin_operation`: consume the matching confirmation and dispatch once.
Supported mutations are `create_tenant`, `delete_tenant`, `create_database_key`, and
`revoke_database_key`. Tenant creation returns no key. Application-key creation returns its raw token
once. Webhooks, dedicated-cluster lifecycle, networking, regions/SKUs, branches/backups, schema
introspection, execution polling/cancellation, and project update are not exposed.
## Durable confirmation contract
Prepare and execute must use the same principal, server audience, operation, canonical target, and
validated payload. The shared backend database stores only the confirmation/token hashes, identity,
audience, operation, target, expiry, and state—never query bodies, mutation payloads, parameters,
returned secrets, or raw tokens.
Execution atomically changes `prepared` to `consumed` before dispatch. Only one replica can win.
Expired or consumed confirmations cannot be reused. A crash before dispatch or any timeout, gateway,
broker, or ambiguous post-dispatch failure leaves it consumed; do not retry the mutation.
## Client configuration
Configure `https://mcp.helix-db.com/mcp` for normal user or agent access and complete the browser
OAuth flow when prompted. Clients can follow the protected-resource metadata advertised by the
endpoint at
`https://mcp.helix-db.com/.well-known/oauth-protected-resource/mcp`.
Use a service credential only with the HTTP API or a separately deployed Admin MCP endpoint. Create
the minimum scope required, capture the one-time token in a secrets manager, and send it only to the
intended audience.
Do not put WorkOS tokens, application keys, service-credential tokens, or confirmation tokens in
source control, agent instruction files, or query payloads.
# Multi-Tenancy
Page type: Guide
Guide
Multi-tenant architectures generally fall into one of three isolation levels.
## Isolation Levels
| Level | Description | Isolation | Resource efficiency |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------- |
| **Infrastructure-level** | Separate database instance per tenant. Fully independent compute, storage, and networking. | Strongest. No shared resources. | Lowest. Each tenant pays the full cost of an idle cluster. |
| **Namespace-level** | Shared infrastructure, separate logical partitions (databases, schemas, or namespaces) per tenant. | Strong. Logical separation with shared compute. | Moderate. Shared compute, but metadata and indexes scale per tenant. |
| **Row-level** | Shared infrastructure, shared data structures. Tenants distinguished by a property on every record, enforced at query time. | Application-enforced. Relies on consistent query-time filtering. | Highest. All tenants share indexes, caches, and storage. |
## Row-Level Isolation in Helix Cloud
Helix Cloud focuses on row-level isolation, which lets you implement any tenancy model at the
application layer without structural constraints on the database. Adding a tenant is a write, not a
provisioning event.
Assign a tenant identifier as a property on every node and edge, index it with an equality index,
and filter every query on it so each request only sees its own tenant's data. This is the same
mechanism as any property-based filtering: secondary indexes make the lookup fast, and snapshot
isolation keeps concurrent tenants from interfering.
The model stays shared infrastructure throughout — one writer fleet, one reader fleet, shared caches
and secondary indexes. When search results also need isolating, vector and text search can use
[tenant-partitioned indexes](#tenant-partitioned-search-indexes).
### In Practice
The pattern is the same regardless of node label: create an equality index on the
tenant property, attach `tenant_id` to every node and edge written, and scope every
read with a source predicate so the equality index is eligible for push-down.
```rust Rust
read_batch()
.var_as(
"docs",
g()
.n_with_label_where(
"Doc",
SourcePredicate::eq("tenant_id", "acme"),
)
.value_map(Some(vec!["$id", "title"])),
)
.returning(["docs"]);
```
```ts TypeScript
readBatch()
.varAs(
"docs",
g()
.nWithLabelWhere("Doc", SourcePredicate.eq("tenant_id", "acme"))
.valueMap(["$id", "title"]),
)
.returning(["docs"]);
```
```go Go
helix.ReadQuery("tenant_docs").
VarAs(
"docs",
helix.G().
NWithLabelWhere("Doc", helix.SourceEq("tenant_id", "acme")).
ValueMap("$id", "title"),
).
Returning("docs")
```
```python Python
(
read_batch()
.var_as(
"docs",
g()
.n_with_label_where(
"Doc",
SourcePredicate.eq("tenant_id", "acme"),
)
.value_map(["$id", "title"]),
)
.returning(["docs"])
)
```
```json JSON
{
"request_type": "read",
"query_name": "tenant_docs",
"query": {
"read": {
"entries": [{
"query": {
"name": "docs",
"root": {
"value_map": {
"input": {
"nodes_where": {
"predicate": {
"and": {
"predicates": [
{
"eq": {
"left": { "property": "$label" },
"right": { "constant": { "string": "Doc" } }
}
},
{
"eq": {
"left": { "property": "tenant_id" },
"right": { "constant": { "string": "acme" } }
}
}
]
}
}
}
},
"properties": ["$id", "title"]
}
}
}
}],
"returns": ["docs"]
}
}
}
```
When the tenant predicate sits mid-traversal — for example after walking edges from a known
starting node — use `.where_(Predicate::eq("tenant_id", "acme"))`. The same scope rule applies
at every hop: edges that fan out across the graph remain tenant-scoped as long as every step
filters on the tenant property.
## What This Provides
- **Data isolation.** Queries scoped to a tenant ID never observe another tenant's data. Isolation
is enforced by the query layer, not by network or infrastructure boundaries.
- **Shared infrastructure.** All tenants share the same writer, readers, caches, and object
storage. No per-tenant provisioning, no per-tenant scaling configuration.
- **Uniform scaling.** Reader auto-scaling responds to aggregate query load across all tenants.
A spike from one tenant benefits from the same scaling that serves all others.
- **Index efficiency.** Equality indexes on the tenant property resolve tenant-scoped queries
without scanning unrelated data.
- **Full flexibility.** The application layer decides how tenancy is modeled, scoped, and
enforced. Helix Cloud provides the primitives; the application owns the policy.
## Tenant-Partitioned Search Indexes
Tenant-partitioned search indexes are optional. They supplement row-level filtering with separate
physical search structures per tenant value.
### Vector Indexes
Vector indexes can optionally partition by a configured tenant property name. Helix reads that
property from each record and maintains a separate vector index for each distinct property value.
For example, if the tenant property name is `tenant_id`, records with different `tenant_id` values
land in different vector indexes. This keeps tenant-scoped search working sets smaller and allows
vector caches to warm, retain, and evict data at tenant granularity. Tenant-partitioned vector
indexes are the preferred way to isolate vector search results when that behavior is required.
Pass `tenant_id` as the tenant property when creating the vector index, store both
`tenant_id` and the embedding on every indexed entity, and pass the tenant value when
calling the SDK's vector-search builder. See [vector indexes](/database/helix-db/query-guides/vector-indexes)
for the cross-language index definition.
### Text Indexes
Text indexes provide the same model for full-text search. The tenant property still means the
property name used to read the partition value from each record. Current text index validation
requires that property name to be `tenant_id`, so Helix maintains a separate text index for each
distinct `tenant_id` value. This keeps tenant-scoped full-text search working sets smaller and
allows local text-search caches to track active tenants more closely. Tenant-partitioned text
indexes are the preferred way to isolate full-text search results when that behavior is required.
Pass `tenant_id` as the partition property when creating the text index, then pass
the request's tenant value to the text-search builder. See
[text indexes](/database/helix-db/query-guides/text-indexes) for the cross-language definition.
## Considerations
- **Noisy neighbors.** Tenants share compute and cache, so a high-volume tenant can affect others'
latency. The [Helix Cloud request bucket](/database/helix-cloud/operate/limits#helix-cloud-request-rate-limits)
is shared by the whole database. Monitor per-tenant query volume and apply a
separate application-side limiter when many application tenants use that database.
- **Shared search semantics.** Secondary indexes remain shared. Tenant-scoped vector and text
searches require an explicit tenant value for the configured tenant property, and the system
remains shared infrastructure even when search indexes are partitioned by tenant.
## Stricter Isolation Requirements
For workloads that require namespace-level or infrastructure-level tenant isolation (regulatory
compliance, data residency, or dedicated-resource SLAs), contact us at
[founders@helix-db.com](mailto:founders@helix-db.com) to discuss options.
# Guarantees
Page type: Reference
Reference
HelixDB executes each query request as one transaction over a committed snapshot.
## Atomicity
All mutations in one write batch commit together or roll back. A failed operation does
not leave earlier mutations from the same request committed.
## Consistency
Constraints such as unique indexed values, property encodings, vector dimensions, and
text index value requirements are checked before the relevant write or index
generation becomes active.
## Isolation
Transactions use serializable snapshot isolation:
- A request reads graph and index state from one committed snapshot.
- A write request reads its own mutations before commit.
- Conflicting writes are detected at commit; the request fails instead of committing
against stale transactional state.
- Secondary, vector, and text lookups participate in the same request transaction.
## Durability
Canonical data is persisted by the selected storage source. In Cloud, local memory and
disk caches are performance layers; object storage is canonical.
Server clients can explicitly set `shouldAwaitDurability(true)` /
`should_await_durability(true)` when the acknowledgement must wait for the configured
durability boundary, or `false` when the application accepts an earlier
acknowledgement. Embedded mode rejects this server-only option.
## Index activation
Index creation and deletion use durable lifecycle operations:
- A build scans existing entities and catches up concurrent mutations.
- A constructing generation is hidden from queries.
- Validation completes before one atomic activation step.
- A blocked or aborted generation never becomes partially queryable.
## Readers and read-after-write
The writer can serve a newly committed state immediately. A reader observes it after
refreshing to a snapshot that contains the commit, so a request routed to a reader may
temporarily lag.
Use a writer-only server request when a separate request requires read-after-write:
Set `writerOnly()` / `writer_only(true)` / the equivalent Go request option before
sending the read.
Embedded writer handles execute against their local writer. Embedded reader handles
are read-only and refresh according to the underlying reader lifecycle.
## Cloud availability
Cloud availability and recovery depend on the purchased deployment topology. Contact
[founders@helix-db.com](mailto:founders@helix-db.com) for current redundancy and SLA
terms instead of assuming a topology from the SDK contract.
# Security
Page type: Reference
Reference
## Direct gateway authentication
All API requests to Helix Cloud are authenticated with a Bearer token. Tokens are managed
through the Helix dashboard. Include the token in the `Authorization` header of every request:
```
Authorization: Bearer
```
The SDK clients attach this header for you—set the key once with `withApiKey`
(TypeScript), `with_api_key` (Rust and Python), or `WithAPIKey` (Go). See the
[cross-language Cloud connection example](/database/helix-cloud/start-here/working-with-enterprise#connect-and-send-a-request).
Requests without a valid token are rejected at the gateway before reaching any database node.
Token rotation and revocation take immediate effect from the dashboard.
The Helix CLI does not use these application keys. Cloud CLI operations authenticate with a rotating
WorkOS session, and Cloud CLI queries execute through the backend broker. Interactive MCP uses WorkOS
OAuth for human sessions and the WorkOS agent registration flow for agents. The public unified MCP
endpoint does not accept service credentials; use explicitly scoped service credentials for headless
HTTP API calls or the separate Admin MCP service where it is deployed.
## Encryption
All traffic between clients and the gateway is encrypted in transit via TLS. Data at rest in
object storage is encrypted using the storage provider's server-side encryption.
## Enterprise features
The following are available for enterprise clusters. Contact
[founders@helix-db.com](mailto:founders@helix-db.com) to enable them for your deployment.
- **Role-based access control.** Scoped API keys with read-only, read-write, or operation-restricted
permissions for least-privilege credentials per service or environment.
- **SSO / SAML.** Dashboard access through your identity provider (Okta, Azure AD, Google Workspace)
with centralized provisioning and deprovisioning.
- **Audit logs.** Per-request logging (timestamp, token identity, query name, source IP, response
status) for compliance (SOC 2, HIPAA, GDPR) and forensic analysis.
- **AWS PrivateLink.** A private endpoint in your VPC that routes to Helix Cloud without traversing
the public internet, for network-isolation requirements in regulated environments.
# Tradeoffs
Page type: Concept
Concept
Every system makes design choices. Helix Cloud optimizes for durable, cost-effective graph,
vector, and text workloads with strong transactional guarantees. These choices have implications.
## Excels At
| Area | Details |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Durable storage** | All data persists in object storage. No risk of data loss from local disk failure. Storage capacity scales independently of compute. |
| **Read scalability** | Readers auto-scale horizontally. Doubling readers doubles read throughput with no coordination overhead. |
| **Serializable transactions** | Every query runs against a stable snapshot with ACID semantics by default. |
| **Mixed graph, vector, and text workloads** | Graph traversals, vector search, and full-text search execute in the same transaction, against the same snapshot. No need to stitch together separate systems for those workloads. |
| **Cost efficiency at scale** | Object storage is significantly cheaper per GB than local SSDs or in-memory stores. Large datasets remain affordable. |
| **Operational simplicity** | Single writer eliminates distributed consensus. No leader election, no split-brain, no quorum management. |
## Not Optimal For
| Area | Details |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Sub-millisecond reads** | Cache hits are fast, but cold reads require an object storage round trip. Workloads that require guaranteed sub-millisecond latency on every read are better served by in-memory databases. |
| **Ultra-low write latency** | Writes incur object storage latency for durability. Write throughput is high, but individual write latency has a floor set by object storage round-trip time. |
| **Exhaustive vector recall** | Vector search is approximate (ANN). Applications that require 100% exact nearest neighbor results should use brute-force search on smaller datasets. |
## Design Choices
**Object storage as the system of record.** Caches accelerate reads but are not required for
correctness. This means cold starts are slower than systems that keep all data on local disk, but
durability and cost characteristics are superior.
**Single writer.** Serializing all writes through one process avoids distributed coordination at the
cost of write throughput being bounded by a single node. In practice, batching and the high
throughput of the writer process make this sufficient for most workloads.
**Specialized cache paths.** Helix maintains separate cache paths for graph data, vector indexes,
and text search artifacts. The tradeoff is less flexibility in cache allocation when only one
workload dominates.
**Dynamic query model.** Queries travel inline with each request, so there is no deploy step and
ad-hoc queries are fully supported. The tradeoff is the small per-request cost of deserializing the
query AST on every call.
# Limits
Page type: Reference
Reference
Current constraints and practical limits. These reflect the current implementation, not
fundamental architectural boundaries.
## Active-text mutation admission
The engine bounds foreground mutations that affect full-text indexes. These limits
apply to Cloud and standalone HelixDB. Exceeding a bound rejects the write transaction
before commit with HTTP 400 and code `active_text_mutation_limit_exceeded`; it does
not partially commit graph changes. The diagnostic reports the measured resource,
observed usage and configured limit.
The default entity ceiling is **512 distinct text-relevant graph entities per
collecting/flush epoch**. Repeated changes to the same entity coalesce within an
epoch. Both nodes and edges can count when a text index observes their changes;
unrelated entities do not count. Consequently, the number of input IDs alone does
not establish whether a request fits. Internal text reads can flush an epoch, but
ordinary bulk deletes accumulate changes until their final text preparation.
Additional active-text defaults remain in force even below 512 entities:
| Resource | Default ceiling |
| --- | ---: |
| Retained/input bytes and text analysis | 64 MiB |
| Output key/value operations | 32,768 |
| Output key/value bytes | 8 MiB |
| Individual split payload and retained split payload budget | 64 MiB |
| Encoded manifest page | 4 MiB |
Admission accounts for complete retained before/after property rows as well as text
index work. Large properties, multiple indexes, or tenant partitions can therefore
hit another bound with fewer entities. These are runtime policy limits, not storage
format maxima; embedded configurations can supply a different validated policy.
Reduce the number or size of mutations before retrying. If the application splits
one request into several, each new request is a separate atomic transaction. The
service does not automatically replay the rejected write. There is no time-based
`Retry-After`: waiting without changing the mutation does not resolve a hard limit.
See [Error handling](/database/helix-cloud/operate/error-handling) for the response
contract. HTTP 429 rate limiting below is a separate mechanism.
## Helix Cloud request rate limits
Helix Cloud applies a distributed token bucket to `POST /v2/query`. The bucket is
scoped to the authenticated Cloud database, so reads and writes from every API
key, application instance, and gateway replica draw from the same allowance.
| Plan | Sustained rate | Burst capacity |
| --- | ---: | ---: |
| Idea | 5 requests per second | 10 requests |
| Startup | 10 requests per second | 20 requests |
| Growth | 20 requests per second | 40 requests |
Database-specific overrides can change the sustained rate, burst capacity, and query attempt budget.
The values assigned to your database take precedence over its plan limits. Each
admitted query request costs one token from one shared bucket per Cloud database.
### Token-bucket behavior
- A full bucket can admit requests up to its burst capacity. Tokens then refill
continuously at the plan's sustained rate, up to that capacity. This is not a
fixed one-second window.
- One incoming request consumes one token whether it is a read, write, or cache
warming request. Warming fanout and gateway retries do not consume additional
tokens.
- Requests rejected during authentication, gateway header validation, or outer
request JSON decoding do not consume a token. Query AST and planner validation
happen after admission, so those later validation failures consume one token.
- The bucket is shared across API keys and gateway replicas. Rotating keys or
distributing calls across connections does not create more capacity.
- Burst capacity controls short-term admission, not the number of queries that
can execute concurrently. Bound client concurrency separately.
### Rate-limit responses
When no token is available, the gateway rejects the request before database
execution:
```http
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 1
{"error":"rate_limited","msg":"rate limit exceeded"}
```
`Retry-After` is a whole number of seconds. Wait at least that long before
retrying, and add jitter when many workers share the same database. The response
does not currently include `RateLimit-*` or `X-RateLimit-*` limit, remaining, or
reset headers.
Current official SDK error objects expose the HTTP status, stable code, and
diagnostic, but not response headers. Use direct HTTP or an application
transport that retains headers when the exact `Retry-After` value is required;
otherwise use a configured, bounded status/code-aware delay with jitter.
If the gateway cannot make a safe distributed rate-limit decision, it fails
closed before database execution:
```http
HTTP/1.1 503 Service Unavailable
Content-Type: application/json
{"error":"rate_limit_unavailable","msg":"tenant rate limit is unavailable"}
```
Retry `rate_limit_unavailable` with bounded exponential backoff and jitter. A
`402` `tenant_disabled` response is an account-credit gate, and a `408`
`query_timeout` response is an execution deadline; neither means the request
bucket was exhausted.
### Application guidance
1. Coordinate admission across workers that target the same Cloud database.
2. Honor `Retry-After` on `rate_limited` instead of retrying immediately.
3. Use bounded exponential backoff with jitter for transient `503` responses.
4. Bound in-flight concurrency as well as request rate to avoid local queues and
latency spikes.
5. Apply a separate per-user or per-workspace limiter when multiple application
tenants share one Cloud database; the Helix bucket does not distinguish those
application tenants.
## Data Model
| Limit | Value |
| ---------------------- | ---------------------------------------------------------------------------------------------- |
| Node and edge ID range | 64-bit unsigned integer (max 2^64 - 1); JSON responses encode lifecycle identifiers as decimal strings |
| Property value types | boolean, integer, float, string, bytes, typed primitive arrays, generic arrays, and objects |
| Nested structures | Stored object/array values are supported. Dotted-path lookup such as `metadata.externalID` works in scan-time filters, expressions, projections, `values`, filtered `valueMap`, and fallback ordering. Arrays are opaque; there is no array-index path syntax. |
| Reserved property keys | `$label` (used for label-based filtering and label-scoped secondary, vector, and text indexes) |
## Vector Indexes
| Limit | Value |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Scope | Node and edge properties |
| Supported property types | Numeric array properties (`float32[]`, `float64[]`, `int64[]`) normalized to `float32` for indexing |
| Tenant partitioning | Optional by configured tenant property name. Tenant-scoped searches require a tenant value. Unknown tenant partitions return no results. |
| Dimension matching | Vectors must exactly match the configured index dimension |
| Distance metrics | cosine, euclidean, manhattan |
| Search type | Approximate nearest neighbor (ANN) |
| Result count | Unrestricted vector search caps effective `k` at 800. Traversal-scoped vector search rejects when `min(k, unique candidates)` exceeds 800 or when the candidate stream exceeds 1,000,000 unique entities. |
| Restricted search | Final membership is the exact current traversal stream; ranking may still use approximate index structures |
## Text Indexes
| Limit | Value |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Scope | Node and edge properties |
| Supported property types | Top-level `String` and `StringArray` properties. Nested object fields are not flattened for BM25. |
| Unsupported values | `null` and non-string values are rejected |
| Analyzer config | Preset analyzers: `standard`, `standard_stem_en`, `whitespace_lowercase` |
| Term positions | Optional |
| Result count | Effective `k` is capped at 800. Traversal-scoped text search returns at most `min(unique candidates, k, 800)` rows; more than 1,000,000 unique candidates is a query error. |
| Tenant partitioning | Optional. Tenant-partitioned text indexes currently require the partition property name to be `tenant_id`, and tenant-scoped searches require a tenant value. |
## Secondary Indexes
| Limit | Value |
| ---------------- | ---------------------------------------------------------------------------------------------------------- |
| Equality indexes | Supported on top-level node and edge properties. Nested dotted paths are scan-only in V1. |
| Range indexes | Supported on top-level numeric and string properties. Nested dotted paths are scan-only in V1. |
| Encoding | Range indexes use lexicographic string encoding. Values must be encoded consistently for correct ordering. |
## Queries
| Limit | Value |
| ----------------- | ------------------------------------ |
| Query model | Dynamic queries |
| Query language | SDK DSLs or dynamic JSON AST |
| Transaction scope | One transaction per query invocation |
| Query attempt budget | 30 seconds in the current default and plan configuration; database-specific overrides may change it |
| Request envelope | One `read` or `write` operation-tree batch with named entries and explicit returns |
## Index lifecycle
| Limit | Value |
| --- | --- |
| Activation | Asynchronous and atomic after scan, catch-up, and validation |
| Progress | Monotonic entity/byte/operation counters; no percentage or total-work estimate |
| Controls | Poll all operations; retry blocked operations; abort eligible constructing builds |
| Memory reporting | Cache and batch budgets do not constitute a hard process-RSS cap |
## Embedded runtime
| Limit | Value |
| --- | --- |
| Storage sources | In-memory, local disk, and S3-compatible object storage |
| Handle modes | Writer or read-only |
| Server options | Gateway headers and routing options are rejected |
| Packaging | Install the SDK and its embedded runtime package |
| Cache configuration | Fixed when the handle opens |
# Handle query errors
Page type: Reference
Reference Helix Cloud
Helix Cloud query failures use one JSON envelope:
```json
{
"error": "query_timeout",
"msg": "query exceeded its wall-clock limit"
}
```
- `error` is a stable, lower-snake-case code. Branch on this field.
- `msg` is a human-readable diagnostic. Log it, but do not parse it or depend on
its exact text.
- The HTTP status remains part of the contract. Use it with `error` when deciding
whether and how to retry.
## Gateway error reference
| HTTP | `error` | Typical `msg` | Meaning | Retry guidance |
| ---: | ------------------------ | --------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| 400 | `invalid_query_json` | `parse error: ` | The request body is not valid query JSON. | Fix the request. |
| 400 | `invalid_request` | A request-specific diagnostic | A required header or request option is missing, malformed, or invalid. | Fix the request. |
| 400 | `tenant_id_required` | `x-helix-tenant-id or x-helix-database-id is required in GA mode` | A Cloud request did not identify its database. | Use the correct database-scoped Cloud endpoint and configuration. |
| 400 | `tenant_id_not_allowed` | `x-helix-tenant-id and x-helix-database-id are not allowed in cluster mode` | A tenant/database header was sent to an endpoint that does not accept it. | Remove the header or use the correct endpoint. |
| 400 | `active_text_mutation_limit_exceeded` | `db error: Active text mutation exceeds : observed , limit . This is a hard mutation-batch limit; reduce the number or size of mutations.` | A mutation exceeds a hard engine admission limit; graph changes are not committed. | Reduce the mutation before retrying; see [Limits](/database/helix-cloud/operate/limits#active-text-mutation-admission). |
| 401 | `unauthorized` | `unauthorized` | The supplied API key is unknown or no longer active. | Refresh or replace the key. |
| 402 | `tenant_disabled` | `tenant query processing is disabled because credit is exhausted` | Query processing is disabled because the tenant has exhausted its credit. | Resolve the account state before retrying. |
| 403 | `forbidden` | `forbidden` | The key is valid but cannot perform this operation. | Use a key with the required permission. |
| 408 | `query_timeout` | `query exceeded its wall-clock limit` | The query exceeded its wall-clock limit. | Reconcile timed-out writes before considering a retry. |
| 409 | `transaction_conflict` | `request conflicted with a concurrent write; please retry` | A concurrent write prevented the transaction from committing. | Retry the whole idempotent transaction with bounded backoff. |
| 413 | `payload_too_large` | `request body exceeds the maximum allowed size` | The query request exceeds the gateway body-size limit. | Reduce the request size. |
| 429 | `rate_limited` | `rate limit exceeded` | The database's request bucket has no token available. | Honor `Retry-After`; see [Limits](/database/helix-cloud/operate/limits). |
| 500 | `internal_error` | An internal or backend diagnostic | An unexpected gateway or backend error occurred. | Retry only if the operation is safe; contact support if persistent. |
| 503 | `backend_unavailable` | `Backend unavailable` | No eligible database backend is currently available. | Retry with bounded exponential backoff and jitter. |
| 503 | `rate_limit_unavailable` | `tenant rate limit is unavailable` | The gateway cannot make a safe rate-limit decision. | Retry with bounded exponential backoff and jitter. |
The text in `msg` can include request-specific details. The `error` values and
HTTP statuses above are the compatibility surface.
## SDK access
Official SDKs decode `error` and `msg` into separate stable-code and diagnostic
fields. Non-JSON responses from older endpoints and intermediaries remain
available as readable diagnostics. Rust and TypeScript also retain the raw
response body separately.
| SDK | HTTP status | Stable code | Diagnostic | Raw response |
| ---------- | --------------------------- | --------------------------- | ------------------------------ | --------------------------------- |
| Rust | `HelixError::status_code()` | `HelixError::remote_code()` | `HelixError::remote_message()` | `HelixError::raw_response_body()` |
| TypeScript | `HelixError.statusCode` | `HelixError.code` | `HelixError.serverMessage` | `HelixError.rawBody` |
| Python | `HelixError.status_code` | `HelixError.code` | `HelixError.details` | Not exposed separately |
| Go | `HelixError.StatusCode` | `HelixError.Code` | `HelixError.Details` | Not exposed separately |
The current SDK error objects do not expose response headers, including
`Retry-After`. Use direct HTTP or an application transport that retains headers
when the exact Cloud rate-limit delay is required.
Branch on the stable code while retaining the diagnostic:
```rust Rust
if let Err(error) = client.query::(request).send().await {
if error.remote_code() == Some("query_timeout") {
eprintln!("{}", error.remote_message().unwrap_or("query timed out"));
}
}
```
```ts TypeScript
import { HelixError } from "@helix-db/helix-db";
try {
await client.query(request).send();
} catch (cause) {
if (cause instanceof HelixError && cause.code === "query_timeout") {
console.error(cause.serverMessage);
}
throw cause;
}
```
```python Python
try:
client.query(request)
except HelixError as error:
if error.code == "query_timeout":
print(error.details)
```
```go Go
err := client.Exec(ctx, request, &response)
var helixErr *helix.HelixError
if errors.As(err, &helixErr) &&
helixErr.Code == helix.QueryErrorCode("query_timeout") {
log.Print(helixErr.Details)
}
```
```json JSON
{
"error": "query_timeout",
"msg": "query exceeded its wall-clock limit"
}
```
## Timed-out writes
An HTTP `408` cancels the gateway's wait, but a write can race with durable
commit. Treat the outcome as unknown. Reconcile using an application identity or
idempotency key before submitting the write again.
## Migration from the previous shape
Some earlier responses used `error` for diagnostic text and `code` for the
machine-readable value, while others returned only `error`. For Cloud gateway
responses, migrate from this shape:
```json
{
"error": "query exceeded its wall-clock limit",
"code": "QUERY_TIMEOUT"
}
```
to `error` as the lower-snake-case code and `msg` as diagnostic text. Keep a
readable diagnostic fallback for intermediaries and older self-hosted endpoints
that do not return the Cloud envelope.
# Troubleshoot HelixDB
Page type: Troubleshooting
Troubleshooting
Start with the first error returned by the SDK or server. HelixDB rejects invalid
requests and transactions instead of partially applying them.
For the stable Cloud response envelope and gateway code reference, see
[Error handling](/database/helix-cloud/operate/error-handling).
## Request uses the wrong AST shape
**Symptoms:** unknown variant errors, missing `query`, or a request containing
top-level step arrays.
**Fix:**
1. Prefer a current SDK builder.
2. Confirm the request uses `request_type`, `query_name`, and a `query.read` or
`query.write` batch.
3. Confirm every nested operation uses `root` or `input` and snake_case wire tags.
## Response is missing expected data
Only names listed in `returns` are present in the response. Confirm the traversal was
assigned with `varAs` or `var_as`, then add that name to `returning`.
If a ranked field such as `$distance` is needed after another traversal, project it
before leaving the hit stream.
## Index operation is blocked
Poll the receipt's `operation_id` and inspect `blocker_code`. Correct the source data
or coordination issue, then retry the same operation. Abort a constructing build when
you want cleanup instead of activation.
Do not create repeated definitions to work around a blocker:
`existing_operation` deliberately points callers at the durable in-flight operation.
## Vector dimension mismatch
The stored vector and query vector must have exactly the dimension declared by the
index. Check all three values:
- Index definition dimension
- Existing property arrays included by the backfill
- Runtime query vector
Malformed existing values block index activation; malformed query vectors fail the
request.
## Embedded runtime is unavailable
An `EmbeddedUnavailable` error means the embedded runtime package could not load for
the current environment. Reinstall the matching package or switch to
`Client.server(...)`.
Review the [embedded installation guide](/database/helix-db/start-here/local-development/embedded-database#install).
## Embedded reader rejects a request
A reader handle is read-only. Open a writer handle for mutations. Server-only request
options are also rejected in embedded mode because no routing gateway is present.
## Request returns HTTP 409
A conflict means the request could not commit against current transactional state.
Retry the entire idempotent transaction with bounded backoff. Do not retry only part of
a multi-mutation request.
For non-idempotent business actions, attach an application-level idempotency key or
read the latest state before deciding whether to resubmit.
## Request returns HTTP 429
`rate_limited` means the shared request bucket for the Cloud database has no
token available. The rejected query did not reach database execution.
Wait for the response's `Retry-After` interval before retrying. Add jitter when
many workers can wake together, and inspect aggregate traffic across every API
key and application instance that uses the database. All of them share the same
bucket.
See [Helix Cloud request rate limits](/database/helix-cloud/operate/limits#helix-cloud-request-rate-limits)
for the current plan limits and token-bucket behavior.
## Request returns `rate_limit_unavailable`
An HTTP `503` with `rate_limit_unavailable` means the gateway could not make a
safe distributed admission decision. It fails closed, so the query did not
reach database execution.
Retry with bounded exponential backoff and jitter. If the response persists,
check [HelixDB status](https://status.helix-db.com) and include the response code,
timestamp, and database identifier when contacting support.
## Local server cannot reach storage
For S3-compatible local storage:
1. Confirm the container can resolve the configured endpoint.
2. Confirm bucket, region, credentials, and HTTP allowance match the service.
3. Use the service name visible inside the container network, not a host-only alias.
4. Restart the local instance after changing storage environment variables.
See [local development](/database/helix-db/start-here/local-development/local-server).
## Still blocked?
Capture the SDK version, request JSON with secrets removed, complete error, operation
ID for lifecycle failures, and deployment mode. Include them when contacting
[founders@helix-db.com](mailto:founders@helix-db.com).
# Getting started with HelixDB CLI
Page type: Tutorial
Tutorial
## Local quickstart
macOS and Linux:
```bash
curl -sSL "https://install.helix-db.com" | bash
```
Windows PowerShell:
```powershell
irm https://raw.githubusercontent.com/HelixDB/helix-db/main/crates/cli/install.ps1 | iex
```
Then:
```bash
mkdir my-helix-app && cd my-helix-app
helix init local
helix start dev
helix query dev --file examples/request.json
helix stop dev
```
Local requests use the local auth-disabled runtime. The default storage is in-memory; use `--disk`
or an S3 storage URI when persistence is required. `helix chef` can automate local scaffolding and
agent setup without any Cloud login.
When `helix chef` launches an installed agent, it uses this priority order:
Claude Code → OpenAI Codex → OpenCode → Cursor Agent.
## Cloud quickstart
```bash
helix auth login
helix workspace list
helix project list --workspace-id
helix database list --project
helix project link
helix add cloud --name production --database tenant:
helix query production --file examples/request.json
```
Cloud commands use only the rotating WorkOS session. Query execution goes through the backend broker
and requires an independent `database.query.read` or `database.query.write` grant. The CLI does not
need a gateway URL, application key, service credential, or sync step.
If a command cannot derive one target, pass an explicit workspace/project or `cluster:` /
`tenant:`. Stable links live only in the current project's `helix.toml`.
Run and query a local instance
Use the session-authenticated Cloud CLI
See every retained command
Resolve common errors
# Local Development
Page type: Guide
Guide
Local development runs the prebuilt `ghcr.io/helixdb/helixdb:v0.0.4` container and exposes the standalone server at `POST /v2/query`. By default, storage is in-memory. Use `--disk` when you want persistent local data backed by a CLI-managed MinIO volume.
## Prerequisites
- **Docker** or **Podman** on `PATH`.
- The Helix CLI:
- macOS and Linux: `curl -sSL "https://install.helix-db.com" | bash`.
- Windows PowerShell: `irm https://raw.githubusercontent.com/HelixDB/helix-db/main/crates/cli/install.ps1 | iex`.
## Initial setup
For an agent-assisted first app, [`helix chef`](/cli/command-reference/chef) can run this setup end-to-end: it installs Helix skills and the docs MCP, initializes `~/my-first-helix-project`, starts `dev`, seeds starter data, and launches your coding agent to build the app.
```bash
helix chef
```
Use the manual flow below when you want to scaffold and run each step yourself.
```bash
mkdir my-helix-app
cd my-helix-app
helix init
```
`helix init` creates `helix.toml`, `.helix/`, and `examples/request.json`.
```bash
helix start dev
```
Starts a background container named `helix-my-helix-app-dev` on port `6969`. The CLI waits for `GET /healthz` to report ready before returning.
For attached log streaming use `helix start dev --foreground` and stop with Ctrl-C.
For persistent local storage use `helix start dev --disk`, or initialize the project with `helix init local --disk` to make disk mode the default for that instance.
```bash
helix query dev --file examples/request.json
```
The example counts `User` nodes. Try `--compact` to print on one line, or
`--warm` to populate the standalone process caches while returning the normal
response.
Default local storage is in-memory. `helix stop` or `helix restart` wipes in-memory data — keep your seed data in JSON request files so you can replay it, or use `--disk` for persistent local storage.
## Persistent local storage
```bash
# One-off disk mode for this run
helix start dev --disk
# Persist disk mode in helix.toml for a new local instance
helix add local --name persistent --disk
helix start persistent
```
Disk mode starts a MinIO sidecar, creates the `helix-db` bucket, and stores data in a Helix-managed Docker/Podman volume. `helix stop` removes the containers but keeps the volume. `helix prune ` removes the volume and deletes the persisted local data.
## Iteration loop
```bash
# Edit a request file (or write a new one)
$EDITOR examples/request.json
# Send the request
helix query dev --file examples/request.json
# Tail container logs in another shell
helix logs dev --follow
# Stop and restart from a clean state
helix restart dev
```
`helix restart` falls back to a fresh `helix start` if the container has been removed.
## Multiple local instances
```bash
# Add a second local instance on a different port
helix add local --name staging --port 9090
# Run them independently
helix start dev
helix start staging
# See what's running
helix status
```
Each instance is isolated by container name and host port. Disk-mode instances also get their own MinIO container, network, and volume.
## Inspecting logs
```bash
helix logs dev # one-shot dump from docker/podman logs
helix logs dev --follow # stream
```
`--range`, `--start`, and `--end` are Helix Cloud-only and rejected for local instances.
## Cleaning up
| Goal | Command |
|------|---------|
| Stop one instance | `helix stop ` |
| Restart one instance | `helix restart ` |
| Remove containers, workspace state, and disk-mode volume for one instance | `helix prune ` |
| Remove everything Helix-owned, for every local instance | `helix prune --all` (`--yes` in non-TTY) |
| Permanently delete an instance from `helix.toml` | `helix delete ` (`--yes` in non-TTY) |
[`helix prune`](/cli/command-reference/prune) only touches Helix-managed containers (`helix--` and disk-mode MinIO sidecars), networks, volumes, and the per-instance `.helix/` directory. It never runs a broad `docker/podman system prune`.
## Authoring dynamic queries
A request JSON file must contain:
- `request_type`: lowercase `"read"` or `"write"`.
- `query_name` (optional): top-level operational name for logs and query diagnostics. Missing or
`null` falls back to `__dynamic__`.
- `query`: exactly one `read` or `write` batch with `entries[]` and `returns[]`.
- `parameters` and `parameter_types` (optional): named values and their declared types.
Each entry contains one nested operation-tree `root`; source operations appear at the
innermost input. See [`helix query`](/cli/command-reference/query) for the request shape.
## What next?
Authenticate, link a project, and query a remote cluster
Every command, subcommand, and flag
# Helix Cloud CLI workflow
Page type: Guide
Guide
```bash
helix auth login
helix auth status
```
```bash
helix workspace list
helix project list --workspace-id
helix database list --project
```
```bash
helix project link
helix add cloud --name production --database tenant:
```
```bash
helix query production --file request.json
helix shell production
```
The WorkOS session identifies the user. `database.query.read` or `database.query.write` independently
authorizes the selected database; project-management access does not imply query access. The backend
forwards the authorized request using the existing cluster-scoped operational gateway key and, for a
tenant database, the exact tenant header. The CLI never receives that key and never contacts the
gateway directly.
Owners/admins have both query scopes by default. Members have neither unless explicitly granted.
Local queries keep the current local auth-disabled path.
Use `helix database key` only to create application keys for direct gateway clients. Use
`helix service-credential` only to manage headless HTTP API credentials and credentials for a
separately deployed Admin MCP service. Neither is a CLI login method.
# CLI configuration
Page type: Reference
Reference
The CLI reads project configuration from `helix.toml` and its WorkOS session from
`~/.helix/credentials`. There is no user-global workspace selection file.
```toml
[project]
name = "example"
queries = "db"
container_runtime = "docker"
id = "project_123" # stable optional Cloud link
workspace_id = "ws_123" # stable optional Cloud link
[local.dev]
port = 6969
[enterprise.production]
database = "tenant:tenant_123"
project_id = "project_123" # optional stable link
workspace_id = "ws_123" # optional stable link
```
Cloud `database` accepts only `tenant:` or `cluster:`. A physical shared cluster is not a
database target. Unknown Cloud fields are rejected. In particular, gateway URLs, query auth headers,
query auth environment variables, source snapshots, sync metadata, and query bundles are invalid.
Target resolution uses an explicit flag first, then an explicit database reference, the linked
database, or the linked project only when exactly one database is eligible. Ambiguous commands print
candidates and require `--workspace`, `--project`, `cluster:`, or `tenant:`.
The strict credential file stores only `access_token`, rotating `refresh_token`, `expires_at`, and
`email`. It is written atomically with mode `0600`. Do not edit it or put application keys or service
credentials in it.
# CLI troubleshooting
Page type: Troubleshooting
Troubleshooting
## Authentication required
Run `helix auth login`. If an access token is near expiry, the CLI refreshes it through WFE while
holding the credential-file lock. Only a typed WFE rejection before handler dispatch can trigger one
refresh-and-retry. A normal authorization denial or any post-dispatch failure is not retried.
Old credential/config fields are intentionally rejected. Remove legacy user/admin keys, arbitrary
authorization headers, gateway URLs, and query-key fields. Service credentials and application keys
cannot be used to log the CLI in.
## Ambiguous Cloud target
Pass `--workspace`, `--project`, `cluster:`, or `tenant:`. Alternatively use
`helix project link` and `helix add cloud` to persist stable project/database linkage in `helix.toml`.
## Query permission denied
Project `read`/`write` does not grant database-data access. Ask an owner/admin to grant independent
`query_read` and, if required, `query_write` for the selected project. Members default to neither.
## Local connection refused
Run `helix start `, verify with `helix status `, or pass local-only `--host` and
`--port` overrides.
## Cloud logs
Cloud `--follow` is not supported. Use an RFC 3339 `--start`/`--end` range or omit both for the last
hour of query errors.
# CLI command reference
Page type: Reference
Reference
Cloud commands authenticate only with the WorkOS session created by `helix auth login`.
They never accept or store application database keys or service credentials.
| Command | Scope | Purpose |
| --- | --- | --- |
| [`helix auth`](/cli/command-reference/auth) | Cloud | Login, inspect, or revoke the WorkOS session |
| [`helix init`](/cli/command-reference/init) | Local, Cloud | Create a project and link an instance |
| [`helix add`](/cli/command-reference/add) | Local, Cloud | Add an instance to `helix.toml` |
| [`helix query`](/cli/command-reference/query) | Local, Cloud | Execute one v3 JSON/SDK query |
| [`helix shell`](/cli/command-reference/shell) | Local, Cloud | Execute line-oriented v3 JSON queries |
| [`helix status`](/cli/command-reference/status) | Local, Cloud | Inspect runtime or database status |
| [`helix logs`](/cli/command-reference/logs) | Local, Cloud | Follow local logs or list Cloud query errors |
| [`helix workspace`](/cli/command-reference/workspace) | Cloud | List or get workspaces; no global selection |
| [`helix project`](/cli/command-reference/project) | Cloud | List, get, create, delete, or link a project |
| [`helix cluster`](/cli/command-reference/cluster) | Cloud | List/get dedicated clusters and active indexes |
| [`helix database`](/cli/command-reference/database) | Cloud | Manage tenants, indexes, and application keys |
| [`helix service-credential`](/cli/command-reference/service-credential) | Cloud | Manage workspace-owned headless credentials |
| [`helix api`](/cli/command-reference/api) | Cloud | Call an authenticated `/v1/...` WFE endpoint |
| `helix start`, `stop`, `restart`, `prune`, `delete` | Local | Manage local instances and local configuration |
| `helix chef`, `skills`, `metrics`, `feedback`, `update` | Local CLI | Scaffolding and CLI utilities |
`push`, `sync`, `auth create-key`, `workspace switch`, and `project update` are not commands.
Cloud resource lifecycle is exposed only where documented above.
# helix add
Page type: Reference
Reference
```bash
helix add local --name dev [--port 6969] [--disk | --storage-uri s3://bucket/prefix]
helix add cloud --name production [--database tenant:|cluster:] \
[--project ] [--workspace ]
```
Cloud add uses the WorkOS session, verifies the selected database, and writes only stable IDs to
`helix.toml`. If a project has multiple eligible databases, pass `--database` explicitly.
# helix auth
Page type: Reference
Reference
```bash
helix auth login
helix auth status
helix auth logout
```
`login` starts WorkOS PKCE in a browser, receives the loopback callback, hydrates all current
workspace memberships, and stores only the rotating WorkOS session in `~/.helix/credentials`.
The CLI refreshes tokens within 60 seconds of expiry and serializes refreshes across processes.
`status` verifies the session and reports its user and membership count. `logout` asks WFE to
revoke the session when possible and always deletes the local file.
The credential file is mode `0600` and rejects old key fields. Cloud commands do not accept
environment API keys, service credentials, legacy user/admin keys, or custom authorization headers.
# helix api
Page type: Reference
Reference
```bash
helix api get /v1/workspaces
helix api post /v1/example --json '{"value":"example"}'
helix api patch /v1/example --json '{"value":"updated"}'
helix api delete /v1/example
```
Only absolute `/v1/...` WFE paths are accepted. Absolute URLs and direct gateway paths are rejected.
The command uses the same rotating WorkOS session and typed pre-dispatch authentication retry rule as
all other Cloud commands. Use resource-specific commands when one exists.
# helix chef
Page type: Reference
Reference
Bootstrap a first HelixDB app for a coding agent. `helix chef` installs agent context, scaffolds a local project, starts the local database, seeds starter data, writes a build prompt, and launches your coding agent to generate the app.
## Usage
```bash
helix chef
```
`helix cook` is an alias for `helix chef`. The command takes no flags — it is fully interactive (and falls back to sensible defaults when run without a TTY).
`helix chef` uses `npx`, so **Node.js/npm must be on `PATH`** for the skills and docs-MCP install, and it needs **Docker or Podman running** to start the local database. It is intended for local development inside a coding-agent environment.
## Authentication
`helix chef` is a local workflow and does not require Cloud authentication. It neither uploads a
project snapshot nor reads Cloud credentials. Use `helix auth login` separately only when you later
run a Cloud command.
## What it does
1. Installs the Helix skills (`npx skills add HelixDB/skills`) and docs MCP.
2. Initializes a local project (`helix init local`) with a `dev` instance on port `6969`, then starts it in-memory.
3. Writes `HELIX_CHEF_PROMPT.md` (your build intent, or a Personal CRM default) and, for the default build, starter query files under `examples/` — then seeds the data.
4. Detects an installed coding agent (Claude Code → OpenAI Codex → OpenCode → Cursor Agent), asks for a permission mode, and launches it against the build prompt.
5. Opens the generated app at `http://localhost:3000` once the agent's frontend is running.
`helix chef` does **not** start a local dashboard — port `3000` is reserved for the Next.js app the agent builds.
## Interactive mode
Running `helix chef` in a terminal prompts first for:
```text
What do you want to build?
```
Leave this blank to use the default Personal CRM build. If you provide an app idea, it is written into `HELIX_CHEF_PROMPT.md` and used to drive the agent.
Next, choose a setup mode:
| Mode | Behavior |
|------|----------|
| Automatic setup | Runs every setup step with defaults. |
| Manual setup | Lets you choose the project path and confirm each setup step. |
## Examples
```bash
# Interactive setup
helix chef
# Alias
helix cook
```
## Related
- [`helix init`](/cli/command-reference/init) — initialize a project without agent setup.
- [`helix start`](/cli/command-reference/start) — start a local instance.
- [`helix query`](/cli/command-reference/query) — send dynamic JSON requests.
# helix cluster
Page type: Reference
Reference
```bash
helix cluster list [--project-id | --workspace-id ] [--format human|json]
helix cluster get [--format human|json]
helix cluster indexes [--cluster-id ] [--format human|json]
```
The command uses explicit IDs or the current `helix.toml` link. It does not persist a workspace.
Dedicated-cluster create/delete, networking, regions/SKUs, branches, and backups are outside the CLI.
# helix database
Page type: Reference
Reference
Database targets use `cluster:` for a dedicated database or `tenant:` for a tenant.
Omit the target only when `helix.toml` links exactly one Cloud database.
```bash
helix database list --project
helix database get tenant:
helix database indexes tenant:
helix database create --project --name --slug --plan
helix database create --project --cluster --name --slug
helix database delete tenant: --yes
helix database key create tenant: --access read-only [--name ]
helix database key create tenant: --access read-write [--name ]
helix database key list tenant:
helix database key revoke tenant: --key --yes
```
Creating a database creates a default read-write application key and prints its raw token once. The
session-authenticated CLI never stores or uses it. Additional key creation is explicit, and each new
raw token is also printed once. Application keys are for software that calls the gateway directly.
Dedicated-cluster create/delete lifecycle is not supported by this CLI.
# helix delete
Page type: Reference
Reference
Delete an instance from `helix.toml` and clean up any local runtime state for it.
For local instances, Helix-owned containers, networks, disk-mode volumes, and the per-instance directory under `.helix/` are deleted. For Helix Cloud instances, only the `[enterprise.]` block in `helix.toml` is removed — the database itself is untouched.
## Usage
```bash
helix delete [OPTIONS]
```
## Arguments
| Argument | Description |
|----------|-------------|
| `INSTANCE` | Instance to delete. Required. |
## Available flags
| Flag | Type | Description |
|------|------|-------------|
| `-y`, `--yes` | Boolean | Skip confirmation prompts. Required in non-TTY environments. |
## Confirmation behavior
In a TTY, `helix delete` prints a warning and asks for confirmation. In non-TTY environments it refuses to run without `--yes`:
```
Refusing to delete '' non-interactively. Re-run with --yes to confirm.
```
## Examples
```bash
# Delete a local instance (TTY)
helix delete staging
# Delete non-interactively
helix delete staging --yes
```
# helix feedback
Page type: Reference
Reference
Send feedback to the Helix team.
## Usage
```bash
helix feedback [MESSAGE]
```
## Arguments
| Argument | Description |
|----------|-------------|
| `MESSAGE` | Feedback message. If omitted, the CLI prompts for one in a TTY. |
## Examples
```bash
# Send feedback inline
helix feedback "love the new dynamic query flow"
# Open an interactive prompt
helix feedback
```
# helix init
Page type: Reference
Reference
```bash
helix init local [--name dev] [--port 6969] [--disk | --storage-uri s3://bucket/prefix]
helix init cloud [--name production] [--database tenant:|cluster:] \
[--project ] [--workspace ]
```
Cloud init authenticates through the WorkOS session and resolves the database from explicit flags or
an unambiguous project. It stores stable linkage only. It has no gateway URL or query-auth options.
Use `--skills` or `--no-skills` to control agent-skill installation.
# helix logs
Page type: Reference
Reference
```bash
helix logs [INSTANCE] [--follow]
helix logs [CLOUD_INSTANCE] [--range] [--start ] [--end ]
```
Local logs use Docker/Podman and may follow. Cloud logs use the WorkOS session and the linked
database's recent query-error WFE endpoint; they never contact the gateway. Cloud follow is not
supported. Without explicit times, the Cloud range is the last hour.
# helix metrics
Page type: Reference
Reference
Configure CLI telemetry and usage metrics collection. Settings are stored in the per-user metrics config.
## Usage
```bash
helix metrics
```
## Available sub-commands
| Sub-command | Description |
|-------------|-------------|
| `full` | Enable full metrics collection (prompts for an email address). |
| `basic` | Enable minimal anonymous metrics. |
| `off` | Disable all metrics collection. |
| `status` | Show current metrics configuration and when it was last updated. |
## `helix metrics status` output
`status` prints the metrics level, your user ID (if logged in), and a relative `Last updated` time:
| Age | Format |
|-----|--------|
| 0–4 seconds | `just now` |
| 5–59 seconds | `s ago` |
| 1–59 minutes | `m ago` |
| 1–23 hours | `h ago` |
| 1+ days | `d ago` |
## Examples
```bash
# Enable full metrics (prompts for email)
helix metrics full
# Enable anonymous basic metrics
helix metrics basic
# Disable all metrics
helix metrics off
# Show current state
helix metrics status
```
# helix project
Page type: Reference
Reference
```bash
helix project list --workspace-id [--format human|json]
helix project get [] [--format human|json]
helix project create --workspace --slug --name
helix project delete [] [--yes]
helix project link [--workspace ]
```
`link` persists the stable project/workspace IDs only in the current project's `helix.toml`.
It does not create global selection state. `project update` is not supported.
# helix prune
Page type: Reference
Reference
Remove Helix-owned local containers, networks, disk-mode volumes, and per-instance workspace state.
`helix prune` only touches resources the CLI manages:
- The container named `helix--`.
- The disk-mode MinIO sidecar, network, and persistent volume when present.
- The per-instance directory under `.helix/`.
It never runs a broad `docker system prune` or `podman system prune`.
## Usage
```bash
helix prune [INSTANCE] [OPTIONS]
```
## Arguments
| Argument | Description |
|----------|-------------|
| `INSTANCE` | Local instance to prune. If omitted, the CLI prompts in a TTY or requires `--all`. |
## Available flags
| Flag | Type | Description |
|------|------|-------------|
| `-a`, `--all` | Boolean | Prune every local instance in the project. |
| `-y`, `--yes` | Boolean | Skip confirmation prompts. Required with `--all` in non-TTY environments. |
## Confirmation behavior
- `helix prune ` removes resources without confirmation, including persisted disk-mode data.
- `helix prune --all` prints a warning and asks for confirmation in a TTY. In non-TTY environments, it refuses to run without `--yes`:
```
Refusing to prune all instances non-interactively. Re-run with --yes to confirm.
```
If nothing was found to prune for an instance, the CLI prints `No local runtime resources found for ''` and exits successfully.
## Examples
```bash
# Prune a specific instance
helix prune dev
# Interactive selection (TTY)
helix prune
# Prune everything Helix-owned for every local instance
helix prune --all
# Same, non-interactively
helix prune --all --yes
```
# helix query
Page type: Reference
Reference
```bash
helix query [INSTANCE] --file [--compact]
helix query [INSTANCE] --json '' [--compact]
helix query [INSTANCE] -e '' [--compact]
helix query [INSTANCE] --ts-file [--compact]
```
Exactly one input is required. The envelope must include lowercase `request_type` (`read` or `write`)
and `query`. Query bundles are not supported.
Local queries post to the auth-disabled local `/v2/query`; `--host`, `--port`, and read-only `--warm`
are local options. With no target, the CLI uses local `dev` or the sole linked instance; ambiguous
projects must specify an instance or an explicit `tenant:` / `cluster:`. Cloud queries use the
WorkOS session:
- `read` uses the backend read-query RPC and requires `database.query.read`.
- `write` uses the backend write-query RPC and requires `database.query.write`.
- The backend rejects an operation/envelope mismatch before gateway dispatch.
- No database key, custom auth header, or direct gateway URL is accepted.
- A mutation is never retried after dispatch, timeout, or ambiguous transport failure.
Cloud query bodies, parameters, results, operational gateway authorization, and credentials are not
logged by the broker.
# helix restart
Page type: Reference
Reference
Restart a background local instance. If the container still exists, it is restarted in place. If the container has been removed (for example after `helix prune`), `helix restart` falls back to a fresh [`helix start`](/cli/command-reference/start).
Default local data is in-memory and is wiped by every restart. Disk-mode instances preserve data in their local MinIO volume.
## Usage
```bash
helix restart [INSTANCE]
```
## Arguments
| Argument | Description |
|----------|-------------|
| `INSTANCE` | Local instance to restart. If omitted in a TTY with multiple instances, the CLI prompts. Defaults to `dev` when present. |
## Examples
```bash
# Restart the default 'dev' instance
helix restart dev
# Restart with interactive picker
helix restart
```
# helix skills
Page type: Reference
Reference
Install, refresh, and inspect the Helix agent skills — the query-authoring skills
(`helix-query-typescript`, `helix-query-rust`, `helix-memory-system`, and friends) that
coding agents like Claude Code use to write correct HelixDB queries. They are installed
with the [`skills`](https://github.com/vercel-labs/skills) CLI under the hood
(`npx skills add HelixDB/skills`), so this command requires **Node.js/npm** (`npx`) on your PATH.
`helix init` and `helix chef` install these skills for you; `helix skills` is how you
manage them afterwards. They install **globally** by default (`~/.agents/skills`, shared
across projects) — pass `--project` to operate on the current project instead.
## Usage
```bash
helix skills
```
## Available sub-commands
| Sub-command | Description |
|-------------|-------------|
| `install` | Install the Helix agent skills (interactive). |
| `update` | Refresh installed Helix skills to the latest version. |
| `list` | List installed agent skills. |
## Available flags
| Flag | Type | Description | Default |
|------|------|-------------|---------|
| `--project` | Boolean | Operate on the current project (`./skills`) instead of globally. | Global |
`helix skills update` re-fetches the skills from source and **overwrites** their files,
so any local edits to the installed skills are discarded.
## Update notifications
When skills are installed, the CLI checks once every 24 hours (the same cadence and
`HELIX_NO_UPDATE_CHECK` opt-out as the CLI version check) whether the Helix skills are out
of date, and prints a one-line notice pointing you at `helix skills update`. It is
**notify-only** — it never rewrites skill files on a routine command. Running
[`helix update`](/cli/command-reference/update) also refreshes installed skills.
## Examples
```bash
# Install the Helix skills globally
helix skills install
# Refresh installed skills to the latest version
helix skills update
# Install into the current project instead of globally
helix skills install --project
# List installed skills
helix skills list
```
# helix start
Page type: Reference
Reference
Start a local instance. By default the container starts in the background and the CLI waits for `GET /healthz` to report ready before returning.
`helix run` is a backwards-compatible alias for `helix start`.
## Usage
```bash
helix start [INSTANCE] [OPTIONS]
```
## Arguments
| Argument | Description |
|----------|-------------|
| `INSTANCE` | Local instance name from `helix.toml`. If omitted, defaults to `dev` when present, otherwise prompts in a TTY or fails if non-interactive. |
## Available flags
| Flag | Type | Description | Default |
|------|------|-------------|---------|
| `--foreground` | Boolean | Run attached and stop the container on Ctrl-C. Useful for streaming startup logs. | `false` |
| `--port` | Number | Override the host port for this run. The container always listens on `8080` internally. | Value from `[local.] port` (default `6969`) |
| `--disk` | Boolean | Use on-disk storage backed by a CLI-managed MinIO container for this run. | `false` |
| `--persist` | Boolean | Write the resolved port and storage settings for this run back to `[local.]` in `helix.toml`, so future runs reuse them. | `false` |
## Behavior
- Pulls `ghcr.io/helixdb/helixdb:v0.0.4` (or the image/tag set in `[local.]`).
- Names the container `helix--` and publishes the configured port to container port `8080`.
- Uses Docker or Podman based on `[project] container_runtime` in `helix.toml`.
- Default storage is in-memory. Passing `--disk` starts a MinIO sidecar, creates the `helix-db` bucket, and runs `helixdb` with S3-compatible storage environment variables.
- Background mode (`-d`, `--restart unless-stopped`) waits up to ~30 seconds for `GET /healthz` readiness and prints the URL and container name when ready.
- Foreground mode (`--rm`) streams the container's stdout/stderr until Ctrl-C, then removes the container.
The default `helixdb` storage mode is in-memory. Stopping or restarting an in-memory instance wipes all local data.
With `--disk`, `helix stop` removes the Helix and MinIO containers but keeps the persistent local volume. `helix prune` removes that volume and deletes the persisted local data.
## Examples
```bash
# Start the default 'dev' instance in the background
helix start
# Start a named instance in the background
helix start staging
# Stream logs in the foreground; Ctrl-C stops the container
helix start dev --foreground
# Override the host port for this run only
helix start dev --port 9090
# Start with persistent local storage for this run
helix start dev --disk
# Start on a new port and save it to helix.toml for future runs
helix start dev --port 9090 --persist
```
## Related
- [`helix stop`](/cli/command-reference/stop) — stop a background instance
- [`helix restart`](/cli/command-reference/restart) — restart a background instance
- [`helix query`](/cli/command-reference/query) — send a dynamic query to a running instance
- [`helix logs`](/cli/command-reference/logs) — view container logs
# helix status
Page type: Reference
Reference
```bash
helix status [INSTANCE]
```
Local status comes from the configured Docker/Podman runtime. Cloud status uses the WorkOS session
and fetches the linked tenant or dedicated cluster; cluster status also includes current topology.
# helix stop
Page type: Reference
Reference
Stop a background local instance and remove its containers.
`helix stop` is idempotent — if the instance is not running, the CLI exits successfully without error.
For disk-mode instances, `helix stop` removes the Helix and MinIO containers but keeps the persistent local volume. Use [`helix prune`](/cli/command-reference/prune) to delete disk-mode data.
## Usage
```bash
helix stop [INSTANCE]
```
## Arguments
| Argument | Description |
|----------|-------------|
| `INSTANCE` | Local instance to stop. If omitted in a TTY with multiple instances, the CLI prompts. Defaults to `dev` when present. |
## Examples
```bash
# Stop the default 'dev' instance
helix stop dev
# Stop with interactive picker
helix stop
# Safe to call in scripts even if the instance is already stopped
helix stop staging || true
```
## Related
- [`helix start`](/cli/command-reference/start) — start a local instance
- [`helix restart`](/cli/command-reference/restart) — restart a local instance
- [`helix prune`](/cli/command-reference/prune) — remove all Helix-owned local state for an instance
# helix service-credential
Page type: Reference
Reference
Owners and admins need the workspace-scoped `service_credentials.manage` permission.
```bash
helix service-credential create --workspace --name \
--grant =project-read,query-read [--expires-at ]
helix service-credential list --workspace
helix service-credential get --workspace
helix service-credential update --workspace \
[--name ] [--grant =query-read,query-write] \
[--expires-at | --clear-expiry]
helix service-credential revoke --workspace --yes
```
Each grant is project-scoped and must name a project inside the owning workspace. Available grants
are `project-read`, `project-write`, `query-read`, and `query-write`; write requires its matching read.
Creation displays the secret once. Updates never reveal or rotate it.
Service credentials authenticate headless HTTP API calls and, where deployed, the separate Admin MCP
service. They do not authenticate the public unified MCP endpoint. They are never a CLI login method
and the CLI never persists them.
# helix shell
Page type: Reference
Reference
```bash
helix shell [INSTANCE] [--compact]
```
Enter one complete v3 query request per line. Use `:quit` or `:exit` to stop. The request's
`request_type` selects read or write execution.
Local instances use the existing auth-disabled local endpoint. With no target, the CLI uses local
`dev` or the sole linked instance; ambiguous projects must specify an instance or an explicit
`tenant:` / `cluster:` reference. Cloud requests use the backend query broker and the current
WorkOS session; the CLI never contacts the Cloud gateway directly.
# helix update
Page type: Reference
Reference
Update the Helix CLI to the latest version. Use `--v1` to update to `v2.3.5`, the last CLI release for v1 projects.
If the [Helix agent skills](/cli/command-reference/skills) are installed, `helix update` also refreshes them to the latest version (a failure here degrades to a warning and never fails the CLI update). Separately, when skills are installed the CLI checks once every 24 hours whether they are out of date and prints a notice pointing you at `helix skills update`; set `HELIX_NO_UPDATE_CHECK=1` to opt out of both the CLI and skills checks.
## Usage
```bash
helix update [OPTIONS]
```
## Available flags
| Flag | Type | Description |
|------|------|-------------|
| `--force` | Boolean | Force update even if already on latest version |
| `--v1` | Boolean | Update to `v2.3.5`, the last CLI release for v1 projects |
## Examples
```bash
# Update to the latest version
helix update
# Force update
helix update --force
# Update to the last v1-compatible CLI release
helix update --v1
```
# helix workspace
Page type: Reference
Reference
```bash
helix workspace list [--format human|json]
helix workspace get [--format human|json]
```
The WorkOS session hydrates all current memberships. There is no `workspace switch` command and no
persisted active workspace. Pass `--workspace` or `--workspace-id` to a command that cannot derive an
unambiguous workspace from its linked project/database.
## Content
- [HelixDB Agent Content](https://www.helix-db.com/content): Technical guides about AI memory, GraphRAG, graph-vector databases, and building production AI systems with HelixDB.
### [Moving Off Memgraph: Migrating Agent Memory to HelixDB](https://www.helix-db.com/content/guides/moving-off-memgraph-migrating-agent-memory-to-helixdb)
Moving off Memgraph for agent memory? Audit your Cypher schema, export it cleanly, and rewrite retrieval so graph traversal, vector search and BM25 run in one query.
# Moving Off Memgraph: Migrating Agent Memory to HelixDB
Memgraph earned its reputation on real-time stream processing and high-frequency graph computation. If your workload involves sliding-window fraud detection over Kafka streams with a fixed-size dataset, keeping every node and relationship in memory makes sense.
Production agent memory is a completely different workload. Agent systems accumulate episodic context, conversation turns, entity graphs, and document embeddings over months. The dataset does not fit inside a fixed memory envelope; it expands continuously as users converse with your system. In an in-memory engine, capacity and cost are the same dial. Object storage is priced in cents per GB per month; provisioned memory is priced in tens of dollars per GB per month. So cold episodic history and embeddings you touch once a week cost the same per gigabyte as the working set you query constantly.
This guide covers moving off Memgraph to [HelixDB](https://www.helix-db.com/content/compare/helixdb-vs-memgraph-which-graph-database-for-ai-memory), an open-source graph-vector database written in Rust. You will audit your existing Cypher schema, map node labels and edge properties to HelixDB, export your data cleanly, and rewrite Cypher retrieval as JSON queries where the graph traversal and the vector search happen in one call.
## Should You Actually Move Off Memgraph?
Start here, because for a real share of readers the answer is no. If you are running sliding-window computation over Kafka streams, or graph algorithms on a working set you can size, Memgraph is built for that and does it well, and nothing below is an argument for moving.
Memgraph is a C++ in-memory engine with ACID transactions and on-disk persistence, and their Community edition is free, open source and described on their own pricing page as production-ready. It ships Cypher, stream connectors for Kafka, Pulsar and Redpanda, vector search, the MAGE algorithm library, and high-availability replication with unlimited replicas at no extra licence cost. Automatic failover is the line that moves you to Enterprise. None of that is the problem here.
The problem is where the bytes live. Push millions of episodic turns, summary nodes and 1536-dimension embeddings into an in-memory graph and every gigabyte you keep is a gigabyte of provisioned host RAM. Read throughput has the same shape, because each replica you add for concurrency holds another full copy of the graph.
One caveat worth stating plainly, because it cuts against the obvious version of this argument: Memgraph now prices an Enterprise AI Platform tier on graph data alone, and says vector indexes are unlimited and do not count toward that licence. So if embeddings are the bulk of what you store, their pricing already answers that. What it does not change is the graph itself, which stays resident in memory and priced on memory. Agent memory is graph-heavy, entities and relationships and episodes and timestamps, not only vectors, and that half is what grows with every user you add.
Much of this episodic interaction data quickly goes cold. With a pure in-memory architecture, you pay top-tier cloud RAM pricing for dead context simply because it lives in the same graph traversal index. Compensating by offloading vectors to a dedicated vector store like Pinecone or Milvus creates exactly the multi-database plumbing problem engineering teams try to avoid. You end up synchronizing two databases over network calls, reconciling state, and chasing split-brain consistency bugs.
HelixDB solves this workload mismatch by decoupling storage tiers. Built from scratch in Rust, HelixDB stores graph topology, vector embeddings, key-value data, and document stores within a unified OLTP engine. In Helix Cloud, the architecture separates compute and persistent object storage with SSD caching on reader and writer nodes. You get low-latency graph traversals over hot working memory without keeping two years of inactive agent conversations resident in expensive RAM. Capacity, concurrency, and retrieval latency become independent operational dials rather than coupled constraints.
## What Does Your Memgraph Side Actually Look Like?
Do not start writing migration scripts until you have mapped every query pattern your agent framework executes. Most engineering teams using Memgraph for [AI agent memory](https://www.helix-db.com/content/guides/how-to-give-ai-agents-persistent-memory-in-one-database) run three distinct retrieval operations: entity resolution, conversational k-hop expansion, and semantic recall over interaction history.
Connect to your Memgraph instance using mgconsole and inspect your existing label indexes and constraints:
```cypher
SHOW INDEX INFO;
SHOW CONSTRAINT INFO;
```
Take note of properties indexed for lookup. Common agent schemas index User(id), Session(id), and Entity(name). Next, profile your most frequent read queries. In Memgraph, an agent loading context for a user typically executes a Cypher pattern like:
```cypher
MATCH (u:User {id: $user_id})-[:HAS_SESSION]->(s:Session)
MATCH (s)-[:CONTAINS_TURN]->(t:Turn)-[:MENTIONS]->(e:Entity)
RETURN e.name, e.summary, t.content
ORDER BY t.timestamp DESC LIMIT 20;
```
And get the embedding dimension before you create anything on the target side, because the index has to match it exactly:
```cypher
MATCH (m:MemoryNode) WHERE m.embedding IS NOT NULL
RETURN size(m.embedding) AS dim, count(*) AS n
ORDER BY n DESC LIMIT 5;
```
Identify where you bolted on vector similarity. If you used Memgraph vector search modules or maintained a foreign key pointer to an external vector database, catalog the embedding dimensionality and metric (cosine, Euclidean, or dot product).
Next, audit write throughput. Calculate the average writes per conversation turn. A standard agent turn writes one Turn node, two to five MENTIONS edges, and updates entity state properties. HelixDB handles both graph mutations and vector insertions in the same transaction over HTTP via its /v2/query endpoint, which makes write reconciliation simpler than managing out-of-band vector updates.
## What Maps Across Unchanged, and What Does Not?
Memgraph uses the property graph model: labeled nodes, directed relationships with types, and key-value properties on both. HelixDB natively implements an open-source OLTP graph-vector model in Rust, so your core entities translate cleanly without structural distortion.
Here is the direct mapping:
First, Node Labels become HelixDB node collections or labels. A Memgraph :User or :AgentMemory node maps directly to a node with equivalent label identifiers in HelixDB.
Second, Relationship Types translate directly into HelixDB directed edges. A [:RECALLS] or [:OBSERVED] relationship retains its direction and edge-level properties.
Third, embedding properties stay properties. Vectors in HelixDB are numeric array properties on nodes and edges, exactly as they are in Memgraph, so the data model maps across unchanged. The difference is where the index lives: Memgraph holds it in memory with the rest of the graph, while HelixDB tiers it across memory, disk and object storage.
Fourth, timestamps stay timestamps. You model history with timestamped nodes and edges exactly as you do now, and the range index is what makes reading it back cheap: gt, gte, lt, lte and between, plus ordered scans in either direction, so "the last twenty turns" is a descending scan you can stop early.
If your Memgraph schema has a User node connected via an OWNS edge to a MemoryNode containing a raw text block, a created_at timestamp, and an embedding vector, that translates directly to HelixDB. In HelixDB, this maps to a graph node for User, an edge OWNS, and a target node MemoryNode containing raw text, metadata properties, and the vector embedding attached directly to the node record. You eliminate external reference IDs and the synchronization glue code required when juggling disconnected stores.
## How Do You Get the Data Out and Load It Without Duplicating on a Retry?
Exporting data from Memgraph can be handled via Cypher CSV dumps or JSON exports using the mgclient Python driver. For high-volume agent memory, avoid single-file JSON dumps that consume massive process memory. Stream your data in batches of 5,000 to 10,000 nodes using Python.
Extract nodes and relationships into structured payloads:
```python
import mgclient
conn = mgclient.connect(host='127.0.0.1', port=7687)
cursor = conn.cursor()
# Label-scoped and ordered by a stable business key, so the export is
# reproducible and resumable rather than one giant unordered scan.
cursor.execute('''
MATCH (n:MemoryNode)
RETURN n.uid AS uid, labels(n) AS labels, properties(n) AS props
ORDER BY n.uid
''')
nodes = cursor.fetchall()
```
Transform the extracted records into HelixDB mutation payloads. HelixDB accepts JSON queries sent to /v2/query, built with native SDK builders that run inside your own application code. There are SDKs for TypeScript, Rust, Go and Python, so you write the query in the language you already ship. The builders serialise to JSON and the database turns that JSON into the query it runs, so there is no query language to learn and nothing to generate ahead of time.
Construct your batch creation payload with operations specifying the target label, properties, and attached vector array. Then send the payload as a JSON POST request to http://localhost:6969/v2/query on a local instance.
Do not carry Memgraph's internal ids across. They are not stable across a restore, so key everything on business ids you control and put a stable relationshipId property on every edge so a replayed batch can find and replace the right one.
Create your indexes before any data lands. Index creation is a write query rather than a client method, and it is asynchronous: the request returning does not mean the index is ready.
```typescript
import { writeBatch, g, VectorDistanceMetric } from "@helix-db/helix-db";
// Dimension must match what your Memgraph audit reported.
const createIndex = writeBatch()
.varAs("index", g().createVectorIndexNodes("MemoryNode", "embedding", 1536, VectorDistanceMetric.Cosine, null))
.returning(["index"]);
```
Then poll the index operation until every status reads succeeded, and stop on blocked, aborted or timeout rather than starting node batches on a half-built index.
Then run node insertion first and edges in a second pass. One request is one transaction, so if a batch comes back 409 you retry the whole batch rather than the failed row, and shaping the load as an idempotent upsert keyed on your business id is what makes that retry safe instead of duplicating.
```typescript
import {
BatchCondition,
g,
NodeRef,
SourcePredicate,
writeBatch,
} from "@helix-db/helix-db";
// Second pass: both endpoints were written in the first pass, so look them up
// by business id rather than creating them again, and only write the edge if
// the lookup actually found them.
// One exported record from the batch you streamed out of Memgraph.
const row = batch[i];
const loadEdges = writeBatch()
.varAs(
"user",
g().nWithLabelWhere("User", SourcePredicate.eq("uid", row.userUid)).limit(1),
)
.varAs(
"memory",
g()
.nWithLabelWhere("MemoryNode", SourcePredicate.eq("uid", row.memoryUid))
.limit(1),
)
.varAsIf(
"edge",
BatchCondition.varNotEmpty("user"),
g().n(NodeRef.var("user")).addE("OWNS", NodeRef.var("memory"), {
relationshipId: row.relId,
occurredAt: row.createdAt,
}),
)
.returning(["user", "memory", "edge"]);
```
The guard matters more on a migration than anywhere else, because a load script runs unattended over hundreds of thousands of rows. `nWithLabelWhere` returns a stream, not a promise of exactly one row, so a missing endpoint makes `addE` a no-op that reports success. Without the uniqueness indexes from step 3 on `User.uid` and `MemoryNode.uid`, a duplicate endpoint writes duplicate edges instead. Have the loader treat an empty `edge` binding as a row to re-queue rather than a row that landed: a request that returns HTTP 200 having created nothing is exactly the failure that shows up later as missing relationships nobody can account for.
## How Do You Rewrite Retrieval So Graph, Vector and Full-Text Run in One Query?
The biggest win when moving off Memgraph is query unification. In Memgraph, combining semantic vector similarity with multi-hop neighborhood traversal often means executing an approximate nearest neighbor lookup, collecting IDs, and then piping those IDs into Cypher match clauses. If you also need full-text search, you have to query an auxiliary service.
HelixDB unifies vector similarity search, graph traversal, and native full-text search in a single dynamic JSON query. Instead of writing fragmented queries across multiple engines, you express the full retrieval pipeline in one JSON query against /v2/query.
Consider an agent query that must find semantically similar memory chunks inside one user's relationship graph. You start at the User node, walk out to what they own, and rank only those:
```typescript
import { SourcePredicate, defineParams, g, param, readBatch } from "@helix-db/helix-db";
const params = defineParams({
user_uid: param.string(),
query_vector: param.array(param.f32()),
limit: param.i64(),
});
// Traversal first: the User walk decides which vectors are eligible at all.
const query = readBatch()
.varAs(
"matches",
g()
.nWithLabelWhere("User", SourcePredicate.eq("uid", params.user_uid))
.out("OWNS")
.vectorSearchWith("MemoryNode", "embedding", params.query_vector, params.limit)
.valueMap(["$id", "body", "occurredAt", "$distance"]),
)
.returning(["matches"]);
const request = query.toQueryRequest(
params,
{ user_uid: "u_8814", query_vector: embedding, limit: 10n },
{ queryName: "recallForUser" },
);
```
The order matters, and it is the opposite of the pattern you are moving away from. The traversal runs first and produces a candidate stream; membership of that stream is exact and authoritative, so a result outside it cannot come back. Vector ranking then runs over those candidates and returns the top k. Full-text chains on the same way with BM25 scores, which means a hybrid query is scoped once and both halves respect the scope.
Two honest caveats. Exact membership does not mean the engine compares every candidate embedding one by one; approximate structures still do the ranking, and the output is validated against the traversal set. And a scoped search can return fewer than k rows, bounded by how many unique candidates the traversal produced. That is the guarantee working, not a bug.
Compare that with searching a whole label and filtering afterwards. The high scorers you then discard have already consumed your top k, so asking for the ten closest memories across fifty thousand and then keeping only this user's can leave you with two results, or none.
## How Do You Validate and Cut Over Without Risking Live Agent State?
Never perform a hard cutover on production agent state. Run a dark-launch phase where your application layer writes to both Memgraph and HelixDB in parallel.
Set up a dual-write interceptor in your agent's memory persistence layer. Every time an agent records an interaction turn or creates an episodic entity, send the write to both databases asynchronously. Direct your read path through a shadow comparator: execute the primary retrieval query on Memgraph and mirror the query to HelixDB. Log execution latency, memory footprint, and recall accuracy.
Verify retrieval quality by comparing the top-k entities returned to the agent prompt. If your Memgraph setup relied on separate BM25 text indices, test HelixDB's native full-text search alongside vector recall.
One thing to be precise about while you validate: scoping a search to a traversal is a retrieval mechanism, not an authorization boundary. It changes which candidates are eligible, and it is not a substitute for access control in your application layer. Keep whatever authorization you have today.
Once shadow validation runs error-free for 72 hours, switch your production read traffic to HelixDB. Monitor your application gateway for latency spikes. With the read and write paths transferred, shut down your Memgraph cluster and release the provisioned RAM instances. The reduction in operational complexity and compute spend will be immediate.
## Conclusion
Agent memory does not behave like a streaming analytics pipeline. If your working set is bounded and you are doing real-time computation over it, Memgraph is the right tool and this migration is not for you. The case for moving is narrower than a cost comparison: it is that an unbounded, mostly-cold knowledge graph keeps growing against a dial where capacity and memory are the same number.
Moving that workload to HelixDB puts graph traversal, vector search and full-text retrieval in one Rust engine, over storage that tiers across memory, disk and object storage. The retrieval win is the part that survives any pricing change on either side: scope the traversal once, and both the vector and the full-text halves rank only what that traversal already decided was eligible.
Run `helix init` and then `helix start dev` to get a local instance up, or spin one up on Helix Cloud. Storage is a startup flag rather than a product tier, so the same engine and the same SDK calls run fully in memory, on disk, or against S3-compatible object storage, and your application code does not change when you move between them.
If this is the shape of problem you are working on, [star HelixDB on GitHub](https://github.com/HelixDB/helix-db).
### [Semantic Search Over Internal Documents Is Not Enough](https://www.helix-db.com/content/semantic-search-over-internal-documents-is-not-enough)
Semantic search over internal documents misses answers that live in a relationship rather than a chunk. Here is what a graph-vector engine does instead.
# Semantic Search Over Internal Documents Is Not Enough
A developer at a mid-sized tech company ships a RAG assistant intended to be the new company brain. They index thousands of pages from Notion, Jira, and Slack into a vector database. On day one, a senior engineer asks, Who is currently responsible for the database migration project? The assistant returns a three-paragraph summary of what the migration is, but it fails to name a person. The semantic search found the project overview doc, but it missed the Slack thread where the lead was assigned three days ago because the vector similarity score for that thread was slightly lower than the doc.
This failure is not about bad embeddings or poor chunking strategies. It is a fundamental architectural mismatch. Internal knowledge is not a collection of isolated text snippets. It is a dense web of relationships between people, projects, codebases, and shifting priorities. Semantic search over internal documents fails because it ignores the edges between these entities. When the answer to a query lives in the relationship between two nodes rather than inside a single text chunk, naive vector search hits a ceiling that no amount of prompt engineering can fix.
## Why Internal Knowledge Disappoints Vector Search (And It's Not the Embeddings)
Most developers assume that if their RAG system hallucinates or misses context, they need a better embedding model or a more complex chunking strategy. They swap an older embedding model for something newer from OpenAI, Cohere or Voyage. They try recursive character splitting and small-to-big retrieval. It helps at the margin. The core problem stays. Internal data is fundamentally different from the public internet data these models were trained on. Public data is often self-contained. A Wikipedia article about a historical event usually contains the necessary context within its own borders.
Internal documents are different. They are highly fragmented and depend on outside context. A technical specification doc might refer to a project by a code name like Project X, while the budget spreadsheet calls it the Q3 Infrastructure Initiative. Semantic search over internal documents treats these as two distinct clusters in vector space. Unless the text explicitly links them, the vector engine sees no connection. This leads to the orphaned chunk problem. The retriever finds a relevant piece of information but lacks the relational context to verify if it is still true or who wrote it. You are not searching for similar text. You are searching for facts distributed across a graph of dependencies. A vector database is a point lookup tool in a world that requires pathfinding. This is why [AI agent memory architecture](https://www.helix-db.com/content/ai-agent-memory-architecture-why-vector-search-is-not-enough) must move beyond simple embeddings.
## What Happens When the Answer Lives in an Edge, Not a Chunk?
Consider the query, Which services will be affected if we deprecate the legacy auth module? To answer this, an AI agent must identify the legacy auth module, find its dependencies, look up the teams that own those dependencies, and check their current project status. This is a multi-step traversal. In a standard vector setup, the LLM has to perform multiple round trips to the database. It searches for auth module, then searches for services using auth, then searches for teams. Each step introduces noise and increases the chance of a retrieval failure.
The real answer lives in the edges. In a graph-vector database like HelixDB, the auth module is a node. The services are other nodes. The relationship between them is an edge labeled DEPENDS_ON. Finding the affected services is a graph traversal, so it returns the same answer every time instead of the closest thing it could find. Relying on semantic similarity to find dependencies is a gamble. Two services might be semantically similar (both are Go microservices) but have zero functional relationship. Conversely, a frontend dashboard and a backend database might be semantically distant but tightly coupled. Vector search cannot distinguish between similarity and relationship. When you treat internal knowledge as a flat list of vectors, you lose the logical structure that makes the information useful to a human engineer.
## How Do You Search When One Person Has Four Different Names?
Internal knowledge is plagued by the entity aliasing problem. A single person might be David Miller in the HR system, d.miller on GitHub, Dave in a Slack thread, and user_882 in the production logs. A vector search for David Miller will likely miss a critical bug report where he was tagged as Dave. Cross-encoder models and re-ranking can help, but they still rely on the initial retrieval set being accurate. If the top 20 chunks do not contain the alias, the re-ranker is useless.
Graphs solve this by resolving those identities to one entity node. The aliases, emails and handles become properties on that node, or their own Identity nodes hanging off it by an ALIAS_OF edge, and the mentions become edges from the systems they came from:
```typescript
import {
BatchCondition, g, writeBatch, NodeRef, SourcePredicate,
} from "@helix-db/helix-db";
const link = writeBatch()
.varAs(
"person",
g()
.nWithLabelWhere("Person", SourcePredicate.eq("email", "david.miller@example.com"))
.limit(1),
)
.varAs("handle", g().addN("Identity", { system: "slack", value: "dave" }))
.varAsIf(
"edge",
BatchCondition.varNotEmpty("person"),
g().n(NodeRef.var("handle")).addE("ALIAS_OF", NodeRef.var("person"), {}),
)
.returning(["person", "handle", "edge"]);
```
That lookup is the part to get right, because the naive version fails quietly. `nWithLabelWhere` returns a stream, not a promise of exactly one row. If no Person matches that email, `addE` receives an empty source, succeeds without creating anything, and the Identity node still commits as an orphan. If two people share the email, you get two ALIAS_OF edges. Atomicity is not the thing protecting you here: one request is one transaction, and it will commit an unattached Identity quite happily, because "every alias belongs to exactly one person" is your invariant, not the engine's. So enforce it with a uniqueness index on the lookup property, `IndexSpec.nodeUniqueEquality("Person", "email")`, gate the edge with `varAsIf` on the lookup having found something, and return all three bindings so the caller can tell an attached alias from an orphaned one.
Resolve the alias once and every mention of that person is one hop away, whichever system wrote it. That is what stops the fragmented recall a chunk-only pipeline produces, and it is what makes a scoped search possible later: once an entity is resolved, it is somewhere to start a traversal from.
## How Do You Stop an Agent Answering From a Superseded Document?
Internal document stores are messy. You likely have five versions of the same onboarding guide, three different API specs for the same service, and a dozen v2_final_final.pdf files. When an AI agent performs semantic search over internal documents, it often retrieves the most semantically relevant chunk, which might be from a document deprecated three years ago. Scoring by recency is a common hack, but it is a blunt instrument. A 2023 document about the company's core values might still be valid, while a 2026 document about a specific sprint goal is already obsolete.
Recency is not a global score. It is a property of the relationship between two documents. A document node can carry a SUPERSEDES edge pointing at the version it replaced, a validUntil timestamp, or a BELONGS_TO_SPRINT relationship that tells you when it stopped mattering. You model that history yourself, with timestamped nodes and edges, the same way you would on any engine.
What makes reading it back cheap is the range index. Put one on the timestamp property and you get gt, gte, lt, lte and between, plus ordered scans in either direction, so everything written between the Q2 kickoff and the code freeze is an indexed scan over a sorted range, and the last twenty revisions of a spec is a descending scan you can stop early. Combine that with a hop across the SUPERSEDES edge and the agent reads the version that is still current, rather than the one that happened to score highest.
## What the Retrieval Gap Looks Like in Practice: GraphRAG vs. Naive RAG on Multi-Hop Queries
To visualize the gap, imagine a multi-hop query: Who wrote the documentation for the service that handles payments? In a naive RAG setup, the retriever looks for payments service and documentation. It might find the payments API docs. Then the LLM has to extract the author from the text. If the author is not explicitly named in the chunk, the process stops. The LLM might hallucinate an author or say the information is missing. Every extra round trip is another chance for the right chunk not to come back, and the chain is only as good as its weakest hop.
With GraphRAG, the process is structured. The engine identifies the Payments Service node. It follows an edge to the Documentation node. It follows another edge to the Person node labeled as AUTHOR_OF. The system retrieves the exact entity, even if the person's name never appeared in the same text chunk as the word payments. This approach reduces the search space and improves accuracy. You can follow the guide on [how to build a GraphRAG pipeline](https://www.helix-db.com/content/guides/how-to-build-a-graphrag-pipeline-from-documents-to-scoped-retrieval) to see how this transition works. The difference is the shift from finding something that looks like the answer to traversing the path that leads to the answer.
## The Architecture That Actually Works: Graph + Vector in One Query
The usual answer to all of this is a second database, and often a third: a vector store for the embeddings, a graph database for the relationships, your application database underneath. Every retrieval crosses all of them. The real cost there is not the latency or the invoice, it is the synchronization. Ingesting one document becomes two writes that have to succeed together, and when one lands and the other does not, your company brain is quietly wrong and nothing tells you.
HelixDB is a graph-vector database written from scratch in Rust that does graph traversal, vector ANN and BM25 full-text search in one engine and one ACID transaction. Vectors are properties on nodes and edges, so there is no second index to keep in step with the first. One write, one source of truth, and one query that traverses the relationships and ranks by similarity at the same time.
## How Does HelixDB Scope a Vector Search to a Graph Traversal?
Because vectors are properties on nodes and edges, a similarity search can be chained onto a traversal instead of running against the whole index. The [documented order](https://docs.helix-db.com/database/helix-db/query-guides/filtering) is graph traversal, then exact candidate membership, then vector ranking, then top k. The traversal membership is authoritative: a result outside the candidate set cannot come back.
In practice that means the query starts where you know the answer lives, not in the global index:
```typescript
import {
g, readBatch, defineParams, param, SourcePredicate,
} from "@helix-db/helix-db";
const params = defineParams({
team: param.string(),
query_vector: param.array(param.f32()),
limit: param.i64(),
});
const recall = readBatch()
.varAs(
"hits",
g()
.nWithLabelWhere("Team", SourcePredicate.eq("name", params.team))
.out("OWNS")
.vectorSearchWith("Document", "embedding", params.query_vector, params.limit)
.valueMap(["$id", "title", "$distance"]),
)
.returning(["hits"]);
const request = recall.toQueryRequest(
params,
{ team: "Security", query_vector: queryVector, limit: 10n },
{ queryName: "documents_for_team" },
);
```
Two honest caveats, because the guarantee is narrower than it sounds. Exact membership does not mean the engine compares every candidate embedding one by one; approximate structures still do the ranking, and the output is validated against the traversal set. And a scoped search can return fewer than k rows, bounded by the number of unique candidates, which is the scope working rather than a bug.
The reason this is not the same as searching everything and adding a where clause is stated in HelixDB's own filtering guide: the high scorers you exclude afterwards have already consumed the source top k, so you are left with fewer eligible results than you asked for. Ask for the ten closest documents across fifty thousand and then keep only the security team's, and you can easily get none. Full-text chains the same way, with textSearchWith and a BM25 $score in the same documented order, so a hybrid query is scoped once and both halves obey it.
One thing scoping is not: it is a retrieval scope, not an authorization layer. It decides which candidates get ranked. Who is allowed to see what still belongs in your application.
## What Else Comes in the Same Engine?
HelixDB also ships native MCP support, so an agent can discover the database as a tool and walk the graph itself, step by step, without a human in the loop.
Storage is a startup flag rather than a product tier. The open source build runs fully in memory, on disk, or against S3-compatible object storage, and it is the same engine, the same SDKs and the same endpoint in all three, so you can prototype in memory and ship on object storage without touching application code. The [run modes](https://docs.helix-db.com/database/helix-db/start-here/run-modes) are documented in full, and Helix Cloud is the managed version of the object-storage mode.
The licence matters if the company brain is something you ship rather than something you run internally. HelixDB is Apache-2.0. Among the actively developed engines a team usually shortlists alongside it, that is unusual: Memgraph and SurrealDB are both under the Business Source License, converting to Apache on a 2030 change date, and FalkorDB is under the Server Side Public License. Kuzu is MIT, but its repository has been archived since October 2025, and LadybugDB, the successor project in the same C++ lineage, is MIT and active.
## Conclusion
The limitations of semantic search over internal documents are a feature of the architecture, not a bug in the models. Vector search is a powerful discovery tool, but it lacks the logical connective tissue required to understand a complex organization. As agents move from answering questions to doing work, what they need is memory that knows how things are connected, not just what they sound like. Duct-taping a vector store onto a graph database is a temporary fix that becomes permanent technical debt. HelixDB puts the graph, the vectors and full-text search in one Rust engine and one transaction. If your RAG pipeline keeps failing on basic ownership and dependency queries, stop tweaking your embeddings and start building a real knowledge graph. The repo is at [github.com/HelixDB/helix-db](https://github.com/HelixDB/helix-db) if you want to read the engine or star it.
### [Open Source Graph Database Written in Rust: How HelixDB Is Built](https://www.helix-db.com/content/open-source-graph-database-written-in-rust-how-helixdb-is-built)
HelixDB is an open source graph database written in Rust that runs graph traversal, vector search and BM25 full-text in one engine. Here is how it is built.
# Open Source Graph Database Written in Rust: How HelixDB Is Built
Most agent stacks end up holding memory in two places. A vector database holds the embeddings, a graph database holds the relationships, and application code keeps the two in sync. Every retrieval crosses both, so you pay two round trips and own a sync layer nobody wanted. The latency is the smaller problem. The real one is drift: once the two stores disagree, a retrieval that reads a stale edge against a fresh embedding returns something confidently wrong, and nothing in your logs says so.
HelixDB was built to solve this duct tape problem. It is a unified graph-vector engine designed for developers who want a single, performant store for knowledge graphs and semantic memory. By writing the core engine from scratch in Rust, HelixDB eliminates the overhead of managing separate systems for vectors, graphs, and full-text search. This post looks under the hood of how this open source graph database written in Rust handles complex queries at scale without the performance penalties of a garbage-collected runtime.
## Why Is HelixDB Written in Rust?
Rust is the vehicle here, not the argument. The argument is that an agent workload punishes unpredictable pauses, and a managed runtime gives you those by design. Collector behaviour varies a lot, so be careful how strongly you state this. A modern low-pause collector keeps the tail far tighter than an older one, and depending on collector and workload a collector can cost you throughput as much as latency. What running without one gives you is not automatically lower latency, it is a lifetime you decide rather than a runtime deciding for you. Rust gives memory safety without a collector, so HelixDB manages the lifetime of large vector indices and adjacency structures explicitly. That removes one source of variance. It does not remove allocation, synchronisation, scheduling or I/O, all of which you still pay for.
Memory layout is the second reason. A multi-hop traversal spends its time following adjacency, and in HelixDB that adjacency is persisted rather than resident, so a hop resolves against the tiered SSD and memory cache sitting above the durable layer rather than against a pointer in a live heap. How tightly nodes and edges pack decides how much of a walk is served from cache and how much becomes a fetch. Rust lets you lay those structures out deliberately instead of accepting whatever an object model hands you. Treat that as a design motivation rather than a measured result: the numbers that would settle it are specific to a workload and a cache size, and they are the ones to run on your own data.
Reliability is the final pillar, and the honest version of it is narrower than the way this usually gets pitched. Safe Rust rules out data races under its soundness assumptions, along with use-after-free and double-free, and it does that at compile time. It does not rule out logical race conditions, deadlocks, panics or resource exhaustion, and it says nothing about the `unsafe` blocks and SIMD paths an engine like this contains, whose correctness rests on review and testing rather than on the borrow checker. Consistency across concurrent readers and writers is the transaction layer's job, not the compiler's. So when you are shipping an [AI agent memory architecture](https://www.helix-db.com/content/ai-agent-memory-architecture-why-vector-search-is-not-enough), what the language buys you is that one class of bug is gone before deployment. That is smaller than "it will not crash" and it is real.
## What Does One Engine for Graph, Vectors and Full-Text Actually Change?
It changes where the join happens. Stitch a vector database to a graph database at the application layer and you are running two fetches and joining them in your own Python or Node code, with your process acting as a query planner that has no statistics and no index. In HelixDB the embedding is a property on the node or the edge, indexed natively by the same engine that stores the relationship. Writing a document means writing a node, its properties, its edges and its embedding in one batch, not writing to one system and then reconciling with another.
That is also what makes a genuinely hybrid query possible in one request. You can traverse the graph to reach a set of entities, run BM25 full-text scoring over that set, and rank the same set by vector similarity, without leaving the engine and without joining anything yourself. The scope is declared once and both halves of the hybrid obey it.
One process is also less to operate. There is one store to back up, one to restore, and one to reason about when a retrieval looks wrong. Because the graph and the embedding live in the same write path, there is no second system to fall behind and no reconciliation job to schedule. That is the foundation under any workable approach to [giving AI agents persistent memory](https://www.helix-db.com/content/guides/how-to-give-ai-agents-persistent-memory-in-one-database).
## How Does Pre-Filtering Scope a Vector Search to a Traversal?
The traversal runs first and the vector search ranks only what it returned. That order is the whole point, and it is the opposite of what most stacks do. The documented pipeline is graph traversal, then exact candidate membership, then vector ranking, then top k, and the traversal membership is authoritative: a result outside the candidate set cannot come back. Full-text chains onto a traversal the same way, with BM25 scores and the same ordering, so a hybrid query is scoped once and both halves respect it. And because embeddings sit on edges as readily as on nodes, the candidate set can be a set of relationships rather than a set of entities, which is the idea behind [scoping vector search to graph edges](https://www.helix-db.com/content/guides/pre-filtering-vector-search-on-graph-edges-how-to-scope-ann-to-relationships).
Take an agent working over one client's matter files. On a whole-label index you search everything and filter by client afterwards. In HelixDB you start at the client node, traverse to that client's documents, and the vector search ranks only those:
```typescript
import { readBatch, g, defineParams, param, SourcePredicate } from "@helix-db/helix-db";
const params = defineParams({
client: param.string(),
query_vector: param.array(param.f32()),
limit: param.i64(),
});
const recall = readBatch()
.varAs(
"hits",
g()
.nWithLabelWhere("Client", SourcePredicate.eq("name", params.client))
.out("HAS_DOCUMENT")
.vectorSearchWith("Document", "embedding", params.query_vector, params.limit)
.valueMap(["$id", "title", "$distance"]),
)
.returning(["hits"]);
const request = recall.toQueryRequest(
params,
{ client: "Acme", query_vector: queryVector, limit: 10n },
{ queryName: "documents_for_client" },
);
```
Two caveats worth stating plainly, because neither is a bug. Exact membership does not mean the engine compares every candidate embedding one by one; approximate structures still do the ranking, and the output is validated against the traversal set. And a scoped search can return fewer than k rows, bounded by how many unique candidates the traversal actually produced. That is the guarantee working.
It is worth being precise about why the ordering matters rather than treating it as an optimisation. Searching the whole label and adding a `where` clause afterwards is not the same operation, and HelixDB's own filtering guide says so: the high scorers you excluded have already consumed the source top k, so you are left with fewer eligible rows than you asked for. Ask for the ten nearest episodes across fifty thousand and then filter to one user, and you can easily get nothing back, not because nothing matched but because the ten you fetched all belonged to somebody else. Scoping first is what makes the k you asked for the k you can actually use. Note also that a tenant partition is a data-partitioning feature, not access control; if you need authorisation, that still belongs in your application.
## Can I Run an Open Source Graph Database Without Object Storage?
Yes, and it is a startup flag rather than a product tier. The open source build runs three ways: fully in memory, on disk, or against S3-compatible object storage. Same engine, same SDKs, same endpoint in all three, which is documented on the [run modes page](https://docs.helix-db.com/database/helix-db/start-here/run-modes).
That matters more than it sounds. You can prototype in memory, run on disk locally, and ship against S3-compatible object storage without touching application code, because the thing that changes is a flag and not your data layer. Getting a local instance up is two commands:
```bash
helix init
helix start dev
```
Helix Cloud is the managed version of the object-storage mode: the durable layer lives in object storage, a single writer serialises mutations, readers scale horizontally, and SSD plus memory act as cache above the bucket. The consequence for an agent workload is that capacity, latency and concurrency stop being the same dial. In an in-memory engine, storing more data and serving more traffic are the same purchase.
## How Do You Query It Without a Query Language?
There is no query language to learn, which is the part people usually do not believe. Queries are JSON, built in your own application code with native SDK builders and sent as one POST to `/v2/query`. There is no query language to write and nothing compiled ahead of time: the builders serialise to JSON, and the database turns that JSON into the query it runs. Any language that can make an HTTP request can talk to it, so cURL is enough to get a first query out.
SDK builders exist for Rust, TypeScript, Python and Go, and they run inside your application rather than in front of the database. They serialise to the same JSON envelope, so behaviour is identical whether your backend is Go and your ingestion pipeline is Python. Writes use the same shape. Note that one request is one transaction, so the whole batch commits or none of it does:
```typescript
import {
BatchCondition,
g,
NodeRef,
SourcePredicate,
writeBatch,
} from "@helix-db/helix-db";
const ingest = writeBatch()
.varAs(
"client",
g().nWithLabelWhere("Client", SourcePredicate.eq("name", "Acme")).limit(1),
)
.varAs("doc", g().addN("Document", { title, embedding, occurredAt: Date.now() }))
.varAsIf(
"edge",
BatchCondition.varNotEmpty("client"),
g().n(NodeRef.var("client")).addE("HAS_DOCUMENT", NodeRef.var("doc"), {}),
)
.returning(["client", "doc", "edge"]);
```
That lookup deserves two sentences of its own, because the obvious version of it is a silent bug. `nWithLabelWhere` returns a stream, not a promise of exactly one row. If no client matches, `addE` gets an empty source, succeeds without creating anything, and the document commits anyway as an orphan. If several match, you get several edges. Atomicity is working correctly in both cases: one request is one transaction, and it will happily commit a document with no client, because "every document belongs to exactly one client" is your invariant and not the engine's.
So enforce it or state it. The real fix is a uniqueness index on the lookup property, created with `IndexSpec.nodeUniqueEquality("Client", "name")`, which makes the match zero-or-one at the storage layer. `limit(1)` above bounds the multiple-match case if you do not have that index yet. `varAsIf` with `BatchCondition.varNotEmpty` gates the edge on the lookup having actually found something, and returning `client` and `edge` alongside `doc` is what lets the caller tell an attached document from an orphaned one instead of reading a successful commit as a successful attach.
Index creation is a write query too, not a client method, and it is asynchronous. The call returns before the backfill finishes, so poll `getIndexOperation` until every status reads succeeded and stop on blocked, aborted or timeout. Starting to write batches because the request was accepted is the mistake worth avoiding:
```typescript
import { writeBatch, g, VectorDistanceMetric } from "@helix-db/helix-db";
const index = writeBatch()
.varAs(
"index",
g().createVectorIndexNodes("Document", "embedding", 1536, VectorDistanceMetric.Cosine, null),
)
.returning(["index"]);
```
The JSON shape happens to suit agents, since a model that is good at emitting structured output is better at building a query object than at building a query string. Bulk writes, filtering predicates and range queries all fit in one request, and range indexes give you `gt`, `gte`, `lt`, `lte` and `between` plus ordered scans in either direction, so "the last twenty things" is a descending scan you can stop early rather than a sort over everything.
## How Does HelixDB Compare to Other Open Source Graph Databases?
Worth being accurate about the field, because it moves. Kuzu was the well-known embedded option and its repository was archived in October 2025; LadybugDB is the successor project in the same C++ lineage rather than a rebrand or a GitHub-tracked fork, and it is actively developed. SurrealDB is multi-model and takes vectors seriously, documenting several index types including a disk-resident one, so the honest contrast there is general-purpose backend against purpose-built agent memory rather than any gap in capability. FalkorDB aims squarely at GraphRAG and says so. This is not a category where the competition is asleep.
The difference that actually decides things is workload shape. Set [HelixDB against LadybugDB](https://www.helix-db.com/content/compare/helixdb-vs-ladybugdb-picking-a-graph-db-after-kuzu) and their own positioning names it: they are optimised for complex analytical workloads over very large databases, which is OLAP. Agent memory is OLTP, many small reads and writes arriving from many concurrent sessions. A columnar, vectorised design is genuinely lighter on memory and genuinely better at scanning a lot of rows to touch a few columns, and it is the wrong shape for transactional agent traffic. That is a topology argument, not a claim that anyone built something badly.
The other thing to put side by side on an open source page is the licence, because it decides whether you can embed the engine in something you ship. HelixDB is Apache-2.0. FalkorDB is under the Server Side Public License. Memgraph and SurrealDB are both under the Business Source License, each with a 2030 change date after which they convert to Apache, which is a real distinction and worth stating rather than glossing. Kuzu and LadybugDB are MIT. So the accurate claim is narrow: among the actively developed engines here, HelixDB is on a permissive licence and the BSL and SSPL options are not, while the MIT lineage is permissive too. If you are embedding a database inside a product you distribute, that is the row in the table you read first.
## How Do I Try It?
HelixDB is open source under Apache-2.0, so you can self-host it, embed it and contribute to the engine without a licence conversation. `helix init` scaffolds a project and `helix start dev` brings up a local instance; add `--disk` if you want it on disk rather than in memory. The CLI also covers deploys and cloud instances, and `helix skills install` pulls down the agent skills that help a coding assistant write correct queries against it. If you want to see how any of this actually works, the engine is on [GitHub](https://github.com/HelixDB/helix-db) and the Rust is readable.
Then try to break it. Load it past what you think is reasonable and run the traversals you would actually run in production rather than the ones that look good in a benchmark. Start with a single scoped retrieval and grow it into an episodic memory as the agent needs one.
The [docs](https://docs.helix-db.com/database/querying) cover the query surface for every SDK, and the [filtering guide](https://docs.helix-db.com/database/helix-db/query-guides/filtering) is the one to read if the pre-filtering order above is the part you care about.
One honest note on fit. If your retrieval is a single top-k lookup over one flat corpus and relationships never enter into it, a plain vector store is a simpler thing to run and you should keep it. This is worth the switch when the relationships are load-bearing.
## Conclusion
The case for an open source graph database written in Rust is not that Rust is fast. It is that graph traversal, vector ranking and BM25 sit in the same query and obey the same scope, and that comes from the data model, the query operators and the transaction implementation rather than from the language. What Rust buys is the freedom to lay those structures out explicitly and run without a collector, which serves that design without being the reason it holds. That removes the sync layer between your vector store and your graph, and with it the drift that makes a retrieval quietly wrong. It runs in memory on your laptop and against object storage in production on the same code path, and the licence does not get in the way if you ship it inside something. If that sounds like your stack, [star it on GitHub](https://github.com/HelixDB/helix-db) and go build something against it.
### [How to Give AI Agents Persistent Memory in One Database](https://www.helix-db.com/content/guides/how-to-give-ai-agents-persistent-memory-in-one-database)
Give AI agents memory that survives restarts: model episodes as timestamped nodes and edges, then scope semantic recall to one user with a graph traversal.
# How to Give AI Agents Persistent Memory in One Database
Most AI agents have no memory. You build a sophisticated reasoning loop, but the moment the session ends, the agent loses every piece of context it worked to acquire. Developers usually try to solve this by dumping conversation logs into a vector database like Pinecone or Weaviate. Basic semantic search works, but it fails to capture the complex relationships between entities or the chronological flow of events. If a user says, 'My manager Sarah just got promoted,' a vector search might find the word Sarah, but it won't update the reporting structure in the agent's internal model.
To build an agent that actually learns, you need a multi-layer memory architecture. You need to store what happened (episodic), what is true (semantic), and how things are connected (relational). Doing this usually requires duct-taping three different databases together, which creates a maintenance nightmare and high latency. This guide shows you how to implement all three layers in one engine using HelixDB, a Rust-native graph-vector database. You will move from a naive vector index to a unified memory store that lets your agent traverse relationships and perform semantic recall in a single query.
## What Does an AI Agent Actually Need to Remember?
Vector search is not a complete memory strategy. When you rely solely on embeddings, your agent retrieves chunks of text that are mathematically similar to the input but often lack the structural context required for complex reasoning. A real [AI agent memory architecture](https://www.helix-db.com/content/ai-agent-memory-architecture-why-vector-search-is-not-enough) requires three distinct types of persistence that work together.
Before any of this, be honest about whether you need it. A single-session assistant with a short transcript does not need a memory store. Keep the transcript in the context window and move on. The rest of this guide is for the case where sessions are long, users come back, and the things the agent needs to connect were said days apart.
First is episodic memory. This is the chronological log of interactions. It lets the agent remember that a specific conversation happened on Tuesday and that the user was frustrated during that exchange. Without episodic memory, the agent cannot handle references like 'what did we talk about last week.'
Second is semantic memory. This represents the global knowledge the agent has acquired, including facts, definitions, and concepts that are not tied to a specific point in time. If the agent learns that a specific API endpoint requires an OAuth2 token, that fact should be stored semantically so it can be retrieved across all future sessions. Vector databases handle this part reasonably well, but they still treat facts as orphaned chunks rather than part of a larger knowledge base. You need a way to store these facts so they remain accessible regardless of the specific phrasing of the query.
Third is relational memory. This is where most RAG implementations fail. Relational memory maps the connections between entities. If Sarah manages the Engineering team and the Engineering team owns the Deployment service, the agent needs to understand those links. In a standard vector store, these relationships are buried inside text blobs. In a graph, they are rows you can traverse. By combining these three types into a unified structure, you avoid the 'goldfish effect' where the agent recognizes a keyword but forgets the surrounding context. HelixDB lets you model these layers as a graph where nodes represent entities or episodes and edges represent the relationships between them, with vector embeddings attached for semantic retrieval. This unified approach removes the need to manage a separate [vector database vs graph database](https://www.helix-db.com/content/vector-database-vs-graph-database-what-ai-memory-needs) stack.
## How Do You Run a Persistent HelixDB Instance Locally?
Two commands. `helix init` scaffolds the project, and `helix start dev` brings up a local instance on port 6969.
Where that instance keeps its data is a startup flag, not a product tier. The open-source build runs three ways: fully in memory, on disk with `--disk`, or against S3-compatible object storage. The engine, the SDKs and the HTTP interface are identical across all three, so you can prototype in memory and later point the same application code at a bucket without changing a line of it. The [run modes page](https://docs.helix-db.com/database/helix-db/start-here/run-modes) has the exact flags. HelixDB can also run embedded, in-process through the native SDK with no HTTP hop at all, and Helix Cloud is the managed version of the object-storage mode with a single writer serialising mutations and readers scaling horizontally.
You talk to it with `POST /v2/query`. There is no query language to learn and nothing to compile: you build queries with the native TypeScript, Rust, Go or Python SDK, in the same files as the rest of your application code, and the builder serialises to a JSON envelope. You can hand-write that JSON if you would rather.
One thing to get right before you write any memory: a vector index is created by a write query, not a client method, and creation is asynchronous.
```ts
import { g, writeBatch, VectorDistanceMetric } from "@helix-db/helix-db";
const createIndex = writeBatch()
.varAs(
"index",
g().createVectorIndexNodes(
"Episode",
"embedding",
1536,
VectorDistanceMetric.Cosine,
null,
),
)
.returning(["index"]);
```
The last argument is the tenant property, and `null` gives you a global index. The request returning successfully means it was accepted, not that the index is ready, so poll `getIndexOperation` until every status reads succeeded and stop on blocked, aborted or timeout. Do not start writing episodes because the create call came back. The [vector index lifecycle](https://docs.helix-db.com/database/helix-db/query-guides/vector-indexes) is documented in full.
## How Should You Model Agent Memory as Nodes and Edges?
A flat list of documents is the enemy of persistent memory. Decide up front how the agent should carve up the world, because that decision is what makes retrieval answerable later. In HelixDB, you model your domain using nodes and edges. Nodes represent the 'things' in your agent's universe, such as Users, Projects, Sessions, or specific Facts. Edges represent the 'verbs' that connect them, such as 'WORKS_ON', 'SAID_IN', or 'IS_MEMBER_OF'. A vector is a property like any other: a top-level numeric array on a node or on an edge, the same shape you would model in Neo4j. What differs is where the index for it lives and what you can scope a search to.
For example, a 'User' node might have a name and a role property. An 'Episode' node representing a chat turn carries the turn text and an `embedding` property. Because the embedding sits on the node, you can write one query that walks to the episodes belonging to a user and ranks only those by similarity. You do not pull ids out of a vector index and then filter them in a second store. "Find the Episodes connected to User A whose content is semantically closest to this query" is a single request, and the next section shows exactly what it looks like.
Edges also support properties, which lets you add context to relationships. You can attach a 'strength' property to an edge to indicate how often two concepts are mentioned together, or a 'timestamp' property to track when a relationship was first established. This level of granularity is important for building a 'company brain' where the agent needs to know not just that a document exists, but who wrote it and which project it belongs to. There is no schema file to write and nothing to push before you query. Deciding your labels and edge types up front is a modelling discipline, not a deployment step, and it is what keeps the agent's memory from turning into a pile of text chunks.
## How Do You Write a New Memory After Each Turn?
Memory should be an active process, not a passive log. After every turn in the conversation, your agent should run a 'memory extraction' step. This involves using an LLM to analyze the recent interaction and identify new entities, updated facts, or changes in relationships. If the user says, 'I am moving the deadline for the Phoenix project to Friday,' the agent should not just store that string. It should identify the node for 'Phoenix Project' and update its 'deadline' property, or create a new 'DeadlineUpdate' node connected to it.
One request is one transaction: every entry in a write batch commits or rolls back together. So the episode, the edge back to the user and the embedding all land in the same operation, which is what removes the drift you get when a graph write succeeds and a vector write does not.
```ts
import {
BatchCondition,
g,
writeBatch,
NodeRef,
SourcePredicate,
} from "@helix-db/helix-db";
const remember = writeBatch()
.varAs(
"user",
g().nWithLabelWhere("User", SourcePredicate.eq("id", userId)).limit(1),
)
.varAs(
"episode",
g().addN("Episode", {
content: turnText,
embedding: turnEmbedding,
occurredAt: occurredAtMillis,
}),
)
.varAsIf(
"authored",
BatchCondition.varNotEmpty("user"),
g().n(NodeRef.var("user")).addE("AUTHORED", NodeRef.var("episode"), {}),
)
.returning(["user", "episode", "authored"]);
```
The user lookup is worth being explicit about, because the version without the guard is a silent bug rather than a loud one. `nWithLabelWhere` returns a stream, not a promise of exactly one row. If that id matches no user, `addE` receives an empty source, returns successfully without creating an edge, and the Episode still commits, so you end up with a memory belonging to nobody. If it matches two, you get two AUTHORED edges. Atomicity is working correctly in both cases: one request is one transaction, and committing an unowned Episode is a valid outcome, because "every episode has exactly one author" is your invariant and not the engine's. The precondition is therefore a uniqueness index on the lookup property, `IndexSpec.nodeUniqueEquality("User", "id")`, which makes the match zero-or-one at the storage layer; `limit(1)` bounds the multiple-match case until you have one. `varAsIf` with `BatchCondition.varNotEmpty` gates the edge on the user actually existing, and returning `user` and `authored` alongside `episode` is what lets the caller distinguish an attached memory from an orphaned one instead of reading a successful commit as a successful attach.
Note `occurredAt` as a plain numeric property. That is the field the time-range queries later in this guide read, and putting it on the node at write time costs nothing. Edges are additive here: `addE` adds, so the same user hitting the same document forty times gives you forty timestamped edges rather than one that keeps getting overwritten. That matters more than it sounds, because repeated events between the same two entities are exactly what an agent's history is made of. The [writing-data guide](https://docs.helix-db.com/database/helix-db/query-guides/writing-data) covers batch semantics.
To make this process manageable, many developers use the Model Context Protocol (MCP). HelixDB provides native MCP endpoints, which lets agents discover tools and query the graph step-by-step. During the write phase, the agent can use these tools to check if a specific entity already exists before creating a duplicate. If the agent finds an existing node for 'Phoenix Project', it updates the current one instead of cluttering the database. This deduplication is a critical part of maintaining a clean memory store. Without it, the agent's context window will eventually fill with redundant, slightly different versions of the same information, leading to confusion and hallucinations.
## How Do You Scope a Memory Search to One User or One Conversation?
You put the traversal first and let the vector search rank only what it reaches. This is the part most retrieval stacks get backwards, and it is the difference between a scoped search that works and one that quietly returns nothing.
The documented order is: graph traversal, then exact candidate membership, then vector ranking, then top k. The traversal membership is authoritative, so a result outside the candidate set cannot come back.
```ts
import {
g, readBatch, defineParams, param, SourcePredicate,
} from "@helix-db/helix-db";
const params = defineParams({
user_id: param.string(),
query_vector: param.array(param.f32()),
limit: param.i64(),
});
const recall = readBatch()
.varAs(
"episodes",
g().nWithLabelWhere("User", SourcePredicate.eq("id", params.user_id))
.out("AUTHORED")
.vectorSearchWith("Episode", "embedding", params.query_vector, params.limit)
.valueMap(["$id", "content", "occurredAt", "$distance"]),
)
.returning(["episodes"]);
const request = recall.toQueryRequest(
params,
{ user_id: "u-42", query_vector: queryVector, limit: 10n },
{ queryName: "recall_user_episodes" },
);
```
The `10n` is not a typo. An i64 parameter takes a BigInt literal.
Now the contrast worth understanding, because it is why the ordering matters. The obvious alternative is to search the whole Episode label and add a `where` clause for the user. HelixDB's own documentation is explicit that this is not a substitute: the high scorers you are about to exclude have already consumed the source top k, so you end up with fewer eligible results than you asked for. For agent memory that is not a subtle degradation. Ask for the ten closest episodes belonging to one user out of fifty thousand users, and the global top ten is almost entirely other people's memories, so after filtering you get nothing back and the agent behaves as though it has no history at all.
Two honest caveats. Exact membership does not mean the engine compares every candidate embedding one by one; approximate structures still do the ranking, and the output is validated against the traversal set. And a scoped search can return fewer than k rows when the candidate set is smaller than k. That is the guarantee working rather than a bug, so do not treat a short result list as a failure.
Full-text search chains onto a traversal the same way, with BM25 scores through `textSearchWith`, and it follows the same order. So a hybrid query is scoped once and both halves obey the scope, rather than each half being filtered separately and reconciled in your application code. The [filtering guide](https://docs.helix-db.com/database/helix-db/query-guides/filtering) documents the pipeline. We went deeper on scoping in the guide on [pre-filtering vector search on graph edges](https://www.helix-db.com/content/guides/pre-filtering-vector-search-on-graph-edges-how-to-scope-ann-to-relationships).
One caveat on tenant-partitioned indexes, since it is easy to misread: a tenant partition is an index partition, not access control. It narrows where the ANN search runs. It does not enforce authorisation, and you should not treat it as a permission boundary.
## How Do You Query Agent Memory by Time Range?
Memory is not just about adding information. It is also about managing what is no longer true. A common problem in agentic systems is memory bloat, where the agent is overwhelmed by thousands of irrelevant historical facts. The fix is a range index on the timestamp you already wrote in the previous section.
You model history the way you would anywhere else, with timestamped nodes and edges. What makes reading it back cheap is the range index: it supports gt, gte, lt, lte and between, plus ordered scans in either direction. So "everything between Tuesday and Thursday" is an indexed scan over a sorted range, and "the last twenty things this user said" is a descending scan you can stop early rather than a sort over their entire history. It composes with the scoped vector search from the previous section too, so recency and semantic relevance resolve in one request instead of two passes and a merge in your application code. If a user changed their coding-style preference last week, the agent can see both versions and take the one with the later timestamp.
Handling contradictions is equally important. When the agent extracts a new fact that conflicts with an existing one, you have to decide how to resolve the clash. You can use the graph structure to store both facts but mark the older one as 'superseded' by creating an edge between them. This lets the agent maintain a history of how information evolved, which is useful for debugging. If you want a form of forgetting, do it with the same timestamp: a range scan bounded to the last N days is how you keep the agent's working context on recent material without deleting the history behind it.
Staleness is the version of this that bites hardest. If a project plan in the memory store is three months old and a newer document has landed since, the agent needs to know which one wins. Model documents and their versions as nodes with a supersedes edge and a timestamp, and the traversal starts from the current node by construction rather than by hoping the newer text scored higher. None of this is something the database decides for you, and no database does: graph versioning is a thing you design. What the engine gives you is the indexed read path that makes the design cheap to query.
## Conclusion
Giving an AI agent persistent memory is not a matter of storing more data. It is a matter of storing the right connections. Relying on a patchwork of disconnected databases forces you to write complex glue code that inevitably breaks as your agent grows. By moving to a unified graph-vector engine like HelixDB, you eliminate the latency of multi-database round trips and the complexity of managing disparate schemas. Your agent gets a single, coherent source of truth where episodic, semantic, and relational data exist in one place.
If your agent is still in goldfish mode, stop duct-taping vector indices together. Run `helix init` and `helix start dev`, point it at the model above, and see how much of your glue code disappears. If the shape of it makes sense to you, [star HelixDB on GitHub](https://github.com/HelixDB/helix-db) and tell us what broke.
### [How to Build a GraphRAG Pipeline: From Documents to Scoped Retrieval](https://www.helix-db.com/content/guides/how-to-build-a-graphrag-pipeline-from-documents-to-scoped-retrieval)
Learn how to build a GraphRAG pipeline to solve multi-hop Q&A. This guide covers entity extraction, graph modeling, and scoped retrieval using HelixDB.
# How to Build a GraphRAG Pipeline: From Documents to Scoped Retrieval
You ship a RAG bot for a legal team and everything works until the first complex query arrives. A lawyer asks: 'Which partners signed off on the Project Alpha revisions after the compliance audit?' Your Pinecone index returns five chunks about Project Alpha, but none of them mention the audit or the partners involved. The vector search found semantic matches for the project name but failed to follow the relationship between the audit, the document revisions, and the people who approved them. This is the wall every engineer hits with naive top-k retrieval.
Top-k RAG searches for similarity, not connection. It treats your documents like a bucket of loose confetti. GraphRAG treats them like a map. By the end of this guide, you will know how to build a GraphRAG pipeline that extracts entities, models relationships, and uses a unified engine to traverse connections before ranking results. You need a basic understanding of embeddings and chunking to follow along. We will move past simple similarity to build a system that understands how your data is actually linked.
## Step 1: Why Does Naive RAG Miss Connected Context?
Naive RAG retrieves by resemblance. If a question spans three documents, a vector-only search usually pulls chunks from two of them and misses the third, because that one never uses the words you searched for. GraphRAG adds a second axis, the entities in your documents and the relationships between them, so retrieval can follow a connection rather than only measuring a distance.
GraphRAG fixes the 'orphan chunk' problem. In a standard pipeline, a chunk about 'Jane Doe' and a chunk about 'The Executive Committee' might have no semantic similarity in vector space. But if Jane Doe is the Chair of that committee, a graph edge connects them. GraphRAG allows your retrieval step to follow that edge even if the text doesn't explicitly mention Jane in the committee chunk. This is the difference between finding documents that look like the question and finding documents that contain the answer.
That said, GraphRAG is not a magic fix for poor data. If your extraction layer is weak, your graph becomes a collection of hallucinated nodes. It also adds real operational overhead. Most teams try to duct-tape Neo4j to Pinecone and then add a Postgres instance for metadata. That three-database setup creates latency and synchronization problems. HelixDB solves this by putting graphs, vectors, and full-text search in a single Rust engine. You get graph connectivity with vector index speed, without managing three different schemas. Before you build, accept that GraphRAG is for relational complexity, not just better search accuracy. If your users only ask for simple facts found in single paragraphs, stick to naive RAG and save the compute credits.
## Step 2: How Do I Extract a Knowledge Graph from My Documents?
The quality of your GraphRAG pipeline depends entirely on your extraction logic. You cannot simply dump text into a graph. You must convert unstructured prose into triples: Subject, Predicate, and Object. For example, 'Alice works at Acme Corp' becomes a node for Alice, a node for Acme Corp, and a 'WORKS_AT' relationship between them. This process is called Named Entity Recognition and Relation Extraction (NERRE).
Use a high-reasoning model for this step to ensure the extraction logic is robust. Give the model a specific schema of the entities you care about, such as People, Organizations, Dates, and Projects. If you let the LLM invent its own entity types, your graph becomes a messy hairball that is impossible to query. Force the model to output structured JSON. Local entity extraction tools can also be utilized for efficiency, though larger models often identify complex relationships more effectively. [Agent memory](https://www.helix-db.com/content/ai-agent-memory-architecture-why-vector-search-is-not-enough) needs this level of precision, because an agent that splits one entity across three nodes loses track of who did what.
Entity resolution is the final hurdle in extraction. If one document says 'IBM' and another says 'International Business Machines', your pipeline must recognize they are the same node. Without resolution, your graph splits and traversals fail. Use a combination of fuzzy string matching and LLM-based clustering to merge these duplicates before they hit your database. Once you have a clean list of entities and relationships, you are ready to build the physical model.
## Step 3: How Should I Model the Graph, the Chunks, and the Embeddings?
In a GraphRAG system you do not choose between a graph and a vector index, you need both. Entities become nodes, relationships become edges, and an embedding is a property on whichever of those you intend to search. In HelixDB a vector is a top-level numeric array on a node or an edge, the same shape it takes in any property graph. What changes is that the traversal and the ranking run against the same store, so there are no round trips between two systems and no join to write in your application code.
Your model should include three layers. First, Entity Nodes represent the 'who' and 'what'. These nodes store properties like names, descriptions, and a vector embedding of that description. Second, Relationship Edges connect these nodes. An edge might represent 'OWNED_BY' or 'CONTRIBUTED_TO'. Edges can carry embeddings too, which is worth doing when the meaning lives in the relationship rather than in either end of it, though the worked example below indexes nodes. Third, Document Chunks remain in the graph as nodes. Each chunk links to the entities it mentions. This creates a bridge between the high-level knowledge graph and the raw source text.
This structure allows for a dual-mode search. You can find an entity by its name or its semantic meaning, then immediately traverse to all related document chunks. This is why the [vector database versus graph database](https://www.helix-db.com/content/vector-database-vs-graph-database-what-ai-memory-needs) framing is usually a false choice. You need a unified engine that understands both. Storing the embedding on the node it describes is what removes the synchronisation problem, because there is no second store holding a copy of the same id. Any node you have declared a vector index for is searchable, and every hit that comes back is already a graph node you can traverse away from.
## Step 4: Index the Graph and Vectors Together
Indexing is where pipeline performance is won or lost. In a naive RAG setup, you only index vectors using an algorithm like HNSW. In GraphRAG the traversal matters as much as the ranking, and when those live in separate systems every scoped query costs you a round trip plus a list of ids shuttled between them. In HelixDB they sit in the same storage layer, so a graph hop and a vector search happen in the same execution context.
Index time as well as text. Relationships go stale, and a legal or financial agent needs to know what was true when, not only what is true now. You model that with timestamps on the nodes and edges that represent events, and a range index over those timestamps is what makes reading them back cheap: gt, gte, lt, lte and between, plus ordered scans in either direction, so the last twenty revisions is a descending scan you can stop early. It composes with a scoped search, so recency and semantic relevance resolve in one request rather than two.
Batch the work, and create the indexes before the bulk load rather than after. There is no schema file and no compile step here: an index is made by a write query, with the same SDK you read and write everything else with.
```ts
import { writeBatch, g, VectorDistanceMetric } from "@helix-db/helix-db";
const index = writeBatch()
.varAs(
"index",
g().createVectorIndexNodes(
"Entity", "embedding", 1536, VectorDistanceMetric.Cosine, null,
),
)
.returning(["index"]);
await client.query(index);
```
The arguments are the label, the property holding the embedding, the dimension, the distance metric, and a tenant property to partition the index on, with null for a global index. Creation is asynchronous, so poll getIndexOperation until every status reads succeeded, and stop on blocked, aborted or timeout. Do not start loading just because the request came back accepted; the backfill has not necessarily finished.
## Step 5: How Do I Scope a Vector Search to What the Traversal Found?
The retrieval pattern is what makes GraphRAG work. Don't just run a vector search across all chunks. Use a 'prefilter-then-rank' pattern instead. First, use the user's query to identify the starting entities in your graph. If the user asks about 'Project Alpha', find the Project Alpha node. Second, traverse the graph to find all related nodes and documents within one or two hops. This scopes your retrieval to only the relevant context.
Once you have that scoped set, rank inside it. The documented order is graph traversal, then exact candidate membership, then vector ranking, then top k, and the traversal set is authoritative: a result outside the candidate set cannot come back. Searching the whole label and then applying a where clause is not a substitute for this, because the entries your filter throws away have already consumed the source top k, so you finish with fewer eligible results than you asked for. That is the failure mode most teams have already hit without naming it. We went through the mechanics in more depth in the [pre-filtering guide](https://www.helix-db.com/content/guides/pre-filtering-vector-search-on-graph-edges-how-to-scope-ann-to-relationships).
In HelixDB that is one request and one transaction. You build it with the SDK in whatever language your service is already written in, and it serializes to JSON; there is no query language to learn and nothing is compiled.
```ts
import {
g, readBatch, defineParams, param, SourcePredicate,
} from "@helix-db/helix-db";
const params = defineParams({
project: param.string(),
query_vector: param.array(param.f32()),
limit: param.i64(),
});
const recall = readBatch()
.varAs(
"hits",
g().nWithLabelWhere("Project", SourcePredicate.eq("name", params.project))
.out("HAS_REVISION")
.vectorSearchWith("Revision", "embedding", params.query_vector, params.limit)
.valueMap(["$id", "title", "$distance"]),
)
.returning(["hits"]);
const request = recall.toQueryRequest(
params,
{ project: "Project Alpha", query_vector: queryVector, limit: 10n },
{ queryName: "revisions_for_project" },
);
```
Two things to expect from that. You can get back fewer rows than your limit, because the result is bounded by how many unique candidates the traversal reached, and that is the guarantee working rather than a bug. And exact membership does not mean the engine compared every candidate embedding one by one: approximate structures still do the ranking, and the output is checked against the traversal set.
## Step 6: How Do I Know GraphRAG Is Actually Better Than My Baseline?
You cannot manage what you do not measure. After building your GraphRAG pipeline, test it against your original top-k RAG baseline. Use an evaluation framework such as RAGAS to measure faithfulness, answer relevance and context precision. You will likely find that GraphRAG has higher Context Recall for multi-hop questions, but it may also have higher latency due to the extraction and traversal steps.
Create a gold-standard dataset of 50 to 100 complex questions that require connecting facts across documents. Run these through both pipelines and compare results using a model-based grader like G-Eval. If GraphRAG isn't providing a clear accuracy improvement, your graph model is probably too simple or your extraction is missing key relationships. You may need to tune your hop count or adjust how you weight vector similarity versus graph proximity.
Building a GraphRAG pipeline is an iterative process. You will find that some entity types are more useful than others. You might realize you need to index edge properties more heavily. Don't be afraid to wipe your graph and re-index with a new schema. The goal is a 'company brain' that evolves as your data grows. If you are still stitching together multiple databases to achieve this, you are fighting the tools instead of the problem. A unified engine simplifies this evaluation by letting you tweak query logic in one place.
## Conclusion
GraphRAG earns its cost when your users ask questions that span documents, and not much before that. When they do, extracting entities and modelling their connections is what gives the model the structural context that similarity alone will not surface. The biggest mistake engineers make is over-complicating the infrastructure. You do not need to manage three separate databases to get these results. Duct-taping a vector store to a graph store only produces high latency and synchronization bugs that break your agent memory.
HelixDB is a single Rust engine that runs graph traversal, vector search and full-text in one transaction, so the scope and the ranking are not two systems you keep in step. `helix init` then `helix start dev` gets you a local instance to point your first extraction run at, and the run mode is a startup flag rather than a product tier: in memory, on disk, or against S3-compatible object storage. [Star HelixDB on GitHub](https://github.com/HelixDB/helix-db) if the approach is one you want to follow.
### [HelixDB vs LadybugDB: Picking a Graph DB After Kuzu](https://www.helix-db.com/content/compare/helixdb-vs-ladybugdb-picking-a-graph-db-after-kuzu)
Kuzu is archived. LadybugDB is columnar and analytical, in-process or in the browser. HelixDB is OLTP agent memory with pre-filtered vector and keyword search.
KuzuDB getting archived on GitHub left a real problem for developers who built their RAG pipelines around its embedded graph architecture. If you spent the last year tuning GraphRAG or building agent memory on Kuzu, you are now facing a forced migration. The real decision is not C++ versus Rust. It is whether your memory layer needs to stay inside one process.
This decision is not just about moving code. It is about what the engine underneath is tuned for. LadybugDB is the successor project in the same C++ lineage, and it keeps the embedded, single-process shape that made Kuzu pleasant to work with, with columnar disk-based storage and a vectorised query processor aimed at analytical workloads. HelixDB is embeddable too, in memory or on disk, and the same engine also runs as a local server and as a distributed managed cloud without the application code changing. So embedded versus server is not the axis here. The axis is what each engine is optimised for, how retrieval gets scoped, and what happens on the day one process is not enough.
## What Happened to KuzuDB and Why You're Choosing Again
The kuzudb/kuzu repository is archived on GitHub, its last commit landed on 2025-10-10, and that ends active development on that repo. It sits at roughly four thousand stars under an MIT licence, so the code is still there and still usable. What stopped is the maintenance. Kuzu was liked for handling structured graph queries without a server to operate, and that has not changed. What an archived repo changes is who is responsible for the core you depend on. The archival forced a pivot: either fork the code and maintain it yourself, or move to a modern engine designed for the current graph-vector era.
Choosing a replacement is not a one-to-one swap, and it is worth being accurate about what this lineage already gives you. LadybugDB ships native full-text search and vector indices alongside the property graph, so the old duct-tape story of running a graph engine next to Pinecone and joining the two in application code does not describe it. Both engines on this page put the relationships and the embeddings in one place. That is the shift behind the [HelixDB vs Neo4j]() comparison developers are running now, and both of these have already made it.
Which leaves three narrower questions that actually decide this one. What is the engine tuned for, analytical scans or transactional agent traffic. Whether a similarity or keyword search can be scoped by a graph traversal before it ranks, rather than filtered after it. And what happens when the workload outgrows a single process.
## What LadybugDB Is (and What It Inherits from Kuzu)
LadybugDB is the logical landing spot for developers who want to keep the Kuzu spirit alive. It is a successor project in the same C++ lineage rather than a rebrand or a GitHub-tracked fork of the original repo, and it keeps the C++ foundation and the embedded, single-process philosophy. It is MIT licensed and actively developed, with commits landing this month.
Their own feature list is worth reading rather than paraphrasing, because it is stronger than "embedded graph database" suggests: Cypher over a property graph, native full-text search and vector indices, columnar disk-based storage with columnar sparse row-based adjacency indices, a vectorised and factorised query processor, multi-core query parallelism, serializable ACID transactions, and WebAssembly bindings so the engine runs in the browser. They describe it as optimised for complex analytical workloads on very large databases, and that description is the most useful sentence in the comparison.
Columnar and vectorised is a design for scanning many rows while touching few columns, which is what analytical work looks like, and it is lighter on memory than doing the same job row by row. Running in the browser through WASM is a genuinely separate capability, and if that is on your roadmap nothing on the other side of this comparison replaces it.
What an embedded engine gives you is also what bounds it. Everything lives in your process, which is why there is no network hop and no server to operate, and equally why the capacity of the graph is the capacity of that one machine. To be clear about what this is not: LadybugDB documents serializable ACID transactions and multi-core query parallelism, so this is not an argument about weak guarantees inside the process. It is an argument about topology. One process on one machine is the right trade for a notebook, a batch pipeline, or a tool that ships as a binary. It is a harder trade for a company brain that several services write to at once, because the coordination you did not need at one process is what you end up building yourself at three, and the ceiling stays whatever that machine has.
## What HelixDB Is: One Rust Engine for Graph, Vector, and Full-Text
HelixDB was built from scratch in Rust to solve the problem of fragmented AI memory. Instead of forcing you to stitch together three different types of databases, it provides a single [vector and graph database]() engine. It is an OLTP graph-vector database that natively supports graph nodes and edges alongside vector embeddings, full-text search, and document storage. Vectors are a property on nodes and edges, the same as in any property graph. What differs is where the index lives and what a single request can do with it: one request is one transaction, and it can traverse a graph, match on full-text keywords and rank by vector similarity without leaving the engine.
There is no query language to learn. Queries are plain JSON, built with the native Rust, TypeScript, Go and Python SDKs inside your own application code and sent as one POST to /v2/query, so your own type checker is what validates the query as you build it. Nothing is compiled and there is no push step before a query runs: the JSON goes over and the database turns it into the query it executes. HelixDB also includes native support for the Model Context Protocol (MCP), allowing AI agents to discover tools and query the graph step by step. For a team building a production RAG pipeline, HelixDB removes the glue code required to sync a vector store like Pinecone with a graph store like Neo4j. You store the document as a node, the embedding on that node, and the relationships to other entities in the same engine. That is the shape [agent memory]() actually wants: one request returning the relational context and the semantic match together, rather than two round trips you reconcile afterwards. The open-source core is Apache-2.0, and the same build runs fully in memory, on disk, or against object storage, meaning S3 or any S3-compatible store. That is a startup flag, not a different product.
## Head-to-Head: The Criteria That Actually Matter
When comparing HelixDB vs LadybugDB, the differences come down to how you deploy and how your agents reach the data. LadybugDB is embedded by design. HelixDB can be embedded too, and can also run as a server, which is the distinction the table is really drawing.
| Criterion | LadybugDB | HelixDB |
| --- | --- | --- |
| Language | C++ (Kuzu lineage) | Rust (From scratch) |
| Deployment | Embedded, single process, plus WASM in the browser | Embedded in memory or on disk, Local server in memory, on disk or on object storageHA distributed cloud on object storage |
| Optimised for | Complex analytical workloads on large databases (OLAP) | Transactional (OLTP) agent memory and RAG under concurrent load |
| Storage | Columnar, disk-based | In memory, on disk, or object storage, chosen at startup |
| Search Types | Graph, vector, full-text | Graph, vector, full-text, KV, range scans |
| Scoped retrieval | Vector and full-text indexes | Vector or full-text search chained onto a traversal, membership authoritative |
| Querying | Cypher | JSON built with native SDKs in Typescript, Python, Go, and Rust. No query language |
| Scaling shape | Capacity of one machine | Single writer, readers scale horizontally, object storage underneath |
The deployment shape is where these two genuinely diverge, and it is worth being precise because HelixDB runs embedded as well. The difference is that the same engine also runs as a local server and as a managed cloud, where a single writer serialises mutations and readers scale horizontally over object storage. So when a workload outgrows one process you are changing a startup flag and an endpoint rather than migrating engines. Vector indexes can also be partitioned by a tenant property, which scopes an approximate nearest neighbour search to one workspace or conversation without standing up more infrastructure. That is an index partition rather than an access-control system, so authorisation still belongs in your application.
## The Pre-Filtering Difference: Why It Changes Retrieval Correctness
Most vector databases fail when you apply a highly selective filter. If you ask for the most similar document from a specific user, a standard vector index might scan millions of items only to find that the few matching the user filter do not rank high enough in the approximate nearest neighbor (ANN) search. This leads to a silent failure where the database returns zero results even though relevant data exists. HelixDB handles this with [pre-filtering](). Because the graph and the vectors live in one engine, you start with a traversal and chain the vector search onto it, and the engine ranks only the exact members of that stream. The documented order is graph traversal, then exact candidate membership, then vector ranking, then top k, and the traversal membership is authoritative: a result outside the candidate set cannot come back. The honest caveat is that exact membership does not mean every candidate embedding was compared one by one, since approximate structures still do the ranking and the output is checked against the traversal set.
Full-text gets the same treatment, and that matters more than it sounds. Chain a text search onto a traversal and it ranks only that stream, with BM25 scores attached, in the same documented order. So a hybrid query can be scoped once and have both halves respect the scope, rather than scoping the vector side and hoping the keyword side agrees. The docs are also explicit that faking it with a whole-label search plus a filter afterwards is not equivalent, because the high scorers you excluded have already consumed the top k.
That changes what retrieval correctness means in a GraphRAG pipeline. "Documents this user may access" stops being a filter you apply hopefully afterwards and becomes the boundary of the search itself. It composes with time, too. You model history the way you would anywhere else, with timestamped nodes and edges, and range indexes over those timestamps support gt, gte, lt, lte and between plus ordered scans in either direction, so "what did this agent see between Tuesday and Thursday" is an indexed scan over a sorted range rather than a traversal you filter at the end. Chain a vector search onto that time-bounded traversal and recency and semantic relevance resolve in one request.
Here is the whole thing in TypeScript. The traversal in the middle is what does the scoping.
```
import {
g, readBatch, defineParams, param, SourcePredicate,
} from "@helix-db/helix-db";
const params = defineParams({
owner: param.string(),
query_vector: param.array(param.f32()),
limit: param.i64(),
});
const recall = readBatch()
.varAs(
"hits",
g().nWithLabelWhere("User", SourcePredicate.eq("id", params.owner))
.out("AUTHORED")
.vectorSearchWith("Document", "embedding", params.query_vector, params.limit)
.valueMap(["$id", "title", "$distance"]),
)
.returning(["hits"]);
const request = recall.toQueryRequest(
params,
{ owner: "u-42", query_vector: queryVector, limit: 10n },
{ queryName: "owned_document_matches" },
);
```
You can get back fewer rows than the limit you asked for, because the result is bounded by how many unique candidates the traversal reached. That is the guarantee working rather than a failure: nothing outside the candidate set exists to pad the list with.
## Choose LadybugDB If... Choose HelixDB If...
Your choice depends on the boundary of your application. Choose LadybugDB if the work is analytical, it fits on one machine, and you want the database inside your own process. If you are exploring a graph in a notebook, running a batch pipeline, shipping something that should not need a server running alongside it, or you need the engine to run in the browser, that is their ground, and the columnar design is lighter on memory for it. The Kuzu lineage is familiar territory if that is where you are coming from.
Choose HelixDB for agent memory in production, which is most of the reason anyone reads a page like this. It is the right call when several services write to the same memory, when retrieval has to be scoped by relationship rather than by a tag on a row, and when the thing cannot go down: the managed cloud is distributed, with a single writer, readers that scale horizontally and high availability, which is not what an in-process engine is trying to give you. The queries are ordinary functions in Rust, TypeScript, Go or Python, so a typo in a label is a build error rather than an empty result set in production. And the storage decision is a startup flag: prototype in memory, ship on S3-compatible object storage, without the query code changing.
## Conclusion
The KuzuDB archival marks a concrete change in how we think about graph infrastructure. You are no longer just looking for a way to store nodes and edges. You are looking for a reliable way to power the next generation of AI agents. LadybugDB is a reasonable landing place if the work is analytical, single-machine, or browser-bound, and it is actively maintained. For agent memory, which is the workload this page is really about, HelixDB is the better fit: pre-filtering that scopes both vector and keyword search to a traversal, a storage mode you pick at startup rather than at purchase, and a distributed cloud for when the thing has to stay up. HelixDB puts graph traversal, vector search and full-text in one transaction, and `helix init` followed by `helix start dev` gets you a local instance to point yesterday's data at. [Star HelixDB on GitHub]() if the approach is one you want to follow.
### [How to Migrate from Neo4j to HelixDB: A Migration Guide](https://www.helix-db.com/content/guides/how-to-migrate-from-neo4j-to-helixdb-a-migration-guide)
Migrate from Neo4j to HelixDB: map the graph, export a checksummed snapshot, load it with replay-safe batches, translate your Cypher, and verify before cutover.
# How to Migrate from Neo4j to HelixDB: A Migration Guide
Engineering teams building production AI agents often hit a performance ceiling with Neo4j. The typical RAG stack uses Neo4j for the knowledge graph and a separate database like Pinecone or Milvus for vector embeddings. This multi-database architecture forces developers to write complex glue code to synchronize node IDs and metadata across different network calls. Every retrieval crosses the network twice, and you own the consistency problem between the two stores for as long as you run them.
Migrating to HelixDB replaces that with a single Rust engine doing graph traversal, vector ANN and BM25 full-text search, with ACID transactions across all three. This guide is the practical version: what maps cleanly out of Neo4j, what needs a decision, how to load the data, how to rewrite your Cypher, and what you give up by leaving. We will be direct about that last part, because you are the one on call afterwards.
## Step 1: Decide Whether the Migration Is Worth It
Neo4j is the incumbent and it earned that. The tooling, the visualisation, the driver ecosystem and the size of the Cypher talent pool are all ahead of everyone else, and foundation models write good Cypher because there is so much of it to learn from. None of that changes if you leave, so be honest about whether you need to.
You should probably stay on Neo4j if your team is fluent in Cypher and productive in it, if you lean on the Graph Data Science library for algorithms or on visual exploration, if your workload is analytical rather than agent-shaped, or if your working set fits in memory and is not growing with your user count.
The reason to move is what happens when the vector side grows. Neo4j's own operations manual asks you to budget spare filesystem cache for the vector index on top of heap and page cache: roughly 40 percent of the physical index size when quantized, closer to 100 percent unquantized. That is their number, not ours, and their operations manual's memory configuration guide has the current figures. Do that arithmetic against the embedding count you expect in a year before you decide anything else.
HelixDB is built in Rust, and the case for switching is functional first and ergonomic last. You get vector pre-filtering and true hybrid retrieval inside one ACID engine, so a similarity search can be scoped to a tenant partition or to the exact set of nodes a traversal reaches, instead of sweeping a global index and discarding most of the hits afterwards. Post-filtering a global ANN result is not just slower. It can return nothing at all when the filter is selective, because the top k came back and none of it belonged to the tenant you were asking about.
Then scale. The open-source build runs three ways as a startup configuration: fully in memory, on disk, or against S3-compatible object storage. Same engine, same SDKs, same endpoint in all three, so capacity stops being the same dial as cost. Helix Cloud is the managed version of the object-storage mode, with a single writer, readers that scale horizontally, and SSD and memory caching above the bucket. That is also the answer to the uptime and availability question a platform lead will ask third.
Licence freedom is the last one and it takes a minute to check. The HelixDB open-source core is Apache-2.0, in the LICENSE file on [the repo](https://github.com/HelixDB/helix-db), which matters if you are embedding a database inside something you ship. If you want the longer side-by-side on retrieval models rather than migration mechanics, we covered that in [vector database vs graph database](https://www.helix-db.com/content/vector-database-vs-graph-database-what-ai-memory-needs) and in [HelixDB vs Neo4j](https://www.helix-db.com/content/compare/helixdb-vs-neo4j-graph-and-vector-search-in-one-engine).
## Step 2: Audit Your Neo4j Schema and Vector Indexes
Before moving any data, map your Neo4j labels and properties to the HelixDB data model. Most of it carries over unchanged, because both are labelled property graphs. Node labels stay node labels, relationship types become edge labels, properties stay properties.
Two things need a decision rather than a copy. Multi-label nodes: Neo4j lets a node carry several labels, so pick a primary one and model the rest as properties or as edges to a type node. And vectors: in HelixDB a vector is a property on a node or an edge, exactly as in Neo4j, but it has to be a top-level numeric array rather than nested inside a map. Vector indexes normalize to float32 and support cosine, euclidean and manhattan distance, and the query vector's dimension has to match the index.
Time is worth planning properly, and it maps across unchanged. You model history the way you already do in Neo4j, with timestamped nodes and edges, because graph versioning is a thing you design rather than a thing a database hands you.
What carries the load once you have modelled it is the range index. Numeric and string properties support gt, gte, lt, lte and between, plus ordered scans in either direction, so "everything this agent saw between Tuesday and Thursday" is an indexed scan over a sorted range rather than a full traversal filtered afterwards, and "the last twenty things that happened to this user" is a descending scan you can stop early. Index the timestamp fields you actually filter on when you get to step 5, and the recency half of agent memory stops being the expensive half. It composes too: chain a vector search onto a time-bounded traversal and recency and semantic relevance resolve in one request.
## Step 3: Pause Writes and Export a Snapshot You Can Check
### Export Something You Can Replay
The export is where migrations go wrong, and almost always in the same way: someone exports a graph that is still taking writes, then spends two days reconciling counts that were never going to match.
Pause every writer first. Then read the graph in one read transaction, with label-scoped queries rather than one query for the whole thing, and sort every record by its stable ID so two exports of the same data produce the same file. Write a SHA-256 sidecar next to it and keep the two together.
Version the snapshot and discriminate every record by kind, so an unsupported or ambiguous record fails at the door instead of halfway through the load:
```json
{
"version": 1,
"exportedAt": "2026-08-11T00:00:00.000Z",
"nodes": [
{ "kind": "document", "documentId": "d-q3-board", "title": "Q3 board notes", "embedding": [0.021, -0.118] },
{ "kind": "entity", "entityId": "e-acme", "name": "Acme", "type": "Organisation" }
],
"relationships": [
{ "kind": "mentions", "relationshipId": "r-q3-acme", "fromDocumentId": "d-q3-board", "toEntityId": "e-acme", "count": 3 }
]
}
```
Note what is not in there: Neo4j's internal node and relationship IDs. Do not migrate them. They are not stable across a restore, and a migration keyed on them is a migration you cannot safely replay. Use the business IDs already on your nodes, and if your relationships have no stable ID of their own, add one before you export. Every idempotent step later in this guide depends on that ID existing.
### Write Down What You Are Actually Moving
A typical GraphRAG schema on the Neo4j side looks something like this. Write yours out before you touch anything, because the migration is mostly this document turned into code.
```cypher
// constraints and indexes on the source
CREATE CONSTRAINT doc_id IF NOT EXISTS
FOR (d:Document) REQUIRE d.id IS UNIQUE;
CREATE VECTOR INDEX doc_embedding IF NOT EXISTS
FOR (d:Document) ON (d.embedding)
OPTIONS {indexConfig: {
`vector.dimensions`: 1536,
`vector.similarity_function`: 'cosine'
}};
// the shape you are moving
(:Document {id, title, text, embedding, createdAt})
(:Entity {id, name, type})
(:Document)-[:MENTIONS {count}]->(:Entity)
(:Document)-[:REFERENCES]->(:Document)
```
Get the inventory out of the database rather than out of your memory of it:
```cypher
CALL db.labels();
CALL db.relationshipTypes();
SHOW INDEXES;
MATCH (d:Document)
RETURN count(d) AS docs,
size(head(collect(d.embedding))) AS dimension;
```
That last query gives you the embedding dimension you have to declare on the HelixDB side. It is the single most common thing people get wrong, and you find out at load time rather than at design time.
### Getting the Data Out
A Neo4j native `.dump` is their backup format, and HelixDB cannot load it. Their dump and restore documentation covers what it is actually for. What you want is a logical export you transform explicitly.
The Neo4j driver plus label-scoped Cypher is the straightforward path, because it puts the shape of the output under your control and lets you sort and check as you go. If your team already runs APOC, short for Awesome Procedures On Cypher, Neo4j's standard extension library where the export procedures live, its JSON export works as a source too, because it preserves array types and CSV does not. File export is off by default and enabled in `apoc.conf`, and the file lands in the import directory rather than wherever you ran the query from.
```cypher
CALL apoc.export.json.all("graph.json", {useTypes: true});
```
Either way, treat the output as an intermediate. You still transform it into the versioned snapshot above, because that is the artefact everything downstream is checked against.
### If You Are Coming from Neptune Instead
Everything after the export is a transformation script, so the rest of this guide holds whatever the source is. Only this step changes.
Amazon Neptune exports through neptune-export, which runs either as a managed service or as a command-line utility, documented in the AWS Neptune user guide. Property-graph exports publish to S3, with node data split into separate files by label combination, so your transformation reads a directory rather than one file.
One line in their docs should shape your cutover plan rather than surprise you during it: AWS state that if the cluster's data changes during an export, the consistency of the exported data is not guaranteed, and the fix they offer is to have the job clone the cluster and export from the clone. That is the same reason to pause writes before the snapshot, arriving from the other direction.
Verify that your embeddings are included in the export. Some teams store large vector arrays in a separate service. If that is your case, join the export with your vector store export on a common ID field, because HelixDB expects them in the same record. This is also the right time to strip out legacy properties and orphan nodes that have accumulated in your graph.
## Step 4: Validate the Snapshot Before You Write Anything
Run the validation while Neo4j writes are still paused, and run it against the file rather than against the database, so a failure costs you a re-export and not a half-loaded target.
Check the checksum, the dump version, the exact property types, that node and relationship IDs are unique, that arrays you rely on are not empty, and that both endpoints of every relationship actually exist in the node set. The failures you want to catch here read like this:
- `duplicate Document.documentId: d-q3-board`
- `r-q3-acme references missing Entity e-acme`
- `checksum mismatch for graph.v1.json`
- an unknown `version` or `kind`
If validation fails, fix the exporter or the mapping and take a new snapshot. Do not hand-edit the dump to get past a check. The point of the checksum is that the file you validated is the file you loaded, and an edited dump quietly gives that up at the exact moment you would want it.
## Step 5: Install HelixDB and Create Your Indexes
Scaffold a project and bring up a local instance:
```bash
mkdir helix-migration && cd helix-migration
helix init
helix start dev
```
That gives you an instance on port 6969 speaking the same interface Helix Cloud does.
[Run mode](https://docs.helix-db.com/database/helix-db/start-here/run-modes) is a startup flag, not a product tier. In-memory is the default, `--disk` gives you a persistent local run, and the same engine runs against S3 or any S3-compatible object storage. Prototype the migration in memory, re-run it on disk, ship it against object storage, without the loading script changing.
While you are set up, install the agent skills:
```bash
helix skills install
```
Those are query-authoring skills, including `helix-query-typescript`, `helix-query-rust` and `helix-memory-system`, that a coding agent reads so it writes real HelixDB queries instead of guessing at an API. On a migration you are rewriting every read path you own, which is exactly the job worth handing an agent that has the current API in front of it. They install globally to `~/.agents/skills`, or into the project with `--project`, and the [CLI command reference](https://docs.helix-db.com/cli/command-reference) has the rest of the surface.
There is no schema file and no compile step. Indexes are created by a write query, with the same SDK you write and read everything else with. For a GraphRAG workload that is usually a vector index on the property holding your document embeddings, plus range indexes on the timestamp fields you filter on.
```ts
import { writeBatch, g, VectorDistanceMetric } from "@helix-db/helix-db";
writeBatch()
.varAs(
"index",
g().createVectorIndexNodes(
"Document",
"embedding",
1536,
VectorDistanceMetric.Cosine,
null,
),
)
.returning(["index"]);
```
The arguments are the node label, the property holding the embedding, the dimension, the distance metric, and a tenant property to partition the index on. Pass null for a global index. Cosine, euclidean and manhattan are the available metrics, and the dimension has to match your vectors exactly, which is why you counted it in step 3. The [vector index guide](https://docs.helix-db.com/database/helix-db/query-guides/vector-indexes) has the full lifecycle.
You want equality indexes as well, on the identity properties the snapshot is keyed on: one per node label on its business ID, and one on `relationshipId` for each edge label. Those are what make the load idempotent and the verification cheap. Submit them with `createIndexIfNotExists` so re-running the setup is harmless.
Then wait for them. Index creation is asynchronous, and a request coming back means it was accepted, not that the index is usable. Parse the operation ID from each response, poll `getIndexOperation` until every status reads succeeded, and stop if one comes back blocked or aborted or times out. Starting the node batches because the index request was accepted is the fastest route to a load you have to throw away.
Create the indexes before the bulk load rather than after. Index creation returns before the backfill has necessarily finished and a new generation stays invisible until it validates and activates, so it is easier to have the load write into an index that already exists than to wait on a backfill over everything you just inserted.
The engine is written from scratch in Rust and it is OLTP, so what you are migrating to is a database you can write to under load, not a read-only analytics copy. If you are going straight to Helix Cloud, point the CLI at your cloud endpoint instead of a local instance. Everything below is identical either way, which is the whole point of the run modes.
## Step 6: Transform and Load Your Data into HelixDB
Convert the Neo4j JSON export into HelixDB writes. Every operation, bulk loads included, is a JSON envelope sent as one POST to /v2/query. You do not hand-write that JSON. You build the query with the native Rust, TypeScript, Go or Python SDK inside your own transformation script and the SDK serializes it. Nothing is compiled and nothing is generated.
Load every node before you load any edge, and key both passes on the stable IDs from step 3 rather than on anything Neo4j generated. That is what makes the load replayable.
Make the node write an upsert rather than an insert. Look for the node by its business ID, update it if it is there, create it if it is not, and the same batch can run twice without duplicating anything:
```ts
import {
BatchCondition,
g,
NodeRef,
Predicate,
PropertyInput,
writeBatch,
} from "@helix-db/helix-db";
const body = writeBatch()
.varAs(
"existing",
g().nWithLabel("Document").where(Predicate.eqParam("documentId", "documentId")),
)
.varAsIf(
"updated",
BatchCondition.varNotEmpty("existing"),
g()
.n(NodeRef.var("existing"))
.setProperty("title", PropertyInput.param("title"))
.setProperty("embedding", PropertyInput.param("embedding")),
)
.varAsIf(
"created",
BatchCondition.varEmpty("existing"),
g().addN("Document", {
documentId: PropertyInput.param("documentId"),
title: PropertyInput.param("title"),
embedding: PropertyInput.param("embedding"),
}),
);
const request = writeBatch()
.forEachParam("rows", body)
.returning(["updated", "created"])
.toQueryRequest(rowsParams, { rows }, { queryName: "upsert_documents" });
```
Relationships follow the same shape, keyed on `relationshipId`: drop the existing edge by ID and write it again, so a replay replaces rather than duplicates. Because nodes land first, both endpoints are already there to attach to.
One HelixDB request is one transaction. If a request fails, nothing in that batch committed, so once the writes themselves are idempotent a failed batch is safe to retry whole. Retry the complete batch on an HTTP 409 conflict rather than picking through it for the rows that made it. Keep batches bounded, a few hundred to a thousand operations, because an oversized batch turns one bad record into a rollback of everything you just sent. The [write batch semantics](https://docs.helix-db.com/database/helix-db/query-guides/writing-data) are worth reading before you pick a size.
Run one loader process against a fresh target. Sequential replay is safe, but edge equality indexes are not uniqueness constraints, so two loaders racing each other can still produce duplicates that neither of them notices. An interrupted load is fine: rerun it and the upserts settle. The Python SDK fits neatly here if your ETL already lives in Python.
## Step 7: How Do I Rewrite a Cypher Query Without Cypher?
Your Cypher does not carry over, and there is no HelixDB query language to learn in its place. Queries are built with the SDK in whatever language your service is already written in, then serialized to JSON and sent in one request. A Cypher string you concatenated and shipped over Bolt becomes a builder chain your own compiler checks.
Translate behaviour, not tokens. For each query, write down five things before you touch the builder: which property is the indexed anchor, which way the edges run, which edge properties the result needs, which fields come out, and how the rows are ordered. Then keep the repository interface your application already calls and replace only the adapter underneath it. That gives the migration a real finish line: it is done when both implementations return equal objects, not when the new code compiles.
Two builder shapes cover most of the work. `project` pulls named fields off whatever the stream is currently standing on, and on an edge stream `Projection.fromEndpoint` reaches through to the node at the other end, which is how a Cypher pattern comprehension that collects the documents pointing at an entity becomes one edge traversal. When you need fields from both the edge and the node it leads to, bind them and project by binding name: `.outE("MENTIONS").bind("mention").outN().bind("entity")`.
One difference to plan for rather than discover: HelixDB does not order rows after a binding projection, so a Cypher query ending in an ORDER BY over collected rows gets its sort in the adapter instead. That is a few lines in the repository, not a redesign, but it is much better found while you are writing the query than while you are diffing results.
```ts
// Cypher:
// MATCH (u:User {id: $uid})-[:AUTHORED]->(d:Document)
// RETURN d LIMIT 20
import { readBatch, g, SourcePredicate } from "@helix-db/helix-db";
readBatch()
.varAs(
"docs",
g()
.nWithLabelWhere("User", SourcePredicate.eq("id", uid))
.out("AUTHORED")
.limit(20)
.valueMap(["$id", "title"]),
)
.returning(["docs"]);
```
This is the part of the migration an agent is genuinely good at, and the reason to install the skills in step 5. The translation is mechanical once you know the builder names, and mechanical plus repetitive across a whole codebase is the shape of work worth delegating. Read what it produces, though. The traversal semantics carry over from Cypher almost directly; the filtering semantics do not, because a source predicate that can be pushed down to an index is a different method from a predicate that filters the stream afterwards.
The retrieval queries are where the migration actually pays. In Neo4j a GraphRAG step is usually a `CALL db.index.vector.queryNodes` for the semantic half, a `MATCH` for the structural half, and application code stitching the two together. In HelixDB both halves are operations in the same request against the same engine, so there is no window where one side has moved and the other has not.
```ts
import { defineParams, param } from "@helix-db/helix-db";
const params = defineParams({
uid: param.string(),
query_vector: param.array(param.f32()),
limit: param.i64(),
});
readBatch()
.varAs(
"hits",
g()
.nWithLabelWhere("User", SourcePredicate.eq("id", params.uid))
.out("AUTHORED")
.vectorSearchWith("Document", "embedding", params.query_vector, params.limit)
.valueMap(["$id", "title", "$distance"]),
)
.returning(["hits"]);
```
That is the query worth migrating for, so be precise about what it does. The traversal runs first and defines an exact candidate set, the vector ranking runs over that set, and then you take the top k. Traversal membership is authoritative: a result outside the candidate set cannot come back. That is the opposite of the usual arrangement, where you take a global top k and filter it afterwards and a selective filter hands you an empty list because none of the k belonged to the user you asked about.
[Exact membership](https://docs.helix-db.com/database/helix-db/query-guides/filtering) here means the output is validated against the traversal set, not that the engine compares every candidate embedding by brute force. Approximate structures still do the ranking. Two other requirements are easy to miss: the candidate label and property need a compatible vector index at the right dimension, and you should project `$distance` before traversing away from a ranked hit or it will not survive into the response. If the index is tenant-partitioned, build the candidate stream from the same partition the index was built with. Expect fewer rows than your limit sometimes, too, because the result is bounded by the number of unique candidates the traversal reached.
All four SDKs emit the same JSON, so a Go service and a TypeScript service see the same query surface. In TypeScript, Rust and Python the call picks the node or edge form from the traversal state it is standing on; Go spells the two out separately.
## Step 8: Verify Parity and Cut Over
Run the same repository calls against both databases and compare the objects that come back. Node and edge counts by label, properties, relationship directions, edge values, and the full result of every read path your application actually uses.
Do not cut over on counts alone. Equal counts hide reversed edges, missing properties and changed ordering, and all three of those pass a count check and then fail in production. While you are there, replay the entire snapshot a second time and confirm nothing moves. That is the cheapest proof that the load is genuinely idempotent, and it is the thing you will want to be sure of if the cutover goes long and you need to re-run it.
Retrieval is worth checking on its own terms. Run a vector search per index to confirm each one answers at the right dimension, and compare ranked results against your Neo4j baseline. Expect small ranking differences, because the two engines use different index structures. What you are looking for is not identical order, it is the same documents coming back for the same question.
Keep writes paused through the final verification, then change the dependency injection in your application from the Neo4j repository to the HelixDB one, deploy, and run smoke tests through the real API rather than against the database. Keep the source snapshot until the rollback window closes.
If you cannot take a maintenance window, the shape changes but the steps do not: take the snapshot, then keep a change stream or dual writes running against both databases, drain the remaining changes, and verify before you switch. The changes still have to arrive as the same idempotent writes the loader uses, which is the other reason to build the load that way.
Measure the latency of your own pipeline afterwards rather than trusting anyone's number, ours included. What you removed is a network hop and a synchronisation step, so the size of the win depends entirely on how much of your latency lived there.
## Migration Checklist
- Every node and relationship has a stable application ID, and no Neo4j internal IDs are being migrated.
- Writes are paused for the snapshot and for the final cutover.
- Multi-label nodes have an explicit single-label mapping.
- The checksum and the schema validation both pass before any write.
- Every index reads succeeded before the first node batch.
- Nodes load before relationships.
- A full replay produces no duplicates.
- Counts, directions, properties, edge values and repository results all match.
- The application runs its smoke tests against HelixDB.
- The source snapshot is retained for the rollback window.
## Conclusion
Migrating from Neo4j to HelixDB makes sense for teams that have outgrown the duct-tape approach to AI memory. Consolidating your knowledge graph, vector search, and metadata into a single Rust engine removes the operational complexity and high latency of multi-database retrieval. You end up with one engine to run, one place where the data is consistent, and a storage mode you pick at startup rather than at purchase.
If you are tired of managing separate clusters for every data type in your RAG pipeline, `helix init` and `helix start dev` will have a local instance up in a couple of minutes, and you can point yesterday's export at it. [Star HelixDB on GitHub](https://github.com/HelixDB/helix-db) if the approach is one you want to follow.
### [Pre-Filtering Vector Search on Graph Edges: How to Scope ANN to Relationships](https://www.helix-db.com/content/guides/pre-filtering-vector-search-on-graph-edges-how-to-scope-ann-to-relationships)
Learn how to scope vector search on graph edges for precise RAG. Move beyond flat ANN scans by filtering embeddings within specific relationships and subgraphs.
Most engineers start their AI journey by dumping document chunks into a flat vector database like Pinecone. This works until the agent needs to answer a question that requires structural context. If a user asks for messages similar to a specific bug report but only within the React project, a global search returns the nearest neighbors from the entire corpus. You end up with documents about Vue or Angular because they are semantically close, even though they are structurally irrelevant.
This guide shows you how to move beyond flat search. We will cover how to implement vector search on graph edges to scope approximate nearest neighbor (ANN) retrieval to specific relationship types or subgraphs. You will learn how to attach embeddings directly to edges, and how to scope a search so the results come back both semantically similar and structurally valid. By the end you will be able to build retrieval logic that combines graph structure with vector recall in a single engine.
## Step 1: Understand Why Global ANN Breaks in Relational Contexts
Global vector search assumes all data points live in the same bucket. When you query a standard vector index, the engine calculates distances across every single point in the embedding space. This approach fails the moment your application requires multi-tenancy or complex entity relationships. We went through that trade-off in [vector database vs graph database](). The short version is that a flat index cannot respect a boundary without expensive post-filtering.
Traditional ANN algorithms like HNSW are designed to find the closest points in a high-dimensional space. They do not naturally understand that Point A is a message sent by Alice and Point B is a comment on a Jira ticket. If Alice asks a question about her own files, a global search might return files from Bob because their embeddings are statistically similar. You then have to filter these results in application code, which often leads to the empty result problem. If the top 100 neighbors are all Bob's files, Alice gets zero relevant results after filtering.
In production, structural relevance is usually more important than raw semantic similarity, and a global search has no idea the graph exists. The point generalises past any one engine: if you can restrict the candidate set by relationship before you calculate distance, you get results that are both structurally valid and semantically close. If you cannot, you are picking one and hoping for the other. What you want is a search space that is already narrowed to the right part of the graph by the time the vector comparison runs.
## Step 2: Attach Embeddings to Edges, Not Just Nodes
The standard way to model data is to put embeddings on the nodes. You might have a Document node with a vector representing its content. This works for simple retrieval, but it ignores the richness of how entities interact. Attaching embeddings to edges lets you search for relationships themselves. Imagine an edge type called MENTIONS that connects a Slack message to a specific project. By putting the vector search on graph edges, you can query for the most similar mentions within a specific context.
This shift in modeling changes the retrieval pattern. Instead of asking for similar nodes, you ask for similar interactions. If you are building [agent memory](), you might want to retrieve past conversations where a user expressed a specific sentiment about a feature. The sentiment is the edge. By embedding the interaction rather than the static document, you capture the dynamic state of the knowledge graph.
This is not exotic. Memgraph supports vector indexes on both nodes and edges, and so does HelixDB. The part worth understanding is what declaring the index over an edge label actually buys you: the search space is defined by the relationship type before any distance is calculated, because the index only ever contained embeddings from that one edge label. You are not filtering a global result set down to the COMMENTED_ON edges. There was never anything else in the index to begin with.
In HelixDB you declare a vector index over the label and property you intend to search, then hop onto the edge stream and rank it. The SDKs pick the node form or the edge form of the search from whatever the traversal is currently standing on, so an edge hop followed by a vector search ranks edges. Queries are plain JSON built from your own application code, so there is no second system to keep in step and no ID-mapping layer between the graph and the vectors.
## Step 3: Choose Your Scoping Strategy: Pre-Filter vs Post-Filter
When you scope a vector search, you have two technical paths: post-filtering and pre-filtering. Post-filtering is the naive approach. You perform a global ANN search, get 100 results, and then throw away the ones that do not match your graph criteria. This is dangerous. If your graph filter is restrictive, such as looking for files owned by a single user in a million-user system, you will likely end up with zero results. The ANN index will simply not find the needles in the haystack if they are far away from the global centroid.
Pre-filtering is the better shape for scoped retrieval: narrow the candidate set first, then search inside it, so everything that comes back is already valid. The idea is not new. Qdrant's filterable HNSW is a well-known implementation of it, keeping the walk inside the permitted partition rather than discarding hits afterwards, and their indexing documentation is worth reading if you want the mechanics. What most vector databases give you, though, is a flat metadata filter. The partition is a tag on a row, not a relationship.
HelixDB gives you three ways to pre-filter, and they differ in how much you have to decide up front.
The first is the traversal itself, and it is the one to reach for when membership is a correctness requirement rather than a tuning choice. You start with a node or edge traversal, then chain the vector search onto it, and the engine ranks only the exact members of that stream. The [documented order]() is graph traversal, then exact candidate membership, then vector ranking, then top k. The guarantee is the part worth reading twice: the traversal set is authoritative, and a result outside the candidate set cannot be returned. So "documents this user may access" stops being a filter you apply hopefully afterwards and becomes the boundary of the search itself. The docs are blunt about the alternative: running a search across the whole label and then applying a `where` clause is not the same thing, because the excluded high scorers have already consumed the top k and you are left with fewer eligible results than you asked for. Build the candidate stream first.
The second is tenant partitioning. Declare the index with a tenant property and the ANN search runs inside one partition rather than across the whole indexed label. Leave the property off at creation and the index is global. The two compose rather than compete: scoping by traversal against a partitioned index means the candidate stream has to be built from the same partition the index was. That is how you say "closest match semantically, but only inside this workspace".
The third is the edge vector index from the previous step. An index declared over a relationship type is scoped to that relationship by construction, before any query runs.
Reach for the traversal when relationships, permissions, or an earlier filter define who is eligible. Use a source-level search when the whole indexed label, plus any tenant partition, already is the candidate pool. And constrain the candidate traversal if it could grow unbounded, because everything it reaches is work the ranking has to carry.
## Step 4: Build the Scoped Query in HelixDB (JSON + SDK)
HelixDB has no query language at all. Queries are plain JSON, or built with the native Rust, TypeScript, Go, or Python SDKs inside your own application code, and sent as one POST to /v2/query.
There are two steps. Declare the index once at setup, then search it. Index creation is a write query rather than a method on the client, so it goes inside a write batch like any other mutation.
```
import {
g, readBatch, writeBatch, defineParams, param,
SourcePredicate, VectorDistanceMetric,
} from "@helix-db/helix-db";
// Setup: declare the index over the label and property you will search.
// The final argument is the tenant property; null leaves the index unpartitioned.
const index = writeBatch()
.varAs(
"index",
g().createVectorIndexNodes(
"Comment", "embedding", 1536, VectorDistanceMetric.Cosine, null,
),
)
.returning(["index"]);
// Query: walk to the comments on this project, then rank only those.
const params = defineParams({
slug: param.string(),
query_vector: param.array(param.f32()),
limit: param.i64(),
});
const recall = readBatch()
.varAs(
"matches",
g().nWithLabelWhere("Project", SourcePredicate.eq("slug", params.slug))
.out("COMMENTED_ON")
.vectorSearchWith("Comment", "embedding", params.query_vector, params.limit)
.valueMap(["$id", "body", "$distance"]),
)
.returning(["matches"]);
const request = recall.toQueryRequest(
params,
{ slug: "react", query_vector: queryVector, limit: 10n },
{ queryName: "project_comment_matches" },
);
```
The traversal in the middle is doing the scoping. Without it, the same search ranks every comment you have. With it, the ten results come from the comments on that one project and nothing else can appear. You can also get back fewer than ten, because the result is bounded by the number of unique candidates the traversal actually reached. A thin subgraph returns what it has rather than padding the list from somewhere else.
Swap `.out` for `.outE` and the stream is edges rather than nodes, and the same search call then ranks the embeddings sitting on those relationships, because the SDKs choose the node or the edge operation from whatever the traversal is standing on. Go is the exception and spells them out as `VectorSearchNodesWithin` and `VectorSearchEdgesWithin`. The `With` suffix means the call takes typed parameters; `vectorSearch` is the same operation with the values written inline. Keep `$distance` in a projection before you traverse past a ranked hit or you lose it. Indexes support cosine, euclidean and manhattan distance, the declared dimension and every query vector have to match exactly, and vector properties have to be top-level rather than nested. [Index creation]() can also return before the backfill finishes, and a new generation stays hidden until it validates and activates, so an empty result straight after creating an index is not a bug.
Run `helix init` and then `helix start dev` to get a local instance up and test this. The open-source build [runs three ways]() and you pick one at startup: fully in memory, on disk, or against S3-compatible object storage. The engine, the SDKs, and the endpoint are identical in all three, so the query above does not change when you move from a laptop to production.
The builders are ordinary functions in your own language, so a typo in a label is a build error rather than an empty result set in production. That is a narrower failure mode than assembling a query string and finding out at runtime. Because full-text search and KV lookups run in the same engine, you can also mix a keyword match into the same request.
## Step 5: Validate Recall Under Tight Scopes
One of the biggest hurdles in vector search on graph edges is ensuring high recall when the subgraph is small. HNSW indexes rely on a connected graph of vectors. When you filter by a specific relationship, you are essentially removing most of the points in that index for the duration of the query. If the remaining points are not well-connected in the HNSW graph, the search algorithm might fail to find the actual nearest neighbor. This is the disconnected graph problem in ANN.
This is a general property of filtered ANN, not a quirk of any one engine: the effectiveness of a filtered search depends on the ratio of the filtered set to the total population. Search a partition holding a tiny fraction of your corpus and a graph-based index has fewer usable edges to walk, so recall degrades. The usual levers are exploring more candidates at query time, or falling back to an exhaustive scan once the candidate set is small enough that scanning it is cheap.
The practical advice is the same whatever you are running on. Pick your partitions so they are not pathologically small, and measure. Compare scoped results against a known ground truth on a small development subgraph before you scale to millions of nodes, because a filtered search that quietly returns the second-best answer looks exactly like one that returns the best.
## Step 6: Extend the Pattern: Multi-Hop Scoped Retrieval
Single-hop scoping gets you most of the way, but the questions agents actually get asked are multi-hop. Find the security whitepapers written by engineers who worked on the same project as the current user. That is a traversal from User to Project to Engineer, and then a similarity search over what those engineers wrote.
This is the shape prefiltering exists for. You walk User to Project to Engineer, then chain the vector search onto the end of that walk, so the ranking runs over the engineers the traversal actually reached and over nothing else. It is one request against one store, with no round trip to a second database and no ID list shuttled between them. The membership guarantee holds across the hops: a whitepaper written by someone the traversal never reached cannot come back, however close its embedding sits.
What to watch on multi-hop is the size of the candidate set rather than its correctness. Two hops out of a well-connected node can fan out a long way, and everything it reaches is work the ranking carries. Constrain the traversal before the search when the fan-out is unbounded.
That composition is what a company brain needs. It keeps the agent from surfacing chunks that are semantically plausible but belong to a project the user has nothing to do with. The precision comes from the structure, not from a better embedding model.
HelixDB exposes native MCP endpoints, so an agent can discover the graph structure and walk it step by step rather than being handed one opaque query. The agent explores the neighbourhood, works out which relationship it cares about, and runs the scoped vector search against that edge index.
## Conclusion
Scoping vector search to graph edges turns a generic retrieval system into a context-aware memory engine. Most RAG pipelines fail because they lack structural grounding, which leads to hallucinations or irrelevant results. By letting the traversal define who is eligible before any distance is calculated, you keep your agents inside the right context rather than filtering your way back to it afterwards. You no longer need to manage the complexity of syncing data between three different databases just to run a simple filtered search.
HelixDB was built to remove that duct tape. Graph traversals and vector search run in one engine, so the scope and the similarity search are not two systems you keep in step. If you are tired of the overhead of a separate vector store and graph store, `helix init` and `helix start dev` get you an instance to try this against, and you can [star HelixDB on GitHub]() if the approach is one you want to follow.
### [HelixDB vs FalkorDB: Choosing a Graph Database for GraphRAG](https://www.helix-db.com/content/compare/helixdb-vs-falkordb-choosing-a-graph-database-for-graphrag)
HelixDB vs FalkorDB for GraphRAG: in-memory speed against object-storage scale. Compare pre-filtering, high availability, licensing and what each one costs.
Building a RAG pipeline in 2026 starts with a hard choice. You either chunk your data into a vector store and hope semantic similarity finds the right context, or you build a knowledge graph to map real relationships. Most engineers start with the former and quickly realize its limits. Vector search alone creates a goldfish mode for AI agents. The agent might find the right paragraph, but it loses the connection to the person who wrote it, the project it belongs to, or the timeline of changes.
GraphRAG solves this by combining the semantic power of embeddings with the structural precision of a graph. FalkorDB and HelixDB are both aimed squarely at engineers building that architecture, and they have made opposite bets about what matters.
FalkorDB bets on latency. It is a fork of RedisGraph, the whole graph lives in memory, and their marketing leads with speed. HelixDB bets on scale: object storage underneath, so the data can grow without all of it being hot, and thousands or millions of concurrent requests are a matter of adding readers. Both bets are coherent. Which one is right for you depends on whether your bottleneck is microsecond latency, or terabytes of data and thousands of concurrent requests.
## Same Target, Different Bets: What This Comparison Is Actually About
Both databases target the shift from naive RAG to GraphRAG. The core problem is context fragmentation. When an agent queries a standard vector database, it retrieves orphaned text chunks: the right paragraph with none of the structure around it. A graph keeps the relationships that top-k similarity throws away, which is why engines like FalkorDB and HelixDB exist at all.
Worth saying plainly up front, because most comparison posts dodge it: this is a genuine head-to-head. FalkorDB is not aimed at a different workload. They describe themselves as a knowledge graph for LLMs, they ship a GraphRAG SDK, and they integrate with LangChain and LlamaIndex. They want the same reader this post is written for. So the honest question is not who is for agents, it is which trade-offs you prefer.
So the real difference is what each one optimises. FalkorDB's primary focus is speed, and they are good at it. As a RedisGraph fork it keeps the entire graph resident in memory, which is how you get traversals measured in microseconds. Their site at falkordb.com is explicit that GraphRAG is the target, and they have the integration maturity to back that up.
Here is the part worth arguing with, and we will be blunt about our own position: for an agent workload, that latency advantage is mostly invisible. The gap between a 500 microsecond traversal and a 2 millisecond one disappears inside an LLM call that takes hundreds of milliseconds. Meanwhile the things that do decide whether an agent product works, whether the memory can keep growing, whether it stays up, and what it costs when it does both, are exactly the things an in-memory architecture makes hard.
HelixDB optimises for that instead. Vectors are properties on nodes and edges, the same shape you would model anywhere else. What differs is that the durable copy lives in object storage with memory as a cache in front of it, so not all of your data has to be hot to be queryable. Add pre-filtering and BM25 full-text in the same ACID engine and you get genuine hybrid retrieval rather than a graph store you bolt things onto. The repo is at github.com/HelixDB/helix-db, and we went through the underlying category question in our post on what AI memory actually needs.
FalkorDB wins on integration maturity and raw traversal latency. HelixDB wins on scalability, availability, cost at volume, hybrid retrieval, and licence freedom. That is the trade, stated plainly.
## Architecture and Storage Model: Sparse Matrices in RAM vs Object Storage
The internal mechanics dictate what each engine can do at scale. FalkorDB is built on GraphBLAS, representing graphs as sparse matrices and performing traversals with linear algebra. It is mathematically elegant and genuinely fast, and for PageRank or deep path-finding the matrix approach is hard to beat.
The consequence is where it stores things. FalkorDB descends from RedisGraph and keeps the graph in memory, and its vector index sits in memory alongside it. That is the source of the speed, and it is not an accident or an oversight; it is the design. Their own plans page makes the shape visible: continuous persistence is a feature of the Pro tier and above, not something the cheaper tiers have.
So the ceiling is your RAM, and the bill tracks it. Their pricing is quoted per gigabyte of memory. That is a reasonable trade for a bounded working set and a poor one for agent memory, where the corpus grows with every user and conversation and most of it is cold most of the time. You end up paying memory prices to store data nobody is querying today.
HelixDB inverts it. Graph traversal, vector similarity and BM25 full-text run in one Rust engine, so there is no stitching between a vector index and a graph index and no second system to fall behind. The durable copy sits in object storage and memory is a cache in front of it, which means capacity stops being a function of how much RAM you are willing to rent.
Storage is a startup configuration rather than a fixed property of the engine. The open-source build runs three ways: fully in memory, on disk, or against object storage, meaning S3 or any S3-compatible store. Same engine, same SDKs, same POST /v2/query interface across all three, so you can prototype in memory and ship against a bucket without touching any of your application code. That matters for the query shape agent memory actually needs, where you want a user's recent history, their related projects and a semantic match in one round trip. We went deeper on that in our post on AI agent memory architecture.
Helix Cloud is the high availability, managed version of that object-storage mode. A single writer serializes mutations, readers scale horizontally, and durable state lives in object storage with SSD and memory caching on the compute nodes above it. Capacity, latency and concurrency end up as three separate dials rather than one. Our HelixDB vs Neo4j comparison works through the same storage argument against a different incumbent.
## What Does FalkorDB Cost Compared to HelixDB?
Different shapes, so compare the shape as well as the number. These are their published figures as of August 2026; check both vendors before you commit, since cloud pricing moves.
FalkorDB sells memory. Their plans page lists four tiers:
| Tier | Price | Memory | What it adds |
| --- | --- | --- | --- |
| Free | $0 | 100 MB | Multi-graph and multi-tenancy, graph access control, community support. No TLS, no continuous persistence, no high availability. |
| Startup | from $73 a month | 1 GB | TLS, automated backups every 12 hours. Still no cluster, no high availability, no continuous persistence. |
| Pro | from $350 a month | 8 GB | Cluster deployment, high availability, multi-zone, continuous persistence. Business-hours support. |
| Enterprise | tailored | custom | VPC, advanced monitoring, dedicated account manager, 24/7 support. |
Two things in that table matter more than the headline prices.
First, high availability starts at the Pro tier. If you are running an agent product on Startup, you are on a single in-memory instance whose backups run twice a day, and their own table says continuous persistence is not included at that tier. That is a data-loss window you should size before you ship, not after.
Second, look at the unit. $73 buys one gigabyte of memory per month. That is the same pricing model we walked through in our Memgraph comparison, and it has the same consequence: capacity and cost are the same dial, so the bill grows in lockstep with the corpus whether or not anyone is reading it.
HelixDB sells usage. A standard GA tenant starts at $5 for a million reads and 100,000 writes a month, with no separate storage charge, and it is highly available by default rather than at a tier. A dedicated highly available cluster is $1,600 a month for three database nodes and three gateway nodes with bottomless storage behind them.
Put the two side by side and the comparison is not really about which number is smaller at the bottom of the range. It is that one vendor charges you for provisioned memory and gates availability behind a tier, and the other charges for the queries you actually make and treats availability as the default. For a corpus that grows with your user count, only one of them tracks the workload.
## Query Interface: Cypher Strings vs Native SDK Builders
This one is a genuine difference but it is not the reason to switch, so treat it as a preference rather than an argument. FalkorDB relies on OpenCypher, the industry standard for graph queries. If you have spent years working with Neo4j, you will feel at home. Cypher is declarative and uses ASCII-art style syntax to describe patterns. This makes it expressive for data scientists. However, Cypher can be difficult to integrate into modern CI/CD pipelines because queries are often just strings passed to the database. There is no built-in way to catch a typo in a property name until the code runs and fails in production.
HelixDB has no query language at all. You build queries with the native Rust, TypeScript, Go or Python SDK, in the same files as the rest of your application code. Nothing is compiled and nothing is generated. The builder serializes to a JSON envelope that goes out as one POST to /v2/query, and you can hand-write that JSON if you prefer.
```
import { g, readBatch, SourcePredicate, defineParams, param } from "@helix-db/helix-db";
const params = defineParams({
owner: param.string(),
query_vector: param.array(param.f32()),
limit: param.i64(),
});
// walk to this user's documents, then rank only those
const recall = readBatch()
.varAs(
"docs",
g().nWithLabelWhere("User", SourcePredicate.eq("id", params.owner))
.out("AUTHORED")
.vectorSearchWith("Doc", "embedding", params.query_vector, params.limit)
.valueMap(["$id", "title", "$distance"]),
)
.returning(["docs"]);
const request = recall.toQueryRequest(
params,
{ owner: "u-42", query_vector: queryVector, limit: 10n },
{ queryName: "owned_document_matches" },
);
```
The SDKs for TypeScript, Rust, Go and Python all emit the same JSON structure, so the experience is consistent across languages and you do not learn one syntax for vector filtering and another for graph hops. There is a helix CLI for getting a local instance up: helix init to scaffold, then helix start dev. FalkorDB ships a dedicated GraphRAG SDK aimed at Python users, which is a faster path if you want a prescriptive pipeline rather than to assemble your own.
## Indexing for GraphRAG: Vector, Full-Text, and Range Support Side by Side
Indexing is where RAG performance lives or dies. FalkorDB provides integrated vector support, allowing you to store embeddings directly on nodes. It uses HNSW for fast similarity search. The genuine benefit of FalkorDB here is that graph and vector live in the same system, which removes the need to keep a separate vector store in sync. But co-location is not the same as native integration. Without pre-filtering, you cannot scope a vector search to a graph-filtered candidate set — the ANN sweep always runs across the full index first. That blocks the retrieval pattern that matters most for GraphRAG: finding nodes or edges that are both semantically similar and structurally related in a single pass. Instead you are forced into a workaround — run the vector search, take the top-k results, traverse from them, and hope the context you needed was inside that top-k. If it was not, you miss it entirely. There is no second chance, because the graph structure was never consulted before the similarity calculation ran. It is not a minor inconvenience; it is a ceiling on what the retrieval layer can do.
HelixDB adds BM25 full-text search, vector search and graph traversals in the same engine, so a company-brain query can combine a keyword match, a semantic match, a time bound, and a multi-hop traversal without leaving the store once.
The bigger difference is pre-filtering, and it is the functional gap worth understanding before you pick. HelixDB can narrow the candidate set before the distance calculation runs. A vector search chains onto a graph traversal and ranks only the members of the stream that traversal produced, so the documented order is traversal, then exact candidate membership, then vector ranking, then top k, and a result outside that candidate set cannot be returned. Vector indexes can also be tenant-partitioned, so an ANN search runs inside one tenant's partition instead of sweeping the global index. Full-text search chains on the same way with BM25 scores, so a hybrid query is scoped once and both halves respect the scope. We wrote that up separately in our post on scoping vector search to graph edges.
FalkorDB's indexing docs describe vector indexes but we have not found a pre-filtering mechanism in them, so on the evidence available you are filtering after the search rather than before it. That distinction sounds academic until it bites. Post-filtering means you fetch the global top-k and discard whatever fails your criteria, and when the criteria are selective, say one workspace out of fifty thousand, the global top-k contains nothing you are allowed to return. The query comes back empty and the fix is to over-fetch, which costs latency and still is not a guarantee.
That is what "true hybrid" has to mean to be worth the phrase: semantic similarity, keyword match, relationship structure and a scope, resolved together in one ACID engine rather than reconciled afterwards in application code.
## GraphRAG Pipeline Fit: SDK and Integrations vs. Single-Engine Flexibility
Integration into an AI pipeline is often about the glue code required to make the database work with an LLM. FalkorDB has lean, specialized tools like their GraphRAG SDK. This Python-focused SDK gives engineers a worked path from raw text to a queryable knowledge graph. It simplifies the process of building the knowledge graph from raw text and then querying it. For teams who want a prescriptive way to build GraphRAG on a Python-heavy stack, that is a real benefit, and the SDK lives in their GitHub org.
HelixDB offers a different type of flexibility by supporting the Model Context Protocol (MCP). This allows HelixDB to expose native endpoints for agent discovery. An AI agent can browse the database schema, understand the relationships available, and build its own queries step-by-step. This makes HelixDB a better fit for autonomous agents that need to evolve their search strategy based on the task at hand. Instead of a static RAG pipeline, you get a dynamic memory layer that the agent can interact with natively. HelixDB can run embedded, but also under Docker via the helix CLI, so it drops into an existing containerized environment without ceremony.
The choice here depends on your agent's autonomy. If you are building a traditional RAG pipeline where the retrieval logic is hard-coded in Python, FalkorDB's SDK provides a fast path. If you are building a multi-agent system where agents need to discover and query their own memory across vectors, graphs, and documents, HelixDB is the better choice. HelixDB eliminates the multi-database architecture that plagues most RAG stacks. Replacing Pinecone, Neo4j, and Redis with one ACID engine reduces the number of points of failure in your pipeline. For teams building complex 'company brains' that must scale without becoming a maintenance nightmare, that architectural consolidation is the primary value.
## Does the Licence Affect Embedding a Graph Database in My Product?
It might, and this is the single sharpest difference between the two. Put the two licences side by side and decide for yourself.
The HelixDB open-source core is Apache-2.0, confirmed from the LICENSE file at github.com/HelixDB/helix-db. FalkorDB is under the Server Side Public License v1, MongoDB's SSPL, confirmed from their LICENSE.txt. Both are readable and runnable for ordinary development. The difference bites if you intend to embed the database inside something you ship or offer as a service, because SSPL attaches conditions in that situation that Apache-2.0 does not. Neither of us gets to tell you how much that matters to your legal position. It is worth knowing before you build on either.
On deployment, both offer self-hosting and a managed cloud. HelixDB's open-source build reaches object storage on its own, so the scaling story is not gated behind a paid tier; Helix Cloud is the managed version of that same mode rather than a different product. FalkorDB documents replication, clustering and Kubernetes support for self-hosting, and on their cloud those capabilities sit at the Pro tier and above per their plans page. Check their docs and plans for the current shape rather than taking a summary of it from us.
Operational surface is the last factor, and here the two are closer than the usual pitch admits. Both hold the graph and the vectors in one engine, so neither of them forces you into the classic sync-two-databases problem.
Where they diverge operationally is what you have to manage as you grow. On an in-memory engine, capacity planning is a recurring task: watch memory, size the next instance, and past a point start sharding a graph, which is a genuinely hard (and often almost impossible) thing to shard. On our engine, HelixDB manages the capacity and what you focus on instead is read concurrency, which is a matter of adding readers (simple). Availability differs too, since on FalkorDB it arrives with the Pro tier while on HelixDB's GA cloud it is the default. For a small team the question is not which has fewer moving parts today, it is which one asks you to do less as the data grows.
## Verdict: Choose FalkorDB If…, Choose HelixDB If…
The choice comes down to whether you are optimising latency or scale.
**Choose FalkorDB if:**
- Traversal latency is a hard requirement and the difference between microseconds and low milliseconds genuinely shows up in your product.
- You want integration maturity today: a prescriptive GraphRAG SDK, LangChain and LlamaIndex support, and the Cypher ecosystem's tooling.
- You are already fluent in Cypher, or you want an LLM writing your queries, which foundation models do better in Cypher than in anything else.
- Your working set is bounded and you are happy to provision memory for it.
**Choose HelixDB if:**
- Your data corpus grows with your user count and you do not want capacity and cost to be the same dial.
- You need pre-filtering, because your retrieval is "closest match, but only inside this tenant or this conversation" rather than closest match globally.
- You want genuine hybrid retrieval, vectors, plus keyword, plus structure, plus scope, resolved in one ACID engine.
- You need high availability without it being a pricing tier, and reliability at thousands of concurrent requests.
- Apache-2.0 matters because you are embedding a database in something you ship.
Run it locally with the helix CLI, and star HelixDB on GitHub if the shape of it makes sense to you.
## Conclusion
Both of these engines are aimed at GraphRAG and both are credible. The difference is what they treat as the binding constraint.
FalkorDB treats it as latency, and solves it by keeping everything in memory. That is a real answer to a real problem, and if you need microsecond traversals over a working set you can size, they are the better tool and you should use them.
We think the binding constraint for agents is different. An agent's memory grows with every conversation, most of it is cold, it has to stay up, and it has to serve a lot of sessions at once. That points at object storage rather than RAM, at availability by default rather than by tier, at pre-filtering so a scoped query is cheap rather than lucky, and at a licence that does not complicate shipping the thing inside your product. Saving a millisecond on a traversal does not help if the memory cannot grow.
If that is your situation, the docs are at docs.helix-db.com and the quickstart takes minutes.
### [Vector Database vs Graph Database: What AI Memory Needs](https://www.helix-db.com/content/vector-database-vs-graph-database-what-ai-memory-needs)
An architectural comparison of vector vs graph databases for AI memory. Learn why HelixDB replaces the duct-taped RAG stack with a single Rust engine.
Engineers building AI agents in 2026 are spending more time on data synchronization than on model optimization. The standard AI stack has become a collection of specialized silos: a vector store for semantic search, a graph store for relationships, and a relational database for application state. This fragmentation is not a feature. It is a maintenance tax that slows down every release.
When you build a RAG pipeline or a company brain, you quickly realize that semantic similarity is only half the battle. Retrieving the most similar chunk to a query is easy. Understanding how that chunk relates to a specific project, a legal contract, or a previous conversation requires structure that vectors cannot provide. Most teams solve this by duct-taping three different databases together with a layer of glue code. The vector database vs graph database question is usually the wrong question, and the rest of this is about why.
## What a Pure Vector Store Is Actually Good At (and Where It Stops)
Pure vector stores like Pinecone or Milvus are specialized engines for geometry. They are built to solve the approximate nearest neighbor (ANN) problem at scale. When you feed them a 1536-dimensional embedding, they commonly use ANN indexes such as HNSW or IVF to support fast similarity search, though the actual performance and latency depend on the specific system, dataset size, and hardware. This is the foundation of basic RAG. If you need to find text chunks that resemble some natural language query, a vector store is the right tool.
The vector store stops working when your query requires logical precision. Vector search is inherently fuzzy. It does not understand entities or the relationships between them. Ask "Which developer updated the auth module in the last three days" and a vector search might return a chunk about the auth module, but it will likely miss the specific developer and the temporal context. Vectors treat every chunk as an island. While metadata filters can narrow down a search, performance may decrease as metadata complexity increases, and most vector databases only rely on post-filtering, which means you miss out on most of the results you need.
Vector databases also lack transactionality for complex operations. If you need to update a document and all its associated metadata across multiple indices, most vector-only stores cannot guarantee atomicity. They are retrieval engines, not primary databases. For teams building production-grade agents, this lack of structure leads to hallucinations where the model retrieves the right topic but the wrong facts.
## What a Graph Store Is Actually Good At (and Where It Stops)
Graph databases are built for traversal and relationship density. They treat the connections between data points as first-class citizens. In a graph, you don't just store a document. You store the fact that a specific user wrote that document, that the document belongs to a project, and that the project has a budget. This lets you ask complex relational questions that would require ten joins in a standard SQL database.
Graph stores are excellent for strict logic. They can perfectly map out an organization's hierarchy or a software codebase. However, for AI memory, where data is often unstructured and evolving, maintaining a rigid graph becomes a full-time job. You end up with a brittle system that breaks whenever the LLM tries to predict and query complex relationships that don't exist. A graph-only approach can work where workloads are rigid, but can struggle on their own where AI data is messiest.
## Can a Graph Database Replace a Vector Database for AI Agent Memory?
Not on its own, and not for the reason most people expect. Graph databases can hold embeddings as node properties and run similarity search over them, so on paper it can replace the vector store. What it usually cannot do is keep that index cheap as the corpus grows, because most graph engines hold the vector index in memory, which bounds your embedding count by the RAM on one machine. That is the real constraint, not the data model.
The reverse question is easier. A vector database cannot replace a graph database for agent memory, because top-k similarity has no way to express "and then follow this relationship two hops out". You can approximate it with metadata filters and repeated round trips, and plenty of teams do, but at that point you are rebuilding traversal in application code and maintaining it yourself.
So the useful question is not which one wins. It is whether the graph and the vectors live in one engine or two, and what the second one costs you in synchronization.
## Where Both Break for Agent Memory
Agent memory is more than a search index. An autonomous agent needs to maintain a coherent state of the world across multiple steps. This requires episodic memory (what happened), semantic memory (what the facts are), and procedural memory (how to do things). Neither store handles that on its own. We went through the shape of it in our post on AI agent memory architecture.
With only a vector store, the agent is in goldfish mode. It retrieves relevant chunks but forgets the sequence of events. It cannot follow a chain of reasoning that spans multiple documents because it lacks the edges to connect them. With only a graph store, the agent becomes overly literal. It misses context that was not explicitly labeled. Real agent memory requires the ability to traverse a path of related entities while simultaneously searching for similar concepts within those entities.
Most current agent frameworks try to fix this in the application layer. They pull data from two different sources and merge it. This fails because the ranking algorithms for vectors and graphs are incompatible. There is no standard way to weight a vector similarity score against a graph path distance. The result is often an agent that gets distracted by irrelevant but high-scoring vector matches, losing the structural context the graph was supposed to provide.
## The Real Problem: You're Running Both and Maintaining the Glue
A common AI stack may use a vector database for embeddings, a graph database for relationship-centric data, and Postgres for transactional application data. Every time you store a new piece of information, your application performs three separate writes, and every one of them is a place the write can half-succeed. If the vector store update lands but the graph update fails, your agent now has an inconsistent view of the world and nothing tells you.
You are also paying for the glue code. This code maps IDs between systems, handles retries, and manages separate connection pools. It is a hidden engineering cost that adds latency to every request. In a complex RAG pipeline, these trips happen sequentially: vector query, collect the IDs, second round trip to the graph to hydrate them, then generation. The user waits through all of it before the first token appears.
This plays out repeatedly in internal knowledge graph projects. Teams start with a simple vector search, realize it is insufficient, and then add a graph layer. They spend the next six months fighting synchronization bugs instead of improving their product. Maintaining three different query languages (SQL, Cypher, and a vector DSL) creates a massive cognitive load for the development team.
## The Operational Cost Nobody Budgets For: Dual Writes, Embedding Drift, and Split Deletes
Operating a split-database architecture introduces three specific technical debts that rarely come up in the design phase. The first is the dual-write problem. Without distributed transactions, you cannot guarantee that your vector index and graph index are in sync. If a write to your graph fails, your vector index will still return that data, but the agent will fail when it tries to look up the associated relationships. This produces intermittent, hard-to-debug errors in production.
The second issue is embedding drift. As you iterate on your RAG pipeline, you might change your embedding model. With a unified system, you can re-index in one pass. In a fragmented stack, you have to coordinate a migration across two or three different platforms. If your graph nodes contain embedded data and your vector store contains the same data, you now have two sources of truth that will inevitably diverge.
Finally, there are split deletes. Handling GDPR or user data deletion requests becomes a nightmare. You must purge the data from the relational DB, the vector store, and the graph nodes. If the background job clearing the vector index fails, those embeddings are still sitting there and still retrievable. That is a real compliance risk, and teams tend to find it while preparing for an audit. HelixDB solves this by treating all these data types as a single unit of work in one ACID-compliant engine.
## What a Single Graph-Vector Engine Changes
HelixDB is built from scratch in Rust to remove that fragmentation. Graph traversal, vector ANN, and BM25 full-text search all run in one engine, and a single query can combine them. Vectors are properties on nodes and edges, so nothing about the data model is exotic here. What changes is that there is no second system to keep in step.
There is also no query language to learn. You build queries with the native Rust, TypeScript, Go, or Python SDK, in the same files as the rest of your application code.
```
import { g, readBatch, SourcePredicate, defineParams, param } from "@helix-db/helix-db";
const params = defineParams({
owner: param.string(),
query_vector: param.array(param.f32()),
limit: param.i64(),
});
// one request, one round trip: walk to this user's documents, then rank only those
const recall = readBatch()
.varAs(
"docs",
g().nWithLabelWhere("User", SourcePredicate.eq("id", params.owner))
.out("AUTHORED")
.vectorSearchWith("Doc", "embedding", params.query_vector, params.limit)
.valueMap(["$id", "title", "$distance"]),
)
.returning(["docs"]);
const request = recall.toQueryRequest(
params,
{ owner: "u-42", query_vector: queryVector, limit: 10n },
{ queryName: "owned_document_matches" },
);
```
Compare that to what most teams are running now: query the vector store, collect the IDs it hands back, issue a second query against the graph to hydrate the relationships, then reconcile two incompatible ranking schemes in application code. Same answer, three moving parts and an extra round trip.
The ordering is the part worth stealing. The traversal runs first, the vector search ranks only the members of the stream it produces, and the top k comes out of that set, so a result outside the candidate set cannot be returned. That is how you say "closest match semantically, but only inside this conversation", and it is the query agent memory actually wants. A scoped search can hand back fewer than k rows when the candidate set is smaller than k, which is the guarantee working rather than a bug. Full-text search chains onto a traversal the same way with BM25 scores, so a hybrid query is scoped once and both halves respect the scope. It is awkward to express at all when your vectors live in a different database from your edges. HelixDB's vector index is also tiered across memory, disk, and object storage rather than pinned in RAM, which is what lets it outgrow the memory on one machine.
Be precise about deployment when you size something, because storage in HelixDB is a configuration choice rather than a fixed property of the engine. The open-source build at github.com/HelixDB/helix-db is Apache-2.0 and runs three ways: fully in memory, on disk, or against S3-compatible object storage. Same engine, same SDKs, same endpoint in all three, so prototyping in memory and shipping on S3 is a startup flag rather than a rewrite. Helix Cloud is the managed high availability version of that last mode, where nodes, edges, properties, and index artifacts persist durably in object storage, a gateway routes traffic, a single writer serializes mutations, and readers scale horizontally under serializable snapshot isolation with tiered SSD and in-memory caching. The Apache-2.0 license on the core matters more than it sounds if you are embedding a database in something you ship, since most engines in this category sit on BSL or SSPL.
HelixDB also exposes native MCP endpoints, so an agent can discover what it is allowed to query and walk the graph step by step instead of being handed one fixed retrieval function. That makes the database a participant in the agent's reasoning rather than a passive file cabinet.
## Choosing the Right Architecture for Your Memory Stack
The first question when deciding between a vector database vs graph database should be whether you actually need two separate systems. If your project is a simple search bar over a few hundred PDFs, a basic vector store is probably fine. You do not need a graph if there are no meaningful relationships between your documents. Keep it simple and use a specialized tool for that specific use case.
If you are building an autonomous agent, a company brain, Karpathy's LLM wiki, or a complex recommendation engine, you need both relationships and semantics. Do not start by duct-taping three different databases together. The operational cost will eventually outpace the benefits. A single engine that handles graphs, vectors, and documents is the more sustainable path for long-term development. Your team can focus on building features instead of managing infrastructure.
Check your own stack for dual-write logic and manual ID mapping. If a real share of your backend is code that exists only to move data between two databases, that is the tax, and it compounds with every feature. Consolidating onto one engine is how that code goes away. You can start on the cloud for only $5 a month, or the open-source build locally through the helix CLI; in-memory, on-disk, or pointed at your own bucket, and move to the managed cloud later without changing how you write queries.
## Conclusion
The split between vector search and graph traversal is a legacy of how these tools were originally developed. It does not serve the needs of modern AI agents. Building a reliable company brain requires a system that understands both the fuzzy context of language and the hard facts of relationships. More databases is not the answer. Better integration is.
HelixDB is one open-source engine in Rust that holds the graph, the vectors, and the full-text index together, which removes the synchronization work rather than automating it. Try it locally with the helix CLI, and star HelixDB on GitHub if the shape of it makes sense to you. If you build something on it and something breaks, we want to hear about that too.
### [HelixDB vs Memgraph: Which Graph Database for AI Memory?](https://www.helix-db.com/content/compare/helixdb-vs-memgraph-which-graph-database-for-ai-memory)
HelixDB vs Memgraph: in-memory graph analytics against object-storage-backed agent memory. Which one actually scales, and what does each one cost to run?
Building an AI agent that actually remembers context requires more than just a vector index. Most developers start by duct-taping Pinecone for embeddings to Neo4j for relationships, only to realize they have built a fragile, high-latency pipeline that breaks the moment a query gets complex. This friction has pushed two specific technologies to the front of the GraphRAG conversation: HelixDB and Memgraph.
Memgraph is an in-memory graph database (hence the name) that speaks Cypher and is built for low-latency real-time analytics. This means the whole database lives in RAM, and that single fact shapes both what it's good at and what it costs. HelixDB is a Rust engine that puts graph traversal, vector search, BM25 full-text, and time-range indexing in one store, with object storage underneath as the persistence layer for cheap and scalable storage.
So the comparison is not about which engine traverses a graph faster in a vacuum. It comes down to two questions, and they are the ones worth arguing about.
The first is workload. Are you running real-time analytics over a working set you can size in advance, or are you serving agent memory and context for a user base that keeps growing? The second is scaling economics. Is your ceiling the RAM on your largest machine, or the price of object storage? Memgraph is a good answer to the first workload. HelixDB is built for the second.
## Who Each Database Is Actually Built For
Memgraph is built for engineers who live in the world of real-time streaming and complex network analysis. If you are processing millions of events per second from Kafka and need to run Graph Neural Networks (GNNs) or community detection algorithms on the fly, Memgraph is the standard choice. It targets data scientists and MLOps leads who require a high-performance, C++ based engine that maintains compatibility with the OpenCypher ecosystem. It is a straightforward move for teams that have outgrown Neo4j but want to keep their existing query logic.
HelixDB is built for AI engineers shipping agents who are tired of managing three different databases. It targets the developer who needs to store a company brain (org structures, project documents, Slack threads, and meeting transcripts) and query it semantically. Vectors in HelixDB are properties on nodes and edges, the same shape you would use in Memgraph or Neo4j. The difference is that the index behind them is part of an ACID engine rather than a separate service you keep in sync. It is for the team that wants one query that fetches a user's recent messages, finds semantically similar documents, and traverses the relationship graph to see who else worked on those files. We went deeper on that shape in our post on AI agent memory architecture.
Memgraph thrives in the data engineering pipeline. HelixDB thrives in the application backend serving live agents.
The distinction that matters most in practice is volume and concurrency. Agent memory has no natural ceiling. Every conversation, document, tool call, and retrieved chunk is more data you have to keep and still be able to retrieve, multiplied by every user you add. That is a poor fit for an engine whose queryable set has to sit in memory, because the dataset grows on a curve you do not control and RAM is the one resource you cannot buy casually.
So you choose Memgraph when your bottleneck is streaming graph analytics over a working set you can size. You choose HelixDB when you need to hold a lot of data, serve a lot of simultaneous users, and not pay for all of it in memory.
## Architecture: How They Store and Query Graph + Vector Data
The architectural philosophies of these two engines diverge at the storage layer. Memgraph is fundamentally an in-memory database. By keeping the entire graph in RAM, it achieves sub-millisecond traversal speeds for deep queries. While it offers persistence to disk via snapshots and WAL (Write-Ahead Logging), its performance peak requires enough memory to hold your active dataset. That is the trade, stated plainly: you buy sub-millisecond traversals with RAM, and RAM is the most expensive tier you can provision. Growing the dataset means vertically growing the instance, and every read replica you add for throughput pays for another full copy of the graph in memory. For vector support, Memgraph lets you store embeddings as properties and build vector indexes on both nodes and edges, but their docs are candid about its memory requirements.
HelixDB takes a different approach by building a multi-modal engine in Rust from the ground up. It does not treat the graph as a layer on top of a vector store or vice versa. Graph traversal, vector similarity, and BM25 full-text search run in one engine, and a single query can combine all three.
The storage split is the part worth dwelling on, because it is where the two engines stop being comparable. Memgraph's practical ceiling is the RAM on your largest machine. HelixDB inverts that relationship: object storage is the durable layer, and memory is a cache in front of it rather than the place your data has to live. The vector index is tiered across memory, disk, and object storage, so the sizing question stops being whether your index fits in RAM.
Worth being precise about what "the persistence layer" means here, because in HelixDB it is a configuration choice rather than a fixed property of the engine. The open-source build runs three ways: fully in-memory, on-disk, or against S3-compatible object storage. Same engine, same SDKs, same POST /v2/query interface in all three. You point it at a bucket with a storage URI and a region, or you leave that unset and it stays in memory or disk. So you can prototype in memory or disk and ship on S3 in production without touching the code. The run modes are documented at https://docs.helix-db.com/database/helix-db/start-here/local-development/local-server.
Helix Cloud is the managed version of that last mode, and it is the one to compare against Memgraph for a production agent workload. Nodes, edges, properties, and index artifacts persist durably in object storage. A gateway routes traffic, a single writer serializes mutations, and readers scale horizontally on compute nodes that cache hot data in SSD and memory above the bucket. Durability and capacity come from object storage; latency comes from the cache tier; concurrency comes from adding readers. Those are three separate dials, which is the point. In an in-memory engine they are all the same dial, and it is the expensive one.
Query execution also differs. Memgraph relies on the Cypher execution engine: you assemble a query string in your application, ship it over Bolt, and Memgraph parses and plans it at runtime. HelixDB has no query language at all. You build queries in your own code with the native Rust, TypeScript, Go, or Python SDKs, they serialize to a JSON envelope, and that goes out as one POST to /v2/query. The practical difference for an agent backend is where a mistake surfaces: a malformed Cypher string fails at runtime, while an SDK builder that does not typecheck fails in your own build.
## Comparison Across the Criteria That Matter for AI Memory
Evaluating HelixDB vs Memgraph for a memory layer requires looking beyond raw nodes-per-second. You need to consider how the database handles the specific requirements of RAG: semantic recall, relationship traversal, and temporal awareness. AI agents often need to know not just what happened, but when it happened. You model that with timestamped nodes and edges, and what decides whether it stays usable as the history grows is how cheaply you can read it back. HelixDB puts range indexes on numeric and string properties, supporting gt, gte, lt, lte and between plus ordered scans in either direction, so everything between Tuesday and Thursday is an indexed scan over a sorted range and the last twenty events is a descending scan you can stop early. It also composes with a scoped vector search, so recency and semantic relevance resolve in one request. Users tell us that is the part they actually needed.
| Criterion | HelixDB | Memgraph |
| --- | --- | --- |
| Primary Language | Rust | C++ |
| Query Interface | JSON queries built with native SDKs | Cypher (OpenCypher compatible) |
| Vector Search | Vector index tiered across memory, disk, object storage for scale | Vector indexes held in memory |
| Storage Model | Unified graph, vector, KV, document; configurable in memory, on disk, or on object storage | In-memory graph with snapshot and WAL persistence |
| Scaling Model | Durable state in object storage, readers scale horizontally behind SSD and memory caches | Scale the instance up to fit the dataset in RAM; each replica holds another full copy |
| Cost Driver | Actual usage: the reads and writes you make, with storage priced in cents per GB per month | Provisioned memory, priced in 10s of dollars per GB per month |
| Concurrency | Add readers above the same durable store | Add replicas, each with a full in-memory copy |
| License | Apache-2.0 | BSL 1.1 |
| Agent Protocol | Native MCP support | Bolt protocol and standard drivers |
| Best For | Agent memory and context at scale, GraphRAG | Real-time streaming analytics on a sized working set |
Latency in a RAG pipeline is often cumulative. In a traditional stack, you perform a vector search in Pinecone, get IDs, and then query Neo4j for the relationships. That is multiple round trips. HelixDB collapses that into one request, because the vector search and the traversal run inside the same query against the same store. Memgraph reduces latency by keeping data in memory, but if your application still needs a separate document store or vector DB for scale, the network overhead remains and it becomes a latency bottleneck anyway. HelixDB is designed to be the only engine in the room.
## Scaling and Cost: A RAM Ceiling vs Object Storage
This is the part most comparison posts skip, and for an agent workload it is the deciding factor.
Start with the price list, because the gap is not a tuning difference. Object storage is billed in cents per GB per month. Provisioned memory on a memory-optimized instance works out in dollars per GB per month. Two orders of magnitude separate them, and the entire question is which one your dataset has to live in.
For an in-memory engine, capacity and cost are the same variable. A corpus of documents, embeddings, and a year of conversation history for a growing user base is not a fixed number you can size once. It goes up. When it exceeds the RAM you have, you provision a bigger instance, and when it exceeds the biggest instance available you start sharding, which is almost impossible in graph databases. Read throughput has the same shape: serving more concurrent sessions means more replicas, and each replica is another full copy of the graph in memory.
HelixDB Cloud separates those concerns. The durable copy of your graph, your vectors, and your index artifacts sits in object storage, which is effectively unbounded, cheap, and highly available without you configuring anything. Compute nodes in front of it cache hot data in SSD and memory, so the working set gets memory like speed while the long tail stays where it is cheap. Readers scale out horizontally against that same durable store, so going from a thousand simultaneous users to a million is a matter of adding readers rather than buying a larger machine or duplicating the dataset again. A single writer serializes mutations under serializable snapshot isolation, so consistency does not degrade as you add read capacity.
The practical consequence: with HelixDB you can afford to keep everything an agent might need to remember, rather than deciding which memories to evict because they are sitting in RAM. That is a product decision disguised as an infrastructure one, and it is the reason the persistence layer belongs in this comparison at all.
### What That Looks Like on the Invoice
Abstractions are easy to argue with, so here are the actual numbers as of August 2026. Check both vendors yourself before you commit to either, since cloud pricing moves.
Memgraph Cloud sells you a machine, and they publish a cost calculator so you can check this without talking to anyone. Pick a region and the smallest size, **1 GB of RAM with 2 CPUs**, and it estimates about **$58.88 a month**, broken out as 0.0672 an hour of compute, 0.0108 an hour of storage, and 0.27 per GB of network. The size dropdown climbs through 2, 4, 8, 16 and 32 GB, and the top of the generally available menu, **32 GB with 8 CPUs, lands around $2,000** a month. Each of those is a fixed monthly cost for a fixed amount of memory, billed whether or not anybody queries it, and 32 GB is where the menu stops.
HelixDB sells you usage. On a standard GA tenant the entry price is **$5** for a million reads and 100,000 writes a month, with no separate storage charge, because storage is the cheap part and there is no reason to meter it like memory. Reader nodes scale up under load and back down when it drops, so the bill follows the traffic. If you want isolation, a dedicated highly available cluster starts at **$1,600** a month and deploys at minimum three database nodes at 2 vCPU and 16 GB each, plus three gateway nodes at 1 vCPU and 2 GB each, with bottomless storage behind them.
Put those side by side and the shape of the difference is clearer than any architecture diagram. Two thousand dollars a month buys one 32 GB machine, and when your data outgrows it you are off the end of that menu. Sixteen hundred buys six nodes, high availability, and storage with no ceiling. At the other end, a project that has not hit scale yet pays $5 rather than $60, because it is paying for the queries it actually made instead of for memory sitting idle. The thing to notice is not which number is smaller. It is that one of them is a machine size and the other is a usage meter, and only one of those tracks a workload that grows with your user count.
One more thing worth checking for yourself, because it decides whether a comparison is even like for like: high availability. Memgraph's pricing page lists high-availability replication under the self-hosted Community and Enterprise editions, and positions Cloud for prototyping, learning, and early-stage projects; HA does not appear in the Cloud feature list. HelixDB's GA cloud is highly available by default. If you are pricing a production agent workload, make sure the two numbers you are comparing both include staying up.
## Query Interface: JSON Builders vs Cypher
Cypher is the industry standard for graph queries. It is expressive and uses a pattern-matching syntax that feels natural for describing relationships. If your team is already proficient in Cypher, Memgraph offers a zero-learning-curve experience. You can use standard drivers and tools from the Neo4j ecosystem to interact with your data. This is a real advantage if you are migrating an existing knowledge graph to a faster, vector-capable engine.
HelixDB does not ask you to learn a query language. You build queries with the native TypeScript, Rust, Go, or Python SDK, in the same files as the rest of your application logic. The builders read roughly like the traversal you are describing, something along the lines of g().nWithLabelWhere("User", SourcePredicate.eq("id", params.owner)) walked out along an edge and then chained into a vectorSearchWith call, which ranks only the nodes that traversal reached, and they serialize to a JSON envelope that goes out as one POST to /v2/query. You can hand-write that JSON instead if you prefer. The database turns that JSON into the query it executes, so there is no query language to learn and nothing to generate ahead of time. HelixDB also exposes native MCP endpoints, so an agent can discover what it is allowed to query and walk the graph step by step. The querying docs at docs.helix-db.com go through the builders in detail.
For an AI engineer, the choice depends on where the logic lives. If you want your LLM to write the queries, Cypher is well supported by most foundation models, and that is a genuine advantage for Memgraph. The flip side is that generated Cypher is prone to syntax errors and hallucinated relationship types. With HelixDB you tend to write the access patterns yourself, in a language your compiler and your tests already see, and let the agent call them with parameters. That is a narrower blast radius than handing a model a string and hoping.
## Where Memgraph Wins: Streaming, Real-Time Analytics, Cypher Ecosystem
Memgraph is the stronger choice for use cases like fraud detection and real-time recommendation engines, where sub-millisecond latency is the hard requirement and the working set is bounded enough that holding it in memory costs you nothing you care about.
Memgraph also wins on ecosystem maturity. Because it is compatible with OpenCypher, it works with a wide array of visualization tools, BI platforms, and existing graph libraries. If you are building an internal tool for data scientists to explore relationships visually, Memgraph's compatibility with the Bolt protocol means you can use standard tools like Neovis.js or Bloom. The availability of MAGE (Memgraph Advanced Graph Extensions) gives you a library of graph algorithms like PageRank and betweenness centrality out of the box, and their site documents the streaming and analytics use cases in real depth.
Choose Memgraph if your AI application is secondary to a larger real-time data analysis project. If you have a dedicated data engineering team that manages complex ETL pipelines and requires a specialized graph engine to sit at the end of a Kafka stream, Memgraph is the right tool for the job. It provides the stability and tooling of a mature graph database while adding the vector capabilities needed for modern ML workflows.
What it is not designed for is the agent workload: a corpus that grows with every user and every conversation, queried by thousands of simultaneous sessions, where most of the data is cold most of the time. That is a different problem with different economics, and holding all of it in memory is the wrong answer to it. This is not a knock on Memgraph. It is built for a workload where the working set is known and latency is the only thing that matters, and it does that well.
## Where HelixDB Wins: One Engine, and One That Scales Cheaply
HelixDB wins by solving the duct-tape problem. Most AI engineers do not want to be database administrators; they want to ship features. By providing a single engine that handles graph, vector, and full-text search, HelixDB removes the operational burden of synchronizing data across multiple different systems. There is no need to worry about a vector search returning a document that was deleted from the graph five seconds ago, because there is no second system to lag behind. On Helix Cloud, that work runs under serializable snapshot isolation. That kind of consistency is what makes a company brain trustworthy rather than merely fast.
Being built from scratch in Rust means the engine manages memory explicitly rather than through a collector, so the lifetime of a large vector index is a decision rather than a runtime's schedule. Read that as a design choice and not a latency guarantee: modern low-pause collectors are good, and Rust still pays for allocation, synchronisation and I/O. What HelixDB gets from starting recently is an engine shaped around the GraphRAG access pattern, where you jump between semantic similarity and structured relationship traversals inside a single query. HelixDB also supports tenant partitioning on its vector indexes, so a similarity search can be scoped to one tenant's vectors instead of sweeping the whole index and discarding most of the hits. That pre-filtering idea is what makes the agent-memory query practical: closest match semantically, but only inside this tenant, this project, or this conversation.
The second half of that argument is the one-stop shop in scaling, not just in functionality. Graph, vectors, full-text, and time-range indexing in one engine saves you three systems and the glue between them. Object storage as the persistence layer, with disk and memory caching on compute nodes above it, is what lets that one engine stay in front of an agent product as the data and the user count grow. Cheap storage, horizontal read scale, and high availability without a sharding project are the same promise applied to operations instead of features.
Native support for MCP makes it the obvious choice for developers building in the agentic ecosystem. If you are starting a new AI project today, HelixDB provides a clean, unified foundation that scales from a local Docker container to a managed cloud backed by object storage.
## Verdict: Choose HelixDB If…, Choose Memgraph If…
The decision between HelixDB vs Memgraph is a workload decision before it is a feature decision. Memgraph is a specialized engine for high-performance graph analytics and streaming over a working set that fits in memory. HelixDB is a graph-vector store for agent memory and context management, built so that the data can outgrow any single machine's RAM without the bill or the architecture going sideways. Both are good at what they are for, and they are for different things.
**Choose HelixDB if:**
- You are building AI agents or RAG pipelines and want to replace your entire stack (Pinecone + Neo4j + Postgres) with one engine.
- You would rather build queries in TypeScript, Rust, Go, or Python than maintain Cypher strings in your application.
- You want graph traversal, vector search, and BM25 full-text in one engine, with a vector index that does not have to fit in RAM.
- You want a Rust-native, open-source engine you can run in memory, on disk, or against your own S3-compatible bucket, with a managed cloud available when you outgrow self-hosting.
- Your dataset grows with your user count and you do not want capacity and cost to be the same variable.
- You need to serve thousands or millions of simultaneous sessions by adding readers rather than duplicating the graph in memory.
**Choose Memgraph if:**
- You need to process massive real-time streams of data from Kafka or Pulsar with sub-millisecond latency.
- You need a mature, C++ based engine with deep support for real-time analytics and visualization tools.
- Your dataset has a known ceiling you are happy to provision RAM for, and latency on that working set is the only metric that matters.
To see how a unified graph-vector engine changes your retrieval logic, star HelixDB on GitHub and try the GraphRAG quickstart today.
## Conclusion
Picking the right anchor for your AI memory stack is the difference between a responsive agent and a high-latency maintenance nightmare. Memgraph offers a powerful, in-memory solution for teams that need deep analytical capabilities and Cypher compatibility. For teams building the next generation of autonomous agents and GraphRAG pipelines, though, the overhead of managing fragmented databases is a real tax on shipping speed.
HelixDB removes that tax twice over. Putting graph traversal, vector search, BM25 full-text, and time-range indexing in one Rust engine means you build a company brain without a synchronization job in the middle. Putting object storage underneath it, with disk and memory caching on the compute nodes in front, means that brain can keep growing with your user base without capacity turning into a RAM budget.
If your workload is real-time analytics over a bounded graph, Memgraph is the better tool and you should use it. If it is agent memory at scale, star HelixDB on GitHub, run the quickstart, and tell us what you are building.
### [HelixDB vs Neo4j: Graph and Vector Search in One Engine](https://www.helix-db.com/content/compare/helixdb-vs-neo4j-graph-and-vector-search-in-one-engine)
Compare HelixDB vs Neo4j for GraphRAG and agent memory. Learn why a unified Rust engine beats a bolted-on vector approach for high-performance AI applications.
Most engineers building RAG systems are running three databases at once: Pinecone for semantic recall, Neo4j for relationship mapping, and Postgres for basic application state. That means three separate round trips for every user query, three systems to synchronize, and a nasty failure mode where your vector index updates but your graph index lags and your AI agent hallucinates on stale context. This is the duct tape problem that kills performance in production.
Neo4j is the mature giant of the graph world, but it was built long before the current AI wave. It has since added vector search as a feature on top of its core property graph engine. HelixDB takes a different path. It is a graph-vector database written from scratch in Rust, handling knowledge graphs, vector search, and full-text search in a single engine. For developers building a company brain or persistent agent memory, the choice between Neo4j and HelixDB comes down to whether you want a mature ecosystem or a unified engine built for the age of AI agents.
## Who Each Database Is Actually Built For
Neo4j is built for companies mapping out complex fraud detection patterns or managing a massive supply chain. It is designed for deep, multi-hop traversals where the primary goal is understanding relationships between millions of entities. Its ecosystem is vast, with extensive documentation and a large pool of Cypher-literate developers. The overhead is significant, though, and its pricing reflects its focus on large-scale corporate contracts.
HelixDB is built for the AI engineer who is shipping an autonomous agent today. This developer does not want to manage three different databases. They need agent memory that handles semantic recall and graph traversal in one step, which we worked through in our post on AI agent memory architecture. HelixDB targets teams building GraphRAG pipelines where the database must act as a persistent memory store. It is for builders who prioritize Rust-native performance and want to cut the latency of stitching together separate vector and graph stores. Neo4j serves the legacy graph market. HelixDB serves the developer building a unified company brain.
If your team is already deep into the Neo4j ecosystem and your use case is 90% graph traversal with only occasional vector needs, Neo4j is a safe bet. If you are starting a new project where vector search and graph relationships are equally important for agentic reasoning, HelixDB is the better fit. The two databases represent different eras of data architecture: one built for structured transaction relationships, one built for the high-velocity requirements of AI agents.
## Data Model: Where the Vector Index Actually Lives
Neo4j's vector index is Lucene's HNSW implementation, and it is resident in memory. It sits in the OS filesystem cache, off-heap, outside the Neo4j page cache, so the database has no direct control over the memory it consumes. Neo4j's own operations manual tells you to budget for it as a separate line item: allow roughly 40% of the physical index size in spare filesystem cache for a quantized index, closer to 100% for an unquantized one, on top of heap and page cache. Miss that and the OS starts reading vectors off disk or swapping, and your tail latency goes with it. Developers have reported memory pressure and overflows on datasets that do not look large on paper. Neo4j's position is that its index is no more memory-intensive than comparable implementations. The sizing arithmetic is the part nobody disputes.
HelixDB's vector index is tiered instead of resident. It spans memory, local disk, and object storage, with the hot set cached and the cold set persisted durably underneath. You are not sizing an instance to hold the whole index in RAM, which is what makes it cheaper to run and what lets it grow past the memory ceiling of one machine. Same data model, different resource curve.
A single query still combines both. Find the people who worked on a project (graph traversal), then rank them by how close their past write-ups sit to a new task (vector search), in one engine, without moving data between subsystems.
Keeping the vector index inside the graph engine buys you pre-filtering. You can scope a vector search to the vectors hanging off a particular set of related entities, so approximate nearest-neighbor search runs over the neighborhood you care about rather than sweeping the global index and discarding most of what it returns. For agent memory that is almost always the query you actually wanted: closest thing semantically, but only inside this tenant, this project, this conversation.
If your agent needs to know what was true last Tuesday, you model that explicitly with timestamped nodes and edges, the same as you would in Neo4j. What the engine gives you is range indexing over those timestamps: ordered scans with gt, gte, lt, lte, and between, ascending or descending. So "what did this agent know between Tuesday and Thursday" is an indexed range scan instead of a full traversal with a filter bolted on the end. Teams building episodic memory have told us that is the part that mattered.
## Can You Have Multiple Edges of the Same Type Between Two Nodes?
In both engines, yes. This question comes up often enough from teams evaluating a move that it is worth being precise about, because plenty of them arrive convinced the storage engine forbids it.
Neo4j is a multigraph. Nothing in the storage layer stops you putting fifty MENTIONED relationships between the same two nodes, each carrying its own properties. What trips people up is the idiom. `MERGE (a)-[:MENTIONED]->(b)` matches an existing relationship rather than adding another one, and MERGE is what most tutorials, most object-graph mapping layers and most import tooling reach for by default. Aura's importer behaves the same way, keeping the last row when a pair repeats. So a team modelling every mention, every message, every state change as its own edge writes code that looks right, runs it, and finds one relationship where they expected thousands. You need CREATE, and you need to know that before you load rather than after.
The second place it bites is analytics. Graph Data Science projections do not preserve parallel relationships unless you tell them how to aggregate, so an algorithm can quietly collapse repeats into a single weighted edge.
HelixDB is additive by default. `addE` adds an edge. There is no match-or-create shape to fall into, and equality indexes on edge properties are lookup indexes rather than uniqueness constraints, so nothing rejects the second edge between the same pair. Replacing one is an explicit operation: drop it by its id and write it again, rather than a side effect of which verb you happened to use.
That default matters most for exactly what agent memory is made of, which is repeated events between the same two entities. A user asking about the same document forty times. An agent citing the same source across a dozen runs. A person joining a team, leaving, and rejoining. Those are naturally parallel edges with timestamps on them, and paired with range indexes over those timestamps you can read the whole sequence back, or just the last twenty, as an indexed scan rather than a traversal you filter afterwards.
One thing to check before you migrate: if your Neo4j graph was built through MERGE, it may already have collapsed those repeats, in which case the history is gone at the source and no migration recovers it. Count the relationships between a pair you know should have many before you plan the export.
## Vector Search: One Plan or Two Subsystems
Neo4j reaches its ANN index through Lucene, called from Cypher as a procedure. It works, and for a mostly-graph workload with occasional similarity lookups it gets by. The friction shows up when one query needs both structure and similarity, because you are coordinating a traversal engine with a separately managed index rather than expressing a single plan. That usually means over-fetching neighbors and filtering the survivors in application code.
HelixDB treats vector search as a core part of its Rust engine. Because it was built from scratch, the vector indexing and graph storage share the same underlying memory management and execution path. This produces high-performance results even for queries that combine full-text search, vector recall, and graph traversal. HelixDB provides a high-performance foundation that supports the graph-vector model through its native storage engine. This unified approach cuts the latency spikes that appear when a database has to coordinate between a graph index and a separate vector index.
HelixDB also composes retrieval modes inside a single query. BM25 keyword search, ANN vector recall, and multi-hop traversal all sit in one request instead of three round trips you reconcile in application code. That matters for agent memory, where the context you actually want is usually part "semantically close to this question" and part "two hops from this entity". In our benchmarks, graph traversals run faster than Neo4j and our vector performance lands on par with dedicated vector databases. Those are our numbers, so measure them against your workload before you commit. The architectural point holds either way: one engine, one query, no sync layer to keep honest.
## Query Interface: Cypher Strings vs. Native SDK Calls
Cypher is the industry standard for graph queries. Declarative, readable, and if you can draw the pattern on a whiteboard you can usually write it. The catch inside application code is that a Cypher query is a string. Your editor does not know whether the label exists, your compiler does not know the shape of what comes back, and a typo in a property name shows up as an empty result set in production rather than a red squiggle in your editor.
HelixDB does not have its own query language, and there is no compile step or push before you can run a query. You write queries directly in your application code through the Rust, TypeScript, Go, and Python SDKs, using builders like g().nWithLabel("User") and .vectorSearchWith(...), and the SDK serializes that to a JSON query sent as one POST to /v2/query. Your own language's type checker is what validates the query as you build it, and the database turns the JSON it receives into the query it executes, so there is no separate query language sitting between your code and the database. Prefer to skip the SDK entirely and the JSON is a documented format you can hand-write or generate.
For teams using the Model Context Protocol (MCP), HelixDB provides native support. This lets AI agents discover and execute graph queries step-by-step. Instead of the agent writing complex Cypher strings, it can use the MCP endpoints to explore the graph and refine its search based on the results it receives. This agent-first approach to querying makes HelixDB easier to integrate into a multi-agent system compared to the more traditional, human-centric Cypher interface. The JSON query format helps here too, since asking a model to emit a JSON object is a far safer bet than asking it to emit a syntactically correct string in a language it half-knows.
## Deployment and Operational Overhead
Running Neo4j in production is a serious commitment. They offer a managed service called Aura, but self-hosting requires significant Java expertise and careful tuning of heap sizes and garbage collection. The operational overhead of maintaining a Neo4j cluster is well-documented in the enterprise space. Licensing is also a factor. There is a community edition, but most production features require a commercial license, and costs scale rapidly as your data footprint grows.
HelixDB is designed for low-friction deployment. You can deploy it using Docker or manage local instances using the Helix CLI. `helix init` followed by `helix start dev` gets a local instance running in minutes. HelixDB is open-source under the Apache-2.0 license, giving you a free self-hosting option alongside a managed Helix Cloud for teams that want to offload infrastructure management. The open-source build runs fully in memory, on disk, or against S3-compatible object storage, so the storage decision is a startup flag rather than a different product.
Helix Cloud uses a modern architecture built on top of object storage, with SSD caches on writer and reader nodes to maintain high performance and availability while keeping the long-term persistence layer cost-effective. This is much more aligned with modern cloud-native practices than the traditional disk-heavy approach of older graph databases. For a startup or an indie hacker, starting free with a single binary and then scaling to a managed cloud service is a real operational advantage. You do not need a dedicated database administrator to keep HelixDB running.
## Side-by-Side Comparison
Choosing between these two databases means choosing between a mature, enterprise-grade graph platform and a modern, high-performance engine designed for the AI era. Neo4j offers the safety of a large ecosystem. HelixDB offers the speed and simplicity of a unified stack. Below is a breakdown of how they compare across the criteria that matter most to backend developers.
| Criterion | Neo4j | HelixDB |
| --- | --- | --- |
| Core Engine | Java-based Property Graph | Rust-based Graph-Vector |
| Vector Index | Lucene HNSW, resident in memory | Tiered across memory, disk, object storage |
| Query Interface | Cypher strings | Native SDK builders or JSON over HTTP |
| Search Types | Graph, Vector, Full-text | Graph, Vector, Full-text, KV, range scans |
| Repeated Edges | Multigraph, but MERGE and import tooling collapse them by default | Additive by default, no uniqueness constraint on edges |
| Deployment | Managed (Aura) or VM | Managed (Cloud), Docker, or CLI |
| License | Commercial / GPL | Open Source (Apache-2.0) |
| Agent Support | Third-party integrations | Native MCP support |
Neo4j is the right choice if you're building fraud detection or supply chain and you need enterprise support. It handles massive, multi-billion node graphs, provided you have the money to throw at scaling. HelixDB is the right choice if you are building an AI-first product and need to consolidate your vector, graph, and application data into a single, high-speed engine, and scale that to thousands of agent swarms and users. For smaller, fast-moving teams, the reduction in architectural complexity is usually the deciding factor.
## When to Choose Neo4j, When to Choose HelixDB
Choose Neo4j if you are working within a large corporate environment where Cypher is already the standard. If your data is purely relational and your graph traversals are very deep, the mature query optimizer in Neo4j will serve you well. It is also the better choice if you need a wide range of third-party integrations with legacy business intelligence tools. Neo4j is a well-understood platform that fits into traditional enterprise IT stacks.
Choose HelixDB if you are building a GraphRAG pipeline or an AI agent that requires long-term memory. If you are tired of managing a vector database and a graph database separately, HelixDB will simplify your stack. It is the better choice for developers who value simplicity, reliability, and scalability. If you need your AI to understand the context of a company brain, where relationships and semantic meaning are equally important, HelixDB provides the unified engine to make that happen without the duct tape. Star the project on GitHub and join the community to see how other engineers are building the next generation of agent memory.
## Conclusion
The choice between HelixDB and Neo4j is about the architecture of your entire AI stack. Neo4j is a powerful tool for traditional graph problems, but an in-memory vector index is a hard constraint on how far a RAG pipeline can grow before it gets expensive. HelixDB puts the graph and the vector index in one Rust engine and tiers that index across memory, disk, and object storage instead of pinning it to RAM. Fewer round trips, no sync layer, and a memory bill that does not scale with your embedding count. If you are ready to stop managing three different databases and start building a real company brain, star HelixDB on GitHub and try the Helix CLI today.
### [AI Agent Memory Architecture: Why Vector Search Is Not Enough](https://www.helix-db.com/content/ai-agent-memory-architecture-why-vector-search-is-not-enough)
Learn why modern AI agent memory architecture requires knowledge graphs. Compare GraphRAG vs. vector search and see how HelixDB unifies both in one Rust engine.
# AI Agent Memory Architecture: Why Vector Search Is Not Enough
A clear lesson in modern AI development is that agents need more than a simple prompt; they require a robust way to store and recall experience. But if you follow most tutorials, your AI agent memory architecture is probably a single vector database. You chunk your text, embed it with an OpenAI model, and retrieve the top three results by cosine similarity. This works for a basic chatbot. It falls apart the moment you ask an agent to do complex reasoning or hold state across a long session.
Vector search is a similarity tool, not a memory system. Real memory means understanding how entities relate to each other, how those relationships change over time, and which facts carry more weight than others. When you build an autonomous agent for production, you find quickly that similarity is a poor substitute for logic. You need a data store that understands the structure of your information. This is why the industry is moving toward a unified graph-vector approach to fix the coherence problems that plague simple RAG pipelines.
## The Default Agent Memory Stack (and Why It Breaks)
The standard approach to AI agent memory architecture follows a predictable pattern. You store unstructured data in a vector database like Pinecone or Milvus. You keep structured application state in a relational database like Postgres. If you are feeling ambitious, you add a graph database like Neo4j to track complex relationships. This is what many developers call the duct-tape stack: a fragmented architecture that forces you to manage three different data models, three different query languages, and three different sets of permissions.
This stack breaks because agents cannot query across these silos in a single step. Imagine an agent trying to answer a question about a specific project budget. It first performs a vector search to find relevant document chunks. Then it queries Postgres to check who has permission to view those documents. Finally, it hits a graph to see if the person who wrote the document is still on the project team. By the time the agent has gathered all that context, you have made three round trips to different databases. That adds hundreds of milliseconds of latency to every turn of the conversation.
Data synchronization is the second point of failure. When a document is updated, you must update the vector index, the relational database, and the graph simultaneously. If one fails, your agent starts hallucinating based on stale or conflicting data. Maintaining consistency across a multi-database stack is an operational burden most small teams cannot afford. You end up spending more time on data plumbing than on agent logic. HelixDB solves this by putting graphs, vectors, and full-text search into one Rust engine.
## What Vector Search Actually Does, and Doesn't Do
Vector search is a mathematical trick for finding things that sound similar. It takes a piece of text and turns it into a long list of numbers called an embedding. When you search, the database finds other lists of numbers that are close in a high-dimensional space. This is excellent for finding a recipe for chocolate cake when a user asks for dessert ideas. It is terrible at finding the specific chocolate cake recipe that was approved by the head chef last Tuesday.
Similarity does not equal truth. Vector search is structurally blind to the specific connections between entities. It does not know that User A is the manager of User B. It only knows that the words "manager" and "User A" appear in the same paragraph. This leads to the orphaned chunk problem. Your database returns a highly relevant piece of text, but the agent has no idea where that text came from, who wrote it, or whether it is still valid.
Vectors also struggle with negation and precise constraints. If an agent asks for all reports excluding the Q3 update, a vector search will often return the Q3 update because the words "reports" and "update" are semantically close to the query. A vector index is a fuzzy lookup table. It is a component of memory, but it is not a complete memory system. It lacks the hard constraints and relational mapping required for an agent to move through a complex corporate knowledge base without making mistakes.
## The Four Memory Gaps That Kill Agent Coherence
When you rely solely on vectors, four specific gaps appear in your AI agent memory architecture. The first is the temporal gap. Most vector databases treat all data as if it exists in a flat, eternal present. They do not natively track when a fact was recorded or when it was superseded. For an agent managing a calendar or a project timeline, this is a fatal flaw. It might retrieve an outdated project plan from 2023 because it matches the query better than the current plan from 2026.
The second gap is relational depth. Real-world information is hierarchical. A company has departments, which have teams, which have projects, which have tasks. Vector search flattens this hierarchy into a list of chunks. The agent loses the context of how a small task relates to a larger corporate goal. Without a graph layer, the agent cannot walk up the tree to find the overarching objective.
The third gap is causal tracking. If an agent makes a mistake, it needs to remember why it made that choice to avoid repeating it. Traditional RAG systems do not store the chain of thought or the sequence of actions as part of the searchable memory. They have no record of cause and effect.
Finally, there is the permission gap. In a production environment, an agent should only remember what the current user is allowed to see. If your memory is a flat vector index, you have to build complex filtering logic on top of every query. This is often where security leaks happen. HelixDB narrows this at the storage layer with tenant-partitioned vector indexes. Pass a tenant and the nearest-neighbor search runs inside that partition instead of over the global index, so the boundary is part of the query rather than a filter you remember to apply afterwards.
## Why a Knowledge Graph Fixes What Vectors Can't
A knowledge graph introduces formal structure to your agent memory. Instead of storing chunks of text, you store nodes representing entities like people, projects, and concepts. You connect these nodes with edges that define their relationships. This allows an agent to perform multi-hop reasoning. For example, an agent can find all documents written by anyone who reports to the Engineering VP. A vector database cannot do this without a massive, inefficient pre-filtering step.
When you combine a knowledge graph with a vector index, you get the best of both. You can use vector search to find an entry point into the graph, then use graph traversal to explore the related context. This is the foundation of GraphRAG. If an agent is researching a technical bug, it can use vectors to find the error message in a log file, then use the graph to find the specific code commit that introduced the bug and the developer who wrote that code.
This architecture gives the agent a ground truth. The graph is the skeletal structure of the memory, while the vectors provide descriptive detail. This combination reduces hallucinations because the agent can verify facts against the defined relationships in the graph. If the graph says Project X ended in 2025, the agent will not suggest it as a current priority, regardless of what a vector search returns. HelixDB is designed as a single engine to handle these traversals and similarity searches in a single serializable transaction.
## GraphRAG vs. Naive RAG: What the Benchmarks Show
The performance difference between naive RAG and GraphRAG is not just theoretical. Researchers at Microsoft demonstrated that GraphRAG improves the comprehensiveness and diversity of answers for complex queries (Microsoft, 2024). In their testing, naive RAG often missed critical context that was only one or two hops away from the primary search result. GraphRAG was able to synthesize information across entire datasets by following the edges of the knowledge graph.
Naive RAG has a ceiling. Once your document store grows beyond a few thousand pages, the signal-to-noise ratio in vector search drops. You start getting chunks that are semantically similar but contextually irrelevant. GraphRAG maintains its accuracy at scale because it uses the graph to prune the search space. It does not just look for similar text; it looks for similar text within a specific, relevant neighborhood of the graph.
For developers building AI agent memory architecture, this means higher reliability. There is no independent benchmark of multi-step task completion across memory architectures that we would stand behind, so take the mechanism rather than a number as the argument. When the answer depends on the relationship between disparate data points, such as linking a customer support ticket to a specific product version and a known bug report, retrieval that can follow an edge finds it and top-k similarity has to get lucky.
## What a Unified Graph-Vector Memory Store Looks Like
A unified memory store eliminates glue code by merging the data models. In HelixDB, an embedding is a property on a node or an edge, indexed in place by the same engine that stores the graph. You are not writing the vector to one system and the node to another, and you are not keeping two indexes in sync. One request can find a node by its ID, traverse three levels deep through its relationships, and then run a vector similarity search across everything it found at that depth. Because the index sits inside the graph engine, you can also pre-filter: scope the nearest-neighbor search to vectors hanging off a specific set of related entities, rather than sweeping a global index and throwing most of the results away.
Time is where the range indexes earn their place. You timestamp the nodes and edges that represent events, and HelixDB indexes those timestamps so reading them back stays cheap as the history grows: gt, gte, lt, lte and between, plus ordered scans in either direction, so everything between Tuesday and Thursday is an indexed scan over a sorted range and the last twenty events is a descending scan you can stop early. It composes with a scoped vector search too, so recency and semantic relevance resolve in one request rather than two. If you are building a legal or financial agent, that is the mechanism you want. Knowing what the policy was on the day a transaction occurred becomes an indexed range scan instead of a full traversal you filter afterwards.
Native MCP support is another critical feature of a modern memory store. The Model Context Protocol allows agents to discover and interact with the database directly. Instead of a developer writing every possible query ahead of time, the agent can use MCP to explore the graph and build its own queries step-by-step. This turns the database from a passive storage bin into an active participant in the agent reasoning process. That is the difference between a static knowledge base and a dynamic company brain.
## Building Agent Memory Without the Multi-DB Tax
The multi-DB tax is the hidden cost of complexity. It is the time spent configuring Docker containers for three different databases and the money spent on three different cloud bills. When you use a unified engine like HelixDB, you pay this tax once. HelixDB is written in Rust, which rules out a class of memory bugs at compile time and lets the engine manage the lifetime of large indices explicitly rather than leaving it to a collector. That is narrower than it sounds and worth keeping narrow: safe Rust prevents data races, not logical races, deadlocks or resource exhaustion, and consistency across concurrent readers and writers is the transaction layer's job rather than the compiler's. You get graph, vector, full-text, and key-value storage in a single binary.
Developer experience improves on a single engine. Queries are written directly in your application code through the Rust, TypeScript, Go, and Python SDKs, which serialize to a JSON query sent as a single HTTP request. There is no separate query language to learn and no compile or push step: the SDK sends JSON and the database turns that JSON into the query it runs, so your own type checker is what catches a bad query before an agent runs into it mid-conversation.
For teams moving from a prototype to production, the transition is often painful because the simple Pinecone setup they started with cannot scale to meet complex requirements. Starting with a unified graph-vector architecture prevents this rework. It lets you begin with simple vector search and gradually add graph relationships as your agent becomes more sophisticated. You can self-host the open-source version under the Apache-2.0 license, running it fully in memory, on disk, or against S3-compatible object storage, or use the managed Helix Cloud to handle the infrastructure. Either way, you are building on a foundation designed for the future of agentic AI.
## Conclusion
The simple vector-only RAG pipeline is running out of road. As agents take on more autonomous responsibility, the flaws in flat similarity search become impossible to ignore. A reliable AI agent memory architecture requires the structural integrity of a knowledge graph and the semantic flexibility of vectors. HelixDB provides this in a single, high-performance Rust engine. It cuts the operational overhead of managing multiple databases and gives your agents a coherent, time-aware memory. Star HelixDB on GitHub today and start building a company brain that actually remembers.