Home / Projects / Orchestrata Ultimate / Decisions / ADR index / ADR-0094

ADR-0094: Graph queries run with the ontology structure memory injected first

← ADR-0093 · ADR-0095 →

The record

Status: Accepted · Date: 2026-10-12 · Ruled: 2026-10-12 (Mohamed's directive; the mechanism below is designed under it)

Context

• The directive. Mohamed, 2026-10-12, verbatim: "ontology structure should be memory we inject before queries".

• What "ontology structure" is here. The project queries two graph databases (docs/LEVEL0.md, "The two DATABASES — do not conflate them"):

  • the operational KG, database orchkg, about 39 labels: sessions, gateway audit, CXP packets, code intelligence, specs, volks, ToolCall events;
  • the shared semantic/RAG database memgraph. Its labels co-mingle between knowledge-wiki and orchestrata's semantic_graph ingest, and its chunk labels are split across SemanticChunk, CodestralChunk, QwenChunk and Chunk.

  The canonical schema is knowledge_graph/canonical_schema.py (SPEC-106 FR-001, CLI scripts/kg_schema.py). The root-connectivity invariant is that every node leads to the root :Project, checked by scripts/check_kg_connectivity.py.

• Not in context at query time. Level 0 names the two databases, but the structure itself is not in context when a Cypher query is written:

  • labels and relationship types with their endpoint labels;
  • key properties, constraints and indexes;
  • where the live graph diverges from the canonical schema.

  A query written from memory guesses labels, and an empty result from a wrong label reads like an empty graph.

• The mechanism exists. ADR-0093 (Accepted the same day) extends claude/hooks/workflow_context_inject.py with:

  • a prompt-keyword domain;
  • a PreToolUse(Bash) command trigger that fires on every match;
  • a seen-state reset on SessionStart compact, resume and clear;
  • memory-dir resolution by the git common dir;
  • a live headless delivery test.

Decision

Mohamed's directive above is the decision. Under it:

1. The memory.
   • A project memory kg-ontology-structure lives in the same memory directory as the ADR-0093 memories.
   • Its first section, ## Query card, is at most 60 lines. For each database it gives:
     • endpoint, database name and the env key that selects it;
     • every label with its key properties;
     • every relationship pattern as (:From)-[:TYPE]->(:To);
     • the constraints and indexes.
   • The rest of the file carries the detail:
     • node and relationship counts with the date they were measured;
     • each divergence between the live graph and canonical_schema.py;
     • the co-mingled and split labels;
     • the :Project connectivity invariant;
     • the exact read-only commands that re-derive every number in the file.
   • It is built from canonical_schema.py, read through the AST toolkit, and from read-only introspection of the TEST fleet graph (10.53.2.10). It is never built from the prod subnet 10.53.1.x.
2. The injection. workflow_context_inject.py gains an ontology domain. It injects the memory's ## Query card verbatim, plus the file's path and its **How to apply:** line. A missing file or a missing ## Query card section is named as missing, never skipped.
   • Prompt trigger. Word-boundary matches on: cypher, graph query, knowledge graph, KG, ontology, orchkg, memgraph, semantic graph, RAG graph, MATCH (, MERGE (.
   • Command trigger, on EVERY match with no dedup. It fires on a Bash command that runs any of:
     • graph_query.py, graph_browser.py, semantic_search.py, kg_schema.py;
     • check_kg_connectivity.py, bootstrap_graphs.py, sync_*_to_graph.py, ingest_orchestrata_ultimate.py;
     • cypher-shell, mgconsole, wiki-rag-query;
     • any command whose text contains a Cypher clause (MATCH (, MERGE (, CREATE () or imports the neo4j driver.
3. Shared mechanism. Compaction reset, memory-dir resolution and the structured additionalContext delivery are ADR-0093's. The live headless delivery test gains one ontology case per event.

Alternatives rejected

• A path-only reminder ("read kg-ontology-structure.md first"). This is the failure ADR-0093 names: it depends on the session choosing to read. The labels are needed in the moment the query text is written, so the query card itself is injected.
• Inject the whole memory file. The counts, divergences and re-derivation commands are long, and are needed only when a query result surprises. The bounded query card carries what a query needs.
• Rely on Level 0. docs/LEVEL0.md is generated for every session and every subagent. Adding the full label inventory there pays its token cost on every turn, including turns that never touch a graph.

Consequences

• Every graph query command runs with the label and relationship card for both databases in context at that moment.
• The memory is a measurement with a date. Re-running its re-derivation commands refreshes it. Generating the card from the live graph automatically is a separate decision.
• The memory content is built by the same verification swarm as the ADR-0093 memories: parallel readers, per-section refuters and a completeness critic.
• The build is a follow-up brief (T2) on the ADR-0093 branch, written after T1 lands, so T1's scope does not grow mid-flight.

Provenance

• Directive: Mohamed, 2026-10-12 (quoted verbatim in Context).
• Interpretation: "queries" is read as graph queries (Cypher against the operational KG and the semantic graph), the only stores in this project with an ontology. Covering other query paths, such as the AST toolkit or the Prolog code-intelligence KB, is a new ruling.
• Evidence:
  • docs/LEVEL0.md § "The two DATABASES";
  • docs/CODEBASE_MAP.md: knowledge_graph/canonical_schema.py, scripts/kg_schema.py, scripts/check_kg_connectivity.py;
  • ADR-0093.
• The orchestrator designed the mechanism under the directive. Changing the mechanism requires a new ADR.

Related ADRs

• Also mentioned: ADR-0093

Rulings cited

None.

Specs cited

• SPEC-106