operations

name	operations
description	Hermes self-improvement plugin（`hermes-self-improvement`）の設計・実装・検証・運用に使う bundled operational skill。runtime hook、telemetry、evidence、runner、scorer/evaluator calibration、安全な skill/memory 改善を扱うときに読む。

hermes-self-improvement operations

Hermes の skill / memory / scorer / evaluator を改善するための user plugin を扱う operational index。詳細な設計や roadmap は repo-tracked docs / .hermes/plans/ に置き、この skill は毎回必要な判断だけを短く保持する。

まず守ること

• Hermes 本体や upstream-managed code を直接編集しない。plugin 内で解決する。
• Runtime hook は観測専用。hook 内で LLM、GEPA optimizer、skill patch、memory edit、重い集計を実行しない。
• Primary CLI / tool surface は improve, calibrate, report, status の4つ。
• improve と calibrate は default mutation-capable。preview-only は --dry-run。
• plan, apply, rollback, outcome / record_outcome, --execute, item/hash 指定 flag は primary surface に戻さない。
• 改善対象は skill, memory, scorer, evaluator だけ。runtime config、prompt policy、tool policy、任意 docs/config、Hermes core へ広げない。
• Curator telemetry（skill usage / lifecycle / pinned / archive state）は Curator を source of truth にし、plugin hooks で重複収集しない。
• Plugin hooks は Curator が持たない情報だけを集める: tool failure context、memory operation/failure、user correction/session outcome、subagent outcome、LLM/API failure metadata。
• improve は Curator/Hermes telemetry を skill candidate source-of-truth として使う。運用時は built-in Curator を disabled にせず paused にする。paused でも telemetry / lifecycle state は読み、mutating improve は Curator と同じ automatic lifecycle transition を最初に実行してから telemetry を読むことがある。
• Skill mutation は local mutable active/stale Hermes-created skills のみを対象にし、skill_manage など公式 skill tools だけで実行する。pinned / archived / built-in / bundled / hub-installed / plugin-bundled / external-dir / ambiguous provenance は LLM-facing candidate list にも載せず、artifact に除外件数・理由だけ残す。Curator に直接 attach できない evidence は context window 付き candidate として残す。Evidence pack は inventory health、memory duplicate/stale pair、Hermes-created stale singleton、coverage gap candidate を持てる。Target resolver は attachment-only で attach_existing_skill / memory_candidate / unresolved / skip_noise の4分類だけを返し、single visible target は generic failure の attach 根拠ではなく negative-fit signal として扱う。Planner は patch_skill / merge_skills / archive_skill / create_skill を必要に応じて選び、Dry-run summary は recommendation に加えて knowledge maintenance の代表テーマを短く出す。観測から新規 skill が必要だと planner が判断した場合でも、durable procedural workflow かつ既存 Hermes-created skill に改修・統合先がないときだけ skill_manage(action="create") 経由で作成できる。direct filesystem fallback は使わない。
• Archived skills は通常の candidate / duplicate-prevention / restore candidate として使わない。Curator behavior に合わせる。
• Memory mutation は memory tool / provider-native memory tool だけで実行する。evidence-triggered related-memory recall/search context は使うが、built-in memory files、provider DB、provider internals を直接編集しない。CLI/standalone 実行でも公式 tools.memory_tool.MemoryStore を load して memory_tool(..., store=store) を呼ぶ。Conversation-derived memory gap 抽出では既存 built-in memory の compact entry を digest に渡し、抽出後にも類似チェックで duplicate add を skip、関連 stale fact を replace に寄せる。USER/MEMORY/Skill の置き場所も LLM-facing inventory evidence として扱い、USER=好み/会話スタイル/期待値、MEMORY=環境事実/規約/学んだこと、Skill=手順/workflow という公式境界を渡す。clear な USER↔MEMORY move は add-before-remove で実行し、曖昧なら defer。明白な stale memory pair は既存 memory inventory planning に memory_replace hint として流し、曖昧・不確実・temporary・secret っぽい pair は defer に留める。raw terminal/search output は memory にしない。full memory lifecycle / sweep はしないが、built-in memory add が容量上限で失敗した場合は公式 tool の current_entries を入力に、最大3件の replace/remove compaction を試してから add を再試行する。それでも満杯なら active external provider が expose する tool にだけ fallback する。外部 provider はユーザーごとに異なるため、Hindsight 固定にしない。Conversation-derived memory gaps are first-class candidates; filters may rank candidate windows, but must not be hard gates for semantic value.
• Rollback は primary feature ではない。失敗や誤変更は future evidence として次の improvement run で correction する。Curator-style archive restore は別扱い。
• Scorer/evaluator self-improvement は prompt / rubric / runtime-private eval cases が対象。Python implementation code は自己変更しない。Repo base prompt は hermes_self_improvement/prompts.py の薄い kernel（schema / allowed action/tool / hard safety boundary）に留め、厚い planner/editor/evaluator guidance は ${HERMES_HOME:-~/.hermes}/self-improvement/evaluator/ の runtime-private overlay を正本にする。defaults/prompt-overlays/*.md は setup 用 seed で、GEPA/DSPy は runtime overlay を改善する。overlay は role ごとに 150 行 / 12000 文字まで。
• improve は skill / memory 変更を episode として append-only に記録する。calibrate は rolling window（既定30日）で観測を見直し、明示的に紐づく observation だけを outcome scoring に使う。unmatched observation は artifact に残し、弱・中・強の材料分類と繰り返し失敗の runtime eval case 化に使う。improve run artifact に unmatched candidates や conversation memory gaps が残った場合も、overlay calibration 用の runtime-private eval cases にできる。
• DSPy/GEPA は hook / plugin discovery path では lazy import を維持し、Hermes runtime 全体の必須依存にしない。
• Proposal scoring は llm（既定）または heuristic のみ。scoring は advisory で、無人変更の許可として扱わない。GEPA/DSPy は calibrate で evaluator / prompt / rubric 改善に使う。
• Model routing は current schema の model.planner（proposal/evidence planning）、model.editor（mutation agent）、model.evaluator（DSPy/GEPA evaluator calibration）だけを使う。旧 role key は残さない。
• 変更前に git status --short と対象 diff を確認し、無関係な変更を巻き戻さない。

主要パス

• plugin.yaml: plugin manifest / exposed tools
• __init__.py: root thin plugin entrypoint
• hermes_self_improvement/schemas.py: plugin tool schemas
• hermes_self_improvement/tool_handlers.py: CLI parity tool handlers。wrapper CLI に shell out せず core function を使う
• hermes_self_improvement/cli.py: CLI parser、report rendering、runner orchestration
• hermes_self_improvement/observer.py: hook observer、redaction、JSONL telemetry
• hermes_self_improvement/evidence.py: event aggregation / evidence extraction / context-windowed unmatched candidates
• hermes_self_improvement/target_resolver.py: LLM target resolution digest / normalization
• hermes_self_improvement/conversation_memory.py: conversation window ranking and memory gap candidates
• hermes_self_improvement/calibration.py: calibration evidence、outcome prepass、regression-gated active evaluator promotion
• hermes_self_improvement/runtime_eval_cases.py: runtime-private eval case builders for episodes, unmatched observations, and improve run artifacts
• hermes_self_improvement/outcome_observer.py: calibrate 前処理で outcome observation を生成する lightweight producer
• hermes_self_improvement/mutation_policy.py: provider-aware memory mutation policy / context builders
• hermes_self_improvement/mutation_worker.py: tool-mediated mutation executor
• evals/proposal/: repo-tracked public evaluator regression seed。user-specific runtime eval cases はここに混ぜない
• skills/operations/SKILL.md: この bundled operational skill

Runtime artifact は ${HERMES_HOME:-~/.hermes}/self-improvement/ 配下。主な subdir は state/, daily/, runs/, evidence/, ledgers/, evaluator/, cache/。evaluator/ は evaluator state、active-prompts.json、role-level prompt-candidates/、prompt candidate sets、runtime eval cases、default asset copy を置く場所で、GEPA はその中の optimizer 実装の一つとして扱う。

日常コマンド

bin/hermes-self-improve setup --check
bin/hermes-self-improve status
bin/hermes-self-improve report --since-hours 24 --json
bin/hermes-self-improve improve
bin/hermes-self-improve improve --dry-run
bin/hermes-self-improve calibrate
bin/hermes-self-improve calibrate --dry-run
bin/hermes-self-improve calibrate --from-candidate-set /path/to/candidate-set.json

Primary plugin tools:

self_improvement_status
self_improvement_report
self_improvement_improve
self_improvement_calibrate

変更時の進め方

1. README.md, AGENTS.md, 関連 reference、該当 repo-tracked plan を読む。
2. 新しい runner / proposal scoring / mutation 挙動は TDD で fail-closed を先に固定してから実装する。
3. Hook path を触る場合は、redaction・retention・partial event filtering が壊れないか確認する。
4. Proposal scoring / evaluator path を触る場合は、advisory-only と runtime-private eval cases を崩さない。
5. Tool handler / schema を触る場合は、plugin.yaml, schemas.py, tool_handlers.py, registration、tests/test_plugin_tools.py を同時に更新する。
6. __init__.py / registration / bundled skill discovery を触ったら、unit test だけでなく plugin manager loading も確認する。
7. 実 mutation step を追加するときは、skill は official skill tools、memory は memory/provider tools だけに閉じる。

検証 checklist

通常変更後:

PY=${PYTHON:-.venv/bin/python}
$PY -m py_compile __init__.py hermes_self_improvement/*.py
$PY -m pytest tests -q
bin/hermes-self-improve status

Registration / tool surface 変更後:

PY=${PYTHON:-python3}
$PY - <<'PY'
from hermes_cli.plugins import discover_plugins, get_plugin_manager
import json

discover_plugins(force=True)
info = [p for p in get_plugin_manager().list_plugins() if p['name'] == 'hermes-self-improvement']
print(json.dumps(info, ensure_ascii=False, indent=2))
PY

Expected: enabled true, error null, tools 4。

Pitfalls

• Evidence skill target names may be bare (skill-name) or qualified (dir-name:skill-name). Resolve exact qualified Curator candidate matches first; otherwise fall back to bare-name matching and attach evidence to every mutable candidate with that bare name so the mutation agent can decide. Do not hardcode a user-specific prefix such as hermes-custom:.
• Planner quality should be evaluated from proof counts, not selected count alone. Watch attached_candidate_count, unmatched_evidence_count, selected_with_evidence, action_like_skips, target-hint attachment counts/match kinds, evidence-strength counts, weak_only_selected_count, cluster evidence counts, editor prompt chars, and planner/editor prompt source/hash in dry-run output/artifacts. If target hints attach nearly everything, inspect match kinds and strength before trusting the planner selection.
• Agent tool handlers must not return full run/calibration payloads. Return compact summaries with artifact paths; keep full payloads in runtime artifacts or CLI --json only. self_improvement_improve should return counts/status, semantic action_summary / actionable buckets (apply / defer / skip / block), prompt source/hash metadata, artifact_path / full_payload.path, and short next actions. self_improvement_calibrate should expose components.prompt_overlay_set, components.evaluator, overlay_candidate_set, and full_payload.path. Never include full evidence, planner decision bodies, editor instructions, full prompt text, role-level prompt_overlays, or prompt candidates in tool results.
• Native mutation editor follow-up messages must avoid role: tool; some auxiliary/provider paths reject it with Invalid value: 'tool'. Execute tools inside the plugin, then feed compact tool results back as ordinary user-role context.
• root 直下に tools.py や tools/ package を置かない。Hermes core tools.registry を shadow する。
• Plugin-bundled skills は repo file として編集する。skill_manage で plugin-bundled skill を編集しない。
• importlib.util.module_from_spec で unit test する場合は、exec_module 前に sys.modules[spec.name] = module を入れる。
• Runtime code で relative import を含む plugin module を読む場合は、file-location spec の単体名で exec_module しない。importlib.import_module("hermes_self_improvement.<module>") など package context 付きで読む。単体名だと from .prompts ... が attempted relative import with no known parent package で落ちる。
• DSPy/GEPA evaluator tests は基本 fake dependency で書く。runtime hook / normal import が dspy を eager import しないことを守る。