Paperclip Adapter for Hermes Agent

A Paperclip adapter that lets you run Hermes Agent as a managed employee in a Paperclip company.

Hermes Agent is a full-featured AI agent by Nous Research with 30+ native tools, persistent memory, session persistence, 80+ skills, MCP support, and multi-provider model access.

Why Hermes Agent?

| Feature | Claude Code | Codex | Hermes Agent | |---------|------------|-------|-------------| | Persistent memory | ❌ | ❌ | ✅ Remembers across sessions | | Native tools | ~5 | ~5 | 30+ (terminal, file, web, browser, vision, git, etc.) | | Skills system | ❌ | ❌ | ✅ 80+ loadable skills | | Session search | ❌ | ❌ | ✅ FTS5 search over past conversations | | Sub-agent delegation | ❌ | ❌ | ✅ Parallel sub-tasks | | Context compression | ❌ | ❌ | ✅ Auto-compresses long conversations | | MCP client | ❌ | ❌ | ✅ Connect to any MCP server | | Multi-provider | Anthropic only | OpenAI only | ✅ Anthropic, OpenAI, OpenRouter, Google |

Installation

npm install @nousresearch/paperclip-adapter-hermes

Prerequisites

• Hermes Agent installed (pip install hermes-agent)
• Python 3.10+
• At least one LLM API key (Anthropic, OpenRouter, or OpenAI)

Quick Start

1. Register the adapter in your Paperclip server

Add to your Paperclip server's adapter registry (server/src/adapters/registry.ts):

import * as hermesLocal from "@nousresearch/paperclip-adapter-hermes";
import { execute, testEnvironment } from "@nousresearch/paperclip-adapter-hermes/server";

registry.set("hermes_local", {
  ...hermesLocal,
  execute,
  testEnvironment,
});

2. Create a Hermes agent in Paperclip

In the Paperclip UI or via API, create an agent with adapter type hermes_local:

{
  "name": "Hermes Engineer",
  "adapterType": "hermes_local",
  "adapterConfig": {
    "model": "anthropic/claude-sonnet-4",
    "maxIterations": 50,
    "timeoutSec": 300,
    "persistSession": true,
    "enabledToolsets": ["terminal", "file", "web"]
  }
}

3. Assign work

Create issues in Paperclip and assign them to your Hermes agent. On each heartbeat, Hermes will:

1. Receive the task instructions
2. Use its full tool suite to complete the work
3. Report results back to Paperclip
4. Persist session state for continuity

Configuration Reference

Core

| Field | Type | Default | Description | |-------|------|---------|-------------| | model | string | anthropic/claude-sonnet-4 | Model in provider/model format | | provider | string | (auto-detected) | API provider override | | maxIterations | number | 50 | Max tool-calling iterations per run | | timeoutSec | number | 300 | Execution timeout in seconds | | graceSec | number | 10 | Grace period before SIGKILL |

Tools

| Field | Type | Default | Description | |-------|------|---------|-------------| | enabledToolsets | string[] | (all) | Toolsets to enable | | disabledToolsets | string[] | [] | Toolsets to disable |

Available toolsets: terminal, file, web, browser, code_execution, vision, mcp, creative, productivity

Session & Memory

| Field | Type | Default | Description | |-------|------|---------|-------------| | persistSession | boolean | true | Resume sessions across heartbeats | | skipMemory | boolean | false | Disable persistent memory | | worktreeMode | boolean | false | Git worktree isolation |

Advanced

| Field | Type | Default | Description | |-------|------|---------|-------------| | hermesCommand | string | hermes | Custom CLI binary path | | contextFiles | string[] | [] | Extra context files to load | | extraArgs | string[] | [] | Additional CLI arguments | | env | object | {} | Extra environment variables | | promptTemplate | string | (built-in) | Custom prompt template |

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 |

Conditional sections:

• {{#taskId}}...{{/taskId}} — included only when a task is assigned
• {{#noTask}}...{{/noTask}} — included only when no task (heartbeat check)

Architecture

Paperclip                          Hermes Agent
┌──────────────────┐               ┌──────────────────┐
│  Heartbeat       │               │                  │
│  Scheduler       │───execute()──▶│  hermes chat -q  │
│                  │               │                  │
│  Issue System    │               │  30+ Tools       │
│                  │◀──results─────│  Memory System   │
│  Cost Tracking   │               │  Session DB      │
│                  │               │  Skills          │
│  Org Chart       │               │  MCP Client      │
└──────────────────┘               └──────────────────┘

The adapter spawns Hermes Agent's CLI in single-query mode (-q). Hermes processes the task using its full tool suite, then exits. The adapter captures stdout/stderr, parses token usage and session IDs, and reports results back to Paperclip.

Session persistence works via Hermes's --resume flag — each run picks up where the last one left off, maintaining conversation context, memories, and tool state across heartbeats.

Development

git clone https://github.com/NousResearch/hermes-paperclip-adapter
cd hermes-paperclip-adapter
npm install
npm run build

License

MIT — see LICENSE

Links

• Hermes Agent — The AI agent this adapter runs
• Paperclip — The orchestration platform
• Nous Research — The team behind Hermes
• Paperclip Docs — Paperclip documentation