hermes-agent/website/docs/developer-guide/memory-provider-plugin.md

sidebar_position, title, description

sidebar_position	title	description
8	Memory Provider Plugins	How to build a memory provider plugin for Hermes Agent

Building a Memory Provider Plugin

Memory provider plugins give Hermes Agent persistent, cross-session knowledge beyond the built-in MEMORY.md and USER.md. This guide covers how to build one.

:::tip Memory providers are one of two provider plugin types. The other is Context Engine Plugins, which replace the built-in context compressor. Both follow the same pattern: single-select, config-driven, managed via hermes plugins. :::

Installation Layouts

Hermes discovers memory providers from four sources, in this precedence order:

Source	Location	Notes
Bundled	plugins/memory/<name>/	Ships with Hermes. Closed to new providers — see CONTRIBUTING.
User	$HERMES_HOME/plugins/<name>/	Dropped in by the user, per profile.
Project	./.hermes/plugins/<name>/	Opt-in via HERMES_ENABLE_PROJECT_PLUGINS=1.
Package	hermes_agent.memory_providers entry point	Distribution supplied by the installation owner; nothing to copy.

Earlier sources win on a name collision, so a directory dropped into a working tree can never shadow a shipped provider.

:::note This is the reverse of the general plugin system's later-wins order. A memory provider is activated by name (memory.provider), so shadowing would silently redirect the agent's memory rather than merely override a tool. :::

Discovery only enumerates — it never imports a provider. Nothing runs until memory.provider names it.

Entry-point discovery does not install packages. Do not inject a provider into Hermes's selected environment with pip. On PM-managed installations, ship a directory provider with declared Python dependencies; plugin admission and hermes memory setup prepare them through PM before use. Owner-managed builds (such as Nix) can include an entry-point distribution declaratively.

CLI and dashboard setup share candidate preparation. PM includes the provider's pyproject.toml or legacy pip_dependencies / python_dependencies alongside the active plugin union; an importable module does not bypass declared version constraints. Dashboard readiness checks the same inputs without installing anything. A successful preparation may require restarting Hermes before the running process can use the selected dependency generation. External sidecar checks and setup commands remain separate from the Python union.

Directory Provider

A directory provider lives in plugins/memory/<name>/ when bundled with Hermes, in $HERMES_HOME/plugins/<name>/ when installed by a user, or in ./.hermes/plugins/<name>/ for a project-local one:

plugins/memory/my-provider/
├── __init__.py      # MemoryProvider implementation + register() entry point
├── plugin.yaml      # Metadata (name, description, hooks)
└── README.md        # Setup instructions, config reference, tools

Packaged Provider

A pip-installed provider publishes an entry point in the hermes_agent.memory_providers group. The entry-point name is the provider name users select in memory.provider; its value points to the provider's register(ctx) function:

[project.entry-points."hermes_agent.memory_providers"]
my-provider = "my_provider:register"

Point the entry point at the package, or at a register(ctx) inside it, and keep your implementation, skills, and other resources in the normal Python package layout. No copy under $HERMES_HOME/plugins/ is required.

A package entry point gets everything a directory install does, including the two files Hermes reads from disk rather than importing — config_schema.py (the dashboard config panel) and cli.py (your hermes <provider> subcommands). Both are found next to your package's __init__.py, so point the entry point at a package rather than a single module if you ship either.

The MemoryProvider ABC

Your plugin implements the MemoryProvider abstract base class from agent/memory_provider.py:

from agent.memory_provider import MemoryProvider
from agent.secret_scope import get_secret

class MyMemoryProvider(MemoryProvider):
    @property
    def name(self) -> str:
        return "my-provider"

    def is_available(self) -> bool:
        """Check if this provider can activate. NO network calls."""
        return bool(get_secret("MY_API_KEY"))

    def initialize(self, session_id: str, **kwargs) -> None:
        """Called once at agent startup.

        kwargs always includes:
          hermes_home (str): Active HERMES_HOME path. Use for storage.
        """
        self._api_key = get_secret("MY_API_KEY") or ""
        self._session_id = session_id

    # ... implement remaining methods

Initialization context

AIAgent passes session context through MemoryManager.initialize_all() to initialize(session_id, **kwargs). Accept **kwargs and tolerate missing optional fields; callers may initialize a provider without an agent or a session database.

