Cognee Plugin for Hermes Agent

Give 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:

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:

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:

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.0 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:

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 and embedding providers.

To avoid a separate LLM key altogether, run Cognee as an MCP server 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_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
`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 <path-or-git-url> indexes a repository into a deterministic code graph (add --index-vectors to also embed code entities for semantic search, --dataset <name> to name the code dataset instead of the default codebase-<repo>-<digest>, and --wait <seconds> 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)

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

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
Capture: Each completed turn is synced to the session cache automatically
Promote: At session end (with COGNEE_IMPROVE_ON_END=true), cognee.improve(session_ids=[...]) promotes the session cache into the permanent graph
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 <cognee_memory> 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).

GitHub Repository

View source code and examples

Hermes Agent

Learn about Hermes Agent

Overview

Cloud LLM Providers

Observability

Evaluation

Data Ingestion

Agent Frameworks

Coding Agents

No-Code & Low-Code

Team Chat

Why Use This Integration

Installation

Quick Start

Connection Modes

Authentication

Configuration

Tools

How It Works

GitHub Repository

Hermes Agent

​Why Use This Integration

​Installation

​Quick Start

​Connection Modes

​Authentication

​Configuration

​Tools

​How It Works

GitHub Repository

Hermes Agent

Why Use This Integration

Installation

Quick Start

Connection Modes

Authentication

Configuration

Tools

How It Works