Skip to main content
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

The cognee-integration-hermes-agent package is not yet published on PyPI. Install the plugin locally from the cognee-integrations repository:
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.

​
Quick Start

Configure your LLM key, then run Hermes as usual — memory is captured and recalled automatically:
During a session, just talk to the agent:
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.

​
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: 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 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. Non-secret settings are also saved to $HERMES_HOME/cognee.json; secrets go to $HERMES_HOME/.env.
Manage the plugin with hermes cognee status, hermes cognee setup, hermes cognee config, and hermes cognee install.

​
Tools

The plugin exposes three tools to the agent:

​
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

GitHub Repository

View source code and examples

Hermes Agent

Learn about Hermes Agent