Keyword	Meaning
hermes_home	Active profile's storage directory.
platform	Session surface, such as cli, gui, acp, or telegram.
session_title	Stored session title, when available. A display label is not necessarily a user-selected identity.
session_title_source	Stored title provenance, when available: derived, llm, or user. Automatic sources must not be mistaken for explicit identity overrides; missing provenance retains a provider's legacy behavior. Shared constants live in hermes_state_common.py.
cwd	Non-empty logical workspace supplied as AIAgent(cwd=...), available before provider initialization. Omitted for None or an empty string.
gateway_session_key	Stable messaging-chat identity for per-chat session isolation.
user_id, user_id_alt, user_name, chat_id	Gateway identity fields, included when present.
agent_identity	Active profile name, when available.
agent_workspace, agent_context	Runtime agent scope. agent_workspace is hermes; agent_context is cron for scheduler runs, subagent for delegate_task children, else primary — skip automatic writes for the non-primary values.

Do not assume os.getcwd() identifies the conversation's workspace: one Desktop or gateway backend can serve several sessions. If cwd is absent and directory routing is needed, agent.runtime_cwd.resolve_agent_cwd() honors the session cwd context, then scoped terminal.cwd (carried internally as TERMINAL_CWD), then the launch directory. Construction-time workspace metadata does not require changing the process cwd or rebuilding an existing conversation's system prompt.

Desktop/TUI workspace changes synchronize the live agent's session_cwd through tui_gateway/session_workdir.py::_register_session_cwd, including when a deferred agent is attached after a workspace move. This lets a first or restarted Codex app-server session use the current workspace instead of its construction-time cwd. It does not move an already-running Codex thread, reinitialize memory providers, change an existing Honcho session identity, or invalidate the cached system prompt. Provider initialization still receives the construction-time workspace; absent or empty cwd remains unpinned.

Required Methods

Core Lifecycle

Method	When Called	Must Implement?
name (property)	Always	Yes
is_available()	Agent init, before activation	Yes — no network calls
initialize(session_id, **kwargs)	Agent startup	Yes
get_tool_schemas()	After init, for tool injection	Yes
handle_tool_call(tool_name, args, **kwargs)	When agent uses your tools	Yes (if you have tools)

Config

Method	Purpose	Must Implement?
get_config_schema()	Declare config fields for hermes memory setup	Yes
save_config(values, hermes_home)	Write non-secret config to native location	Yes (unless env-var-only)

Optional Hooks

Method	When Called	Use Case
system_prompt_block()	System prompt assembly	Static provider info
prefetch(query, *, session_id="")	Before each API call	Return recalled context
queue_prefetch(query, *, session_id="")	After each turn	Pre-warm for next turn
sync_turn(user, assistant, *, session_id="", messages=None)	After each completed turn	Persist conversation
on_session_end(messages)	Conversation ends	Final extraction/flush
on_pre_compress(messages)	Before context compression	Save insights before discard
on_memory_write(action, target, content, metadata=None)	Built-in memory writes	Mirror to your backend
shutdown()	Process exit	Clean up connections

For native replace and remove, metadata["previous_content"] contains the full entry selected under the native-store lock. Notifications are emitted only after the complete write or batch succeeds. Batch notifications preserve operation order; each operation's previous content reflects earlier operations in that batch. old_text is the caller's search text, not the identity of the changed entry. Older Hermes versions can omit previous_content. Providers that require exact identity should skip destructive mirroring when it is absent.

Oversized prefetch results

External prefetch() results are returned in full by default, preserving the provider's relevance-ranked recall, up to a safety ceiling of 10× hooks.output_spill.max_chars (at least 100,000 characters) above which they still spill. Keep your own recall budget well under that. To opt into spilling oversized results for the active profile, set:

memory:
  prefetch_spill_enabled: true  # default: false

When enabled, results above the shared hooks.output_spill.max_chars threshold (default 10,000 characters) are written to a private spill file and replaced with the configured head/tail preview plus its path. The default preview keeps only the first and last 500 characters; the model must read the file to recover the middle. Results at or below the threshold remain unchanged.

