hermes-web-ui/docs/planning/learn-command-integration.md

/learn Command Web UI Integration Plan

Date: 2026-06-25

Context

Hermes Agent added a /learn slash command that turns a user-described source or recent workflow into a reusable Hermes skill. The command does not use a separate model or learning engine. It builds a standards-guided prompt with agent.learn_prompt.build_learn_prompt() and submits that prompt through the normal agent loop.

Web UI chat sessions use the local bridge run path instead of always going through the upstream CLI or gateway slash-command handler. For a reliable user experience, Web UI should explicitly recognize /learn and expand it through the bridge command path before running the generated prompt.

Goals

• Let users type /learn <source or workflow> in a normal Hermes chat session.
• Show /learn in the chat input slash-command picker.
• Run the prompt generated by Hermes Agent's build_learn_prompt() as the real agent input.
• Preserve the visible transcript as a command invocation, not as the expanded internal prompt.
• Support bare /learn as "learn from this conversation".
• Fail clearly when the bundled/runtime Hermes Agent version does not provide agent.learn_prompt.

Non-Goals

• Do not add a dedicated model, provider, or auxiliary model for /learn.
• Do not create a new Web UI page for skill creation.
• Do not duplicate Hermes Agent's skill-authoring prompt in TypeScript.
• Do not treat /learn as memory, fine-tuning, or persistent model training.

Proposed Design

Server Bridge Command

Add /learn to the Web UI session-command layer:

• Extend CommandName in packages/server/src/services/hermes/run-chat/session-command.ts.
• Add learn to COMMAND_ALIASES.
• Handle command.name === "learn" similarly to /skill:
  • call the bridge command endpoint with /learn <args>;
  • expect a handled result with type: "learn" and a generated message;
  • enqueue or start a run with the generated message as the actual input;
  • keep the visible/display input as /learn <args>.

Python Bridge

Add support in packages/server/src/services/hermes/agent-bridge/python/bridge_pool.py:

• In dispatch_command(), recognize learn.
• Import build_learn_prompt from agent.learn_prompt.
• Return a handled bridge result:

{
    "session_id": session_id,
    "command": name,
    "handled": True,
    "type": "learn",
    "message": build_learn_prompt(arg),
}

If the import fails, return a clear unsupported-version message instead of silently passing /learn through as normal text.

Client Slash Picker

Update packages/client/src/utils/hermes/bridge-session-commands.ts:

• Add learn to BridgeSessionCommandName.
• Add a command definition with text args.
• Keep it as a bridge session command so the UI renders it as a command message.

Update all locale files under packages/client/src/i18n/locales/:

• Add chat.slashCommands.learn.
• Reuse the existing chat.slashCommandArgs.text placeholder unless a more specific placeholder is needed.

Runtime Compatibility

The feature depends on Hermes Agent containing agent/learn_prompt.py. Web UI should not copy the prompt text locally. The bridge should surface a clear error when the runtime agent is too old, for example:

/learn requires a newer Hermes Agent runtime with agent.learn_prompt.

This keeps the upstream agent as the source of truth for skill-authoring rules.

UX Notes

• Idle session:
  • user sees /learn ... as a command message;
  • assistant runs the generated skill-authoring prompt;
  • final answer should mention the created skill name and category, as directed by the upstream prompt.
• Running session:
  • /learn ... should queue like /skill and /plan;
  • queued item should display the original command, not the expanded prompt.
• Bare /learn:
  • should be accepted and should expand to the upstream fallback for the current conversation.

Tests

Add or update focused tests:

• Server:
  • parseSessionCommand("/learn from docs") returns a learn command.
  • idle /learn starts a run using the bridge-generated prompt.
  • running /learn queues the command like /skill.
  • missing agent.learn_prompt returns a clear error.
• Client:
  • slash picker includes /learn.
  • isKnownBridgeSessionCommand("/learn something") is true.
  • queued/running behavior displays /learn ..., not the expanded prompt.
• Harness:
  • Run the smallest relevant unit tests while iterating.
  • Run npm run harness:check before opening a PR.

Rollout

1. Land bridge command support and tests.
2. Update bundled/runtime Hermes Agent to a revision containing agent/learn_prompt.py.
3. Add the client slash-picker entry and locale strings.
4. Verify against a local chat session with:
   • /learn
   • /learn from docs/workflow.md
   • /learn the workflow we just performed

Open Questions

• Should /learn be available in workflow node chat drawers, or only normal Hermes chat sessions?
• Should Web UI refresh the skills list automatically after /learn completes?
• Should the skills page show a lightweight "created by /learn" marker if the upstream skill metadata exposes one later?