you-should-know
A Hermes Agent plugin: a side agent reads the conversation while Hermes works
and surfaces the one thing you might have missed — a tradeoff made without
calling it out, a result that looks off, an irreversible action, a silent
assumption — as a short, dismissible note above the prompt.
✦ Heads up · Migration dropped the old index; rollback now needs a rebuild.
Learn more Knew this already Dismiss
Silence is the default. A note is a rare event, not a turn summary.
Hermes adaptation of Claude Code's built-in cc-plugin-you-should-know mod
(independent implementation against the Hermes plugin API — no Claude Code code
is copied; see Provenance).
Requirements
- Hermes Agent >= 0.21.5 (
requires_hermesis enforced by the loader). - Desktop app for the banner; the hooks and
/ysknowalso work in the CLI and TUI. - A text model configured in Hermes — the plugin uses your active provider and
model and never handles credentials itself.
Install
From the Hermes plugin catalog:
hermes plugins install you-should-know
hermes plugins enable you-should-know
From a checkout of this repository:
hermes plugins install bonesnasty/you-should-know
hermes plugins enable you-should-know
Then let the running process pick it up:
- Agent half (hooks,
/ysknow): takes effect on the next session in each
process — the CLI, the desktop backend and the messaging gateway each load
plugins at their own startup. - Desktop half (the banner): reload the desktop plugin folder once —
Ctrl/Cmd+K → "Reload desktop plugins" — or restart Hermes. A folder created
while the app is running is not picked up automatically; existing folders
hot-reload on save.
Disclosure — what this plugin does to your machine
Required by the catalog's rule 13. Read this before installing.
- Network calls. Each review is exactly one LLM request through Hermes's
host-ownedctx.llmlane, sent to your configured provider and model. The
plugin makes no other network calls. There is no telemetry, no analytics and no
update checker. - What leaves the machine. A transcript excerpt — up to
max_transcript_chars(12,000 characters, newest messages kept) of user
messages, assistant messages, tool names/arguments and truncated tool results
— is sent to your provider for that single request. Treat it with the same
care as any message you send to that provider. - Cost. Every review spends your provider tokens. The plugin is throttled
(default: at most 4 mid-turn reviews per turn, one per 45 s, plus one end-of-
turn review for replies over 400 characters) and only runs on turns that used
tools. Messaging gateways are excluded by default (platforms: [desktop, cli, tui]) so a busy channel does not bill a review per message. - Local reads and writes. It writes notes, counters and per-session
bookkeeping to<HERMES_HOME>/plugin-data/you-should-know/state.json(last 50
notes, 40 sessions; atomic replace). It reads Hermes's own settings for this
plugin, read-only. It does not read your files,.env,auth.json, another
tool's credentials, or any credential store; Hermes attaches provider auth
itself and the plugin never sees a token. - Background work. Reviews run in daemon threads after the request, bounded
by a 60-second timeout. There are no shell commands, no subprocesses, no file
modification outside the plugin data directory, and no self-updating code;
updates arrive only through a reviewed catalog pin. - Desktop polling. While the Desktop app is open, the banner polls the
plugin's own backend route (/api/plugins/you-should-know/note) every 3
seconds. That is a loopback call to the Hermes process, not an external
request. - Failure mode. Every path is fail-open: an LLM error is counted
(/ysknow status,llm_errors) and never surfaces to the turn.
Pieces
| Path | Role |
|---|---|
plugin.yaml | Manifest + settings (all tunable without code). |
__init__.py | Hooks: pre_api_request (mid-turn reviews), post_llm_call (end-of-turn review), on_session_end (cleanup). Registers /ysknow. |
store.py | State shared by both halves — <hermes home>/plugin-data/you-should-know/state.json, lock + atomic replace. |
dashboard/plugin_api.py | /api/plugins/you-should-know/note, /note/{id}/dismiss, /status. |
desktop/plugin.js | Composer top banner + the three actions. |
dashboard/dist/index.js | Empty dashboard entry so discovery stays happy; no dashboard tab. |
Behaviour details
- Trigger: a turn with tool activity, at least
min_api_requestsprovider
round-trips (default 2), then at most one review permin_seconds_between_reviews
(45 s) andmax_reviews_per_turn(4). A final review fires on turn end when the
reply is longer thanmin_turn_end_chars(400). - Side agent:
ctx.llm.complete_structured, the user's active provider/model,
no tools, transcript capped atmax_transcript_chars(12k chars, newest kept). - Noise control: confidence floor
min_confidence(0.55), raised by 0.05 for
each consecutive "Knew this already" (cap +0.3); repeat/similar notes are
suppressed per session and against the last 30 minutes of notes. - Durability: a note survives restarts for
max_note_age_seconds(15 min) and
is returned for whichever session asks if no exact session match exists, because
hook session ids and UI runtime ids are not guaranteed to agree. - Failure mode: every path is fail-open. An LLM error is counted and never
surfaces to the turn.
Commands
/ysknow— show the open note/ysknow clear— dismiss it/ysknow on|off— toggle/ysknow status— counters
Settings
plugins.entries.you-should-know.settings.* — see config_schema in
plugin.yaml; the Desktop Settings → Plugins → You should know page renders a
form from it.
| Key | Default | Meaning |
|---|---|---|
enabled | true | Master switch (/ysknow off toggles it too). |
min_api_requests | 2 | Provider round-trips before the first review in a turn. |
min_seconds_between_reviews | 45.0 | Cooldown between reviews for one session. |
max_reviews_per_turn | 4 | Hard cap on mid-turn reviews. |
min_confidence | 0.55 | Below this, a candidate note is dropped. |
max_note_age_seconds | 900.0 | How long an undismissed note keeps showing. |
max_transcript_chars | 12000 | Transcript budget handed to the side agent. |
review_on_turn_end | true | Run one final review when a tool-using turn ends. |
min_turn_end_chars | 400 | Skip the end review for shorter replies. |
platforms | [desktop, cli, tui] | Surfaces that get a banner. |
Provenance
Original concept and prompt shape: Anthropic's cc-plugin-you-should-know
(ships with Claude Code, off by default, enabled with
/plugin enable cc-plugin-you-should-know@builtin). This is an independent
implementation against Hermes' plugin API — no Claude Code code is copied.
README from the reviewed commit e100b4a; it updates when the author re-pins.

BonesNasty