The shared hooks.output_spill preview lengths and directory still apply, and hooks.output_spill.enabled: false disables spilling even with memory opt-in. Both settings are snapshotted when the external provider is registered; restart Hermes to apply changes to existing sessions. Built-in memory and normal plugin-hook spilling are unaffected. See Plugins — oversized-context spill.

Pre-Compress Checkpoints (fail-closed)

on_pre_compress() is best-effort by default: if your provider raises, the host logs the failure and compression proceeds. That is the right default for insight extraction — and the wrong one for a provider whose job is to archive transcript evidence to a durable store before the lossy rewrite. For that case the host offers an opt-in checkpoint contract (API v2):

from agent.memory_provider import MemoryProvider

class MyArchivingProvider(MemoryProvider):
    # Opt in: every successful on_pre_compress() return means the durable
    # checkpoint is committed. Raise on any failure — do not return partial
    # success. Version 1 (the inherited default) is the implicit historical
    # contract: best-effort semantics, raw message list.
    pre_compress_checkpoint_api_version = 2

    def on_pre_compress(self, messages, *, require_checkpoint=False):
        # require_checkpoint mirrors the operator's checkpoint_required
        # setting: True means a raise here blocks the lossy rewrite.
        ids = self._archive(messages)   # must be durable before returning
        return f"checkpoint: {ids}"     # forwarded into the summary prompt

Operators enable enforcement per deployment:

compression:
  checkpoint_required: true   # default: false

With the gate on, compression fails closed before any lossy rewrite unless an active provider advertising the API completed its checkpoint: the uncompressed transcript is preserved, the compaction attempt errors with BLOCKED_MISSING_PREREQUISITE, and it can be retried once your store recovers. With the gate off (default), nothing changes for existing providers.

None of the providers bundled with Hermes advertise checkpoint API v2 — the contract is opt-in and exists for third-party archiving providers. Enabling checkpoint_required without one therefore blocks every compression attempt (manual and automatic): agent init logs a warning naming the active provider, and each refusal names compression.checkpoint_required as the key to disable.

The gate binds to every compaction authority, not just the Hermes summarizer: server-side native compaction (compression.codex_responses_native) is suppressed while the gate is armed, post-turn micro-compaction (compression.micro_compact) is forced off at agent init (it absorbs old exchanges into a rolling summary with no checkpoint hook in its path), and the codex_app_server API mode is refused at agent init — the codex agent compacts its own thread with no truthful pre-compaction boundary, so a required checkpoint cannot be guaranteed there. The checkpoint-aware Hermes compressor stays the only lossy authority.

What your provider receives depends on its declared API version. Version 1 providers (the implicit default — every pre-existing provider) keep the historical contract: the raw message list, exactly as before. Version 2 checkpoint providers receive normalized direct evidence instead: user/assistant text rows only — tool results, system messages, the tool_calls payload of assistant messages (their prose is kept), and prior compaction summaries are filtered host-side. Prior summaries are recognized via a persistent _compressed_summary message marker that survives process restarts, so a resumed session never feeds derivative summaries back into your archive.

Checkpoints must be idempotent. After a fail-closed block, the next compaction attempt calls on_pre_compress() again with the same transcript — and a transcript that grew only slightly produces largely overlapping evidence. Key your archive writes by content (for example a transcript digest) and upsert, so retries and overlaps deduplicate instead of accumulating duplicate archives.

Contract tests: tests/agent/test_pre_compress_checkpoint_contract.py.

Setup UX — what a standalone provider keeps

Every setup surface Hermes gives a bundled provider is driven by files in the provider's own directory, so a provider installed from the plugin catalog keeps all of them:

Surface	What the provider ships
Desktop → Capabilities → Tools → Memory (config panel)	config_schema.py (below)
hermes memory setup wizard	get_config_schema() declares the fields the wizard prompts for, save_config(config, hermes_home) persists them, post_setup(hermes_home, config) runs afterwards for anything interactive (OAuth, first sync); get_status_config() feeds hermes memory status
hermes <provider> … subcommands	cli.py with register_cli(subparser) (Adding CLI Commands)
Python dependencies	pyproject.toml [project] dependencies (or python_dependencies in plugin.yaml); installed under Hermes' own pins at install time and re-applied across hermes update

Your provider's name, memory.<name> config section, data directory and tool names are the contract with existing users. A provider that moves out of core keeps all four; Hermes then installs the catalog plugin automatically for anyone whose memory.provider still names it (on hermes update, and once at agent start when security.allow_lazy_installs is on).

