hermes-agent-nous-research

What this skill does

```markdown
---
name: hermes-agent-nous-research
description: Practical guide skill for Hermes Agent, the open-source AI Agent framework by Nous Research featuring a self-improving learning loop, three-layer memory system, and automatic Skill creation and evolution.
triggers:
  - "set up hermes agent"
  - "use hermes agent framework"
  - "configure hermes agent skills"
  - "hermes agent memory system"
  - "nous research hermes agent"
  - "build agent with hermes"
  - "hermes agent learning loop"
  - "hermes agent tool integration"
---

# Hermes Agent — Nous Research Framework Guide

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

Hermes Agent is an open-source AI Agent framework by [Nous Research](https://hermes-agent.nousresearch.com/) (released February 2026). It differentiates from Claude Code and OpenClaw through three core innovations:

1. **Self-Improving Learning Loop** — the agent observes outcomes and refines its own behavior
2. **Three-Layer Memory System** — working memory, episodic memory, and semantic/skill memory
3. **Automatic Skill Creation & Evolution** — reusable Skill modules are generated and improved from experience

Official repo: [https://github.com/NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent)  
Docs: [https://hermes-agent.nousresearch.com/docs/](https://hermes-agent.nousresearch.com/docs/)

---

## Installation

### Prerequisites

- Python 3.10+
- Node.js 18+ (for web-based integrations)
- An LLM API key (OpenAI, Anthropic, or a local model via Ollama)

### Install via pip

```bash
pip install hermes-agent
```

### Install from source

```bash
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
pip install -e ".[dev]"
```

### Verify installation

```bash
hermes --version
hermes doctor  # checks dependencies and config
```

---

## Configuration

Hermes Agent uses a config file at `~/.hermes/config.yaml` (auto-created on first run) and respects environment variables.

### Environment Variables

```bash
# LLM provider credentials
export HERMES_LLM_PROVIDER=openai          # openai | anthropic | ollama | openrouter
export OPENAI_API_KEY=your_key_here
export ANTHROPIC_API_KEY=your_key_here

# Memory backend (default: local sqlite)
export HERMES_MEMORY_BACKEND=sqlite        # sqlite | postgres | redis
export HERMES_MEMORY_PATH=~/.hermes/memory.db

# Skill registry
export HERMES_SKILL_REGISTRY=~/.hermes/skills/
export HERMES_AUTO_SKILL_CREATION=true

# Logging
export HERMES_LOG_LEVEL=info               # debug | info | warn | error
```

### `~/.hermes/config.yaml` structure

```yaml
llm:
  provider: openai
  model: gpt-4o                # or claude-3-7-sonnet, hermes-3-70b, etc.
  temperature: 0.2
  max_tokens: 8192

memory:
  backend: sqlite
  path: ~/.hermes/memory.db
  working_memory_ttl: 3600     # seconds; ephemeral per-session context
  episodic_retention_days: 90  # how long to keep past session logs

skills:
  registry: ~/.hermes/skills/
  auto_create: true            # agent can write new Skills from experience
  auto_evolve: true            # agent can improve existing Skills

tools:
  web_search: true
  code_execution: true
  file_system: true
  shell: false                 # disable for sandboxed environments

harness:
  instructions_path: ~/.hermes/instructions.md
  constraints_path: ~/.hermes/constraints.md
```

---

## CLI Key Commands

```bash
# Start interactive agent session
hermes chat

# Run a one-shot task
hermes run "Summarize the latest commits in this repo"

# Run with a specific skill loaded
hermes run --skill python-refactor "Refactor src/utils.py for readability"

# List installed skills
hermes skills list

# Install a skill from the registry
hermes skills install python-refactor

# Create a new skill interactively
hermes skills create

# Inspect memory
hermes memory show --type episodic --last 10
hermes memory show --type semantic

# Clear working memory (keeps episodic + semantic)
hermes memory clear --working

