> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memanto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Hermes Agent Integration

> Give the Hermes agent typed long-term memory with semantic recall, automatic turn capture, and RAG answers — one pip install, one config line.

# Hermes + Memanto

<img src="https://mintcdn.com/memanto/hhBFws82L-0USNre/logo/integrations/hermes.png?fit=max&auto=format&n=hhBFws82L-0USNre&q=85&s=c37dec01bfac011b6638580b293644f0" alt="Hermes" width="140" style={{marginBottom: "1.5rem"}} data-path="logo/integrations/hermes.png" />

The [`hermes-memanto`](https://pypi.org/project/hermes-memanto/) package is a **memory-agent provider** for the [Hermes agent](https://github.com/NousResearch/hermes-agent). It gives Hermes typed long-term memory backed by [Memanto](https://memanto.ai) and the [Moorcheh](https://moorcheh.ai) 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.

<CardGroup cols={2}>
  <Card title="Auto-recall" icon="brain">
    Relevant memories are retrieved and injected into context before each turn — no tool call required.
  </Card>

  <Card title="Turn capture" icon="floppy-disk">
    Meaningful conversation turns are stored as `event` memories in the background; trivial acknowledgements are skipped.
  </Card>

  <Card title="Explicit tools" icon="wrench">
    `memanto_remember`, `memanto_recall`, and `memanto_answer` let Hermes manage memory deliberately when it needs to.
  </Card>

  <Card title="Profile isolation" icon="users">
    `agent_id: hermes-{identity}` scopes memory per Hermes profile — `{identity}` expands to the profile name at startup.
  </Card>
</CardGroup>

## 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](https://github.com/NousResearch/hermes-agent) install
* A [Moorcheh API key](https://console.moorcheh.ai/api-keys) (free tier: 100K ops/month)

## Install

<Steps>
  <Step title="Install the package">
    This pulls in the `memanto` SDK as a dependency.

    ```bash theme={null}
    pip install hermes-memanto
    ```
  </Step>

  <Step title="Drop the plugin into your Hermes home">
    The bundled console script copies a self-contained plugin into `~/.hermes/plugins/memanto/`.

    ```bash theme={null}
    hermes-memanto-install
    ```

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

  <Step title="Configure your key and select the provider">
    ```bash theme={null}
    export MOORCHEH_API_KEY=your_key_xxxxxxxxxxxxxxxxxx   # https://console.moorcheh.ai/api-keys
    hermes config set memory.provider memanto
    ```
  </Step>
</Steps>

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

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

### From a source checkout

```bash theme={null}
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`).

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

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

<AccordionGroup>
  <Accordion title="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](/reference/memory-types) for guidance on picking the right type. If Hermes omits the `type`, the provider infers one from the content.
  </Accordion>

  <Accordion title="Provenance values">
    `explicit_statement`, `inferred`, `corrected`, `validated`, `observed`, `imported`.

    Tool writes are tagged `explicit_statement`; automatically captured turns are tagged `observed`.
  </Accordion>
</AccordionGroup>

## 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

<Warning>
  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.
</Warning>

* 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`](/integrations/mcp)       | `memanto-mcp`    | MCP server for any MCP-compatible client (Claude, Cursor, Windsurf, …). |
| [`integrations/crewai`](/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

```bash theme={null}
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

<CardGroup cols={2}>
  <Card title="Memory Types Reference" icon="layer-group" href="/reference/memory-types">
    Learn which memory type to pick for each piece of information.
  </Card>

  <Card title="Agent Management" icon="user-gear" href="/guides/agent-management">
    Create, activate, and switch Memanto agents.
  </Card>

  <Card title="Remember API" icon="floppy-disk" href="/api-reference/data/remember">
    The REST endpoint the `memanto_remember` tool wraps.
  </Card>

  <Card title="Recall API" icon="magnifying-glass" href="/api-reference/search/recall">
    The REST endpoint the `memanto_recall` tool wraps.
  </Card>
</CardGroup>

***

**Links**

* [`hermes-memanto` on PyPI](https://pypi.org/project/hermes-memanto/)
* [Memanto on GitHub](https://github.com/moorcheh-ai/memanto)
* [Hermes agent](https://github.com/NousResearch/hermes-agent)