Config Schema

get_config_schema() returns a list of field descriptors used by hermes memory setup:

def get_config_schema(self):
    return [
        {
            "key": "api_key",
            "description": "My Provider API key",
            "secret": True,           # → written to .env
            "required": True,
            "env_var": "MY_API_KEY",   # explicit env var name
            "url": "https://my-provider.com/keys",  # where to get it
        },
        {
            "key": "region",
            "description": "Server region",
            "default": "us-east",
            "choices": ["us-east", "eu-west", "ap-south"],
        },
        {
            "key": "project",
            "description": "Project identifier",
            "default": "hermes",
        },
    ]

Fields with secret: True and env_var go to .env. Non-secret fields are passed to save_config().

:::tip Minimal vs Full Schema Every field in get_config_schema() is prompted during hermes memory setup. Providers with many options should keep the schema minimal — only include fields the user must configure (API key, required credentials). Document optional settings in a config file reference (e.g. $HERMES_HOME/myprovider.json) rather than prompting for them all during setup. This keeps the setup wizard fast while still supporting advanced configuration. See the Supermemory provider (a plugin catalog entry) for an example — it only prompts for the API key; all other options live in supermemory.json. :::

Save Config

def save_config(self, values: dict, hermes_home: str) -> None:
    """Write non-secret config to your native location."""
    import json
    from pathlib import Path
    config_path = Path(hermes_home) / "my-provider.json"
    config_path.write_text(json.dumps(values, indent=2))

For env-var-only providers, leave the default no-op.

Plugin Entry Point

def register(ctx) -> None:
    """Called by the memory plugin discovery system."""
    ctx.register_memory_provider(MyMemoryProvider())

A provider may also expose read-only skills from the same callback. Skills are qualified by the entry-point name and are loaded only when that memory provider is active:

from pathlib import Path

SKILLS_DIR = Path(__file__).parent / "skills"

def register(ctx) -> None:
    ctx.register_memory_provider(MyMemoryProvider())
    ctx.register_skill(
        "maintenance",
        SKILLS_DIR / "maintenance" / "SKILL.md",
        "Maintain the provider's memory store",
    )

With the my-provider entry point active, the skill is available as my-provider:maintenance through skill_view().

plugin.yaml

name: my-provider
version: 1.0.0
description: "Short description of what this provider does."
hooks:
  - on_session_end    # list hooks you implement

Threading Contract

sync_turn() MUST be non-blocking. If your backend has latency (API calls, LLM processing), run the work in a daemon thread — spawned with agent.memory_provider.spawn_context_thread, never a bare threading.Thread. Profile isolation (the active HERMES_HOME, the per-turn secret scope) lives in contextvars, and a plain thread starts with an empty context: under multiplexed profiles it would silently write into the default profile's store, and get_secret() fails closed there.

from agent.memory_provider import spawn_context_thread

def sync_turn(self, user_content, assistant_content, *, session_id="", messages=None):
    def _sync():
        try:
            self._api.ingest(user_content, assistant_content, session_id=session_id, messages=messages)
        except Exception as e:
            logger.warning("Sync failed: %s", e)

    if self._sync_thread and self._sync_thread.is_alive():
        self._sync_thread.join(timeout=5.0)
    self._sync_thread = spawn_context_thread(_sync, name="myprovider-sync")
    self._sync_thread.start()

The same applies to prefetch and writer threads. Small JSON config sidecars ($HERMES_HOME/<provider>.json) are read with utils.read_json_or_empty and written with utils.atomic_json_write; anything under config.yaml goes through hermes_cli.config.save_config(..., merge_existing=True).

messages is optional OpenAI-style conversation context as of the completed turn. When present, it includes user/assistant messages, assistant tool calls, and tool result messages. Providers that do not need raw turn context can omit the messages parameter; Hermes will continue calling them with the legacy signature.

Cloud providers should document what parts of messages are sent off-device. Tool calls and tool results may contain file paths, command output, or other workspace data.

Profile Isolation

All storage paths must use the hermes_home kwarg from initialize(), not hardcoded ~/.hermes:

# CORRECT — profile-scoped
from hermes_constants import get_hermes_home
data_dir = get_hermes_home() / "my-provider"

