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

ADR-0072: The conversation graph endpoint is the prod orchgraph cluster, database orchkg

← ADR-0071 · ADR-0073 →

The record

Status: Accepted (ruling, Mohamed, 2026-10-07: "cluster = Memgraph, DB = orchkg (ADR stands)") · Date: 2026-10-06

Context

orchestrata-conversation-consumer.service (SPEC-021 US-021-007, the Redis queue → graph writer for captured conversation turns) resolves its target through knowledge_graph.conversation_consumer.resolve_conversation_endpoint, which reads exactly two keys, CONVERSATION_KG_URI and CONVERSATION_KG_DATABASE, and raises when either is blank: "the conversation graph has its own endpoint and must never be resolved through the profile-driven KG_ROUTING_URI/KG_URI keys, which a dev/test overlay redirects" (REQ-021-069). ADR-0066 (Accepted, R16) put those two keys in the secrets-only file ~/.config/orchestrata/.env and recorded that "the conversation-graph endpoint value (which server and database host the conversation graph) is an operational parameter still to be named by Mohamed (plan item R16b); until it is set the consumer unit is refused by design, not by accident."

Measured 2026-10-06 after the P5 ship (plans/ast-daemon-deployment-plan.md § 3b, row "P5 verify_package fix"): with the two P5 blockers gone (plain units retired, test-env record GREEN), promote_env.py promote --to prod ran its first real prod deploy and failed at verify because the consumer exited 1 with the RuntimeError above. The rollback to 287826a9 could not restart it for the same reason. /opt/orchestrata/.env holds 5 keys (DEEPSEEK_API_KEY, GEMINI_API_KEY, GITLAB_TOKEN, JWT_SECRET, OPENROUTER_API_KEY) and no CONVERSATION_KG_*; ~/.config/orchestrata/.env has none; ~/.env has none. No host, dev or test file names a conversation endpoint today.

Facts that bound the choice:

• The prod operational KG is the HA orchgraph cluster, coordinator routing URI neo4j://10.53.1.160:7691, database orchkg (env/prod.env lines 23–25). The nightly orchgraph-backup.service snapshots every database on that cluster (memgraph, orchkg per its log).
• The unit's own description reads "conversation-turn consumer (Redis queue -> orchkg graph)", and the SPEC-021 Tier I conversation labels are part of the canonical schema of the operational KG (tests/knowledge_graph/test_canonical_schema_conversation.py), where the root-connectivity invariant (every node reaches :Project) is enforced.
• The reason the endpoint is a separate key pair is NOT that the data lives elsewhere; it is that a dev/test session must never redirect the writer by swapping the profile overlay (REQ-021-069). A fixed value in the secrets-only file satisfies that.

Decision (proposed)

Set, in ~/.config/orchestrata/.env (ADR-0066's file, mode 0600) on the prod host:

CONVERSATION_KG_URI=neo4j://10.53.1.160:7691
CONVERSATION_KG_DATABASE=orchkg

The conversation graph is the prod operational KG itself: same cluster, same database, written through the dedicated key pair so no profile overlay can redirect it. The installer copies the file to /opt/orchestrata/.env on the next promote; the key names are recorded here as ADR-0066 requires ("grows only by keys the promote's stage proves missing — each addition recorded by key name").

Alternatives rejected

• A dedicated database conversation on the same cluster. Cleaner isolation, but it needs CREATE DATABASE on the HA cluster, a canonical-schema split (conversation labels today sit in the orchkg schema with cross-links to Session, Volk, Project), a second hub for root connectivity, and a change to every reader (graph_query.py, conversation_recall, the gateway knowledge handler). Nothing in SPEC-021 asks for a separate database. Reconsider if conversation volume ever dominates orchkg.
• The shared semantic/RAG Memgraph on the test node (10.53.2.10). Prod must not write to the test fleet (LEVEL0: prod subnet 10.53.1.0/24, test 10.53.2.0/24, "NEVER a test target" in either direction).
• Resolving through KG_ROUTING_URI. Rejected by REQ-021-069 and by the consumer's code; a dev overlay would silently redirect prod turns.
• Leaving it unset. The consumer is refused forever and prod promotion never passes verify (ActiveState: expected active, got activating/failed).

Consequences

On Accepted: Mohamed (or the orchestrator on his word) appends the two keys to ~/.config/orchestrata/.env; the next bash deploy/ship.sh promote copies them to /opt/orchestrata/.env and the consumer starts; promote_env.py verify then has two remaining host findings to clear (plan PH1: orchestrata-kg-retention.service unit env, orchgraph-backup.service exit 1) and one verifier change (P6: tool-tree template instances judged against /opt/orchestrata-tools). ADR-0066's key-set record gains the two names. Dev/test sessions keep writing nowhere until they set their own values in their own secrets file; that is the existing behaviour and is unchanged by this ADR.

Provenance

ADR-0066 (Accepted 2026-09-24) item R16b. Orchestrator findings 2026-10-06, P5 ship 2 (scratchpad/p5_ship2.log: [FAIL] verify … orchestrata-conversation-consumer.service: no process (MainPID=0); journalctl --user -u orchestrata-conversation-consumer.service: RuntimeError: CONVERSATION_KG_URI and CONVERSATION_KG_DATABASE not set). Code: src/orchestrata_ultimate/knowledge_graph/conversation_consumer.py:66-112. Infra: env/prod.env:23-25; /var/lib/orchestrata/backups/orchgraph/backup.log. Awaiting Mohamed's ruling; only he rules.

• Ruled Accepted by Mohamed on 2026-10-07, verbatim: "cluster = Memgraph, DB = orchkg (ADR stands)". The cluster is the Memgraph orchgraph HA cluster (Neo4j standalone was retired 2026-07-26; neo4j:// is the Bolt URI scheme, not a Neo4j server); the target database stays orchkg as proposed. Execution: set CONVERSATION_KG_URI=neo4j://10.53.1.160:7691 and CONVERSATION_KG_DATABASE=orchkg in ~/.config/orchestrata/.env on the prod host (ADR-0066's file, mode 0600); the installer copies them to /opt/orchestrata/.env on the next promote.

Related ADRs

• Also mentioned: ADR-0066

Rulings cited

None.

Specs cited

• SPEC-021