Hermes + Memanto

The hermes-memanto package is a memory-agent provider for the Hermes agent. It gives Hermes typed long-term memory backed by Memanto and the Moorcheh semantic platform — semantic recall across sessions, automatic turn capture, RAG-style answers, and per-profile memory isolation.

Unlike a passive “memory layer”, every namespace in Memanto is a first-class agent (memanto agent create/activate). This provider maps one Hermes identity to one Memanto agent, so each profile gets its own persistent memory.

Auto-recall

Relevant memories are retrieved and injected into context before each turn — no tool call required.

Turn capture

Meaningful conversation turns are stored as event memories in the background; trivial acknowledgements are skipped.

Explicit tools

memanto_remember, memanto_recall, and memanto_answer let Hermes manage memory deliberately when it needs to.

Profile isolation

agent_id: hermes-{identity} scopes memory per Hermes profile — {identity} expands to the profile name at startup.

How It Works

┌──────────────┐   register(ctx)   ┌──────────────────┐   HTTPS + API key   ┌─────────────┐
│    Hermes    │ ────────────────► │  memanto plugin  │ ──────────────────► │   Moorcheh  │
│    agent     │ ◄──────────────── │  (this provider) │ ◄────────────────── │   Service   │
└──────────────┘  recall / capture └──────────────────┘  no-indexing search └─────────────┘

Hermes discovers memory providers as directories under $HERMES_HOME/plugins/<name>/, each holding an __init__.py that exposes register(ctx) plus a plugin.yaml. This package ships exactly that, plus an installer that drops it into place. On first use the provider activates a Memanto session (auto-creating the agent if needed) and reuses it for the run.

Prerequisites

Python 3.10+
A running Hermes agent install
A Moorcheh API key (free tier: 100K ops/month)

Install

Install the package

This pulls in the memanto SDK as a dependency.

pip install hermes-memanto

Drop the plugin into your Hermes home

The bundled console script copies a self-contained plugin into ~/.hermes/plugins/memanto/.

hermes-memanto-install

Flags: --hermes-home /path/to/.hermes (defaults to $HERMES_HOME or ~/.hermes) and --force to overwrite an existing install.

Configure your key and select the provider

export MOORCHEH_API_KEY=your_key_xxxxxxxxxxxxxxxxxx   # https://console.moorcheh.ai/api-keys
hermes config set memory.provider memanto

hermes memory setup also lists memanto once the plugin is installed, walks you through configuration, and writes MOORCHEH_API_KEY into ~/.hermes/.env for you.

The first memory call auto-creates the agent and namespace; every subsequent call reuses the same persistent memory.

From a source checkout

git clone https://github.com/moorcheh-ai/memanto.git
cd memanto/integrations/hermes-agents
pip install -e .
hermes-memanto-install            # or: hermes-memanto-install --hermes-home /path/to/.hermes

The installer copies hermes_memanto/provider.py verbatim as the plugin’s __init__.py, so the installed plugin is self-contained and only needs the memanto SDK at runtime (declared in its plugin.yaml).

Memory providers are auto-detected as exclusive and selected via memory.provider — not hermes plugins enable. Just run hermes config set memory.provider memanto.

Tools Exposed to Hermes

The provider registers three tools with Hermes:

Tool	When Hermes should call it
`memanto_remember`	Persist a durable fact, preference, decision, goal, or instruction — with optional `type`, `tags`, and `confidence`.
`memanto_recall`	Semantic search across the agent’s memory. Use this first, before asking the user to repeat stable info. Supports a `type` filter and `limit` (1–100).
`memanto_answer`	A grounded RAG answer synthesized only over stored memories — no extra LLM key required. Prefer over `recall` when you need a synthesized answer rather than a ranked list.

Memory types accepted by memanto_remember / memanto_recall

fact, preference, goal, decision, artifact, learning, event, instruction, relationship, context, observation, commitment, error.See the Memory Types Reference for guidance on picking the right type. If Hermes omits the type, the provider infers one from the content.

Provenance values

explicit_statement, inferred, corrected, validated, observed, imported.Tool writes are tagged explicit_statement; automatically captured turns are tagged observed.

Automatic Memory (no tool calls required)

Beyond the explicit tools, the provider keeps memory in sync on its own:

