Hermes Memory Patterns

Target: ~/.hermes/memories/ & OMP ACP Orchestration (routa.db) Summary: Hyper-dense, budget-constrained Markdown memory synced with a SQLite state-machine orchestrator via stdio.

💡 Best Practices

• Hyper-Dense Compression: Treat markdown memory like constrained L1 cache. Strip all conversational bloat; express heuristics in absolute minimum words.
• Delegate History to Routa: Store all chronological history, Kanban transitions, and JSON artifacts exclusively in routa.db. Reserve .md memories strictly for semantic agent constraints.
• Delimiter Discipline: Utilize the § character to isolate distinct heuristics. It allows clean parsing without JSON overhead and maximizes token-to-signal ratio.
• Atomic Flushes: Always respect MEMORY.md.lock and USER.md.lock during swarm operations. Instant-replace content on each turn; never append indefinitely.
• Sandboxed Secrets: Never embed raw API tokens in subshell heredocs or memory files. Pass secrets dynamically via env=dict to avoid parsing errors.

🚨 Anti-Patterns

• Audit Trail Bloat: Treating MEMORY.md as an append-only transaction log. It lacks an audit trail by design to prevent context starvation and budget overflow.
• Conversational Syntax: Writing full paragraphs, greetings, or meta-commentary inside memory files. Every redundant character risks hitting the budget and causing silent truncation.
• Manual DB Mutations: Modifying routa.db directly instead of routing transitions via omp acp. Bypassing the protocol breaks evidence constraints and session tracking.
• Ambient Context Reliance: Assuming subprocesses (e.g., cron, execute_code) inherit environment variables globally. Explicitly source .env before any external API calls.

🔧 Patterns & Architecture

• Flush-On-Turn: Memory files are aggressively rewritten per turn. This maintains the latest valid snapshot of truths without historical cruft.
• ACP Subprocess Orchestration: omp acp bridges the agent runtime and routa.db via stdio. It securely manages acp_session_key, acp_pid, and task_id tracking.
• Lane Transition Engine: Workspaces enforce strict state-machine progressions (e.g., backlog ➔ evidence_required ➔ verdict). routa.db locks lane transitions until evidence JSON arrays are fulfilled.
• Concurrency Control: Subagents use strict file locks (.lock) to prevent state clobbering. Parallel task execution requires atomic writes to shared memory files.