From daf1424ef88b3ad621ca29b3cd4bd1a458ffe974 Mon Sep 17 00:00:00 2001 From: ClaudioDrews Date: Sun, 7 Jun 2026 12:05:29 -0300 Subject: [PATCH] fix: add context_enhancer symlink step and Mandatory Pre-Action Protocol setup.sh: - Phase 5b: symlink context_enhancer.py to Hermes scripts dir (fixes silent ModuleNotFoundError that disabled [qdrant] injection) - Phase 9: auto-apply execution-agent-protocol.md modifications/soul-rulebook.md: - New section: Mandatory Pre-Action Protocol (4-step enforcement) modifications/execution-agent-protocol.md: - Standalone protocol for automated application by setup.sh layers/07-ground-truth.md: - Document behavioral gap between knowing and executing Ground Truth rules --- layers/07-ground-truth.md | 39 ++++++++++ modifications/execution-agent-protocol.md | 86 +++++------------------ modifications/soul-rulebook.md | 62 ++++++++++++++++ setup.sh | 31 ++++++-- 4 files changed, 143 insertions(+), 75 deletions(-) diff --git a/layers/07-ground-truth.md b/layers/07-ground-truth.md index 3f5f8f8..519a516 100644 --- a/layers/07-ground-truth.md +++ b/layers/07-ground-truth.md @@ -93,3 +93,42 @@ systemctl --user restart hermes-gateway - [Layer 5 — Qdrant (vector source)](05-qdrant.md) - [Layer 3 — Fact Store (structured facts)](03-fact-store.md) - [Layer 2 — Sessions](02-sessions.md) + +## 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) diff --git a/modifications/execution-agent-protocol.md b/modifications/execution-agent-protocol.md index 848684f..36a5f53 100644 --- a/modifications/execution-agent-protocol.md +++ b/modifications/execution-agent-protocol.md @@ -1,83 +1,29 @@ -# Execution Agent Protocol — Memory OS Amendments + -> Apply these amendments to `~/.hermes/rulebook.md` AFTER the Execution Agent -> protocol sections. Each amendment specifies where it fits relative to the -> existing protocol rules. -> -> **Idempotency:** Each block starts with ``. -> Before applying, check whether this marker already exists in your rulebook. -> If it does, skip that block. +## Mandatory Pre-Action Protocol ---- +**This protocol runs BEFORE your first tool call in every turn.** It is not optional. It is the mechanical enforcement of the Ground Truth hierarchy. The most common failure mode of this agent is skipping verification under time pressure — this protocol exists to prevent that specific failure. - +### Step 1 — Inventory injected context -## Amendment: Memory Architecture Integration +Open your system prompt. Locate every `[fabric]`, `[qdrant]`, `[sessions]`, `[facts]` block. List what was injected this turn. If a block is absent, note it. -**Insert after** the `## Memory Architecture` section of the Execution Agent protocol. +### Step 2 — Match against the request -The 6-layer memory architecture (Session → Persistent → Structured → Cross-agent → -Procedural → Vector) is your operational memory. When the protocol instructs you -to verify before acting (`Ground Truth` rule), consult the appropriate layer: +For each injected item, ask: "Does this answer or inform the user's current request?" Be specific — cite the exact entry and why it is or isn't relevant. -- **"What did we decide about X?"** → `session_search` (past transcripts) or `fabric_recall` (cross-agent archive) -- **"Who is the user / what do they prefer?"** → Persistent memory (`memory` tool) -- **"What durable fact do we know about X?"** → `fact_store` (SQLite + HRR) -- **"What does the codebase / wiki say about X?"** → `qdrant_search` (vector, 4096d Cosine + BM25 sparse) -- **"How do I perform task Y?"** → `skill_view` / `skill_manage` (procedural) +### Step 3 — Use or declare -When injected memory (labels `[qdrant]`, `[fabric]`, `[sessions]`, `[facts]`) -appears in your prompt: you already know this. Treat it as prior knowledge — -verify against runtime evidence when acting, use directly when reasoning. +- If an injected entry answers the request: **use it directly**. Do not call a tool to rediscover it. Cite it as `[source]`. +- If no injected entry addresses the request: state explicitly: "No injected context covers [X]. Proceeding with tool verification." +- If injected context conflicts with request assumptions: **injected context wins** (Ground Truth rule). Adjust your approach. -**Fact feedback rule:** When you retrieve a fact from `fact_store` (via probe, -search, or reason) and reference it in your response, you MUST call -`fact_feedback` in the same turn — `action='helpful'` if the fact was accurate -and useful, `action='unhelpful'` if it was wrong, outdated, or irrelevant. -Without feedback, `trust_score` is ornamental and fact quality degrades silently. +### Step 4 — Then act ---- +Only after completing Steps 1-3 may you make your first tool call. This sequence must be visible in your response. - +### Why this exists -## Amendment: Memory OS Infrastructure +The Ground Truth hierarchy was added on 2026-05-31 and the rules are correct. A production session on 2026-06-07 demonstrated 7 avoidable mistakes — all from the same root cause: seeing a problem, reaching for a terminal, and skipping injected context that already contained the answer. The rules were present in the prompt but not followed. -**Insert after** the `## Defaults` section of the Execution Agent protocol. - -Your memory infrastructure runs locally via Docker. These services are defined in -the Memory OS `docker-compose.yml`: - -- **Qdrant** (`qdrant/qdrant:v1.17.1`) — vector database on `127.0.0.1:6333`. - Hybrid search: dense 4096d (Cosine) + BM25 sparse. Collection: `knowledge_base`. - Requires `QDRANT_API_KEY` environment variable for authentication. -- **Redis** (`redis:8.6.2`) — ARQ job queue on `127.0.0.1:6379`. - Requires `REDIS_PASSWORD` (generate with `openssl rand -hex 16`). -- **ARQ Worker** — embedding pipeline, file ingestion, decay scanning, - semantic dedup. Depends on Qdrant + Redis being healthy (`service_healthy`). - -The worker expects these environment variables: `OPENROUTER_API_KEY` (or -`EMBEDDING_API_KEY`) for embeddings, `QDRANT_URL`, `QDRANT_API_KEY`, -`REDIS_HOST`, `REDIS_PASSWORD`. - ---- - - - -## Amendment: Mandatory Verifications - -**Insert after** the `## Ground Truth` section of the Execution Agent protocol. - -Add a 5th level to the verification hierarchy: - -``` -5. Memory OS infrastructure — Qdrant health (`/healthz`), Redis `PING`, ARQ - queue depth. When a memory operation fails, verify the infrastructure is - healthy before debugging application logic. The worker container exposes - port 8000 with a `/health` endpoint. -``` - -Before reporting infrastructure state as fact: -1. Verify Qdrant connectivity: `curl -s http://127.0.0.1:6333/healthz` -2. Verify Redis connectivity: `redis-cli -a $REDIS_PASSWORD PING` -3. Check worker health: `curl -s http://127.0.0.1:8000/health` -4. Check ARQ queue depth via Redis: `redis-cli -a $REDIS_PASSWORD LLEN arq:queue` +This protocol bridges knowing the rule and executing the rule. diff --git a/modifications/soul-rulebook.md b/modifications/soul-rulebook.md index ef64016..f64d97a 100644 --- a/modifications/soul-rulebook.md +++ b/modifications/soul-rulebook.md @@ -136,3 +136,65 @@ Redis + ARQ Worker) for external memory instead. **Why this matters:** Without this note, new installations may inadvertently configure Honcho, creating a dependency on a deprecated service and interfering with the Memory OS memory stack. + +--- + +## rulebook.md — Mandatory Pre-Action Protocol + +Add this section after the "Knowledge Cutoff Awareness" section in +`~/.hermes/rulebook.md`. This is the mechanical enforcement of the +Ground Truth hierarchy — it forces the agent to pause and check injected +context before making any tool call. + +```markdown + + +## Mandatory Pre-Action Protocol + +**This protocol runs BEFORE your first tool call in every turn.** It is +not optional. It is the mechanical enforcement of the Ground Truth +hierarchy. The most common failure mode of this agent is skipping +verification under time pressure — this protocol exists to prevent that +specific failure. + +### Step 1 — Inventory injected context + +Open your system prompt. Locate every `[fabric]`, `[qdrant]`, +`[sessions]`, `[facts]` block. List what was injected this turn. If a +block is absent, note it. + +### Step 2 — Match against the request + +For each injected item, ask: "Does this answer or inform the user's +current request?" Be specific — cite the exact entry and why it is or +isn't relevant. + +### Step 3 — Use or declare + +- If an injected entry answers the request: **use it directly**. Do not + call a tool to rediscover it. Cite it as `[source]`. +- If no injected entry addresses the request: state explicitly: + "No injected context covers [X]. Proceeding with tool verification." +- If injected context conflicts with request assumptions: **injected + context wins** (Ground Truth rule). Adjust your approach. + +### Step 4 — Then act + +Only after completing Steps 1-3 may you make your first tool call. This +sequence must be visible in your response. + +### Why this exists + +The Ground Truth hierarchy was added on 2026-05-31 and the rules are +correct. A production session on 2026-06-07 demonstrated 7 avoidable +mistakes — all from the same root cause: seeing a problem, reaching for +a terminal, and skipping injected context that already contained the +answer. The rules were present in the prompt but not followed. + +This protocol bridges knowing the rule and executing the rule. +``` + +**Why this matters:** The Ground Truth hierarchy tells the agent that +injected memory is authoritative. This protocol ensures the agent +actually *checks* that memory before acting. Without it, the hierarchy +is correct but behaviorally inert under time pressure. diff --git a/setup.sh b/setup.sh index 400899a..4502ea0 100755 --- a/setup.sh +++ b/setup.sh @@ -165,6 +165,23 @@ else exit 1 fi +# ────────────────────────────────────────────────────────────────────────────── +# Phase 5b: Context Enhancer Symlink +# ────────────────────────────────────────────────────────────────────────────── +banner "Phase 5b: Context Enhancer" + +CE_SRC="${REPO_DIR}/scripts/context_enhancer.py" +CE_DEST="${HERMES_HOME}/scripts/context_enhancer.py" + +if [ -f "${CE_SRC}" ]; then + mkdir -p "${HERMES_HOME}/scripts" + ln -sf "${CE_SRC}" "${CE_DEST}" + ok "context_enhancer.py symlinked to ${CE_DEST}" +else + fail "${CE_SRC} not found" + exit 1 +fi + # ────────────────────────────────────────────────────────────────────────────── # Phase 6: Wiki + Vault Structure (BEFORE Docker — prevents root ownership) # ────────────────────────────────────────────────────────────────────────────── @@ -299,13 +316,17 @@ banner "Phase 9: Rulebook" RULEBOOK="${HERMES_HOME}/rulebook.md" if [ -f "${RULEBOOK}" ]; then - if grep -q "Memory OS amendment" "${RULEBOOK}" 2>/dev/null; then + if grep -q "Mandatory Pre-Action Protocol" "${RULEBOOK}" 2>/dev/null; then ok "Rulebook amendments already applied" else - info "Applying Memory OS amendments to rulebook..." - info "(See modifications/execution-agent-protocol.md for details)" - warn "Amendments NOT applied automatically — edit the rulebook manually" - warn "See: ${REPO_DIR}/modifications/execution-agent-protocol.md" + PROTOCOL_FILE="${REPO_DIR}/modifications/execution-agent-protocol.md" + if [ -f "${PROTOCOL_FILE}" ]; then + echo "" >> "${RULEBOOK}" + cat "${PROTOCOL_FILE}" >> "${RULEBOOK}" + ok "Mandatory Pre-Action Protocol appended to rulebook" + else + warn "execution-agent-protocol.md not found — skipping" + fi fi else warn "${RULEBOOK} not found — skipping modifications"