Hermes Local Knowledge

Goal

Hermes Local Knowledge is a reusable Hermes Agent plugin that routes a local question to the whole artifact the agent should inspect first: a skill, support document, script, runbook, cron job, MCP server, or generated tool routing note.

It is an artifact router, not chunk RAG. Search results are routing hints; the agent should still read the selected source before acting.

Unquoted searches recognize narrow artifact-type nouns only when a query ends in one unambiguous type noun and includes at least two high-signal terms: runbook, skill, doc/document/documentation/reference, and memory (including their exact plural forms) join the existing script, cron/job, and MCP/wrapper intent. At most one fully matching artifact family is promoted. The exact target must carry a complete configured entity label in its own ID, title, or path and must match a distinct operation/topic term; body-only mentions and evidence from support siblings do not qualify. Eligibility is resolved across the complete current index, then one stable move keeps an owning skill adjacent to a promoted support document without reordering unrelated results. Topic-only, mixed, underspecified, ambiguous, or conversational uses of those nouns retain baseline ranking exactly. Quoted searches, explicit type filters, script-reference protection, skill-parent lifting, and support-document diversity retain their normal behavior.

Sources

source_root is the curated local tree to index. $HERMES_HOME remains a separate runtime source for skills, cron jobs, and MCP configuration.

