Skip to content

deploy

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

deploy

README.md

Hermes Deploy

Optimal Hermes Agent setup for a multi-agent research + email marketing system with MemOS-backed persistent memory.

This directory lives inside the hermes-multi-agent repo. Everything here is what gets installed to a fresh machine.

What's Included

Component Description
config/config.yaml Tuned Hermes config: MiniMax M2.7 + DeepSeek fallback, Firecrawl/SearXNG search, Camofox anti-bot, holographic memory, Deepgram STT, Gemini vision
config/.env.template Environment template with all required API keys
config/agents-auth.example.json Reference for the v2 bcrypt auth format (real file generated by provisioning)
profiles/research-agent/ Isolated research agent — SOUL.md + config
profiles/email-marketing/ Isolated email marketing agent (plusvibe.ai) — SOUL.md + config
plugins/quality-monitor/ Tracks research quality scores + logs tool calls
plugins/memos-toolset/ Native memos_store + memos_search tools — identity injected from env, zero credentials in LLM context
scripts/setup-web-stack.sh Bootstraps Firecrawl + SearXNG + Camofox Docker stack
scripts/setup-memos-agents.py Provisions MemOS cubes + generates bcrypt-hashed API keys per agent
searxng/searxng-settings.yml SearXNG meta-search config (Google + Bing + DDG + Startpage)
install.sh One-command installer — runs all of the above in order

Prerequisites

Tool Purpose Install
Hermes Agent CLI The agent runtime curl -fsSL https://hermes-agent.nousresearch.com/install | bash
Patched MemOS Memory backend (vector + graph) pip install git+https://github.com/sergiocoding96/memos
Docker Runs Firecrawl, SearXNG, Qdrant, Neo4j apt install docker.io docker-compose-v2
Python 3.10+ Provisioning script System package
age (optional) Secret encryption for MemOS apt install age or brew install age

Quick Install

git clone https://github.com/sergiocoding96/hermes-multi-agent
cd hermes-multi-agent/deploy
./install.sh

The installer will:

  1. Deploy config.yaml + .env.template to ~/.hermes/
  2. Deploy both agent profiles with their SOUL files
  3. Deploy both plugins (quality-monitor, memos-toolset)
  4. Clone/sync the shared badass-skills repo
  5. Bootstrap the web stack (Firecrawl + SearXNG + Camofox)
  6. Deploy SearXNG settings
  7. Call setup-memos-agents.py to provision cubes + generate API keys (prints keys ONCE)

Architecture

┌─────────────────────────────────────────────────────────────┐
│ CEO (Claude Opus 4.6 via Paperclip, localhost:3100)         │
│ ↓ spawns via hermes-paperclip-adapter                       │
│ Hermes Worker (MiniMax M2.7, DeepSeek fallback)             │
└─────────────────────────────────────────────────────────────┘
                       │
   ┌───────────────────┼──────────────────┐
   ▼                   ▼                  ▼
research-agent   email-marketing    default
profile           profile           profile
(own MemOS cube)  (own MemOS cube)
                       │
                       ▼ via memos-toolset plugin (bcrypt-authed)
              ┌──────────────────────┐
              │ MemOS (localhost:8001)│
              │ ├── Qdrant (vectors)  │
              │ ├── Neo4j (graph)     │
              │ └── SQLite (ACL)      │
              └──────────────────────┘

Web stack:
  Firecrawl (3002) → SearXNG (8888)   unlimited search
  Firecrawl → Playwright               JS-rendered scraping
  Camofox (9377)                       Cloudflare-bypass browser

Skills:
  ~/.hermes/skills/ (per-profile)
  ~/Coding/badass-skills (shared via external_dirs)

Required API Keys

Key Purpose Free Tier
MINIMAX_API_KEY Primary LLM Token plan
DEEPSEEK_API_KEY Fallback LLM + MemOS MEMRADER Pay-per-use
GEMINI_API_KEY Vision + image generation Free tier available
DEEPGRAM_API_KEY Speech-to-text $200 free credit
TELEGRAM_BOT_TOKEN Messaging gateway (optional) Free
MEMOS_API_KEY Auto-generated per agent by provisioning —

