fix: add context_enhancer symlink step and Mandatory Pre-Action Protocol (#25)
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 Co-authored-by: ClaudioDrews <claudio@drews.com.br>
This commit is contained in:
Claudio Drews
GitHub
parent
0d6523d6ec
commit
a25f3a95d6
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -1,83 +1,29 @@
|
|||
# Execution Agent Protocol — Memory OS Amendments
|
||||
<!-- Memory OS additions — do not duplicate -->
|
||||
|
||||
> 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 `<!-- Memory OS amendment — do not duplicate -->`.
|
||||
> 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.
|
||||
|
||||
<!-- Memory OS amendment — do not duplicate -->
|
||||
### 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.
|
||||
|
||||
<!-- Memory OS amendment — do not duplicate -->
|
||||
### 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`.
|
||||
|
||||
---
|
||||
|
||||
<!-- Memory OS amendment — do not duplicate -->
|
||||
|
||||
## 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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
<!-- Memory OS additions — do not duplicate -->
|
||||
|
||||
## 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.
|
||||
|
|
|
|||
31
setup.sh
31
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"
|
||||
|
|
|
|||
Loading…
Reference in New Issue