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

---
sidebar_position: 8
title: "Memory Provider Plugins"
description: "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](./context-engine-plugin.md), 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](https://github.com/NousResearch/hermes-agent/blob/main/CONTRIBUTING.md). |
| 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:

```toml title="pyproject.toml"
[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`:

```python
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:

```yaml
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](./plugins/index.md#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):

```python
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:

```yaml
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](#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`:

```python
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](https://github.com/supermemoryai/hermes-supermemory) (a plugin catalog entry) for an example — it only prompts for the API key; all other options live in `supermemory.json`.
:::

## Save Config

```python
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

```python
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:

```python
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

```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.

```python
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`:

```python
# 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.

```python
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

```python
# 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`](https://github.com/plastic-labs/honcho/blob/main/hermes-plugin-honcho/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.