memory-os/layers/07-ground-truth.md

Layer 7 — Ground Truth Hierarchy

Type: Identity-layer fix (SOUL.md + rulebook.md) Why it exists: Context injection is not enough — the agent must be instructed to treat injected memory as authoritative. Discovered: 2026-05-31

The problem

Memory OS successfully injects context from all four sources (Fabric + Qdrant + Sessions + Facts) into every prompt. You can see it in the system preamble: [qdrant], [fabric], [sessions], [facts] blocks are right there.

But the agent ignores them.

Symptoms:

• Agent runs search_files, read_file, session_search to rediscover information that [qdrant] already provided
• Treats every question as novel even when the answer is literally in the prompt
• Rediscovers projects, decisions, and constraints from scratch each session

Root cause

Memory OS was injecting memory into the prompt, but the agent's identity documents (SOUL.md and rulebook.md) did not include injected memory in the Ground Truth hierarchy. Without an explicit rank, the injected context was implicitly treated as optional suggestion — below terminal output and official documentation.

The original hierarchy had only 3 levels:

1. Terminal output → Ground Truth
2. Official documentation → Authoritative
3. Training knowledge → Reference only

The injected memory ([qdrant], [fabric], [sessions], [facts]) was not listed at all. No status = no authority.

The fix

The hierarchy was expanded to 4 levels, with injected memory inserted as the second level:

1. Terminal output → Ground Truth for system state (runtime)
2. Injected memory [qdrant, fabric, sessions, facts] → Ground Truth for
   documented knowledge and prior decisions
3. Official documentation → Authoritative for APIs, configs, version-specifics
4. Training knowledge → Reference only; always verify against 1-3

Conflict resolution

Sources conflict	Winner
Terminal vs Injected memory	Terminal wins for system state. Injected memory wins for documented knowledge.
Injected memory vs Assumptions	Injected memory wins. Never treat a question as novel when the answer is already in your prompt.
Injected memory vs Official docs	Official docs win for version-sensitive specifics. Injected memory wins for project context.
Training knowledge vs anything	Training knowledge always loses. Verify against 1-3.

Files changed

File	Change
~/.hermes/SOUL.md	Ground Truth section expanded from 3 to 4 levels; added conflict rules
~/.hermes/rulebook.md	Added "Injected memory" row to Source of Truth table; added mandatory verification behavior

Key instruction added to SOUL.md

"When injected memory contradicts your assumptions, injected memory wins. Never treat a question as novel when the answer is already in your prompt."

Why this matters

The infrastructure layers (01-06) ensure memory is captured, stored, and injected. Layer 07 ensures the injected memory is used. Without it:

• Qdrant points are injected but the agent curls the Qdrant API to verify them
• Fabric entries are injected but the agent calls fabric_recall to re-find them
• Session history is injected but the agent runs session_search to re-discover it
• Facts are injected but the agent probes fact_store to confirm them

Each rediscovery burns tokens, time, and model context. Layer 07 is what stops the waste.

Verification

After applying this fix (updating SOUL.md and rulebook.md), the agent should:

1. Read injected [qdrant], [fabric], [sessions], [facts] blocks before running any search/discovery tools
2. Not rediscover knowledge that is already in the prompt
3. Cite injected context directly instead of re-deriving it
4. Respect the conflict rules when sources disagree

A gateway restart is required after editing SOUL.md or rulebook.md for changes to take effect in new sessions:

systemctl --user restart hermes-gateway

Related

• Layer 4 — Fabric (injection mechanism)
• Layer 5 — Qdrant (vector source)
• Layer 3 — Fact Store (structured facts)
• Layer 2 — Sessions

2026-06-07: The gap between knowing and executing

A production session revealed that the Ground Truth hierarchy alone is not sufficient. The agent made 7 avoidable mistakes in sequence, all sharing the same root cause: the injected context was present in the prompt, the rules were loaded, but the agent defaulted to "resolve fast" mode instead of "verify first."

Two discoveries emerged:

1. Qdrant injection was silently broken. The hooks.py import from scripts.context_enhancer import ... resolved to a path where the file never existed — the code lived under the Memory OS repo. The except Exception: return [] pattern swallowed the ModuleNotFoundError, and [qdrant] was never injected. This had been broken since 2026-05-29 without detection.

2. Behavioral inertia outpaces documentation. The Ground Truth hierarchy was correctly documented and injected into the prompt. The agent read it every turn. It still defaulted to the faster operational mode.

The fix

Technical: Added a symlink step to setup.sh (Phase 5b) so context_enhancer.py is reachable from the import path.

Behavioral: Added the Mandatory Pre-Action Protocol to rulebook.md — a 4-step mechanical sequence (inventory → match → use/declare → act) that runs before every tool call. This protocol bridges the gap between knowing the rule and executing it under time pressure.

Documentation updated:

• modifications/soul-rulebook.md — new protocol section
• modifications/execution-agent-protocol.md — standalone protocol for automated application by setup.sh
• setup.sh — Phase 5b (symlink) + Phase 9 (auto-apply protocol)