# WRONG — shared across all profiles
data_dir = Path("~/.hermes/my-provider").expanduser()

Testing

See tests/agent/test_memory_provider.py and adjacent memory tests (tests/agent/test_memory_session_switch.py, tests/agent/test_memory_user_id.py, tests/agent/test_memory_provider_init.py) for end-to-end patterns.

from agent.memory_manager import MemoryManager

mgr = MemoryManager()
mgr.add_provider(my_provider)
mgr.initialize_all(session_id="test-1", platform="cli")

# Test tool routing
result = mgr.handle_tool_call("my_tool", {"action": "add", "content": "test"})

# Test lifecycle
mgr.sync_all("user msg", "assistant msg")
mgr.on_session_end([])
mgr.shutdown_all()

Adding CLI Commands

Memory provider plugins can register their own CLI subcommand tree (e.g. hermes my-provider status, hermes my-provider config). This uses a convention-based discovery system — no changes to core files needed.

How it works

1. Add a cli.py file to your plugin directory
2. Define a register_cli(subparser) function that builds the argparse tree
3. The memory plugin system discovers it at startup via discover_plugin_cli_commands()
4. Your commands appear under hermes <provider-name> <subcommand>

Active-provider gating: Your CLI commands only appear when your provider is the active memory.provider in config. If a user hasn't configured your provider, your commands won't show in hermes --help.

Example

# plugins/memory/my-provider/cli.py

def my_command(args):
    """Handler dispatched by argparse."""
    sub = getattr(args, "my_command", None)
    if sub == "status":
        print("Provider is active and connected.")
    elif sub == "config":
        print("Showing config...")
    else:
        print("Usage: hermes my-provider <status|config>")

def register_cli(subparser) -> None:
    """Build the hermes my-provider argparse tree.

    Called by discover_plugin_cli_commands() at argparse setup time.
    """
    subs = subparser.add_subparsers(dest="my_command")
    subs.add_parser("status", help="Show provider status")
    subs.add_parser("config", help="Show provider config")
    subparser.set_defaults(func=my_command)

Reference implementation

See the Honcho plugin's cli.py for a full example with 13 subcommands, cross-profile management (--target-profile), and config read/write.

Directory structure with CLI

plugins/memory/my-provider/
├── __init__.py      # MemoryProvider implementation + register()
├── plugin.yaml      # Metadata
├── cli.py           # register_cli(subparser) — CLI commands
└── README.md        # Setup instructions

Single Provider Rule

Only one external memory provider can be active at a time. If a user tries to register a second, the MemoryManager rejects it with a warning. This prevents tool schema bloat and conflicting backends.

HERMES_HOME survival contract (what wrappers can rely on)

For wrapper-style providers that keep their runtime in a sidecar venv outside Hermes-managed Python (no dependency surface — no pyproject.toml, pip_dependencies, or python_dependencies — at the scanned plugin root; a pyproject.toml belonging solely to an external or nested sidecar is not scanned):

• Location. $HERMES_HOME/plugins/<name>/ is the profile-scoped plugin location, and HERMES_HOME follows the active context override, then $HERMES_HOME, then the platform default. Propagate HERMES_HOME when launching the wrapper or sidecar so profile isolation holds; MemoryManager.initialize_all injects the active hermes_home into every provider.
• Survival. Ordinary Hermes updates — including managed-venv rebuild/replacement by pm — do not delete or rewrite $HERMES_HOME/plugins/**. An installed wrapper directory and its marker file (e.g. mnemosyne-wrapper.json) survive. Explicit plugin updates and deletion flows (hermes uninstall, hermes plugins remove, profile deletion, user deletion) are excluded from this guarantee.
• Sidecar isolation. A plugin root with no dependency surface never joins the pm workspace dependency union; a resync or venv rebuild neither provisions deps for it nor touches its tree.
• Conflicts. For native shared-venv plugins, an unsatisfiable dependency union fails loudly: the candidate plugin stays unenabled and unimported (the admission authority refuses before publishing config, reporting the plugin identity plus the resolver's reason, with a re-enable/retry path and a machine-readable pm receipt). Dependency resolution does not automatically disable other plugins or run a bisect. Explicit plugin updates, removal, and independent security gates are separate operations.