Edges & hyperedges

Edges

An edge connects two nodes in one direction and says, in plain language, how they relate and why.

{
  "from_key": "component_checkout",
  "to_key": "tech_redis",
  "relationship": "checkout service uses Redis for session caching and rate limiting"
}

Field	Description
relationship	The wording of the connection. Be specific about why it holds — “uses Redis for session caching”, not just “uses”.
relationship_type	An ontology relationship type. Defaults to related_to.
description	An optional longer explanation.
data	Optional structured facts about the connection: since when, how strong, which version.

An edge is identified by its type and its two endpoints, so asserting it again updates the wording instead of adding a duplicate.

Hyperedges

A hyperedge is one fact over 2 to 256 nodes, with an optional role for each:

{
  "participant_keys": ["release_2_4", "fix_checkout_timeout", "deploy_2026_10_14", "person_alice"],
  "roles": ["release", "change", "deploy", "release manager"],
  "relationship": "Release 2.4 shipped the checkout timeout fix in the 14 October deploy, managed by Alice"
}

A hyperedge is identified by its wording and its set of participants (in any order). Asserting the same fact again returns the existing hyperedge.

When to use which

Situation	Use
A simple fact between two things	Edge
A meeting, decision or event with several participants	Hyperedge
Five or more nodes that make up one piece of work — a feature, release, incident or investigation	Hyperedge naming what they jointly are

How relationships get written

Way	When
With the node — relationships on hm_store	The usual way. Up to 99 relationships, written in the same transaction as the node.
Afterwards — hm_add_relationships	To connect existing nodes or orphans. Up to 25 per call.
By enrichment	HyperMemory’s background workers detect entities in descriptions, discover relationships and add hyperedges.
From documents	Uploaded files are linked to everything extracted from them.

Editing and deleting

• Change an edge’s wording or data with hm_update and its edge_id. Pass edge_version to avoid overwriting someone else’s change.
• Change its endpoints or type, or change a hyperedge: delete it with hm_forget and edge_id, then add it again.
• Deleting an edge never deletes the nodes it connects. Deleting a node deletes its edges.

Edge ids and versions come back from hm_get_nodes.

Session hyperedges

HyperMemory groups the nodes one conversation touched under a session hyperedge (keys starting with chat_). These are reserved for the server; you read them with hm_get_chat_context.

Querying relationships

• hm_recall returns each hit with its strongest relationships in expansion_context.
• hm_find_related walks outward from a node.
• hm_get_nodes returns a node’s edges and hyperedges in full.
• GET /api/v1/memory/relationships/{key} lists one node’s relationships over REST.