Hermes

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

Hermes is a built-in adapter — no plugin install required. Paperclip ships hermes_local out of the box.
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, Copilot, Copilot ACP, HuggingFace, ZAI, Kimi Coding, MiniMax, Kilocode).
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

Field	Required	Default	Notes
`provider`	no	`auto`	API provider. Accepts `auto`, `openrouter`, `nous`, `openai-codex`, `copilot`, `copilot-acp`, `anthropic`, `huggingface`, `zai`, `kimi-coding`, `minimax`, `minimax-cn`, `kilocode`. Usually leave this on `auto` — Hermes infers it from your model or `~/.hermes/config.yaml`.
`timeoutSec`	no	`1800`	Execution timeout in seconds.
`graceSec`	no	`10`	Seconds to wait after SIGTERM before killing the Hermes process.

Tools

Field	Required	Default	Notes
`toolsets`	no	all	Comma-separated list of toolsets, such as `terminal,file,web`.
`maxTurnsPerRun`	no	—	Optional Hermes `--max-turns` limit for tool-calling iterations.

Session & workspace

Field	Required	Default	Notes
`persistSession`	no	`true`	Resume sessions across heartbeats via Hermes `--resume`.
`worktreeMode`	no	`false`	Git worktree isolation.
`checkpoints`	no	`false`	Enables filesystem checkpoints for rollback.

Advanced

Field	Required	Default	Notes
`verbose`	no	`false`	Verbose output.
`quiet`	no	`true`	Clean output — no banner or spinner.
`promptTemplate`	no	built-in	Custom prompt template (see below).
`paperclipApiUrl`	no	—	Optional API base override. Defaults to `PAPERCLIP_API_URL`.

Model Selection

Hermes manages its own model. You set the model in ~/.hermes/config.yaml or through Hermes's own configuration — there is no model field in the Paperclip adapter config. This keeps the "add a Hermes agent" flow one-click: if Hermes is already configured on your machine, you're done.

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:

Variable	Description
`{{agentId}}`	Paperclip agent ID
`{{agentName}}`	Agent display name
`{{companyId}}`	Company ID
`{{companyName}}`	Company name
`{{runId}}`	Current heartbeat run ID
`{{taskId}}`	Assigned task/issue ID
`{{taskTitle}}`	Task title
`{{taskBody}}`	Task instructions
`{{projectName}}`	Project name
`{{paperclipApiUrl}}`	Paperclip API base URL
`{{commentId}}`	Comment ID (when woken by a comment)
`{{wakeReason}}`	Reason this run was triggered

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:

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

Example

{
  "adapterType": "hermes_local",
  "adapterConfig": {
    "toolsets": "terminal,file,web",
    "persistSession": true,
    "checkpoints": true,
    "timeoutSec": 1800,
    "graceSec": 10
  }
}

Everything you need to run Paperclip.