9 · The Plugin System

plugins/, 351 files. This chapter covers how third parties extend the system without touching core code.

9.1 Three Discovery Sources

~/.hermes/plugins/     user-level    — applies to every project on this machine
./.hermes/plugins/     project-level — travels with the repo, shared by the team
pip entry points       package-level — pip install a package and it takes effect automatically

“pip entry points” are a standard Python mechanism: a package declares in its own metadata “I provide this kind of plugin,” and after installation the framework discovers it automatically, with no manual registration by the user.

9.2 What a Plugin Can Provide

plugins/
├── platforms/          22 chat platform adapters        → chapter 1
├── memory/             8 memory backends                → chapter 8
├── context_engine/     context engines                  → chapter 7
├── model-providers/    model providers                  → chapter 11
├── cron_providers/     scheduled-task providers         → chapter 12
├── kanban/             kanban collaboration             → chapter 10
├── browser/            browser automation
├── image_gen/          image generation
├── video_gen/          video generation
├── observability/      observability
├── dashboard_auth/     dashboard authentication
├── security-guidance/  security guidance
├── google_meet/        meeting integration
├── spotify/            music
├── teams_pipeline/     Teams pipeline
├── disk-cleanup/       disk cleanup
├── hermes-achievements/ achievement system
├── web/                web-related
├── plugin_storage.py   ★ persistent storage for plugins
└── plugin_utils.py     ★ plugin utility functions

Through a “context API,” a plugin registers three kinds of things with the system: tools, hooks, and CLI subcommands.

9.3 The Most Important Design Decision: “Stackable Capabilities” vs. “Mutually Exclusive Strategies”

Two places in the source make this constraint explicit:

// Context engine (chapter 7)
“Selection is config-driven: `context.engine` in config.yaml.
  Default is "compressor" (the built-in). Only one engine is active.”

// Memory provider (chapter 8)
“The MemoryManager enforces a one-external-provider limit to prevent
  tool schema bloat and conflicting memory backends.
  Only one external provider runs at a time.”

What happens if you don't make this distinction

9.4 Plugin Storage

plugins/plugin_storage.py

Plugins need to persist their own data (configuration, caches, state). The system provides a unified storage abstraction rather than letting each plugin decide where to write.

This solves three problems:

• Unified paths — backup, cleanup, and migration all have a single entry point (echoing backup_paths() from chapter 8)
• Isolation — plugins can't see each other's data
• Cleanup — uninstalling a plugin can remove all of its data cleanly

9.5 How Plugins Tie into Toolsets

Recall the toolset resolution functions from chapter 4:

def _get_plugin_toolset_names() -> Set[str]        # toolsets provided by plugins
def _get_registry_toolset_aliases() -> Dict[str, str]
def resolve_toolset(name, visited=None, *, include_registry: bool = True)

A plugin doesn't just “register a few tools”; it can register an entire toolset. That way a user can write toolsets: [my_plugin_set] in their config to enable everything the plugin offers, without listing tool names one by one.

That include_registry parameter tells you something: the system distinguishes “built-in toolsets” from “toolsets in the registry (including plugins')”, and in some scenarios it can resolve only the built-in ones — presumably so things still work before plugins have finished loading, or to exclude third-party tools in security-sensitive contexts.

9.6 Plugin Hooks

Plugins can hook into several key points in the system:

The permission gap between pre_llm_call and select_context

9.7 MCP: The Other Extension Path

Besides plugins, Hermes also supports MCP (Model Context Protocol) — an open standard for connecting agents to external tool services.

tools/mcp_tool.py       378 KB    MCP client
mcp_serve.py            38 KB     ★ exposes Hermes itself as an MCP server
optional-mcps/          65 files  built-in optional MCP servers

The mcp_serve.py entry deserves attention: Hermes can expose itself as an MCP server. In other words, another agent can call Hermes as a tool — which makes “agents calling agents” possible.

9.8 The Overall Shape of This Extension System