NousResearch/hermes-paperclip-adapter

Hermes Agent용 Paperclip 어댑터

Paperclip 회사에서 Hermes Agent를 관리형 직원으로 실행할 수 있게 해주는 Paperclip 어댑터입니다.

Hermes Agent는 Nous Research의 풀 기능 AI 에이전트로, 30개 이상의 네이티브 도구, 영구 메모리, 세션 지속성, 80개 이상의 스킬, MCP 지원, 다중 제공업체 모델 액세스를 제공합니다.

주요 기능

이 어댑터는 다음을 제공합니다:

• 8개 추론 제공업체 — Anthropic, OpenRouter, OpenAI, Nous, OpenAI Codex, ZAI, Kimi Coding, MiniMax
• 스킬 통합 — Paperclip 관리형 스킬과 Hermes 네이티브 스킬(~/.hermes/skills/)을 모두 스캔하며, 동기화/목록/해결 API 제공
• 구조화된 트랜스크립트 파싱 — 원시 Hermes 표준 출력을 타입화된 TranscriptEntry 객체로 파싱하여 Paperclip이 상태 아이콘과 확장/축소 기능이 있는 적절한 도구 카드를 렌더링하도록 함
• 풍부한 후처리 — Hermes ASCII 배너, setext 제목, +--+ 테이블 테두리를 깔끔한 GFM 마크다운으로 변환
• 댓글 기반 깨우기 — 작업 할당뿐만 아니라 이슈 댓글에 응답하기 위해 에이전트가 깨어남
• 자동 모델 감지 — ~/.hermes/config.yaml을 읽어 사용자가 구성한 모델로 UI를 미리 채움
• 세션 코덱 — 하트비트 간 세션 상태의 구조화된 검증 및 마이그레이션
• 무해한 stderr 재분류 — MCP 초기화 메시지와 구조화된 로그가 UI에서 오류로 표시되지 않도록 재분류
• 세션 소스 태깅 — 세션이 사용자의 대화형 기록을 어지럽히지 않도록 tool 소스로 태깅
• 파일시스템 체크포인트 — 롤백 안전성을 위한 선택적 --checkpoints
• 사고 노력 제어 — 사고/추론 모델을 위한 --reasoning-effort 전달

Hermes Agent 기능

설치

npm install hermes-paperclip-adapter

사전 요구 사항

• Hermes Agent 설치 (pip install hermes-agent)
• Python 3.10+
• 최소 하나의 LLM API 키 (Anthropic, OpenRouter 또는 OpenAI)

빠른 시작

1. Paperclip 서버에 어댑터 등록

Paperclip 서버의 어댑터 레지스트리(server/src/adapters/registry.ts)에 추가:

import * as hermesLocal from "hermes-paperclip-adapter";
import {
  execute,
  testEnvironment,
  detectModel,
  listSkills,
  syncSkills,
  sessionCodec,
} from "hermes-paperclip-adapter/server";

registry.set("hermes_local", {...hermesLocal,
  execute,
  testEnvironment,
  detectModel,
  listSkills,
  syncSkills,
  sessionCodec,
});

2. Paperclip에서 Hermes 에이전트 생성

Paperclip UI 또는 API를 통해 어댑터 유형이 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. 작업 할당

Paperclip에서 이슈를 생성하고 Hermes 에이전트에 할당합니다. 각 하트비트에서 Hermes는:

1. 작업 지침 수신
2. 전체 도구 모음을 사용하여 작업 완료
3. 결과를 Paperclip에 보고
4. 연속성을 위해 세션 상태 유지

구성 참조

핵심

도구

사용 가능한 도구 세트: terminal, file, web, browser, code_execution, vision, mcp, creative, productivity

세션 및 작업 공간

고급

프롬프트 템플릿 변수

promptTemplate에서 {{variable}} 구문 사용:

조건부 섹션:

• {{#taskId}}...{{/taskId}} — 작업이 할당된 경우에만 포함
• {{#noTask}}...{{/noTask}} — 작업이 없는 경우에만 포함 (하트비트 확인)
• {{#commentId}}...{{/commentId}} — 댓글로 깨어난 경우에만 포함

아키텍처

Paperclip                          Hermes Agent
┌──────────────────┐               ┌──────────────────┐
│  하트비트         │               │                  │
│  스케줄러         │───execute()──▶│  hermes chat -q  │
│                  │               │                  │
│  이슈 시스템      │               │  30+ 도구        │
│  댓글 깨우기      │◀──결과────────│  메모리 시스템    │
│                  │               │  세션 DB         │
│  비용 추적        │               │  스킬            │
│                  │               │  MCP 클라이언트   │
│  스킬 동기화      │◀──스냅샷──────│  ~/.hermes/skills│
│  조직도           │               │                  │
└──────────────────┘               └──────────────────┘

어댑터는 Hermes Agent의 CLI를 단일 쿼리 모드(-q)로 실행합니다. Hermes는 전체 도구 모음을 사용하여 작업을 처리한 후 종료됩니다. 어댑터는:

1. 표준 출력/표준 오류를 캡처하고 토큰 사용량, 세션 ID 및 비용을 파싱합니다.
2. 원시 출력을 구조화된 TranscriptEntry 객체로 파싱합니다 (상태 아이콘이 있는 도구 카드).
3. Hermes ASCII 형식(배너, setext 제목, 테이블 테두리)을 깔끔한 GFM 마크다운으로 후처리합니다.
4. 무해한 stderr(MCP 초기화, 구조화된 로그)를 재분류하여 오류로 표시되지 않도록 합니다.
5. 세션을 tool 소스로 태깅하여 대화형 사용과 분리합니다.
6. 비용, 사용량 및 세션 상태와 함께 결과를 Paperclip에 보고합니다.

세션 지속성은 Hermes의 --resume 플래그를 통해 작동합니다. 각 실행은 이전 실행이 중단된 지점에서 계속되어 하트비트 간 대화 컨텍스트, 메모리 및 도구 상태를 유지합니다. sessionCodec은 실행 간 세션 상태를 검증하고 마이그레이션합니다.

스킬 통합

어댑터는 두 가지 스킬 소스를 스캔하여 병합합니다:

• Paperclip 관리형 스킬 — 어댑터에 번들로 제공되며 UI에서 전환 가능
• Hermes 네이티브 스킬 — ~/.hermes/skills/에서 읽기 전용, 항상 로드됨

listSkills / syncSkills API는 통합된 스냅샷을 제공하여 Paperclip UI가 관리형 및 네이티브 스킬을 한 보기에서 표시할 수 있도록 합니다.

개발

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

라이선스

MIT — LICENSE 참조

링크

• Hermes Agent — 이 어댑터가 실행하는 AI 에이전트
• Paperclip — 오케스트레이션 플랫폼
• Nous Research — Hermes를 만든 팀
• Paperclip 문서 — Paperclip 문서