Mirror Strategy — Auditability Roadmap

8. Mirror Strategy — Auditability Roadmap

Phase 3.D.5 (Memory Mirror) closes the transparency gap for entities/relationships. Based on comprehensive Hermes parity research, here is the complete mirror strategy.

8.1 What Hermes Actually Has vs Gormes

Key Finding: Hermes does not have human-readable transcript exports. Transcripts live in SQLite/JSONL only. The export_session() method returns JSON (machine-readable), not formatted text. Gormes already exceeds Hermes parity with the USER.md mirror for memory entities.

8.2 Remaining Mirror Candidates (Ranked by Priority)

High Priority: Session Index Mirror (Phase 3.E.1)

Problem: Sessions stored in bbolt (~/.local/share/gormes/sessions.db) are opaque. Operators cannot cat, grep, or audit their session mappings without binary tools.

Solution: Mirror the bbolt session map to ~/.local/share/gormes/sessions/index.yaml:

# Auto-generated session index
# This file is a read-only mirror of sessions.db for operator auditability
sessions:
  telegram:123456789: session_abc123
  telegram:987654321: session_def456
updated_at: 2026-04-20T09:30:00Z

Implementation: Background goroutine (like 3.D.5 Mirror) triggered on session write; atomic temp+rename; 30s sync interval.

Rationale: Hermes uses queryable SQLite for sessions; Gormes uses binary bbolt. This provides human-readable session auditability that Hermes has via SQL but Gormes lacks via bbolt opacity.

Medium Priority: Tool Execution Audit Log (Phase 3.E.2)

Problem: Tool calls are ephemeral. The Bear runs terminal(), produces output, but no persistent record exists. An operator cannot audit “what did the agent do yesterday?”

Solution: Append-only log at ~/.local/share/gormes/tools/audit.logl (JSONL):

{"ts":"2026-04-20T09:30:00Z","session":"abc123","turn":5,"tool":"terminal","cmd":"ls -la","duration_ms":150,"status":"ok"}
{"ts":"2026-04-20T09:30:05Z","session":"abc123","turn":6,"tool":"web_search","query":"golang embed","results":3,"duration_ms":2500}

Rationale: This exceeds Hermes capabilities. Python Hermes stores tool results in SessionDB messages table, but there’s no separate audit trail for tool execution. This is new operational visibility.

Medium Priority: Transcript Export Command (Phase 3.E.3)

Problem: While Hermes has no human-readable transcript export, operators may want to export a conversation for sharing, backup, or analysis.

Solution: Add gormes session export <session_id> --format=markdown command that renders a formatted Markdown transcript.

Rationale: This is a Gormes-only feature that exceeds Hermes capabilities. Hermes has no equivalent human-readable export.

Low Priority: Extraction State Visibility (Phase 3.E.4)

Problem: turns.extracted, extraction_attempts, extraction_error columns are invisible to operators. A dead-lettered turn (extracted=2) requires SQLite inspection.

Solution: Optional: add extraction failures to the USER.md mirror footer, or provide gormes memory status command showing extraction queue depth and recent errors.

Rationale: This is debugging/operational visibility. Can be deferred until extraction issues become painful.

8.3 Hermes Files Gormes Does Not Need to Mirror (Yet)

Based on the comprehensive Hermes file inventory, these Hermes files do not need Gormes mirrors today, but may become relevant as features land:

Operational State Files Discovered in Additional Research:

Additional Subsystems with Audit Potential:

Insights Engine Gap: Hermes has a comprehensive InsightsEngine (agent/insights.py, 768 lines) that analyzes historical session data to produce:

• Token consumption reports
• Cost estimates by model/provider
• Tool usage patterns
• Activity trends over time
• Platform breakdowns
• Session metrics (duration, turns, success rate)

Gormes currently has only basic in-memory telemetry (internal/telemetry/telemetry.go) that does not persist. This is a significant operational visibility gap — operators cannot audit their usage, costs, or trends without reimplementing the insights analysis themselves.

Recommended Mirror Addition — Phase 3.E.5: Insights Audit Log

Export aggregated session metrics to ~/.local/share/gormes/insights/usage.jsonl:

{"date":"2026-04-20","session_count":5,"total_tokens_in":45000,"total_tokens_out":12000,"estimated_cost_usd":0.45,"model_breakdown":{"claude-opus":3,"gpt-4":2}}

This would provide a lightweight, append-only cost and usage audit trail that accumulates over time, even before the full InsightsEngine is ported in Phase 4.E.

8.4 Mirror Implementation Principles

All mirrors must follow the 3.D.5 design constraints:

1. Source of truth remains database — mirrors are read-only exports
2. Fire-and-forget — never block the 250ms kernel latency budget
3. Atomic writes — temp file + rename (readers never see partial files)
4. Change detection — hash comparison to avoid redundant writes
5. Graceful degradation — log warnings on errors, never crash the bot
6. Configurable paths — respect XDG directories and config overrides

Mirror Strategy v1.0 — Synthesized from parallel audit of Hermes Python codebase and Gormes Go implementation.