| Artifact type | Source | | --- | --- | | skill | SKILL.md files under configured custom_skill_dirs, plus $HERMES_HOME/skills | | skill_support_doc | Markdown support files under custom skills and runtime skill references/, templates/, scripts/, and assets/ directories | | script | Supported script files under configured script_dirs | | memory_doc, runbook, doc | Markdown under source_root when include_markdown_docs is enabled; configured memory/runbook directories determine the type | | cron_job | $HERMES_HOME/cron/jobs.json | | mcp_server | $HERMES_HOME/config.yaml entries under mcp_servers or the accepted mcp.servers form | | tool_okf | Validated generated notes under <state_dir>/okfs/tools/*.md |

Built-in excluded directory names are .archive, .git, .mypy_cache, .pytest_cache, .venv, .worktrees, __pycache__, htmlcov, logs, node_modules, venv, and worktrees. exclude_dir_names adds deployment-specific exclusions.

Five tools

The plugin registers these native tools in the local_knowledge toolset:

| Tool | Purpose | | --- | --- | | knowledge_search | Find likely artifacts by intent, with an optional type filter and forced rebuild. | | knowledge_get | Fetch one artifact by ID, optionally with graph neighbors. | | knowledge_neighbors | Traverse conservative graph edges for an artifact. | | knowledge_feedback | Record local lookup feedback such as useful, missing, stale, or wrong_artifact. | | knowledge_usage_report | Summarize local usage, failures, zero-result queries, and feedback. |

Native tool responses are intentionally model-facing and concise. Search, get, and neighbor calls return only routing metadata needed to choose or inspect the next artifact, plus actionable warnings or rebuild state when present. Internal trigger vocabularies, index/configuration diagnostics, hashes, counts, and local database paths remain available to the service, CLI doctor, and local telemetry but are not serialized into routine agent context. The usage-report tool similarly returns a compact improvement-oriented projection rather than the complete telemetry schema.

The plugin registers pre_llm_call, on_session_end, and on_session_finalize hooks. On official Hermes v2026.9.14 and newer, public tool_execution middleware captures tool completions into a bounded plugin-owned serial observer while tools remain parallel. Older hosts retain a warned, best-effort post_tool_call fallback; the two transports are never registered together. See observer transport, lifecycle fences, privacy and loss limits. When the configured source is available, Hermes hosts with cache-safe plugin prompt sections add one concise system-prompt hint for each new session: use knowledge_search before broad file search for local Hermes/homelab artifacts, then verify live state directly. Older hosts use the same hint through a deduplicated pre_llm_call compatibility fallback. In either case, pre_llm_call continues to bind optional same-turn implicit search-result feedback; the remaining lifecycle hooks support exact successful consumption through knowledge_get, skill_view, or read_file plus tool-OKF capture/generation while keeping correlation inside the plugin when Hermes dispatches local-knowledge tools through its deferred-tool bridge.

Implicit feedback is enabled by default. It learns a local routing hint when the same artifact is consumed after distinct matching searches, with each supported consumer tied to that search's unassisted baseline in the same Hermes session, task, and turn:

local_knowledge:
  implicit_feedback:
    enabled: true
    min_confirmations: 2
    max_generic_queries: 5

Only a recent search from the same Hermes session, task, and turn is eligible. skill_view and read_file must run in a later model request, after the search result is available, and count only when their successful result resolves by canonical source path to exactly one baseline artifact in the same current index snapshot. Repeated consumption from one search is deduplicated, and overly generic artifacts stop receiving implicit promotion. Explicit feedback remains authoritative, and implicit evidence is not used as evaluation ground truth.

Install and model-token notice

Install and enable the directory plugin:

hermes plugins install https://github.com/stepanov1975/hermes-local-knowledge.git --enable

An SSH URL is also supported on hosts with GitHub SSH access:

hermes plugins install git@github.com:stepanov1975/hermes-local-knowledge.git --enable

The Python package exposes the local_knowledge = hermes_local_knowledge.plugin entry point for environments that install plugins into Hermes' Python environment.

If updating to v0.4.14 caused Hermes' plugin scan to disable the plugin, update to v0.4.15 and then re-enable the reviewed plugin once:

hermes plugins update local_knowledge
hermes plugins enable local_knowledge

Automatic tool-OKF generation and token use

Existing-artifact lookup works without model calls. local_knowledge.okf.auto_generate defaults to true because generated routing notes significantly improve future tool discovery.

Installers and agents should tell users that automatic generation:

• a detached worker invokes the active Hermes model and consumes additional model tokens;
• one worker claims at most max_candidates_per_session candidates (default 2) and makes at most one structured batch call when new content must be authored;
• max_generation_seconds is passed as the provider-request timeout, while provider retry/fallback policy can extend total elapsed time and token use behind that host call;
• session finalization does not wait for generation.

Users who do not want the additional model calls can disable automatic generation while retaining existing lookup and manual OKF management:

hermes config set local_knowledge.okf.auto_generate false

Generated tool notes use Open Knowledge Format v0.2 concept metadata (type plus structured generated.by/generated.at provenance). When automatic generation is enabled, the same bounded worker opportunistically claims completed generator-v3 notes and converts their deterministic frontmatter to v0.2 without a model call, preserving the existing routing content and generation timestamp. A legacy note that cannot be converted losslessly falls back to normal model-backed regeneration.

Install the proactive router skill

The per-turn hook makes the primary search tool discoverable without loading a full routing skill. The bundled skill adds the detailed search/fetch/inspect workflow, freshness guidance, and feedback procedure:

hermes local-knowledge install-router-skill --json

installed and current are successful statuses. A different existing skill produces conflict; review it before choosing --force.

To use an intentionally customized proactive skill instead, configure its deployed runtime path before running doctor or installer commands:

local_knowledge:
  router_skill_path: skills/note-taking/local-knowledge-router/SKILL.md

Relative paths resolve from $HERMES_HOME. The path must name an active SKILL.md under $HERMES_HOME/skills; that runtime path may be a symlink to a separately managed custom-skill repository. Doctor validates the skill's frontmatter name but does not require custom content to match the bundled copy. Invalid or missing configured custom skills appear as explicit doctor warnings while doctor retains its diagnostic-success exit status; the installer fails without modifying the configured target. install-router-skill, including --force, returns current with router_skill_mode: custom and does not overwrite a valid configured custom skill.

From a source checkout before plugin CLI registration is available:

python -m hermes_local_knowledge.cli install-router-skill --json

The plugin also exposes the same file as local_knowledge:local-knowledge-router for explicit skill_view(...) loads. That namespaced copy is not a substitute for installing the normal proactive skill. After installing or changing the skill, run /reload-skills and start a new/reset session, or start a fresh Hermes session.

Configuration

Put non-secret settings in $HERMES_HOME/config.yaml:

local_knowledge:
  source_root: ~/repos/local-operations
  state_dir: ~/.hermes/local_knowledge
  # Optional: use a deployed custom proactive skill instead of the bundled copy.
  # router_skill_path: skills/note-taking/local-knowledge-router/SKILL.md
  custom_skill_dirs: [custom_skills]
  script_dirs: [scripts, hermes_home/scripts]
  memory_dirs: [memory]
  runbook_dirs: [docs]
  include_markdown_docs: true
  exclude_dir_names: [build, dist]
  known_entities: [Hermes, GitHub, MCP, Cron]
  okf:
    enabled: true
    auto_generate: true  # uses additional model tokens in a bounded background worker
    max_candidates_per_session: 2
    max_generation_seconds: 120
    min_use_count: 1

Canonical settings, aliases, and defaults:

| Canonical setting | Accepted alias/override | Default | | --- | --- | --- | | source_root | root; LOCAL_KNOWLEDGE_ROOT overrides config | $HERMES_HOME | | state_dir | index_dir; LOCAL_KNOWLEDGE_STATE_DIR overrides config | $HERMES_HOME/local_knowledge | | hermes_home | HERMES_HOME; explicit CLI --hermes-home selects a profile | Active Hermes home, otherwise ~/.hermes | | router_skill_path | — | $HERMES_HOME/skills/local-knowledge-router/SKILL.md; an explicit relative path resolves from $HERMES_HOME and selects custom-skill validation | | custom_skill_dirs | — | [custom_skills] | | script_dirs | — | [scripts, hermes_home/scripts] | | memory_dirs | — | [memory]