Hermes Insight

Hermes Insight is the missing cognition layer for tool-using agents: durable structure, not just chat history. Agents encode situations as patterns, match them multi-lens, name the controlling lever, bind lived events to rules, and reinforce what actually worked — so the next session does not rediscover the same failure.

Standalone Python library + CLI. Zero cloud dependency. Optional native plugin and skill for Hermes Agent.

Not an official Nous Research product. Independent open-source companion for the Hermes community. Hermes® / Hermes Agent are trademarks of their respective owners.

Quick Install

Library + CLI

git clone https://github.com/PabloTheThinker/hermes-insight.git
cd hermes-insight
python3 -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

Optional environment:

export HERMES_INSIGHT_DB=./my-insight.db
export HERMES_INSIGHT_AGENT_ID=default

Hermes Agent plugin (any seat)

./scripts/install_for_hermes.sh

# Named agent / profile:
HERMES_HOME=~/.hermes/profiles/myagent \
  ./scripts/install_for_hermes.sh --agent myagent --tier worker

Then reload Hermes so insight_* tools appear. The installer merges hermes-insight into plugins.enabled — it does not wipe your existing plugin list.

Getting Started

30-second ability

hermes-insight bootstrap
hermes-insight perceive "two workers share one bot token; long-poll conflicts" \
  -o "409 from getUpdates" --log
hermes-insight observe environment --root .
hermes-insight plan "stabilize the duplicate-consumer failure" \
  -o "409 from getUpdates"
hermes-insight learn --min-support 3       # inspect recurring typed workflows

from hermes_insight import HermesInsight

lat = HermesInsight(db_path="./my-insight.db")
lat.bootstrap()
card = lat.perceive(
    "two workers share one bot token; long-poll conflicts",
    observations=["409 from getUpdates"],
    log_experience=True,
)
print(card["card"])
print(card["action_hint"], "usable=", card["usable"])

CLI cheatsheet

hermes-insight bootstrap              # seed agent-field starter rules
hermes-insight perceive "situation" -o "fact" --log
hermes-insight recall "query"
hermes-insight hygiene                # decay fabric noise + densify links
hermes-insight stats
hermes-insight forge                  # maps / playbooks from the lattice
hinsight perceive "…"                 # short alias

Default agent loop

observe env → perceive → plan? → task open → typed events → task close → learn
    │           │          │         │             │              │         │
 current     lever/rule   route   boundary      evidence       credit   recurrence

New agents: read the Agent Guide once — ontology, pipeline, doctrine, install, examples, anti-patterns.

Why this exists

Language models are strong at next-token reasoning and weak at durable structural memory:

Foundation pipeline:

encode → match → link → distill → perceive → reinforce

How it works

Foundations

1. Pattern lattice — SQLite + FTS5 graph of rules, skills, events, tasks, tools, agents, synthesis nodes
2. Hybrid match — template · prototype · feature · IDF, with structural kind priors (rules up, bare filenames down)
3. Candidate pool — FTS + structural shortlist so large fabric dumps stay fast
4. Distill — controlling variable (lever), refined from strong top matches
5. Experience layer — events / episodes / tasks with instance_of, experienced_as, next links
6. Starters — bootstrap agent-field priors (credentials, cache, isolation, retry storms, skill routing, mesh/DNS, …)
7. Hygiene — decay unused fabric; densify links; weaken session-auto noise
8. Experience-grounded planning — rank workflows from relevance + explicitly attributed task outcomes
9. Native observation layer — provenance-rich events and metadata-only workspace snapshots, with no AgentDrive dependency
10. Evidence-gated induction — repeated ordered workflows become reviewable sequence candidates only after independent task support

Perceive card (what you act on)

1. usable — if false, gather concrete observations; do not invent root cause
2. lever — variable to measure and intervene on
3. Top rule + action_hint — operational next step
4. Lived echoes + hops — prior events and related nodes

Privacy model

• Local SQLite only; one DB per trust boundary (house ≠ client)
• Scrubber redacts secret-shaped strings; skips .env-class paths on ingest
• Session hooks log failed/interrupted turns only — not every completed chat
• Public trees must pass scripts/check_isolation.sh
• Full policy: SECURITY.md

Hermes Agent integration

Optional SOUL / system fragment:

## Pattern recognition (Hermes Insight)
Default tool: insight_perceive. Before hard debugging or architecture, perceive.
If usable, act on lever + top rule + action_hint. Log meaningful scenes (log=true).
Use insight_task for multi-step work. If usable is false, gather observations first.
Separate Insight DBs per trust boundary. Never store raw credentials.

Config sketch:

plugins:
  enabled:
    - hermes-insight          # among your existing entries
  entries:
    hermes-insight:
      agent_id: myagent
      agent_tier: worker      # worker | conductor | client | …
      db_path: /path/to/myagent.insight.db

Env overrides: HERMES_INSIGHT_DB, HERMES_INSIGHT_AGENT_ID, HERMES_INSIGHT_AGENT_TIER.

Documentation

Development

pip install -e ".[dev]"
pytest -q
bash scripts/check_isolation.sh
python3 scripts/production_e2e.py

Requires Python 3.10+. Core runtime dependencies: none beyond the standard library (+ pytest for dev).

Status

0.8.x — production-shaped alpha for companion use:

• perceive ability and experience layer
• plan ability with explicit applied-pattern outcome attribution
• typed events and environment snapshots that ground plans in current workspace state
• recurring workflow induction with distinct-task support, Wilson confidence, retained failures, and no automatic skill writes
• Structural match priors and candidate-pool performance
• Mesh/network starters and session-noise hygiene
• Any-agent install path and public isolation gate

See CHANGELOG.md and Releases.

Contributing

Issues and PRs welcome. Please:

1. Keep the public tree free of operator/host fingerprints (bash scripts/check_isolation.sh)
2. Add or update tests for behavioral changes
3. Prefer skills and docs over one-off prose

Details: CONTRIBUTING.md.

License

MIT © Pablo Navarro

Related

• Hermes Agent — the agent runtime this companion targets
• Hermes Agent docs — official documentation
• agentskills.io — open skill standard (skill packaging compatible in spirit)