# Export all memory to JSON
hermes memory export --output memory-backup.json

# Show agent's self-evaluation log (learning loop output)
hermes log --type learning --last 20

# Doctor / diagnostics
hermes doctor

# Update hermes agent
hermes update
```

---

## Python SDK — Core Usage Patterns

### Basic Agent Session

```python
from hermes_agent import HermesAgent

agent = HermesAgent(
    provider="openai",
    model="gpt-4o",
    # API key read from OPENAI_API_KEY env var automatically
)

response = agent.run("List all Python files in the current directory and summarize their purpose.")
print(response.output)
print(response.skills_used)   # Skills the agent invoked
print(response.memory_refs)   # Memory entries accessed
```

### Streaming Responses

```python
from hermes_agent import HermesAgent

agent = HermesAgent(provider="anthropic", model="claude-3-7-sonnet")

for chunk in agent.stream("Write and explain a binary search implementation in Python"):
    print(chunk.text, end="", flush=True)
```

### Using the Three-Layer Memory System

```python
from hermes_agent import HermesAgent
from hermes_agent.memory import MemoryLayer

agent = HermesAgent()

# Write to semantic memory (persistent facts/skills)
agent.memory.write(
    layer=MemoryLayer.SEMANTIC,
    key="project_context",
    value="This is a FastAPI app using PostgreSQL and deployed on Fly.io"
)

# Write to episodic memory (past event log)
agent.memory.write(
    layer=MemoryLayer.EPISODIC,
    content="Refactored the auth module on 2026-04-08, moved JWT logic to services/auth.py"
)

# Read from memory
context = agent.memory.read(layer=MemoryLayer.SEMANTIC, key="project_context")
recent_episodes = agent.memory.search(
    layer=MemoryLayer.EPISODIC,
    query="auth refactor",
    top_k=5
)

# Working memory is managed automatically per session
# but you can inject context manually:
agent.memory.inject_working(
    "The user prefers concise answers with code examples only, no prose explanation."
)
```

### Creating and Using Skills Programmatically

```python
from hermes_agent import HermesAgent
from hermes_agent.skills import Skill, SkillRegistry

# Define a custom Skill
class GitCommitSummarySkill(Skill):
    name = "git-commit-summary"
    description = "Summarizes recent git commits in a readable changelog format"
    version = "1.0.0"

    def run(self, agent, context: dict) -> str:
        num_commits = context.get("num_commits", 10)
        result = agent.tools.shell(f"git log --oneline -{num_commits}")
        return agent.llm.complete(
            f"Format these git commits as a concise changelog:\n{result}"
        )

# Register and use the skill
registry = SkillRegistry()
registry.register(GitCommitSummarySkill())

agent = HermesAgent(skill_registry=registry)
response = agent.run(
    "Summarize the last 20 commits",
    skill_hint="git-commit-summary"
)
print(response.output)
```

### Auto Skill Creation (Self-Improvement Loop)

```python
from hermes_agent import HermesAgent

agent = HermesAgent(
    auto_skill_creation=True,   # agent writes Skills when it detects repetitive patterns
    auto_evolve=True,           # agent improves existing Skills based on outcome feedback
)

# The agent will observe that it repeatedly does this pattern
# and may auto-generate a "dependency-audit" Skill after a few runs
for project_path in ["./project-a", "./project-b", "./project-c"]:
    agent.run(f"Audit {project_path} for outdated Python dependencies and suggest upgrades")

# Inspect what Skills were auto-created
new_skills = agent.skills.list(source="auto-created")
for skill in new_skills:
    print(f"{skill.name} v{skill.version} — {skill.description}")
    print(skill.source_code)
```

### Multi-Agent Orchestration

```python
from hermes_agent import HermesAgent, AgentOrchestrator

# Specialist agents
researcher = HermesAgent(
    role="researcher",
    system_prompt="You are a research specialist. Gather facts and sources."
)

writer = HermesAgent(
    role="