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

# Hermes Agent

> Add persistent memory to Hermes Agent with a Cognee plugin.

Give [Hermes Agent](https://github.com/NousResearch/hermes-agent) persistent memory with a drop-in Cognee memory provider plugin. Each completed turn is stored in Cognee's session cache and automatically promoted into the permanent knowledge graph at session end — no code required.

## Why Use This Integration

* **Zero code**: Install, run `hermes memory setup`, and memory works automatically
* **Two memory tiers**: Turns land in a session cache, then `improve()` promotes them into the permanent graph
* **Three connection modes**: Local server (default), remote/cloud, or in-process embedded
* **Resilient**: Built-in circuit breaker prevents cascading failures when Cognee is unreachable

## Installation

```bash theme={null}
pip install cognee-integration-hermes-agent
hermes memory setup        # select "cognee" in the memory provider picker
```

<Info>
  Requires Python 3.10+ and pins `cognee>=1.0.0,<2.0.0`. The plugin registers itself via the `hermes_agent.plugins` entry point on install.
</Info>

## Quick Start

Configure your LLM key, then run Hermes as usual — memory is captured and recalled automatically:

```bash theme={null}
export LLM_API_KEY="your-openai-api-key-here"   # cognee extracts knowledge with an LLM
hermes memory setup                              # one-time: pick "cognee"
hermes                                           # start a session
```

During a session, just talk to the agent:

```
You: Remember that Alice works in engineering.
     (Cognee stores this turn in the session cache)

You: What does Alice do?
     (Hermes recalls from Cognee memory)
```

At session end, if `COGNEE_IMPROVE_ON_END=true` (the default), `cognee.improve(...)` runs to promote the session cache into the permanent graph.

## Connection Modes

The plugin connects to Cognee in one of three modes. There are **no silent fallbacks** — if the configured mode fails, the failure surfaces.

| Mode                       | How to enable                                | Notes                                                                                                       |
| -------------------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Local server** (default) | *(nothing)*                                  | Hermes is a thin HTTP client to a single-writer local Cognee server. Safest for concurrent/background work. |
| **Remote / Cloud**         | Set `COGNEE_BASE_URL` (and `COGNEE_API_KEY`) | Thin HTTP client to a managed or cloud Cognee instance.                                                     |
| **Embedded**               | Set `COGNEE_EMBEDDED=true`                   | Runs Cognee in-process. Single-process/offline only; unsafe for concurrency.                                |

## Configuration

Set these as environment variables. Non-secret settings are also saved to `$HERMES_HOME/cognee.json`; secrets go to `$HERMES_HOME/.env`.

| Variable                | Default          | Description                              |
| ----------------------- | ---------------- | ---------------------------------------- |
| `LLM_API_KEY`           | —                | LLM API key used by Cognee               |
| `LLM_MODEL`             | provider default | LLM model name                           |
| `COGNEE_DATASET`        | `hermes`         | Dataset name for stored memory           |
| `COGNEE_BASE_URL`       | —                | Cognee service URL (enables remote mode) |
| `COGNEE_API_KEY`        | —                | Cognee service API key (remote mode)     |
| `COGNEE_EMBEDDED`       | `false`          | Run Cognee in-process                    |
| `COGNEE_TOP_K`          | `5`              | Max results per recall                   |
| `COGNEE_IMPROVE_ON_END` | `true`           | Run `improve()` at session end           |
| `COGNEE_SESSION_PREFIX` | `hermes`         | Session ID prefix                        |

<Info>
  Manage the plugin with `hermes cognee status`, `hermes cognee setup`, `hermes cognee config`, and `hermes cognee install`.
</Info>

## Tools

The plugin exposes three tools to the agent:

| Tool              | Description                                                                                        |
| ----------------- | -------------------------------------------------------------------------------------------------- |
| `cognee_recall`   | Search session memory and the persistent graph (`query`, optional `scope`, `search_type`, `top_k`) |
| `cognee_remember` | Persist important content into the knowledge graph (`content`, optional `dataset`)                 |
| `cognee_forget`   | Delete memory (optional `dataset`, `everything=true`, or `memory_only`)                            |

## How It Works

1. **Prefetch**: Before each turn, `cognee_recall` runs in the background to populate memory context
2. **Capture**: Each completed turn is synced to the session cache automatically
3. **Promote**: At session end (with `COGNEE_IMPROVE_ON_END=true`), `cognee.improve(session_ids=[...])` promotes the session cache into the permanent graph
4. **Resilience**: After repeated failures the provider trips a circuit breaker, pausing briefly before retrying so errors don't cascade

***

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/topoteretes/cognee-integrations/tree/main/integrations/hermes-agent">
    View source code and examples
  </Card>

  <Card title="Hermes Agent" icon="book" href="https://github.com/NousResearch/hermes-agent">
    Learn about Hermes Agent
  </Card>
</CardGroup>