Hyperedges

A hyperedge stores one fact that relates more than two nodes. Zep stores the fact on member edges. Each member edge connects two of the nodes, and every member has the same hyperedge_uuid.

The hyperedge response holds shared values at the top level: fact, valid_at, invalid_at, expired_at, created_at, graph_uuid, and uuid. Each item in edges has its own uuid, name, source_node_uuid, and target_node_uuid. Zep orders the members by uuid.

Add a hyperedge

Use graph.edge.add for a fact about one node pair. Use graph.hyperedge.add when the members span at least three distinct nodes.

The request needs fact and edges. Each member needs a name, source_node, and target_node. You can also set valid_at, invalid_at, expired_at, attributes, and metadata. Zep stores attributes on every member and attaches metadata to the episode created for the hyperedge.

Zep assigns the hyperedge UUID and member edge UUIDs when it accepts the task. The member edges become readable after the task completes. Use task polling to check completion.

from zep_cloud import EdgeNodeRef, HyperedgeInput
result = client.graph.hyperedge.add(
    graph_uuid,
    fact="Alice introduced Bob to Carol at the conference.",
    edges=[
        HyperedgeInput(
            name="INTRODUCED_TO",
            source_node=EdgeNodeRef(name="Alice"),
            target_node=EdgeNodeRef(name="Bob"),
        ),
        HyperedgeInput(
            name="INTRODUCED_TO",
            source_node=EdgeNodeRef(name="Alice"),
            target_node=EdgeNodeRef(name="Carol"),
        ),
        HyperedgeInput(
            name="MET",
            source_node=EdgeNodeRef(name="Bob"),
            target_node=EdgeNodeRef(name="Carol"),
        ),
    ],
)

Read hyperedges

Use graph.hyperedge.get to read one hyperedge. If an access policy hides any member, the API returns 404 for the whole hyperedge.

Use graph.hyperedge.list to read a page of hyperedges. It supports node_uuids, edge_uuids, and episode_uuids filters. A hyperedge matches a filter when any member matches. It must match every filter you provide. The API rejects other filters. The response has no total_size. Zep lists a hyperedge while it has at least one member.

Update a hyperedge

graph.hyperedge.update accepts only fact. Zep writes the new fact to every member in one all-or-nothing update. The name field belongs to each member. If you change fact with graph.edge.update on one member, Zep updates the fact on every member.

Change hyperedge membership

Use graph.hyperedge.create_edge to add one member. Set only name, source_node, and target_node. Use an upper-snake-case value for name. The new member inherits the hyperedge’s fact, timestamps, and episodes.

Use graph.hyperedge.delete_edge to remove one member. Deleting the last member removes the hyperedge. Use graph.hyperedge.delete to delete every member.

Retrieve hyperedge facts

graph.get_context writes each hyperedge fact once in the context block.

Extract hyperedges from episodes

Zep can extract hyperedges from the episodes that you add. The project setting hyperedges_enabled on GET /project and PATCH /project controls the extraction.

To enable extraction, open the project settings in the dashboard. An Account Owner, Account Admin, or Project Admin can select Enable Hyperedges.

Project Editors cannot enable extraction. Project API keys cannot set hyperedges_enabled. If a project API key sends hyperedges_enabled: true to PATCH /project, the API returns 403 permission_denied. A project API key can still read the value with GET /project.

The setting applies to the episodes that Zep receives after the change. Zep does not process again the episodes that it received before the change. An episode that is in the queue at the time of the change keeps the previous value.

The hyperedge API and the hyperedge reads do not use the setting. You can add and read hyperedges in a project where hyperedges_enabled is false.