> ## Documentation Index
> Fetch the complete documentation index at: https://cortex-e852fafe-t3code-rewrite-docs-declutter.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Hermes

> HydraDB memory provider for the Hermes Agent: relevant context is recalled before each turn and completed turns are saved.

HydraDB is a native [Hermes Agent](https://hermes-agent.nousresearch.com/docs/)
**memory provider**: relevant context is recalled before each turn and completed
turns are persisted automatically. This is the proper, native way to make HydraDB
Hermes' long-term memory (alongside providers like supermemory, retaindb, and
ham). It uses the HydraDB public API only (recall + knowledge ingest); no HydraDB
SDK is required.

## Quick Start

<Steps>
  <Step title="Install the provider">
    <Tabs>
      <Tab title="Catalog (recommended)">
        HydraDB is a first-party entry in the curated Hermes plugin catalog:

        ```bash theme={"dark"}
        hermes plugins install hydradb
        hermes memory setup hydradb
        ```
      </Tab>

      <Tab title="Directory (drop-in)">
        Clone the repo and copy the `hydradb_hermes/` folder (it contains
        `__init__.py` and `plugin.yaml`) into your Hermes memory plugins
        directory:

        ```bash theme={"dark"}
        git clone https://github.com/hydra-db/hydradb-hermes-plugin.git
        mkdir -p ~/.hermes/plugins/memory/hydradb/
        cp -r hydradb-hermes-plugin/hydradb_hermes/. ~/.hermes/plugins/memory/hydradb/
        ```
      </Tab>

      <Tab title="pip (from GitHub)">
        ```bash theme={"dark"}
        pip install git+https://github.com/hydra-db/hydradb-hermes-plugin.git
        ```

        Registered via the `hermes_agent.memory_providers` entry point. The package is not on PyPI yet.
      </Tab>
    </Tabs>

    <Note>
      Requires **Python 3.10+** and a Hermes Agent install.
    </Note>
  </Step>

  <Step title="Get credentials">
    * Create an API key from the [HydraDB dashboard](https://app.hydradb.com/keys)
    * Create or copy your database ID from the [HydraDB dashboard](https://app.hydradb.com/databases)
  </Step>

  <Step title="Set environment variables">
    ```bash theme={"dark"}
    export HYDRADB_API_KEY="your-api-key"
    export HYDRADB_DATABASE="your-database"
    ```
  </Step>

  <Step title="Enable it in `config.yaml`">
    Memory providers are single-select:

    ```yaml theme={"dark"}
    memory:
      provider: hydradb
    ```
  </Step>
</Steps>

## How it works

The integration implements Hermes' `MemoryProvider` contract:

| Method | Role | HydraDB |
| - | - | - |
| `prefetch(query, *, session_id)` | **Auto-recall**: context injected before the API call | Hybrid `POST /query` (prefers the server-built `llm_prompt`) |
| `sync_turn(user, assistant, ...)` | Persist the completed turn (**non-blocking**, off-thread) | `POST /context/ingest` |
| `is_available()` | Provider availability | `bool(HYDRADB_API_KEY)` |
| `get_config_schema()` / `save_config()` | Setup wizard (API key, database) | |
| `name` | Provider name | `"hydradb"` |

* **Auto-recall**: Before each turn, Hermes calls `prefetch`, which queries
  HydraDB and returns graph-enriched context to inject into the request.
* **Auto-retain**: After each turn, `sync_turn` persists the user/assistant
  exchange off-thread so the model is never blocked on a write.

## MCP alternative

For pull-style recall (agent-invoked tools) instead of automatic memory, point
Hermes at the HydraDB [MCP server](/plugins/mcp). The memory provider already
gives automatic recall and retain, so MCP is optional.

## Feedback and contributions

This plugin is open source. Feel free to [raise an issue](https://github.com/hydra-db/hydradb-hermes-plugin/issues) or [contribute on GitHub](https://github.com/hydra-db/hydradb-hermes-plugin).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.