Edges & hyperedges

Edges

An edge (relates_to record in SurrealDB) is a directed binary relationship between two nodes with:

Field	Description
relationship	A natural-language label describing the connection
data	Optional JSON metadata (weights, status, timestamps)

Edges are canonicalized by the server — relationship labels are normalized for consistency.

Example edge

{
  "from": "person_sarah",
  "to": "project_phoenix",
  "relationship": "Sarah is the technical lead for Project Phoenix",
  "data": {"since": "2026-01"}
}

Hyperedges

A hyperedge connects three or more nodes in a single relationship. This is implemented as a hyperedge record with participates_in links to each member node.

Example hyperedge

{
  "nodes": ["person_sarah", "person_marcus", "project_phoenix", "event_q3_planning"],
  "relationship": "Sarah and Marcus presented the Phoenix roadmap at Q3 planning"
}

How relationships are created

At store time — hm_store triggers background enrichment that automatically detects entities and creates relationships.

Explicitly — use the REST API endpoint POST /api/v1/memory/relationships to create edges between existing nodes.

Via update — use hm_update to modify relationships on a node.

Via ingest — hm_ingest decomposes dense text into entities and their relationships in one LLM pass.

When to use 2 vs N nodes

Situation	Pattern
Two actors only	Binary edge (2 nodes)
A decision, several stakeholders, a milestone	Hyperedge (N nodes in one relationship)
Soft tag between two things	Binary edge with a specific relationship label

Querying relationships

• Hybrid search: hm_recall searches node descriptions, edge labels, and data fields using BM25, vector similarity, and regex.
• Graph traversal: hm_find_related walks from a starting node with configurable traversal strategies (chain, decay, type-boosted).
• REST endpoint: GET /api/v1/memory/relationships/{key} lists edges connected to a specific node.

Next steps

Nodes

Keys, descriptions, data

Memory graphs

Multiple isolated knowledge bases