Graph queries | Brain Docs

Prerequisites

A Brain client with credentials.
Memories already written that mention named entities (people, orgs, products, places) — the write pipeline extracts the graph from them.
Familiarity with Recall and the entities concept.

What you'll build

An "entity explorer" that resolves a name to an entity, reads its relations, traverses one or two hops out, and falls back to recall when there is no named entity.

Recall vs the graph — pick correctly

recall answers "what do I know about X?" by fusing semantic, lexical, and entity-graph retrieval over memories. It is your default. The graph endpoints are for when you already have the entity and want structured nodes and edges — for a graph UI, or for an agent that walks relationships programmatically.

The typed graph is documented in full under Entities & typed graph and Graph. This guide is the task recipe.

Step-by-step

Names aren't unique. POST /v1/entities/resolve runs the multi-tier resolver and returns an outcome (resolved, created, ambiguous, or not_found) plus the bound entity_id.

curl -X POST https://api.arc-labs.ai/v1/entities/resolve \
  -H "Authorization: Bearer $BRAIN_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "candidate_name": "Priya Sharma", "type_hint": 1 }'

{ "outcome": "resolved", "tier": 1, "confidence": 0.97, "entity_id": "0a1b2c3d-…", "candidate_ids": [] }

On ambiguous, candidate_ids holds ranked entity ids to disambiguate between. On the wire client, this is resolveEntity.

GET /v1/entities/{id}/relations lists the relations touching an entity in a direction (from outgoing, to incoming). Each relation carries its type, endpoints, confidence, and bi-temporal validity window.

curl "https://api.arc-labs.ai/v1/entities/0a1b2c3d-…/relations?direction=from&limit=50" \
  -H "Authorization: Bearer $BRAIN_API_KEY"

To read the facts about the entity (subject–predicate–object), list statements filtered by subject: GET /v1/statements?subject=0a1b2c3d-….

POST /v1/entities/{id}/traverse walks the relation graph from an anchor entity. Depth and node count are bounded server-side (max_depth clamped [1, 5], max_nodes [1, 1000]).

curl -X POST https://api.arc-labs.ai/v1/entities/0a1b2c3d-…/traverse \
  -H "Authorization: Bearer $BRAIN_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "direction": "outgoing", "max_depth": 2 }'

The response is { paths, total_paths, truncated }; truncated: true means a bound was hit before the graph was exhausted. On the wire client this is traverseRelations (with traverseRelationsFrames for the streamed form — see Streaming).

For a visualization, GET /v1/graph exports the typed graph as a paginated nodes-and-edges snapshot. Toggle include_memories to add provenance (which memory asserted each edge) and include_statements for value-object nodes.

curl "https://api.arc-labs.ai/v1/graph?limit=200&include_memories=true" \
  -H "Authorization: Bearer $BRAIN_API_KEY"

Nodes and edges may repeat across pages — dedupe by id. A missing next_cursor means the export is complete. See Graph for the node/edge shapes.

A small decision tree:

The cue names a known entity → resolve it, then read its relations or traverse.
The cue is free-text with no named entity → recall.
You need structured neighbourhood for a UI or an agent walk → the graph endpoints.
You just want the answer, entity or not → recall; the entity-graph retriever already contributes to the fused result.

Managing entities over the wire

Explicit typed-graph writes — createEntity, createStatement, createRelation, mergeEntities, uploadSchema — are wire-only; the HTTP client is a read/subset surface for the graph. Typed-graph writes check per-type against the active schema: a create referencing a declared type is accepted, an undeclared type is rejected. Upload your schema first.

const { entityId } = await client.createEntity({
  entityTypeId: 1,
  canonicalName: "Priya Sharma",
  aliases: ["Priya"],
  attributesBlob: new Uint8Array(),
  requestId: newId(),
  actAs: null,
});

See Typed graph for create, resolve, schema upload, traversal, and merge.

Merged and tombstoned entities are excluded from reads by default. When you merge duplicates (mergeEntities), the source becomes an alias of the target and its relations rebind — schedule a periodic dedup pass over GET /v1/entities filtered by type, because drift here silently degrades retrieval quality.

Recall vs the graph — pick correctly

Step-by-step

Managing entities over the wire

On this page