After Install

The provisioning script prints raw API keys once. Save them into each profile's .env file so the memos-toolset plugin can authenticate:

# Example, per profile
nano ~/.hermes/profiles/research-agent/.env
# Add:
# MEMOS_API_KEY=ak_<raw-key-from-provisioning>
# MEMOS_USER_ID=research-agent
# MEMOS_CUBE_ID=research-agent
# MINIMAX_API_KEY=<your-key>     ← profile .env replaces global .env
# DEEPSEEK_API_KEY=<your-key>

Updating

Pull latest and re-run:

cd hermes-multi-agent && git pull
cd deploy && ./install.sh

The installer is idempotent — existing .env files are never overwritten, and existing agents-auth.json triggers a skip (delete it to regenerate).

Skill Ground Truth — ~/Coding/badass-skills/

~/Coding/badass-skills/ is the single shared skill source for all runtimes:

Runtime How it reads skills
Hermes workers external_dirs in each profile's config.yaml
Claude Code CEO ~/.claude/skills/ symlinks → ~/Coding/badass-skills/*/
MemOS plugin output ~/.hermes/memos-state-*/skills-store symlinked → ~/Coding/badass-skills/auto/

Directory layout

~/Coding/badass-skills/
  gemini-video/     # hand-authored, Hermes + Claude Code compatible
  notebooklm/       # hand-authored
  pdf/              # hand-authored
  auto/             # ← MemOS plugin writes generated SKILL.md files here
                    #   (via ~/.hermes/memos-state-*/skills-store symlink)

Setup (run once per machine)

# 1. Symlink hand-authored skills into Claude Code's discovery directory
bash scripts/migration/symlink-badass-skills.sh

# 2. Redirect plugin skill-output to badass-skills/auto/
bash scripts/migration/configure-plugin-skill-output.sh

# 3. Verify
ls -la ~/.claude/skills/                          # should show 3 symlinks
ls -la ~/.hermes/memos-state-*/skills-store       # should show -> .../badass-skills/auto

Format compatibility

The existing 3 hand-authored skills (gemini-video, notebooklm, pdf) use YAML frontmatter (name:, description:) — the format Claude Code's skill discovery expects. Auto-generated skills from the MemOS plugin land in auto/ in the same format (the plugin's generator.ts writes YAML-frontmatter SKILL.md files).

Skills authored only for Hermes (if any) will appear as "external / user_installed" in Claude Code — usable but not Paperclip-managed. Do not convert single-runtime skills here; note them in the skill's SKILL.md header instead.

Reproducing on a new machine

  1. Clone badass-skills to ~/Coding/badass-skills (or let install.sh do it).
  2. Run scripts/migration/install-plugin.sh <profile> for each Hermes profile.
  3. Run the two setup scripts above.
  4. No further configuration needed — the plugin picks up stateDir/skills-store which now resolves to ~/Coding/badass-skills/auto/.

Ops Invariants

These must be re-run on specific events to keep the stack healthy.

Event Action Script
npm update paperclipai (or any version bump of paperclipai) Re-patch bundled hermes-paperclip-adapter (fixes ctx.config → ctx.context bug). Script is idempotent — safe to run defensively. scripts/paperclip/v2/patch-hermes-adapter.sh
Paperclip restart After any Paperclip restart, verify ~/.paperclip/instances/default/config.json still has deploymentMode: "authenticated". Safer to launch from a stable CWD (e.g. cd ~ && paperclipai run) — inheriting a worktree CWD that later gets deleted breaks Python subprocesses via os.getcwd(). manual check
New Hermes profile added Run scripts/paperclip/v2/apply-prompt-override.sh so the new employee inherits the stdout-completion prompt. Run scripts/paperclip/v2/patch-hermes-adapter.sh only if adapter was reinstalled. both above

Related Repos

Repo Purpose
hermes-multi-agent This repo — source of truth for configs, skills, learnings
sergiocoding96/memos Patched MemOS fork (security + search tuning)
badass-skills Shared skill library (cloned at install time)