context-graph/unstructured2graph: typed relation model on a shared hygm ontology (map #344)

[antejavor]

Closes #344. Closes #357. Closes #365. Closes #371.

• unstructured2graph: entity_id is MERGEd on but never indexed or constrained #357: ensure_lookup adds both a unique constraint and an index. In Memgraph the constraint alone doesn't index.
• unstructured2graph: gliner2's compiled-schema cache is keyed on a memory address #365: the compiled schema is held for the backend's lifetime and passed compiled, which bypasses gliner2's address-keyed cache.
• unstructured2graph: gliner2 cuts relation candidates alphabetically by type on ties #371: both candidate caps are 4096.

Implements map #344 (typed relation model) with hand-written ontologies through ManualStrategy. The derived vocabulary (LlmRecommendationStrategy) stays an interface until its evidence run, #372, passes. The revised plan puts that second, then a full eval as confirmation.

What changes

hygm (new workspace package, pure Python)

• NodeType(label, description, identity), where identity is global, chunk or span (Entity identity across chunks #346, Values, not links: do entity attributes belong in the model #361).
• RelationType(label, description, start_labels, end_labels). Empty endpoints mean any declared label.
• validate_model is the hard gate: labels unique, endpoints declared, and User requires Person (Which User mentions are the user #358).
• Strategies:
  • ManualStrategy (YAML);
  • OwlImportStrategy (owl:Class/owl:ObjectProperty, rdfs:domain/rdfs:range, including owl:unionOf; the hygm[owl] extra);
  • LlmRecommendationStrategy plus an Observer protocol, interface only.

unstructured2graph

• Ontology loads through ManualStrategy. The YAML gains identity, start_labels and end_labels.
• enforce_relation_domain_range is the post-hoc half of the one-spec, two-compilation model (Extraction-time constraints vs post-hoc validation #348). It runs under enforce_ontology and flags a mismatch, never deleting it. ADR 0004 is amended to cover relations.
• ontology_report returns integrity counts and Does LightRAG consume domain/range too #349's coverage signal: untyped relationships versus none at all, and declared types with zero instances.
• from_documents / Document / Segment: text stored verbatim, one Chunk per document, with turn segments. unstructured's partitioner rewrites text (it drops list bullets and folds tables), which would break turn offsets.
• ensure_lookup adds a unique constraint and an index on Chunk.hash and <workspace>.entity_id (unstructured2graph: entity_id is MERGEd on but never indexed or constrained #357). Verified with EXPLAIN: in Memgraph a uniqueness constraint alone does not index, so every lookup was a label scan.
• connect_chunks_to_entities is an indexed lookup instead of a cartesian product.

GLiNER2Backend, rewritten on gliner2.joint_ie

• The typed JointSchema is compiled once and held (unstructured2graph: gliner2's compiled-schema cache is keyed on a memory address #365). Both candidate caps are 4096 (unstructured2graph: gliner2 cuts relation candidates alphabetically by type on ties #371).
• One window per turn, split only past 384 gliner2 words (Chunking and the durability of constraints #352).
• The mention resolver (Which User mentions are the user #358):
  • the user's own mentions bind to (:User {user_id});
  • third parties are re-typed Person;
  • first person in the assistant's mouth is dropped.
• Per-type identity, with MENTIONED_IN written for every chunk a node is mentioned in (Entity identity across chunks #346).
• Relationships are MERGEd per source chunk, carrying valid_at (a Memgraph datetime, from the turn, Resolving relative dates against valid_at #364) and confidence. Superseded facts are kept.
• Self-loops left after identity resolution are dropped and counted (The read-time contract for non-conformant edges #355).

sessions-graph

• reconcile_session sends one segmented Document, with the speaker and Action.timestamp per source.
• A session with no recorded user gets a synthesized anon-<session_id> user (The starter relation vocabulary #347, context-graph-eval: injector never sets a user, so reconciled graphs have no (:User) nodes #354). It is anon- because validate_user_id rejects :.
• ReconciliationSummary gains nonconformant_entities and nonconformant_relations.
• LightRAG also gets the verbatim text on this path now. The LightRAG batch path is unchanged.

eval

• Injected turns are stamped with the session date plus their index in seconds, instead of ingest time (Resolving relative dates against valid_at #364).
• GLiNER2 extracts against a bundled ontologies/longmemeval.yaml, Values, not links: do entity attributes belong in the model #361's hand vocabulary. A non-conformant session is reported as an error.

Follow-ups from running this on a 500-session eval batch:

• Post-processing covers only the chunks just ingested (25d7349). Linking, label promotion, the domain/range check and ontology_report rescanned the whole workspace after every session: 9 s per session at 8,000 entities, 10 s at 16,000, on the way to about 400,000.
• Pronouns typed Person go through the user rule too (f9d4f07). Without this, Person:'you'/'I'/'assistant' merged, under global identity, into hubs spanning up to 110 sessions.
• All-lowercase mentions of a global type stay per chunk (same commit). Otherwise generic nouns like home or area merged across about 50 sessions.

The eval work built on this (hybrid retrieval and friends) is a separate stacked PR. The judge-scoring fix (#387) is also separate, off main.

Found on the way

• Memgraph 3.13.1 planner bug: WHERE (a:X OR b:X) is planned as Filter (a:X), (b:X), an AND. Every edge with only one endpoint in the workspace, e.g. from (:User), silently escaped the check. The workaround is $workspace IN labels(a) OR ..., covered by a regression test. Worth reporting upstream.
• duration.between doesn't exist in Memgraph. Date arithmetic is datetime subtraction.

Verification

• The suites, run against a dedicated Memgraph:
  • hygm: 36 passed;
  • unstructured2graph: 131 passed, 10 skipped;
  • sessions-graph: 71 passed;
  • eval: 237 passed;
  • actions-graph and skills-graph: unchanged, passing.
• ruff and ty are clean.
• The real GLiNER2 e2e (not in CI, which never installs gliner2) passes: 3 tests.
• Port check with the real model on Wire a constrained ontology and read the edges #350's 10 evidence sessions, hand vocabulary:
  • 2525 mentions, against the prototype's 2509;
  • all three answer edges land on the user's node: personal_best → 25:50, visited → Museum of Modern Art, studied → Business Administration;
  • 0 non-conformant entities and relationships;
  • 1 self-loop dropped, The read-time contract for non-conformant edges #355's count.

Not in this PR

• The reporting-only signals: How wide should a relation's declared range be #359's shadow sample, Near-synonymous relation labels all fire on the same pair #360's co-firing signal, Entity identity across chunks #346's highest-degree node signal.
• The retrieval agent is never given question_date #367 (question_date for the retrieval agent, map Map: Context-graph emergence pipeline — reconciliation, retrieval, eval #297).
• Memories reach extraction with no speaker, so User mentions in them are dropped.
• hygm is not on PyPI yet. The unstructured2graph CI job installs it from the workspace, and a release needs hygm published first.

https://claude.ai/code/session_01BczgXHGBrKsHSQUGB8P8te