Tools
Hermione
By OpenClaw plugin porting Hermes Agent features (tool progress + background memory review)
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)
[](https://github.com/openclaw/openclaw)
[](https://github.com/NousResearch/hermes-agent)
[](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
Comments
Sign in to leave a comment