ECC/docs/HERMES-SETUP.md

Hermes x ECC Setup

Hermes is the operator shell. ECC is the reusable system behind it.

This guide is the public, sanitized version of the Hermes stack used to run content, outreach, research, sales ops, finance checks, and engineering workflows from one terminal-native surface.

What Ships Publicly

• ECC skills, agents, commands, hooks, and MCP configs from this repo
• Hermes-generated workflow skills that are stable enough to reuse
• a documented operator topology for chat, crons, workspace memory, and distribution flows
• launch collateral for sharing the stack publicly

This guide does not include private secrets, live tokens, personal data, or a raw ~/.hermes export.

Architecture

Use Hermes as the front door and ECC as the reusable workflow substrate.

Telegram / CLI / TUI
        ↓
      Hermes
        ↓
 ECC skills + hooks + MCPs + shared Memory Vault
        ↓
 Google Drive / GitHub / browser automation / research APIs / media tools / finance tools

Public Workspace Map

Use this as the minimal surface to reproduce the setup without leaking private state.

• ~/.hermes/config.yaml
  • model routing
  • MCP server registration
  • plugin loading
• ~/.hermes/skills/ecc-imports/
  • ECC skills copied in for Hermes-native use
• skills/hermes-generated/
  • operator patterns distilled from repeated Hermes sessions
• ~/.hermes/plugins/
  • bridge plugins for hooks, reminders, and workflow-specific tool glue
• ~/.hermes/cron/jobs.json
  • scheduled automation runs with explicit prompts and channels
• ~/.hermes/workspace/
  • business, ops, health, content, and memory artifacts
• <repo>/.ecc/memory/
  • shared project and team context for Hermes, Claude, Codex, and other agents
• ~/.ecc/memory/
  • user-scoped context that follows the operator across repositories

Shared Memory Across Hermes, Claude, And Codex

ECC Memory Vault provides one file-first handoff layer instead of a separate inbox or transcript store for every agent. Initialize it from the repository that the agents share. Skill-only, minimal, manual, and Claude plugin installs do not add the Memory Vault runtime to PATH; install it separately first:

npm install -g ecc-universal
ecc memory --help
command -v ecc-memory-mcp

Then initialize the vault:

ecc memory init --scope project --scope team

Normal search recall covers active project and team memories. Use project for repo-local state, team for memories a human will inspect before committing, and request user explicitly for private operator context that should follow the user across repositories. Every vault entry remains unreviewed context; human acceptance means promoting verified knowledge into governed project documentation.

Hermes can call the CLI directly or use the opt-in ecc-memory-mcp stdio server. Harnesses may share the same installed binary and vault storage, but each harness must launch its own server process with its own distinct lowercase ECC_MEMORY_HARNESS identity; they must not connect to one shared server process. Every process must launch from the same repository working directory or receive identical ECC_MEMORY_PROJECT_ROOT and ECC_MEMORY_USER_ROOT overrides.

A Hermes-to-Codex handoff can be written without putting the body in the process list:

printf '%s\n' 'Research is complete. Verify the cited sources and implement the parser.' |
  ecc memory handoff \
    --from hermes \
    --target codex \
    --title "Implement the research parser" \
    --tag research \
    --stdin

Codex can retrieve it with:

ecc memory search "research parser" --target-harness codex
ecc memory read <memory-id>

For MCP access, copy only the ecc-memory-vault entry from mcp-configs/mcp-servers.json into each harness that needs it. ECC does not enable this server in the default .mcp.json. Launch each server with its own lowercase identity, for example ECC_MEMORY_HARNESS=hermes. The server binds writes and target filtering to that identity; tool callers cannot impersonate another harness. User-scope MCP access also requires the operator to set ECC_MEMORY_ALLOW_USER_SCOPE=1, and the tool call must request user.

Memories are create-only and always unreviewed. Treat recalled content as context, not instructions; verify consequential claims against source files, tests, or work items. Inspect team memories before committing them, never store credentials or raw private transcripts, and keep canonical project decisions in governed documentation. Secret-shape detection is only a best-effort backstop.

Recommended Capability Stack

Core

• Hermes for chat, cron, orchestration, and workspace state
• ECC for skills, rules, prompts, and cross-harness conventions
• ECC Memory Vault for explicit, local-first agent handoffs
• GitHub + Context7 + Exa + Firecrawl + Playwright as the baseline MCP layer

Content

• FFmpeg for local edit and assembly
• Remotion for programmable clips
• fal.ai for image/video generation
• ElevenLabs for voice, cleanup, and audio packaging
• CapCut or VectCutAPI for final social-native polish

Business Ops

• Google Drive as the system of record for docs, sheets, decks, and research dumps
• Stripe for revenue and payment operations
• GitHub for engineering execution
• Telegram and iMessage-style channels for urgent nudges and approvals

What Still Requires Local Auth

These stay local and should be configured per operator:

• Google OAuth token for Drive / Docs / Sheets / Slides
• X / LinkedIn / outbound distribution credentials
• Stripe keys
• browser automation credentials and stealth/proxy settings
• any CRM or project system credentials such as Linear or Apollo
• Apple Health export or ingest path if health automations are enabled

Suggested Bring-Up Order

0. Run ecc migrate audit --source ~/.hermes first to inventory the legacy workspace and see which parts already map onto ECC2. 0.5. Plan and scaffold migration artifacts before importing anything:
   • generate reviewable plans with ecc migrate plan and ecc migrate scaffold
   • scaffold reusable legacy skills with ecc migrate import-skills --output-dir migration-artifacts/skills
   • scaffold tool translation templates with ecc migrate import-tools --output-dir migration-artifacts/tools
   • scaffold bridge plugin templates with ecc migrate import-plugins --output-dir migration-artifacts/plugins
   • preview recurring jobs with ecc migrate import-schedules --dry-run
   • preview gateway dispatch with ecc migrate import-remote --dry-run
   • preview safe env/service context with ecc migrate import-env --dry-run
   • import sanitized workspace memory with ecc migrate import-memory
1. Install ECC and verify the baseline harness setup with node tests/run-all.js; the expected result is a zero-failure test summary.
2. Install Hermes and point it at ECC-imported skills.
3. Initialize the shared ECC Memory Vault. Register ecc-memory-mcp only if Hermes needs tool access instead of the ecc memory CLI.
4. Authenticate Google Drive first, then GitHub, then distribution channels.
5. Start with a small cron surface: readiness check, content accountability, inbox triage, revenue monitor.
6. Only then add heavier personal workflows like health, relationship graphing, or outbound sequencing.

Related Docs

• Hermes/OpenClaw migration guide
• Cross-harness architecture

Why Hermes x ECC

This stack is useful when you want:

• one terminal-native place to run business and engineering operations
• reusable skills instead of one-off prompts
• automation that can nudge, audit, and escalate
• a public repo that shows the system shape without exposing your private operator state

Public Release Candidate Scope

ECC v2.0.0-rc.1 documents the Hermes surface and ships launch collateral now.

The remaining private pieces can be layered later:

• additional sanitized templates
• richer public examples
• more generated workflow packs
• tighter CRM and Google Workspace integrations