Tools
Reflection
By OpenClaw Hermes agent like reflection plugin
Install
npm install
npmConfiguration Example
{
"plugins": {
"entries": {
"reflection": {
"config": {
"agents": ["general", "coding"],
"turnThreshold": 10,
"flushThreshold": 3,
"maxReplayChars": 60000
}
}
}
}
}README
# openclaw-reflection
An [OpenClaw](https://openclaw.ai) plugin that gives target agents a
Hermes-style **background reflection loop**: it counts turns per session and,
when a threshold is reached (or a session is discarded with enough
unreflected turns), spawns a host-side reflection subagent that replays the
recent transcript and is required to either update memory or explicitly
declare "Nothing to save." — and to file `skill_workshop` proposals for
procedural learnings.
## Behavior
- **Turn counting** (`agent_end`): each completed turn of a configured
agent's *main* session increments an in-memory per-`sessionKey` counter.
Subagent sessions (anything with `:subagent:` in the session key,
including this plugin's own reflection forks) are never counted, so a
reflection run can never trigger another reflection.
- **Threshold fire**: at `turnThreshold` (default 10) the counter resets and
a reflection fork is spawned.
- **Flush fire** (`session_end` / `before_reset`): if a session ends or
resets with at least `flushThreshold` (default 3) unreflected turns, a
reflection fires before the counter is discarded. `session_start` resets
the counter.
- **Reflection fork**: the recent transcript (tail-capped at
`maxReplayChars`, default 60000 characters) is rendered to text and
embedded in the fork's first message together with instructions adapted
from Hermes' combined memory/skill background review prompt. The fork runs
under `agent:<agentId>:subagent:reflection-<uuid>` with the default
(inherited) model; its session is deleted after the run completes.
- **Tool restriction**: `before_tool_call` enforces an allowlist for
reflection fork sessions only — `memory_search`, `memory_get`,
`skill_workshop`, and filesystem writes (`write`, `edit`, `apply_patch`)
whose target path is the workspace `memory/` directory or `MEMORY.md`.
Everything else is blocked. Path checks are fail-closed (unresolvable or
traversal-escaping paths are blocked; `apply_patch` without host-derived
path hints is blocked) and *path-shape* only — confinement to the actual
workspace directory is provided by separate layers (`workspaceOnly`,
[fs-guard](https://github.com/vol1003-labs/openclaw-fs-guard)), which
stack with this plugin. **Do not deploy without a workspace confinement
layer** — an absolute path outside the workspace whose tail matches the
memory shape (e.g. `/elsewhere/memory/x.md`) passes the shape check by
design.
- **Single-flight & fail-quiet**: at most one reflection per session at a
time (re-triggers while one is in flight are skipped), and every failure
in the reflection path is logged and swallowed — the main session is never
disturbed.
- State is in-memory only; counts are lost on gateway restart (accepted
trade-off).
## Install
Not published to npm. Install from the GitHub release tarball:
```bash
openclaw plugins install https://github.com/vol1003-labs/openclaw-reflection/releases/download/v0.1.0/openclaw-reflection-0.1.0.tgz
```
When upgrading an existing install, pass `--force`.
> **Note:** if your gateway config sets `plugins.allow`, it gates *all*
> plugins — add `"reflection"` to the allow list or the plugin will not
> load.
## Configuration
All keys are optional; defaults shown:
```json
{
"plugins": {
"entries": {
"reflection": {
"config": {
"agents": ["general", "coding"],
"turnThreshold": 10,
"flushThreshold": 3,
"maxReplayChars": 60000
}
}
}
}
}
```
- `agents` — agent ids whose main sessions are tracked.
- `turnThreshold` — turns per session between reflections.
- `flushThreshold` — minimum unreflected turns for a flush reflection when a
session ends or resets.
- `maxReplayChars` — transcript tail cap (characters) replayed to the fork.
## Reflection contract
The fork's instructions are ported from
[NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent)'s
combined background review prompt, adapted for OpenClaw:
- memory updates are written with filesystem tools to the workspace daily
note (`memory/YYYY-MM-DD.md`) and `MEMORY.md` index;
- skill updates and new skills are filed as **`skill_workshop` proposals**
(applied only after owner approval), never written directly;
- the active-update stance is kept: the fork must make at least one memory
update or explicitly declare "Nothing to save.", user corrections and
frustration are first-class skill signals, and environment-dependent
failures, negative tool claims, transient errors, and one-off task
narratives are excluded from capture.
## Development
```bash
npm install
npm run check # biome lint + format
npm run typecheck
npm test # vitest
npm run build
```
Releases are cut by pushing a `v*` tag; CI builds, verifies the version
against `package.json` and `CHANGELOG.md`, packs the tarball, and attaches
it to a GitHub Release.
## License
MIT
tools
Comments
Sign in to leave a comment