The starter relation vocabulary

[antejavor]

Part of #344

Question

What is the minimal set of relation types that agent-session memory actually needs, with their domain/range bindings?

default_ontology.yaml ships 11 entity types and zero relation types, and it is the only ontology anything in this repo has ever run. The plan deliberately froze it that way and deferred a real vocabulary to "later, once a real project-specific ontology exists." That deferral is precisely what produced an edgeless graph, so it is in scope here.

Deliberately small — enough to exercise and validate the machinery, not a complete domain ontology. Authoring a full one is its own effort.

Open:

1. Which relations. What does agent-session memory actually need to answer the kinds of questions it gets asked? Candidates worth pressure-testing rather than assuming: works_for, located_in, uses, part_of, decided, prefers. The existing unstructured2graph/evals/gold_corpus.jsonl already exercises works_for / founded / located_in, and its README records that the natural chat corpus carries almost no explicit named-entity-to-named-entity relations (verified: zero matches for "works at/for|founder|founded|CEO|professor at|based in|headquartered" across the whole corpus). So a vocabulary copied from that eval may be a poor fit for real session text — which may itself be the finding.
2. Domain/range per relation. Which of the 11 existing entity types can sit at each end. Note Concept, Content, Artifact, Method, Data, NaturalObject, Creature are deliberately wide categories; a relation bound to Concept at both ends constrains almost nothing.
3. Relations between what, exactly. LongMemEval-style questions ("what was Admon's Sunday shift", "how many months since I visited a museum") often hinge on facts that are not entity-to-entity at all — they are attributes, quantities, or temporal facts. Does a relation vocabulary even address them, or does this surface a need for something else (span attributes, which GLiNER2.5 also offers)? This is the question most likely to reshape the map.
4. Where it lives. Extending default_ontology.yaml vs a separate context-graph-specific ontology file. Partly fog until the vocabulary exists, but flag it if the answer becomes obvious while authoring.

[antejavor]

Resolution

The ticket asked "which relations". The answer turned out to be that we don't hand-author a list at all — but getting there settled eight decisions, and reframed the primitive itself.

What the corpus actually demands (measured, not assumed)

Question-type distribution across the committed 100:

type	n
multi-session	26
temporal-reasoning	26
knowledge-update	16
single-session-user	15
single-session-assistant	11
single-session-preference	6

42% (temporal-reasoning + knowledge-update) is about time and change, which a plain typed binary edge cannot express. And 98/100 questions are first-person — the subject of nearly every fact is the user.

A real knowledge-update case decided the supersession question on its own: "Where do I initially keep my old sneakers?" → "under my bed". It asks for the value that was superseded. "Newest wins" would delete the answer.

Decisions

1. Primitive: time-anchored binary relations. Every edge inherits valid_at from the session that produced it. Session.started_at already carries the real date (inject.py:75), so our writer stamps it — nothing is asked of the extractor. Plain untimed relations were rejected: they cannot serve 42% of the corpus.
2. Supersession: timestamp only. Both edges retained, neither marked superseded; the query picks (ORDER BY valid_at DESC for current, ASC for initial). Rejected an explicit SUPERSEDES marker and valid_from/valid_to intervals because both require the writer to detect that two facts conflict — the identity problem again, in edge form — and a wrong detection silently destroys a real answer. The corpus wants initial and current symmetrically, so neither is privileged.
3. Ontology is a property of the data, derived per corpus — LlmRecommendationStrategy proposes a vocabulary from a sample of the actual corpus, then it is frozen for that deployment. This dissolves the "LongMemEval shape or coding-session shape?" question: both, each from its own data. Consistent with the project's multi-use-case thesis (the schema must match usage shape rather than being fixed up front).
4. Derivation is fully automatic — no human approval. Explicitly overrides the plan's §4 recommendation ("human review before use: recommended yes"). Accepted risk: a bad derivation propagates into every extraction under that vocabulary. Bounded by ADR 0004 and decision 2 — the system keeps everything and Chunk.text is retained, so a bad vocabulary costs bad labels, never lost data, and re-extraction is always possible.
5. What replaces the human gate: self-validation (hard) + stability check (reporting). A derived model must satisfy hygm.validation's issue categories to be accepted — no dangling start_labels/end_labels, no duplicate types, no relation referencing an undeclared type. Separately, derive twice from different samples and record the divergence as a property of the ontology, without blocking on it. Blocking on instability would reintroduce a gate needing a human when it trips, which Release Langchain as toolkit  #4 rules out.
6. User becomes an entity type; the model extracts it. Verified empirically rather than assumed — GLiNER2 resolves first-person pronouns:

   keeps           'I' -> 'sneakers'                (0.78)
   visited         'I' -> 'Natural History Museum'  (0.89)
   accompanied_by  'I' -> 'Sarah'                   (0.97)
   

   Chosen over binding the head by construction, for uniformity: every relation is declared and extracted the same way.
