Hermione

Name: Hermione
Rating: 3.5 (1 reviews)
Author: smilebank7

By smilebank7 ⭐ 1 stars 👁 115 views ▲ 0 votes

OpenClaw plugin porting Hermes Agent features (tool progress + background memory review)

GitHub

Configuration Example

{
  "plugins": {
    "allow": ["hermione"],
    "load": {
      "paths": ["~/.openclaw/hooks/hermione"]
    },
    "entries": {
      "hermione": {
        "enabled": true,
        "config": {}
      }
    }
  }
}

README

<div align="center">

```
     __  ____________  __  ___________  _   ________
    / / / / ____/ __ \/  |/  /  _/ __ \/ | / / ____/
   / /_/ / __/ / /_/ / /|_/ // // / / /  |/ / __/
  / __  / /___/ _, _/ /  / // // /_/ / /|  / /___
 /_/ /_/_____/_/ |_/_/  /_/___/\____/_/ |_/_____/

 Self-Improvement Pack for OpenClaw Agents
```

**Your agent learns from every conversation. Automatically.**

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![OpenClaw Plugin](https://img.shields.io/badge/OpenClaw-Plugin-purple.svg)](https://github.com/openclaw/openclaw)
[![Ported from](https://img.shields.io/badge/Ported_from-Hermes_Agent-orange.svg)](https://github.com/NousResearch/hermes-agent)
[![Version](https://img.shields.io/badge/version-0.3.0-green.svg)](package.json)

[English](README.md) · [한국어](README.ko.md) · [日本語](README.ja.md) · [中文](README.zh.md)

</div>

---

## What Is This?

**Hermione** brings [Hermes Agent](https://github.com/NousResearch/hermes-agent)'s self-improvement loop to any [OpenClaw](https://github.com/openclaw/openclaw) agent. Install once — your agent starts remembering user preferences, learning from mistakes, and building reusable skills across sessions.

### The Closed Loop

```
 User works with agent across sessions
     │
     ▼
 Agent reaches review threshold (10 turns / 10 tool calls)
     │
     ├── Background review subagent spawns silently
     ├── Reads conversation transcript (incremental, cursor-based)
     ├── Extracts: user preferences, environment facts, reusable procedures
     ├── Writes to MEMORY.md / USER.md / skills/ (validated + secured)
     └── "💾 +memory: 2 · +skill: deploy-aws" → Discord notification
     │
     ▼
 Next session: agent loads updated memory + skills automatically
```

---

## Features

### 1. Proactive Memory

The agent saves knowledge without being asked — user preferences, corrections, environment facts. Memory is split into two targets with capacity tracking:

```
USER.md  — who the user is (name, role, preferences, communication style)
MEMORY.md — agent notes (environment facts, project conventions, tool quirks)
```

Each file shows live capacity: `[67% — 1,474/2,200 chars]`. When full, the agent replaces outdated entries rather than failing silently.

**What gets saved (proactively):**
- User corrections ("remember this" / "don't do that again")
- Preferences, habits, personal details
- Environment discoveries (OS, tools, project structure)
- API quirks, workflow conventions

**What doesn't get saved:**
- Task progress or session outcomes
- Temporary TODO state
- Trivial / easily re-discovered info

### 2. Background Review

After configurable thresholds, a review subagent silently extracts durable knowledge from the conversation.

| Trigger | Default | Config Key |
|---------|---------|------------|
| Agent turns since last review | 10 | `memoryReviewTurns` |
| Tool calls since last review | 10 | `skillReviewCalls` |
| Cooldown between reviews | 5 min | `reviewCooldownMs` |

**Human-centered framing**: The review prioritizes *who the user is* (persona, desires, preferences) over technical facts. This matches how Hermes produces memory that actually improves future interactions.

After each review, a Discord notification summarizes what was saved:
```
💾 +user: 1 · +memory: 2 · +skill: aws-deploy
```

### 3. Skill Management

Skills are procedural memory — proven approaches for specific task types. Full lifecycle:

| Action | Description |
|--------|-------------|
| **create** | New skill with YAML frontmatter validation |
| **edit** | Full content replacement with backup |
| **patch** | Targeted string replacement |
| **delete** | Remove skill + clean empty category dirs |

Skills are scanned with a mandatory header before every response:

```
## Skills (mandatory)
Before replying, scan the skills below. If one clearly matches your task,
load it and follow its instructions. If a skill has issues, patch it immediately.
```

**Validation on every write:**
- YAML frontmatter required (name + description)
- Description max 1024 chars, body content required
- Name conflict check across categories
- Security scan with rollback on failure

### 4. Memory Flush

When a session ends before reaching the review threshold, a lighter flush pass captures remaining valuable facts.

```
agent_end → turns >= 6? → no review ran? → flushMemories()
```

### 5. Security Scanning

Every memory write and skill save passes through a security scanner. **32 patterns** across 5 categories:

| Category | Count | Examples |
|----------|-------|----------|
| Prompt Injection | 12 | `ignore previous instructions`, `jailbreak`, `DAN mode`, `pretend you are` |
| Data Exfiltration | 8 | `curl ... $SECRET`, `cat ~/.ssh/id_rsa`, `base64 ... token` |
| Destructive Ops | 5 | `rm -rf /`, `mkfs.`, `dd if=... of=/dev/` |
| Persistence | 4 | `crontab`, `.bashrc`, `authorized_keys` |
| Invisible Unicode | 3 | Zero-width chars, bidi overrides (U+200B–U+2069, U+FEFF) |

Blocked writes are rolled back — they never persist to the filesystem.

### 6. Tool Progress Display

Real-time tool execution progress in Discord. One message per agent run, updated live:

```
💻 exec: ls -la /home/ubuntu
📖 read: /home/ubuntu/.openclaw/openclaw.json
🔧 edit: /home/ubuntu/config.yaml
🔎 search_files: "TODO"
📋 todo: planning 3 task(s)
✅ Done (5 tools, 4.2s)
```

---

## Quick Start

```bash
# Clone into hooks directory
cd ~/.openclaw/hooks/
git clone https://github.com/smilebank7/hermione.git hermione

# Restart gateway
systemctl --user restart openclaw-gateway.service
```

Then add to `openclaw.json` (see [Configuration](#configuration) below).

---

## Installation

### Prerequisites

- [OpenClaw](https://github.com/openclaw/openclaw) with plugin hook support
- Discord bot token _(optional — only for tool progress and review notifications)_

### Step 1: Clone

```bash
cd ~/.openclaw/hooks/
git clone https://github.com/smilebank7/hermione.git hermione
```

### Step 2: Register in `openclaw.json`

```jsonc
{
  "plugins": {
    "allow": ["hermione"],
    "load": {
      "paths": ["~/.openclaw/hooks/hermione"]
    },
    "entries": {
      "hermione": {
        "enabled": true,
        "config": {}
      }
    }
  }
}
```

### Step 3: Agent Setup (Recommended)

Copy the behavioral guidance template into your agent's workspace:

```bash
cat ~/.openclaw/hooks/hermione/AGENTS.md.template \
  >> ~/.openclaw/workspace-<your-agent>/AGENTS.md
```

This teaches the agent *when* and *how* to save memory, maintain skills, and use session recall.

### Step 4: Restart

```bash
systemctl --user restart openclaw-gateway.service

# Verify registration
journalctl --user -u openclaw-gateway.service --since "10s ago" | grep hermione
# Expected: [hermione] Plugin registered
```

---

## Configuration

All options go in `plugins.entries.hermione.config`:

```jsonc
{
  "hermione": {
    "enabled": true,
    "config": {
      // All values below are optional — defaults work out of the box
      "reviewModel": null,            // null = use system default model
      "maxIterations": 8,             // Max tool-use turns per review
      "memoryReviewTurns": 10,        // Turns before memory review triggers
      "skillReviewCalls": 10,         // Tool calls before skill review triggers
      "reviewCooldownMs": 300000,     // Min ms between reviews (5 min)
      "memoryCharLimit": 2200,        // Max chars for MEMORY.md entries
      "userCharLimit": 1375,          // Max chars for USER.md entries
      "flushMinTurns": 6              // Min turns before session-end flush
    }
  }
}
```

### Parameter Reference

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `reviewModel` | `string\|null` | `null` | LLM model for review subagent. `null` = system default. |
| `maxIterations` | `integer` | `8` | Maximum tool-use iterations per review session. |
| `memoryReviewTurns` | `integer` | `10` | Agent turns before triggering memory review. |
| `skillReviewCalls` | `integer` | `10` | Tool calls before triggering skill review. |
| `reviewCooldownMs` | `integer` | `300000` | Minimum ms between reviews. Prevents review storms. |
| `memoryCharLimit` | `integer` | `2200` | Character budget for MEMORY.md entries. |
| `userCharLimit` | `integer` | `1375` | Character budget for USER.md entries. |
| `flushMinTurns` | `integer` | `6` | Minimum turns before session-end flush kicks in. |

### Discord Setup

Requires a Discord bot token via environment variable:

```bash
export DISCORD_BOT_TOKEN="your-bot-token"
```

Or configured in `channels.discord.token` in `openclaw.json`. If no token is found, progress display and review notifications are disabled — all other features work normally.

---

## Architecture

```
 ╭───────────────────────────────────────────────────────────────────╮
 │  hermione                                                        │
 │                                                                  │
 │  ┌──────────────────┐  ┌──────────────────┐  ┌───────────────┐  │
 │  │  before_tool_call │  │  after_tool_call  │  │   agent_end   │  │
 │  ├──────────────────┤  ├──────────────────┤  ├───────────────┤  │
 │  │ Count tool calls  │  │ Detect skill     │  │ Finalize      │  │
 │  │ Reset on manual   │  │  file changes    │  │  progress     │  │
 │  │  memory/skill use │  │ Invalidate cache │  │ Trigger       │  │
 │  │ Push progress     │  │ Validate review  │  │  review or    │  │
 │  │  to Discord queue │  │  subagent writes │  │  flush        │  │
 │  │ Capture skill     │  │  (security +     │  │               │  │
 │  │  backup for       │  │   capacity +     │  │               │  │
 │  │  rollback         │  │   YAML check)    │  │               │  │
 │  └──────────────────┘  └──────────────────┘  └──────┬────────┘  │
 │                                                      │           │
 │  ┌───────────────────────────────────────────────────▼─────────┐ │
 │  

... (truncated)

tools