Auto-recall — before each turn, relevant memories are retrieved and injected into context inside a <memanto-memory> block. Tunable via max_recall_results and min_confidence.
Turn capture — meaningful conversation turns are stored as event memories in the background. Trivial acknowledgements (ok, thanks, …) and very short messages are skipped.
Memory mirroring — Hermes’ built-in memory writes are echoed into Memanto, so manual saves and automatic recall share one store.
Profile isolation — agent_id: hermes-{identity} scopes memory per Hermes profile; {identity} expands to the profile name at startup.

Configuration

After install, settings live in $HERMES_HOME/memanto.json:

Key	Default	Description
`agent_id`	`hermes-{identity}`	Memanto agent id (memory namespace). `{identity}` expands to the Hermes profile name.
`pattern`	`tool`	Agent pattern used when auto-creating: `support`, `project`, or `tool`.
`auto_recall`	`true`	Inject relevant memories before each turn.
`auto_capture`	`true`	Store cleaned conversation turns as `event` memories.
`auto_create`	`true`	Create the agent on first use if it does not exist.
`mirror_memory_writes`	`true`	Echo Hermes’ built-in `memory` writes into Memanto.
`max_recall_results`	`10`	Max memories formatted into prefetch context (1–100).
`min_confidence`	`null`	Drop recalled memories below this confidence (0.0–1.0).
`session_duration_hours`	`null`	Override Memanto session lifetime (1–720).

Environment variable	Required	Description
`MOORCHEH_API_KEY`	yes	Moorcheh API key (powers Memanto).
`MEMANTO_AGENT_ID`	no	Override the agent id (takes priority over the config file).

Session & Lifecycle

Sessions activate lazily on first use and are warmed up in a background thread at startup, so the first turn’s recall doesn’t pay agent-create + activate latency.
A failed activation triggers a short cooldown-and-retry (≈60 s) rather than a permanent kill switch — a transient backend blip doesn’t disable the provider for the rest of the run, but a down backend isn’t re-hit on every turn either.
Writes are automatically disabled in non-interactive contexts (cron, flush, subagent) so background runs don’t pollute memory; recall still works.
Background captures and mirrored writes bind the active client at schedule time, so a delayed write always lands in the session that scheduled it.

Security & Safety

The API key lives only in the environment / ~/.hermes/.env (MOORCHEH_API_KEY). It is never persisted to memanto.json, even if passed through the setup wizard.

Recalled memory is sanitized before injection: the <memanto-memory> wrapper delimiters are stripped from stored content, so a memory that happens to contain those tags can’t break out of the context block and steer later turns.
The memanto SDK is imported lazily, so the module loads even when the package isn’t installed — the provider simply reports unavailable and stays inert until a key and the SDK are present.

Shared Memory Across Integrations

hermes-memanto talks to the same Moorcheh-backed Memanto agents as the sibling integrations, so memory written by one is recallable from the others when they share an agent_id:

Integration	Package	What it does
`integrations/mcp`	`memanto-mcp`	MCP server for any MCP-compatible client (Claude, Cursor, Windsurf, …).
`integrations/crewai`	`crewai-memanto`	CrewAI tools for multi-agent memory sharing.
`integrations/hermes-agents`	`hermes-memanto`	This — a memory provider for the Hermes agent.

Development

pip install -e ".[dev]"
pytest          # provider unit tests (no network; SdkClient is faked)
ruff check .

Try It

Start Hermes and tell it “remember that I prefer concise answers”. In a brand-new session tomorrow, ask “what do I prefer?” — Hermes recalls it before you finish typing.

Next Steps

Memory Types Reference

Learn which memory type to pick for each piece of information.

Agent Management

Create, activate, and switch Memanto agents.

Remember API

The REST endpoint the memanto_remember tool wraps.

Recall API

The REST endpoint the memanto_recall tool wraps.

Links

Documentation Index

​Hermes + Memanto

Auto-recall

Turn capture

Explicit tools

Profile isolation

​How It Works

​Prerequisites

​Install

​From a source checkout

​Tools Exposed to Hermes

​Automatic Memory (no tool calls required)

​Configuration

​Session & Lifecycle

​Security & Safety

​Shared Memory Across Integrations

​Development

​Try It

​Next Steps

Memory Types Reference

Agent Management

Remember API

Recall API

Hermes + Memanto

How It Works

Prerequisites

Install

From a source checkout

Tools Exposed to Hermes

Automatic Memory (no tool calls required)

Configuration

Session & Lifecycle

Security & Safety

Shared Memory Across Integrations

Development

Try It

Next Steps