Hypergraph relations

Shipped in v3-alpha (Beta). Extends the binary mnemo_relation model with n-ary hyperedges. Interfaces may still change before 3.0 stable.

Why binary relations are insufficient

v2 models edges as A --relates_to--> B (pairwise). Reality is often n-ary:

“When deploying (A), if the DB migration (B) fails AND the rollback script (C) is outdated, then the incident runbook (D) applies.”

That’s a 4-ary association. Binary relations express it as 6 pairwise edges and lose the joint constraint — any 2 of the 4 might trigger spurious recalls.

The hyperedge model

CREATE TABLE mnemo_hyperedge (
  id           TEXT PRIMARY KEY DEFAULT gen_cuid2(),
  workspace_id UUID NOT NULL,
 
  -- The association
  member_ids   TEXT[] NOT NULL,  -- ordered fact/entity/decision IDs
  label        TEXT,             -- "deployment-failure-scenario"
  description  TEXT,             -- human-readable explanation
 
  -- Context
  context_query     TEXT,
  context_embedding halfvec(1536),
 
  -- Strength
  activation_count INT DEFAULT 0,
  worth FLOAT DEFAULT 0.5,
 
  -- Bitemporal (same as facts)
  created_at TIMESTAMPTZ DEFAULT now(),
  valid_from TIMESTAMPTZ DEFAULT now(),
  valid_to   TIMESTAMPTZ,
 
  CONSTRAINT min_members CHECK (array_length(member_ids, 1) >= 3)
);
 
CREATE INDEX idx_hyperedge_members ON mnemo_hyperedge USING gin (member_ids);
CREATE INDEX idx_hyperedge_context ON mnemo_hyperedge
  USING hnsw (context_embedding halfvec_cosine_ops);

Recall integration

// During recall, after finding individual facts:
// 1. Check if any recalled facts are members of a hyperedge
// 2. If so, include ALL members of that hyperedge in results
// 3. Weight by hyperedge.worth (only include if worth > 0.5)

Formation

Automatic — when ≥3 facts are consistently co-recalled (Hebbian)
Manual — agent explicitly creates via memory_self_edit
Extracted — LLM identifies n-ary patterns during consolidation