Skip to main content

Hermes Memory Provider Management

Use when installing or migrating a Hermes memory provider. Use this skill when installing, replacing, migrating, or validating an external memory provider for Hermes Agent. It covers the full class of provider integrations: dependency placement, exclusive-provider registration, historical transcript backfill, duplicate-memory avoidance, runtime activation, and end-to-end recall verification.

The official Hermes documentation and live CLI remain authoritative. Load the bundled hermes-agent skill and its configuration/plugin references when available; this skill adds the operational workflow and verification discipline.

Principles​

  • Treat a memory provider as an exclusive Hermes plugin, not merely an MCP server. Native provider hooks can prefetch context, synchronize turns, mirror built-in memory writes, and expose provider tools across every gateway surface.
  • Keep vault data local unless the user explicitly chooses a hosted backend. Verify whether embeddings or reranking cause network calls.
  • Install provider dependencies into the Python environment that runs Hermes, not only into an isolated CLI environment.
  • Preserve existing memories before disabling a previous provider. Avoid two active long-term stores unless their roles are deliberately distinct; otherwise recall fragments and the model receives competing tool surfaces.
  • A configuration success is not an integration success. Verify registration, persistence, semantic recall, cleanup, and fresh-session activation.

Workflow​

1. Discover the real integration surface​

  1. Confirm the provider's official repository/package and current version from primary sources.
  2. Inspect whether it ships one of:
    • a Hermes-native plugin repository with plugin.yaml and register(ctx);
    • an in-package Hermes MemoryProvider implementation;
    • only an MCP server.
  3. Prefer the native provider path when available. Use MCP only when no provider integration exists or when the user explicitly wants a shared remote MCP service.
  4. Inspect the provider for storage path, network behavior, embedding downloads, supported backends, and backup requirements.

2. Install into both required environments​

When a package provides a CLI and an in-process Hermes provider:

  • Install the CLI in an isolated tool environment (uv tool install or pipx).
  • Install the same pinned package version into Hermes' runtime Python. Resolve that Python from the live hermes executable rather than guessing .venv vs venv.
  • Import the provider class using that exact runtime interpreter and check its availability method.

Do not assume a successful standalone CLI install makes imports available to Hermes.

3. Register an in-package provider safely​

If the package ships a provider module but no installable Hermes plugin manifest, create a thin profile-local adapter:

from package.integrations.hermes import ProviderClass

def register(ctx):
    ctx.register_memory_provider(ProviderClass())

Pair it with a minimal plugin.yaml declaring the package requirements. Keep the adapter thin; do not copy a large provider implementation into Hermes when the upstream package already owns it.

Then:

  1. Run hermes plugins doctor <plugin-path> --ci.
  2. Enable the plugin through hermes plugins enable.
  3. Select it with hermes config set memory.provider <name>; never hand-edit config.yaml.
  4. Store provider-specific non-secret settings in its documented config file or Hermes configuration schema. Credentials belong in the profile .env.

4. Initialize and isolate the vault​

  • Create the vault with the provider's own CLI or API.
  • Choose a stable user/project namespace instead of a generic agent namespace when all personal chats should share one vault.
  • Record any vault path excluded from hermes backup; arrange a separate backup policy.
  • Expect the first semantic operation to download a local embedding model when documented. A one-time verified model download is not evidence of cloud memory storage.

5. Migrate historical chats​

For Hermes history stored in state.db:

  1. Export only active user and assistant content from primary sessions.
  2. Exclude tool rows, cron runs, and child/subagent sessions unless the user explicitly wants them; they otherwise dominate retrieval with operational noise.
  3. Export one file per session in a conversation format the provider officially normalizes.
  4. Preserve message timestamps in the export when the format supports them.
  5. Mine/backfill into the same namespace used by live turn synchronization.
  6. Compare exported session/message counts with the source query, and explain intentionally skipped sessions.
  7. Run an idempotent second backfill or provider status check when supported.

For MemPalace-compatible Claude-style JSONL, each record can use:

{"type":"user","timestamp":"2026-01-01T00:00:00+00:00","message":{"role":"user","content":"..."}}
{"type":"assistant","timestamp":"2026-01-01T00:00:01+00:00","message":{"role":"assistant","content":"..."}}

6. Avoid fragmented memory​

After confirming migration and recall:

  • Disable a redundant generic memory MCP server rather than deleting its data immediately.
  • Keep Hermes' built-in memory tool enabled when the provider mirrors or consumes those writes.
  • Clearly distinguish durable user-profile memory, semantic conversation recall, and session search; they are complementary only when their ownership is explicit.

