@so-me/hermes-agent

Drop-in Nous Hermes 4 integration for the so-me.studio MCP. Two ways to use it:

1. Standalone runtime — so-me-hermes "..." from the command line, backed by OpenRouter / Together / vLLM / Ollama.
2. Official Nous Research Hermes Agent — paste a 5-line mcp_servers: block into config.yaml; Hermes Agent auto-discovers all 143 so-me tools.

Naming clash, on purpose. This package (@so-me/hermes-agent) is the integration layer between so-me.studio and the Nous Hermes 4 model. It is not the official Nous Research Hermes Agent product — it integrates with it. Both names start with "Hermes" because they're both built on the same Nous models.

1. Standalone runtime

npm install -g @so-me/hermes-agent
# or run ad-hoc without installing:
npx @so-me/hermes-agent "your prompt"

# Required — your so-me.studio key
export SOMESTUDIO_API_KEY=sk_live_...   # from app.so-me.studio/settings/api-keys

# Required — pick an inference backend
export HERMES_BASE_URL=https://openrouter.ai/api/v1
export HERMES_API_KEY=sk-or-...
export HERMES_MODEL=nousresearch/hermes-4-405b

# Run
so-me-hermes "List my connected social accounts"
so-me-hermes "Schedule a tweet 'launching today' for 9am UTC tomorrow"
so-me-hermes "Generate a Friday LinkedIn caption about Q2 wins"

Optional env:

• SOMESTUDIO_API_URL — override (default https://api.so-me.studio). Use http://localhost:8000 if pointing at a local backend.
• MAX_TURNS — cap agent turns (default 8).

Pick an inference backend

| Backend | Cost | Setup | |---|---|---| | OpenRouter (keys) | $1 covers ~200 runs | 2 min | | Together AI (keys) | Similar | 2 min | | vLLM (self-host) | Free, needs GPUs | See configs/vllm.sh | | Ollama (local) | Free, works on CPU | ollama serve, then HERMES_BASE_URL=http://localhost:11434/v1 + HERMES_API_KEY=ollama + a tool-calling model like hermes3:8b |

Drop-in env templates: configs/openrouter.json, configs/together.json.

Library API

If you'd rather embed the runtime in a larger app:

import { runAgent } from '@so-me/hermes-agent';

const result = await runAgent({
  prompt: "Schedule a tweet 'hello' for tomorrow at 9am UTC",
  soMeApiKey: process.env.SOMESTUDIO_API_KEY!,
  hermesBaseUrl: 'https://openrouter.ai/api/v1',
  hermesApiKey: process.env.HERMES_API_KEY!,
  hermesModel: 'nousresearch/hermes-4-405b',
  onMessage: (msg) => console.log(msg.role, msg.content),
});

console.log(`Stopped after ${result.turns} turns: ${result.stoppedReason}`);

You can override the bundled tools and systemPrompt to scope the agent to a smaller surface or change the persona.

2. Official Nous Research Hermes Agent (recommended for richer agents)

The official Hermes Agent is a full autonomous agent product from Nous Research. Since v0.2.0 it's been a native MCP client — point it at any MCP server and the tools register automatically.

Three steps:

1. Install the official Hermes Agent per their quickstart:

   curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
   source ~/.bashrc   # or ~/.zshrc
   hermes model       # pick an LLM backend (e.g. nousresearch/hermes-4-405b via OpenRouter)

2. Append the snippet from configs/hermes-agent.yaml to ~/.hermes/config.yaml:

   mcp_servers:
     so-me-studio:
       url: https://api.so-me.studio/mcp
       headers:
         X-API-Key: ${SOMESTUDIO_API_KEY}

   (HTTP transport is inferred from the url: field; no transport: key needed.)

3. Save your so-me.studio API key as a Hermes secret and start the agent:

   hermes config set SOMESTUDIO_API_KEY sk_live_...
   hermes --tui    # or `hermes` for the classic CLI

All 143 so-me tools register as mcp_so-me-studio_<tool_name> (e.g. mcp_so-me-studio_create_post, mcp_so-me-studio_list_accounts). Hand-authored guidance lives in bundle/SKILL.md; worked transcripts in bundle/examples/.

Architecture

        ┌──────────────────────────┐
        │   user prompt            │
        └────────────┬─────────────┘
                     │
       ┌─────────────┴─────────────┐
       ▼                           ▼
 ┌────────────────┐    ┌────────────────────────────┐
 │ standalone     │    │ official Hermes Agent      │
 │ so-me-hermes   │    │ (mcp_servers: config)      │
 └────────┬───────┘    └─────────────┬──────────────┘
          │                          │
          └────────────┬─────────────┘
                       ▼
        ┌──────────────────────────────┐
        │ so-me.studio /mcp            │
        │ POST tools/call (X-API-Key)  │
        └──────────────────────────────┘

Every tool call routes through the so-me.studio MCP server — the same dispatch path that Claude Desktop / Cursor / OpenClaw use via the CLI alternative. One source of truth.

What's bundled

• bundle/SKILL.md — hand-authored guide (decision tree, hard rules, gotchas, error table)
• bundle/tools.md — auto-generated catalogue of all 143 MCP tools, grouped
• bundle/tools.json — OpenAI-style schemas for all 143 so-me.studio tools (auto-generated)
• bundle/system_prompt.md — preamble baked into the runtime (auto-generated)
• bundle/examples/{schedule-post,reply-dm,weekly-report}.md — worked transcripts
• configs/hermes-agent.yaml — drop-in MCP block for the official Hermes Agent
• configs/{openrouter,together}.json + configs/vllm.sh — env templates for the standalone runtime
• dist/index.js + dist/bin/so-me-hermes.js — compiled runtime + CLI

Hard rules baked into the system prompt

• Reason inside <think>...</think> before tool calls
• Never invent IDs (account, post, conversation)
• scheduledAt must be ISO 8601 UTC, strictly future
• Multi-step jobs (image → upload → post) run sequentially
• Never reveal API keys or webhook secrets

Full guide and worked examples: bundle/SKILL.md.

Regenerating bundled assets

When the so-me.studio backend ships new MCP tools, regenerate via the cross-format exporter (writes bundle/tools.json + companion bundle/tools.md + bundle/system_prompt.md in one shot):

# from the so-me.studio monorepo
pnpm --filter @so-me/cli build
SOMESTUDIO_API_KEY=sk_live_... node apps/cli/dist/bin/so-me-dev.js \
  agent export-tools \
  --format hermes \
  --out apps/agent-kits/hermes/bundle/tools.json

Bump the package version and republish — see PUBLISHING.md.

Limits in v0.1 (standalone runtime only)

• No streaming output — the runtime fetches the full response per turn. Streaming is a small change to the runtime if you need live tokens.
• Sequential tool calls — multiple calls per turn run serially, not in parallel.
• Default MAX_TURNS=8 — override via env if you need longer sessions.

The official Hermes Agent integration has none of these limits — it's the recommended path for long-running multi-step sessions.

License

MIT — see LICENSE.

Source

github.com/7t1-studio/schedular-app/tree/main/apps/agent-kits/hermes