Hermes Local

hermes_local runs Hermes Agent — a full-featured AI agent by Nous Research — on the same machine as Paperclip. Use it when you want persistent memory, a 30+ tool suite, 80+ loadable skills, multi-provider model routing, and MCP client support in a single adapter.

When To Use

• You already use Hermes Agent locally (pip install hermes-agent).
• You need persistent memory, FTS5 session search, or sub-agent delegation.
• You want to route to multiple inference providers (Anthropic, OpenRouter, OpenAI, Nous, OpenAI Codex, ZAI, Kimi Coding, MiniMax).
• You want filesystem checkpoints for rollback safety.

When Not To Use

• The runtime lives behind a webhook or API. Use OpenClaw Gateway or HTTP.
• You only need a one-shot shell command. Use Process.
• Hermes Agent is not installed on the machine (requires Python 3.10+).

Common Fields

Core

Tools

Session & workspace

Advanced

Auto Model Detection

If you don't set model, the adapter reads ~/.hermes/config.yaml and pre-populates the UI with the user's configured model. This makes the "add a Hermes agent" flow one-click when Hermes is already configured on the machine.

Session Persistence

When persistSession=true (the default), each run resumes via Hermes's --resume flag. This preserves:

• Conversation context.
• Memories.
• Tool state.

Sessions are tagged as tool source so they don't clutter the user's interactive Hermes history. The adapter's sessionCodec validates and migrates session state between runs.

Skills Integration

The adapter scans two skill sources and merges them in the UI:

• Paperclip-managed skills — bundled with the adapter, togglable from the board UI.
• Hermes-native skills — from ~/.hermes/skills/, read-only, always loaded.

listSkills and syncSkills expose the unified snapshot so the Paperclip UI shows both categories in one view.

Prompt Template Variables

Use {{variable}} syntax in promptTemplate:

Conditional sections:

• {{#taskId}}...{{/taskId}} — included only when a task is assigned.
• {{#noTask}}...{{/noTask}} — included only on plain heartbeat checks.
• {{#commentId}}...{{/commentId}} — included only when woken by a comment.

Execution Details

The adapter spawns Hermes Agent in single-query mode (hermes chat -q ...). Hermes processes the task using its full tool suite, then exits. The adapter:

1. Captures stdout/stderr and parses token usage, session IDs, and cost.
2. Parses raw output into structured TranscriptEntry objects (tool cards with status icons).
3. Post-processes Hermes ASCII banners, setext headings, and +--+ table borders into clean GFM markdown.
4. Reclassifies benign stderr (MCP init messages, structured logs) so they don't appear as errors.
5. Tags sessions as tool source.
6. Reports results back to Paperclip with cost, usage, and session state.

Example

{
  "adapterType": "hermes_local",
  "adapterConfig": {
    "model": "anthropic/claude-sonnet-4",
    "toolsets": "terminal,file,web",
    "persistSession": true,
    "checkpoints": true,
    "timeoutSec": 300,
    "graceSec": 10,
    "env": {
      "ANTHROPIC_API_KEY": {
        "type": "secret_ref",
        "secretId": "anthropic-key",
        "version": "latest"
      }
    }
  }
}

Next Steps

• Creating an Adapter
• Adapter UI Parser Contract