7. Processing collapses User extractions onto the session's (:User) node. The same run returned I as three entities and triplicated every edge — nine where there should be three. Since every "I" in a session is the same known person, this is the one identity case with a free answer, and it must not be routed through Entity identity across chunks #346's general similarity mechanism.
8. Anonymous sessions: processing synthesises (:User {user_id: "anon:<session_id>"}).

Layering constraint (carried through all of the above)

Collection — the Claude Code / Codex hooks, via sessions_graph/connector.py:_on_session_start — writes (:User)-[:HAD_SESSION]->(:Session), but only when event.user_id resolves from [identity] user_id. Without it, a bare (:Session) and, in the eval harness's own words, a "half recorded" session.

Processing — core.py's reconcile_session — is where extraction and the User collapse live. It may only read what collection wrote; it never reaches back into the collection tier. Decision 8 exists precisely so processing degrades on its own rather than requiring a collection-tier change.

Concrete gap this exposed: the eval injector never sets a user, which is why the reconciled 501-session graph contained Session, Episode, Chunk, Action and all eleven gliner2 entity labels but zero (:User) nodes. Filed separately as cleanup — not a precondition, since decision 8 makes processing work regardless.

Consequences for the rest of the map

• There is no hand-authored starter vocabulary. The deliverable changed from a list of relation types to a derivation contract.
• LlmRecommendationStrategy moves from out-of-scope (the plan deferred it) to load-bearing. Its open design questions — sampling and prompt contract — are now on the map.
• Wire a constrained ontology and read the edges #350's prototype should use a small hand-written stand-in vocabulary rather than waiting on derivation; it is judging extraction quality, not derivation quality.
• Entity identity across chunks #346 no longer needs to solve identity for User — decision 7 settles it.
• The full versioned evolution loop is out of scope for this map and needs its own.

[antejavor]

The User collapse half is revised by #350's output; revision is tracked in #358. Everything else here stands.

This ticket decided that processing collapses all User mentions onto the session's (:User) node. #350 ran a typed ontology over 10 real sessions and measured what lands in that type: of 599 User endpoints, 502 are first-person forms, 12 are the literal 'assistant', and 85 are third parties — 'kahlo' x38, 'frida' x33, 'frida kahlo' x11, 'you' x2, 'magdy' x1. Collapsed unconditionally, visited(User:'kahlo' -> Location:'Paris') and owns(User:'assistant' -> Product:'Trello') become "the user visited Paris" and "the user owns Trello" — the first from an art-history digression, the second from a tool the assistant recommended.

Confirmed rather than revised: User is a working extracted entity type, and first-person resolution works (the #328 role prefix means every turn also contributes a literal 'user' mention, which is why the type is so densely populated). Time-anchoring rode through the prototype as valid_at stamped by the writer and behaved as specified.

Also worth carrying back here: the fragmentation shape. #350's highest-degree merged nodes are User:'user' (364) and User:'i' (132) — the same entity, and #346's exact-normalized-text-within-type rule cannot join them. The session-node collapse this ticket decided is the only mechanism that can, which is an argument for keeping it in some form rather than dropping it, and is why #358 is about narrowing the rule rather than deleting it.

[antejavor]

Revised by #364: valid_at is the source turn's Action.timestamp, not the session's, and is written as a Memgraph temporal value rather than the raw string (Session.started_at currently holds the corpus's '2023/05/30 (Tue) 17:27'). After #352 each edge comes from exactly one turn's window, so the turn is known. It is correct for a session resumed days later, and it makes date arithmetic a deterministic duration.between. The eval's inject.py must stamp each turn with its fixture's date: today turns carry ingest time.