# Hermes Agent Integration

Atlas can run on **[hermes-agent](https://github.com/NousResearch/hermes-agent)**
(MIT, by Nous Research) as the host runtime. Hermes provides exactly what Atlas
needs: agentskills.io-compatible skill loader, cron scheduler, MCP client,
multi-platform delivery (incl. email/feishu/dingtalk), session memory + FTS5,
and subagent delegation.

This doc tells the operator how to install Atlas on top of Hermes in ≤ 30 minutes.

## What you need

- Hermes installed: `curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash`
- Python 3.10+ (for `atlas-extractor` MCP wrapper)
- This repo (`assistant-claw`) cloned

## Step 1 — Drop Atlas skills into Hermes skills dir

```bash
# Hermes scans ~/.hermes/skills/ on startup
mkdir -p ~/.hermes/skills/atlas
cp -r atlas/skills/* ~/.hermes/skills/atlas/

# Check Hermes sees them
hermes skills list | grep claw-
```

Each `claw-*/SKILL.md` already has the agentskills.io-compatible frontmatter
(`name`, `description`, `version`, `author`, `license`, `metadata.hermes.*`)
so Hermes recognizes them immediately.

## Step 2 — Fetch the nuwa-skill upstream once

```bash
# Public deployment
git clone --depth 1 https://github.com/alchaincyf/nuwa-skill.git \
  ~/.hermes/skills/atlas/claw-boss-distiller/upstream

# Air-gapped deployment (after Moments mirror is up — see ADR-0001)
git clone --depth 1 https://git.moments.top/Moments.top/nuwa-skill.git \
  ~/.hermes/skills/atlas/claw-boss-distiller/upstream
```

## Step 3 — Install atlas-extractor as an MCP server (TBD code)

The `atlas/mcp-tools/email-extractor/` Python package currently exposes a CLI
(`atlas-extract`). Wrapping it as an MCP server is V0.5 work; until then
Hermes can call the CLI via Bash.

```bash
cd atlas/mcp-tools/email-extractor
python -m venv .venv
.venv/bin/pip install -e '.[test]'
.venv/bin/pytest -q   # confirm 7/7 passing
```

## Step 4 — Configure the boss's email account

```bash
hermes env set BOSS_EMAIL boss@clientco.com
hermes env set ATLAS_IMAP_HOST imap.clientco.com
hermes env set ATLAS_IMAP_USER atlas-readonly@clientco.com
hermes env set ATLAS_IMAP_PASSWORD <app-password>     # never main password
hermes env set ATLAS_STATE_DIR ~/.atlas/state
```

## Step 5 — Wire the autopilots into Hermes cron

Atlas's 5 autopilot YAMLs live in `../autopilots/atlas-*.yaml`. Translate each
into Hermes natural-language cron:

```bash
hermes cron add "every day 7:30" "Run Atlas daily-brief skill"
hermes cron add "every monday 8:00" "Run Atlas weekly-rollup skill"
hermes cron add "every month on 1st 9:00" "Run Atlas monthly customer-health skill"
hermes cron add "every quarter on 1st 10:00" "Run Atlas boss_skill quarterly refresh"
```

Andon (event-triggered) is set up via `hermes hooks add` once Atlas writes a
sentinel file like `~/.atlas/state/runs/_andon_pending.flag`.

## Step 6 — Smoke test

```bash
# Manually invoke claw-boss-distiller on the demo input
hermes "Run claw-boss-distiller on atlas/skills/claw-boss-distiller/demo/INPUT/ \
        and write the result to atlas/skills/claw-boss-distiller/demo/OUTPUT/boss_skill.live.md"

# Check it produced a 5-layer doc
diff atlas/skills/claw-boss-distiller/demo/OUTPUT/boss_skill.demo.md \
     atlas/skills/claw-boss-distiller/demo/OUTPUT/boss_skill.live.md
```

## Step 7 — First Daily Brief

Wait until the next scheduled 7:30, OR force-run:

```bash
hermes "Run Atlas daily-brief now and email it to ${BOSS_EMAIL}"
```

The boss receives a 5-minute Brief in their inbox.

## Caveats

1. **Hermes self-improving loop** — Hermes can auto-edit its own skills based
   on usage. **Lock down `SOUL.md` and the SKILL.md `boundaries:` list** by
   adding them to Hermes's skill-write deny list. We never want Atlas to
   auto-relax its own guardrails.

2. **Branding** — Hermes's default identity is "Hermes Agent by Nous Research".
   Override the system prompt to introduce as "Atlas / 总助 Claw" for client
   deployments. See `hermes_cli/skin_engine.py` for theming hooks.

3. **Execution environment** — Use `local` or `docker` backends only for
   client-internal deployments. SSH / Daytona / Modal assume external network.

## Roadmap

- [ ] V0.5: Wrap `atlas-extractor` as proper MCP server (replace Bash CLI invocation)
- [ ] V0.5: Auto-generate Hermes skill manifest from `atlas/skills/*/SKILL.md` on commit
- [ ] V1: Build a Hermes "skill pack" installer (`hermes skills install moments/atlas`)