hm_add_relationships

hm_add_relationships links nodes that already exist. Use it to connect orphans to their context, to add edges that were missed when a node was stored, or to record one fact that spans many nodes as a hyperedge.

Parameters

Parameter	Type	Description
`relationships`	array	Required. 1–25 relationships. Each call is one atomic write; split larger sets into several calls.

Each relationship is either a binary edge (from_key + to_key) or a hyperedge (participant_keys):

Field	Type	Description
`relationship`	string	Required. Plain-language wording of the connection and why it holds.
`from_key`	string	Binary edge: the node the connection starts from.
`to_key`	string	Binary edge: the node it points to.
`participant_keys`	string[]	Hyperedge: 2–256 participating node keys.
`roles`	string[]	Hyperedge: optional role of each participant, in `participant_keys` order (same length). Defaults to `participant`.
`relationship_type`	string	Optional ontology relationship type. Defaults to `related_to`.
`description`	string	Optional longer explanation.
`data`	object	Optional structured facts about the connection.

All nodes must already exist. A relationship whose node is missing is skipped and reported in errors (endpoint_not_found); the rest of the call is still written.

Idempotent by design

Asserting the same fact twice never creates a duplicate:

A binary edge is identified by its type and its two endpoints. Asserting it again with new wording updates the wording.
A hyperedge is identified by its relationship wording and participant set (order doesn’t matter). Repeating it — in the same call or later — returns the existing hyperedge with replayed: true.
“funds” and “works on” over the same nodes are two different facts.
Hyperedge ids are canonical keys assigned by the server. A key you send is kept only as data.client_key.
Retrying a call whose answer was lost is safe.

Session hyperedges (keys starting with chat_, data.hyperedge_kind: "session") are reserved for the server, which uses them to group what was written in one conversation.

Response

Field	Description
`created`	Every relationship written, with `replayed: true` for those that already existed.
`errors`	Every relationship that failed, with the reason.
`summary`	`requested`, `written`, `already_existed`, `failed`.
`effects`	Counts of the entities this write changed.

Example

{
  "relationships": [
    {
      "from_key": "fix_checkout_timeout",
      "to_key": "bug_checkout_timeout",
      "relationship": "fixes the checkout timeout by raising the payment gateway deadline to 30s"
    },
    {
      "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"
    }
  ]
}

Equivalents

curl -X POST https://api.hypermemory.io/api/v1/memory/relationships \
  -H "Authorization: Bearer $HYPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"relationships":[{"from_key":"person_alice","to_key":"project_phoenix","relationship":"Alice leads Project Phoenix"}]}'

To list a node’s relationships over REST, call GET /api/v1/memory/relationships/{key} (CLI: hm relationships KEY).