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

The `cognee-integration-hermes-agent` package is not yet published on PyPI. Install the plugin locally from the [cognee-integrations](https://github.com/topoteretes/cognee-integrations) repository:

```bash theme={null}
git clone https://github.com/topoteretes/cognee-integrations.git
cd cognee-integrations
mkdir -p ~/.hermes/plugins/cognee
cp -R integrations/hermes-agent/. ~/.hermes/plugins/cognee/
hermes memory setup        # select "cognee" in the memory provider picker
```

<Info>
  Requires Python 3.10+. The plugin declares `cognee>=1.0.0,<2.0.0` as a pip dependency in its `plugin.yaml`. Once a PyPI release is available, `pip install cognee-integration-hermes-agent` will register the plugin via the `hermes_agent.plugins` entry point.
</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.                                |

## Authentication

Cognee authenticates with its own credentials — Hermes' model credentials are not reused. Everything Cognee does on its own — entity and relationship extraction, summarization, embeddings, and search-time completions — runs against the provider Cognee itself is configured with, billed by that provider. Cognee's LLM layer authenticates by API key only: a host agent's subscription or OAuth sign-in (for example a Codex-style ChatGPT login) cannot be handed to it, and Cognee's own OAuth flows sign you in to Cognee Cloud or to data-source integrations such as Slack, never to an LLM provider. So in local or embedded mode you need your own `LLM_API_KEY` even when your agent's model is already signed in.

Which credentials you need depends on the connection mode:

| Mode                       | Credentials Cognee needs                                                                       |
| -------------------------- | ---------------------------------------------------------------------------------------------- |
| **Local server** (default) | `LLM_API_KEY` — the local server does extraction and embeddings itself                         |
| **Remote / Cloud**         | `COGNEE_BASE_URL` + `COGNEE_API_KEY`; no LLM key, since the server side holds the provider key |
| **Embedded**               | `LLM_API_KEY` — Cognee runs in-process and calls the provider directly                         |

In local and embedded mode one `LLM_API_KEY` covers everything: Cognee defaults to `openai/gpt-5-mini` for the LLM and `openai/text-embedding-3-large` for embeddings, and embeddings reuse `LLM_API_KEY` when `EMBEDDING_API_KEY` is unset. For another provider, set `LLM_PROVIDER`, `LLM_MODEL`, and — for Azure, Ollama, or OpenAI-compatible endpoints — `LLM_ENDPOINT`, plus the matching `EMBEDDING_*` variables. See [LLM providers](/setup-configuration/llm-providers) and [embedding providers](/setup-configuration/embedding-providers).

<Tip>
  To avoid a separate LLM key altogether, run [Cognee as an MCP server](/cognee-mcp/mcp-local-setup) in a host that grants the MCP `sampling` capability and set `LLM_PROVIDER="mcp-sampling"` — completions are delegated to the host's own model. That is a different setup from this memory provider plugin, and embeddings still need their own provider.
</Tip>

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