Hermes Agent by Nous Research: Architecture, Self-Improving Loops, and MCP Integration

Configuration (~/.hermes/config.yaml)

# Model Provider Routing
providers:
  openrouter:
    api_key: ${OPENROUTER_API_KEY}
    api_mode: openai
    default_model: anthropic/claude-sonnet-4-6
  anthropic:
    api_key: ${ANTHROPIC_API_KEY}
    api_mode: anthropic
    prompt_caching: true

# Terminal Execution Sandbox
terminal:
  backend: docker          # local | docker | ssh | modal | daytona | singularity
  timeout: 180
  docker:
    image: "nikolaik/python-nodejs:python3.11-nodejs20"
    network: "bridge"      # none | bridge | host
    gpu: false

# Memory System & Approval Gates
memory:
  memory_char_limit: 2200
  user_char_limit: 1375
  write_approval: false    # Set true to enforce manual confirmation before saves

# MCP Server Definitions
mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_TOKEN: ${GITHUB_TOKEN}

Implementing Custom Skills

Create a structured skill directory inside ~/.hermes/skills/:

---
name: k8s-deploy
description: Validate, deploy, and inspect Kubernetes resources using kubectl and Helm
version: 1.0.0
platforms: [linux, macos]
metadata:
  hermes:
    tags: [kubernetes, helm, devops]
    category: devops
    requires_toolsets: [terminal]
---

# Kubernetes Deployment Workflow

## Deployment Procedure
1. Verify cluster connectivity:
   ```bash
   kubectl cluster-info

2. Lint Helm charts before installation:

   helm lint ./chart/ -f values.yaml

3. Execute atomic deployment:

   helm upgrade --install <release-name> ./chart/ --namespace <namespace> --atomic --timeout 5m

Rollback Protocol

If deployment fails, verify pod health and revert:

kubectl get pods -n <namespace> --field-selector status.phase!=Running
helm rollback <release-name> 0 --namespace <namespace>

---

## Subagent Delegation & Batch Trajectory Generation

### Parallel Workstream Execution via RPC

```python title="examples/subagent_delegate.py"
from __future__ import annotations

import json
from hermes.tools import delegate


def execute_parallel_audit() -> dict[str, str]:
    # Spawn isolated subagents with independent context budgets
    task_test = delegate(
        action="spawn",
        prompt="Execute pytest test suite in isolated container and report traceback",
        toolsets=["terminal"],
        backend="docker",
        timeout=300,
    )

    task_security = delegate(
        action="spawn",
        prompt="Run bandit and safety audit across all repository dependencies",
        toolsets=["terminal"],
        backend="docker",
        timeout=180,
    )

    return {
        "tests": task_test["output"],
        "security": task_security["output"],
    }

Research Trajectory Export

Hermes supports emitting structured ShareGPT / JSONL interaction trajectories for post-training and imitation learning:

python -m hermes.batch_runner \
  --input prompts/benchmark_tasks.jsonl \
  --output trajectories/sharegpt_v1.jsonl \
  --model anthropic/claude-sonnet-4-6 \
  --max-parallel 8

Production Security & Sandboxing Matrix

Troubleshooting Common Issues

1. Memory Buffer Saturation

• Symptom: Agent logs MemoryLimitExceeded during turn evaluation.
• Resolution: Adjust memory_char_limit in config.yaml or invoke /memory pending to prune obsolete facts.

2. FTS5 Index Desynchronization

• Symptom: session_search fails to recall past conversations.
• Resolution: Rebuild the SQLite full-text index via hermes doctor --reindex.

3. Docker Socket Permission Denied

• Symptom: Tool execution fails with PermissionDenied: /var/run/docker.sock.
• Resolution: Ensure the active user is in the docker user group (sudo usermod -aG docker $USER) and reload the shell.