7. Verify the real path​

Use all applicable checks:

  1. Plugin doctor/import validation.
  2. Provider's official integration tests.
  3. Direct provider initialization under Hermes' runtime Python.
  4. A temporary marker write → semantic search → exact result verification → delete cleanup.
  5. A search for a known historical fact after backfill.
  6. hermes doctor confirming the selected provider is active.
  7. A fresh Hermes session confirming provider-native tools are present.

Do not leave synthetic E2E markers in the user's vault.

8. Monitor and recover provider health​

For an actively relied-on provider, use a silent watchdog rather than waiting for recall failures to surface in conversation:

  • Check resolved provider selection and availability, plugin import/registration, runtime dependency consistency, non-empty vault status, and one known semantic-recall query.
  • Keep healthy runs silent; alert only with the exact failed checks. Default to read-only monitoring. Enable automatic repair only when the user explicitly authorizes it, and then keep recovery classified, bounded, backup-first, and non-destructive.
  • Retry semantic recall before repair so a short post-flush consistency window does not trigger an unnecessary index rebuild.
  • When an import fails after dependency drift, run the runtime environment's dependency checker and align only the provider's declared requirement family. Do not blindly upgrade the whole environment or invent pins for unknown conflicts.
  • For a provider-supported vector-index corruption signature with readable SQLite ground truth, archive the vault and rebuild from SQLite; never delete the source or re-mine as the first response. Record the embedder identity when a rebuilt collection requires it.
  • After any repair, re-run dependency validation, plugin doctor, provider status, index/integrity status, Hermes doctor, and a real historical recall query. A CLI status command alone is insufficient.
  • Healthy and successfully self-repaired cron runs should remain silent; only unrecovered failures should emit bounded diagnostics and a nonzero exit.

See references/mempalace-local-provider.md for a validated dependency-reconciliation and read-only 12-hour watchdog pattern. See references/mempalace-self-healing-watchdog.md for the explicitly authorized backup-first self-healing variant.

9. Activate without breaking the live conversation​

Plugin, tool, and memory-provider changes require a fresh agent/session. Existing cached gateway agents may retain their old provider.

  • For one current conversation, /reset is the low-impact activation path.
  • For every cached chat surface, restart the gateway from a separate shell after the current response is delivered.
  • Do not attempt to restart the gateway from inside the gateway process; Hermes guards this because it would terminate the active tool call and response.

State this activation boundary explicitly rather than claiming the current live conversation already gained new tools.

Pitfalls​

  • CLI-only install: the command works, but the Hermes runtime cannot import the provider.
  • Assuming MCP equals provider integration: MCP tools alone do not automatically synchronize every turn or prefetch context.
  • Copying stale third-party code: prefer a thin wrapper around the provider maintained in the official package when one exists.
  • Duplicate stores: leaving a generic memory MCP and a native semantic provider simultaneously active can fragment recall.
  • Noisy backfill: importing tool output, cron, and subagents reduces retrieval quality.
  • Unverified activation: plugin commands commonly take effect only on a new session or gateway restart.
  • Unsafe migration cleanup: disable old stores first; delete only after the user approves and the new vault is verified.
  • Backup blind spot: external vault paths may not be included in hermes backup.

Verification checklist​

  • Official provider/package identified and pinned
  • Dependency import succeeds in Hermes runtime Python
  • Plugin doctor passes
  • Provider selected in resolved Hermes config
  • Vault initialized at intended path/namespace
  • Old memory store preserved or deliberately disabled
  • Historical export counts reconciled
  • Temporary write/search/delete succeeds
  • Known historical fact is recalled
  • Official integration tests pass when available
  • hermes doctor reports provider active
  • Fresh-session activation path communicated or completed
  • Vault backup scope documented

Session evidence​

See references/mempalace-local-provider.md for a validated MemPalace installation, Hermes-native adapter, historical SQLite export, and verification recipe.

Supporting files: this skill's supporting files are held in the docsite at docs/15-skills/_support/autonomous-ai-agents/hermes-memory-provider-management/ — fetch them fresh from jknash/docsite main alongside this page. Source: jknash/hermes-shared-skills · branch hermes-jkdev001 @ 1d0d545c3970 · skills/autonomous-ai-agents/hermes-memory-provider-management/ · view source · Imported 2026-10-04. Supporting files (references, scripts) remain in the source repository.

version 1.0.0 · author Hermes Curator · license MIT.

Published by Muse · 2026-10-04.