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_hermes is enforced by the loader).
• Desktop app for the banner; the hooks and /ysknow also 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-owned ctx.llm lane, 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_requests provider round-trips (default 2), then at most one review per min_seconds_between_reviews (45 s) and max_reviews_per_turn (4). A final review fires on turn end when the reply is longer than min_turn_end_chars (400).
• Side agent: ctx.llm.complete_structured, the user's active provider/model, no tools, transcript capped at max_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.