feat: add the relationship graph with extraction, corrections and explorer

Phase 11. Entities are mind-scoped nodes with canonical matching, aliases and deterministic kind guessing (hostnames and hyphenated ids are systems, capitalised names people, file suffixes documents). Relationships carry a relation from the shared vocabulary, confidence, source, reinforcement count and the event that produced them; links tie entities to memories, beliefs, events, goals and predictions. The perceive and attend handlers upsert the entities a message or observation mentions and record co-mention edges cited to the event, so the graph grows only from what was actually seen. Operators can merge ("these are the same": edges and links move, the old name becomes an alias, the old id still resolves), record that two entities are different, correct kinds and add typed edges; every correction is an operator action and a corrections row. The explorer renders a bounded subgraph on a canvas with a small force-directed layout in plain JavaScript, with kind filters, focus on a neighbourhood and a side panel per entity. API, entity page, CLI and docs/graph.md.
2026-06-29 19:28:55 +01:00
parent 703d080d13
commit 99a89ba847
25 changed files with 1455 additions and 22 deletions
@@ -0,0 +1,48 @@
+-- Entities and typed relationships (spec §24). Entities are mind-scoped;
+-- merges keep the loser row with merged_into so history never dangles.
+
+CREATE TABLE entities (
+  id            uuid PRIMARY KEY,
+  mind_id       uuid NOT NULL REFERENCES minds(id),
+  kind          text NOT NULL CHECK (kind IN ('person','system','project','document','concept','repository','organisation','place','other')),
+  name          text NOT NULL,
+  canonical     text NOT NULL,
+  aliases       text[] NOT NULL DEFAULT '{}',
+  description   text NOT NULL DEFAULT '',
+  attributes    jsonb NOT NULL DEFAULT '{}'::jsonb,
+  mention_count integer NOT NULL DEFAULT 0,
+  first_seen    timestamptz NOT NULL DEFAULT now(),
+  last_seen     timestamptz NOT NULL DEFAULT now(),
+  merged_into   uuid REFERENCES entities(id),
+  created_at    timestamptz NOT NULL DEFAULT now()
+);
+CREATE UNIQUE INDEX entities_canonical_idx ON entities (mind_id, canonical) WHERE merged_into IS NULL;
+CREATE INDEX entities_mind_kind_idx ON entities (mind_id, kind, mention_count DESC);
+
+CREATE TABLE entity_relationships (
+  id          uuid PRIMARY KEY,
+  mind_id     uuid NOT NULL REFERENCES minds(id),
+  from_entity uuid NOT NULL REFERENCES entities(id),
+  to_entity   uuid NOT NULL REFERENCES entities(id),
+  relation    text NOT NULL,
+  confidence  double precision NOT NULL DEFAULT 0.3,
+  source      text NOT NULL DEFAULT '',
+  event_id    uuid,
+  count       integer NOT NULL DEFAULT 1,
+  first_seen  timestamptz NOT NULL DEFAULT now(),
+  last_seen   timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (from_entity, to_entity, relation)
+);
+CREATE INDEX entity_relationships_to_idx ON entity_relationships (to_entity);
+
+-- Mentions: which memories, beliefs, events, goals and predictions involve an entity.
+CREATE TABLE entity_links (
+  id         uuid PRIMARY KEY,
+  mind_id    uuid NOT NULL REFERENCES minds(id),
+  entity_id  uuid NOT NULL REFERENCES entities(id),
+  kind       text NOT NULL,
+  ref_id     uuid NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (entity_id, kind, ref_id)
+);
+CREATE INDEX entity_links_ref_idx ON entity_links (kind, ref_id);