vrious/README.md

vriōus — Multi-Agent Orchestration & Shared Memory Patterns

Canonical patterns for orchestrating coding agents (pi, opencode, claude-code) from Hermes, with shared memory across a distributed, multi-container fleet.

Architecture Model

This is multi-host, multi-container — not single-host. Each agent runs in its own container or host:

┌─────────────────────────────────────────────────────────────────┐
│                     Hermes (hertz) — orchestrator                │
│  fact_store / memory tool / MCP client                          │
│  Skills: codex, opencode, claude-code, hermes-agent              │
└──────┬───────────────────────────┬────────────────────┬──────────┘
       │                           │                    │
       ▼                           ▼                    ▼
┌──────────────┐    ┌──────────────────┐    ┌──────────────────┐
│ pi agent      │    │ opencode         │    │ claude-code      │
│ (pica)        │    │ (local or cont.) │    │ (local or cont.) │
│ Codex CLI     │    │ OpenCode CLI     │    │ Claude Code CLI  │
│ --print       │    │ run / TUI        │    │ exec / TUI       │
│ NPU inference │    │ provider-agnostic│    │ Anthropic Claude │
└──────┬───────┘    └────────┬─────────┘    └────────┬─────────┘
       │                     │                        │
       └─────────────────────┼────────────────────────┘
                             │
                    ┌────────▼────────┐
                    │  Stash / MCP    │
                    │  memory server  │
                    │ (memory.fritz   │
                    │ .box:8080/sse)  │
                    └─────────────────┘

Each agent is independent — separate process, separate container, separate config. Hermes invokes them via the appropriate transport (MCP shell, lmcp, SSH, direct CLI).

Agents

Agent	CLI	Invocation	Transport	Location
Hermes	hermes	n/a (orchestrator)	—	hertz (bare metal)
pi	pi --print	pi_exec MCP tool, SSH+nohup	MCP / SSH	pica (RPi5, container)
opencode	opencode run	direct terminal or bg pty	local terminal	any container
claude-code	claude	direct terminal or bg pty	local terminal	any container

Invocation Patterns

One-Shot (pi)

# Via pi_exec MCP tool (preferred — configurable timeout)
mcp__pica__pi_exec(
    prompt="Read /path/to/file and summarize it",
    model="qwen3.5-9b-npu",
    provider="hossenfelder"
)

# Via SSH (fallback)
ssh mfritsche@pica "pi --print --provider hossenfelder --model qwen3.5-9b-npu 'prompt'"

One-Shot (opencode)

opencode run 'Implement retry logic for API calls' --model openrouter/anthropic/claude-sonnet-4

One-Shot (claude-code)

claude execute -p 'Refactor the auth module and add tests' --model claude-sonnet-4

Background / Long-Running Tasks

# pi: SSH + nohup with lock file, timeout per file
# See references/batch-pi-processing.md for full pattern

# opencode/claude-code: terminal background + pty
terminal(command="opencode", background=true, pty=true)
# then: process(action="submit", data="prompt")

terminal(command="claude", background=true, pty=true)
# then: process(action="submit", data="prompt")

Shared Memory Patterns

Tier 1: Hermes Holographic Memory (Hermes-only)

fact_store(action='add', content='...', category='general')

Accessed exclusively by Hermes via fact_store and fact_feedback tools. Agents report results, Hermes extracts facts and stores them.

Tier 2: Stash MCP Server (Any MCP-capable agent)

Memory server at memory.fritz.box:8080/sse (boltzmann container)
- Postgres + pgvector + Ollama
- 28 MCP tools
- Query via /stash recall --namespaces "/" -- "query"

If pi, opencode, or claude-code support MCP client configuration, they can read/write to the same stash namespace directly. Otherwise, all memory flows through Hermes.

Tier 3: File-Based (Every agent)

Shared facts.md — agents append with >>, Hermes reads with read_file

Simple, universal. Used in the batch-pi-processing pattern.

Multi-Host, Multi-Container Design

YES — this is designed for separate hosts/containers. Each agent is independently deployed:

Host	Container?	Agent	Notes
hertz	bare metal	Hermes	Orchestrator, MCP client
pica	Incus	pi agent	RPi5, RK3588 NPU, qwen3.5-9b-npu
boltzmann	Incus	Stash / memory	Postgres, pgvector
(any)	Incus or Docker	opencode	Provider-agnostic
(any)	Incus or Docker	claude-code	Anthropic Claude

No shared filesystem required. Communication is via:

• MCP (HTTP/SSE) — stash, pi_exec, file tools
• SSH — fallback for pi on pica
• Hermes terminal — opencode and claude-code on any reachable host

Recommendations

1. New agents go in their own container — keeps dependencies, configs, and sessions isolated
2. Stash as shared memory — structured, queryable, MCP-accessible. Best upgrade path from file-based
3. Hermes as sole memory curator — extracts durable facts from agent outputs, stores in fact_store with trust scoring
4. One-shot for bounded tasks, background TUI for iterative — match the invocation pattern to the task
5. AGENTS.md per repo — project-level context that all agents respect