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