> ## 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.
# Cognee Plugin for 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
Install the plugin from PyPI:
```bash theme={null}
pip install cognee-integration-hermes-agent
cognee-hermes-install # copies the plugin into $HERMES_HOME/plugins/cognee
hermes memory setup # select "cognee" in the memory provider picker
```
The pip package registers the memory provider through Hermes' `hermes_agent.memory_providers` entry point; `cognee-hermes-install` adds the directory copy that carries the `hermes cognee` subcommands and the dashboard config panel. Update with `pip install -U cognee-integration-hermes-agent` followed by `cognee-hermes-install` — `hermes cognee status` tells you when the package and the copy have drifted.
Once the plugin is accepted into the Hermes plugin catalog, you will also be able to install it by name:
```bash theme={null}
hermes plugins install cognee
hermes plugins enable cognee
hermes memory setup
```
Update a catalog install with `hermes plugins update cognee`. `cognee-hermes-install` refuses to overwrite a catalog-managed copy, and `hermes cognee status` and `hermes cognee version` point you at the catalog command instead of checking PyPI, even with `--check-updates`.
For development, copy a checkout into a Hermes home that has no Cognee plugin installed:
```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
```
Requires Python 3.10+ — note that macOS's Xcode Command Line Tools ship Python 3.9, so use a Homebrew, python.org or uv-managed interpreter. The plugin pins `cognee==1.6.1` in its `plugin.yaml` — the installed package doubles as the local Cognee server the plugin spawns, so the pin moves in step with the wire contract, and upgrading the plugin also upgrades that server (its next boot runs the new version's migrations).
## 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. |
cognee 1.6.0 creates its default user only when the server starts with `DEFAULT_USER_PASSWORD` set. The local server the plugin spawns sets it for you. If you run your own local server, start it with `DEFAULT_USER_PASSWORD` matching `COGNEE_USER_PASSWORD`, or set `COGNEE_API_KEY`; otherwise the login fails with `This user does not have a password`.
## 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.6-luna` 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).
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.
## Configuration
Set these as environment variables, or answer the prompts of `hermes memory setup`, which saves non-secret settings to `$HERMES_HOME/cognee.json` and secrets to `$HERMES_HOME/.env`. Values saved in `$HERMES_HOME/cognee.json` take precedence over environment variables, and `hermes memory setup` always writes the mode and dataset there — so after running setup, change those by running setup again, not by exporting a variable.
By default the plugin shares one brain with Cognee's other agent plugins (Claude Code, Codex, OpenClaw): the same `agent_sessions` dataset, the same store under `~/.cognee`, and the same local server on port 8011. Memory written in any of them is recalled in all of them. Set `COGNEE_PLUGIN_DATASET` to give Hermes a dataset of its own.
| Variable | Default | Description |
| - | - | - |
| `LLM_API_KEY` | — | LLM API key used by Cognee |
| `LLM_MODEL` | provider default | LLM model name |
| `COGNEE_PLUGIN_DATASET` | `agent_sessions` | Dataset name for stored memory (`COGNEE_DATASET` is a kept alias). Cognee rejects spaces and dots in dataset names, so the plugin replaces each run of them with a single `_` and logs a warning — `my project` becomes `my_project`; a name made only of spaces and dots falls back to `agent_sessions` |
| `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 and before each context compression |
| `COGNEE_SESSION_PREFIX` | `hermes` | Session ID prefix |
| `COGNEE_USER_EMAIL` / `COGNEE_USER_PASSWORD` | `default_user@example.com` / `default_password` | User the plugin logs in as to mint an API key from a local server; a non-default user must already exist |
| `COGNEE_LOCAL_PORT` | `8011` | Port of the local server the plugin spawns or reuses |
| `COGNEE_DATA_ROOT` / `COGNEE_SYSTEM_ROOT` | `~/.cognee/data` / `~/.cognee/system` | Where the local store lives. To isolate a Hermes profile, point both elsewhere and give it its own `COGNEE_LOCAL_PORT` — a server belongs to whoever reaches its port first |
| `COGNEE_MEMORY_STEER` | `true` | Add a line to the system prompt naming Cognee as the preferred long-term memory; `COGNEE_MEMORY_STEER_TEXT` replaces its wording |
| `COGNEE_MEMORY_HITS` | `true` | Show the per-turn memory-hits line in the injected recall block |
| `COGNEE_CODE_GRAPH_RECALL` | `true` | Add a code-graph lookup to prefetch when the prompt names an indexed symbol |
| `COGNEE_CODE_DATASETS` | — | Comma-separated code datasets to always include in that lookup, for repositories indexed from another machine |
| `COGNEE_UPDATE_CHECK` | `true` | PyPI update check behind `hermes cognee status` / `version` (CLI only, never on the session path) |
Manage the plugin with `hermes cognee status`, `hermes cognee setup`, `hermes cognee config`, `hermes cognee install`, and `hermes cognee version` (plugin version and update availability). `hermes cognee index-repo ` indexes a repository into a deterministic code graph (add `--index-vectors` to also embed code entities for semantic search, `--dataset ` to name the code dataset instead of the default `codebase--` (dots in the repo name become `-`), and `--wait ` to wait for indexing to finish) and needs a Cognee server >= 1.5.4.
## Tools
The plugin exposes five tools to the agent:
| Tool | Description |
| - | - |
| `cognee_recall` | Search the persistent knowledge graph, with this conversation's session id attached (`query`, optional `search_type`, `top_k`) |
| `cognee_remember` | Persist important content into the knowledge graph (`content`, optional `dataset`) |
| `cognee_forget` | Delete memory — two-phase (`action`, plus `terms`, `data_ids`, `confirm`, `dataset`, `everything_in_dataset`) |
| `cognee_switch_dataset` | Move the conversation to another dataset (`action`: `list`, `current`, `switch`, `reset`, plus `dataset`, and `force` to proceed when bridging the current session fails) |
| `cognee_code_search` | Query an indexed repository's code graph (`operation`: `query_facts`, `explore`, `traverse`, `find_path`, `impact_analysis`, `delta`; optional `name`, `target` for `find_path`, `repo`, `limit` default 10) |
In local server and remote mode, `cognee_remember` asks the server to build the graph in the background, so it returns right away with `status: "running"` and the write finishes server-side. A slow or rate-limited LLM endpoint therefore no longer causes a timeout error for a write that actually lands. The flip side is that the new content isn't recallable until that build finishes, and a build that fails server-side no longer shows up as an error in the tool result. In embedded mode the write runs in-process, as before.
`cognee_forget` never deletes on a single call. The agent first runs `action="find"` with `terms` describing what to forget, which returns candidate documents with previews to show you; only then does `action="forget"` with the confirmed `data_ids` and `confirm=true` delete exactly those documents. Clearing a whole dataset takes `everything_in_dataset` alongside `confirm=true`, and both deletions are irreversible.
`cognee_switch_dataset` refuses a `switch` to a name containing a space or a dot rather than rewriting it, and its error suggests the sanitized name (for example `my_data` for `my.data`).
Set `COGNEE_DATASET_SWITCH_TOOL=false` or `COGNEE_CODE_SEARCH_TOOL=false` to withhold either of the last two tools; both are exposed by default.
## How It Works
1. **Prefetch**: Before each turn, a background recall makes one memory request to the knowledge graph, plus a code-graph lookup when the query names indexed symbols
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. Hermes also compresses long conversations, and before each compression the plugin starts the same improve on a background thread. That way, turns that get compressed away still reach the graph even if the session never closes cleanly. Compression never waits for this improve. A failure is only logged as a warning, and no second improve starts while the previous one is still running. It follows the same conditions as the session-end improve (`COGNEE_IMPROVE_ON_END`, writes enabled, circuit breaker closed), and the session-end improve still runs
4. **Resilience**: After repeated failures the provider trips a circuit breaker, pausing briefly before retrying so errors don't cascade
The memory request is a graph-scope `HYBRID_COMPLETION` recall with `only_context=true` and the conversation's session id, so no LLM runs on the server for it. On cognee 1.6.0 the server returns the full input the completion would have received — the session's conversation history, the question with the retrieved graph context, and the session guidance — and the plugin injects that text verbatim, untruncated, as a `` block (older servers return the bare retrieval context, injected the same way). Recall never searches the server's raw session-cache scopes; turns are still written there for `improve()` to promote. Set `COGNEE_RECALL_BUDGET` to change the prefetch deadline (default 20 seconds).
***
View source code and examples
Learn about Hermes Agent
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.