snapshot: preserve central wiki state 2026-08-15 (7 modified + 1 new file)

2026-08-15 22:11:30 +08:00
commit 92e8028bb8
71 changed files with 9897 additions and 0 deletions
@@ -0,0 +1,90 @@
+---
+title: Hermes Tool Search
+type: system
+status: active
+created: 2026-07-25
+updated: 2026-07-25
+review_after: 2026-10-23
+verified_on: 2026-07-25
+version_applies_to: Hermes Agent on CT460
+confidence: high
+tags: [hermes, automation, system]
+sources: [live CT460 configuration and isolated CUA validation]
+---
+
+# Hermes Tool Search
+
+## Why it is enabled
+
+Hermes previously sent every external tool schema to the model on every turn.
+That used a large part of the context window before the conversation began and
+made compaction happen much sooner.
+
+Native Hermes Tool Search is now always on. Core tools remain immediately
+available. External tools are discovered only when they are relevant, then
+described and called through the Tool Search bridge.
+
+## Active configuration
+
+File: `/home/hermes/.hermes/config.yaml`
+
+```yaml
+tools:
+  tool_search:
+    enabled: "on"
+    threshold_pct: 10
+    search_default_limit: 5
+    max_search_limit: 20
+```
+
+`enabled: "on"` is the important setting: it makes Tool Search active on every
+request instead of waiting for the tool schemas to cross an automatic token
+threshold.
+
+## Verified result
+
+- 80 external tools were deferred in the production gateway.
+- Approximately 24,151 schema tokens were removed from the always-present
+  prompt.
+- 36 core or directly visible tools remained available.
+- Estimated fixed baseline fell from about 52,955 to 29,182 tokens, a reduction
+  of roughly 45%.
+- In an isolated Computer Use test, 53 tools were discovered and the
+  `health_report` search, description, and call all succeeded.
+- Native Tool Search tests passed: 39 tests.
+
+Tool Search can add a small discovery call when an external tool is first
+needed. It should not reduce answer quality: the model retains direct access to
+core tools and can search for specialized tools by name or purpose.
+
+## New tools and new skills
+
+New external tools are automatically included in Tool Search after their tool
+provider is loaded. They do not need to be manually assigned to a category.
+
+Skills use a separate discovery system:
+
+- `~/.hermes/skills/devops/my-skill/SKILL.md` is categorized as `devops`.
+- A skill directly under `~/.hermes/skills/` has no category.
+- The skill `name` and `description` come from YAML frontmatter in `SKILL.md`.
+- Directory additions are noticed automatically. An in-place edit may take up
+  to 30 seconds to appear because of the skill cache.
+
+Tool Search therefore does not decide skill categories. The first directory
+below `~/.hermes/skills/` does.
+
+## Rollback
+
+The pre-change configuration is preserved at:
+
+`/home/hermes/.hermes/backups/config.yaml.20260725-before-tool-search`
+
+Restore that file only if Tool Search causes a confirmed regression, validate
+the YAML, and restart `hermes-gateway.service`.
+
+## Related
+
+- [[systems/hermes-agent]]
+- [[systems/skills-index]]
+- [[concepts/tool-calling]]
+- [[runbooks/gateway-resource-resilience]]