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

pip install cognee-integration-hermes-agent
hermes memory setup        # select "cognee" in the memory provider picker
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.

​
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.
ModeHow to enableNotes
Local server (default)(nothing)Hermes is a thin HTTP client to a single-writer local Cognee server. Safest for concurrent/background work.
Remote / CloudSet COGNEE_BASE_URL (and COGNEE_API_KEY)Thin HTTP client to a managed or cloud Cognee instance.
EmbeddedSet COGNEE_EMBEDDED=trueRuns 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.
VariableDefaultDescription
LLM_API_KEY—LLM API key used by Cognee
LLM_MODELprovider defaultLLM model name
COGNEE_DATASEThermesDataset name for stored memory
COGNEE_BASE_URL—Cognee service URL (enables remote mode)
COGNEE_API_KEY—Cognee service API key (remote mode)
COGNEE_EMBEDDEDfalseRun Cognee in-process
COGNEE_TOP_K5Max results per recall
COGNEE_IMPROVE_ON_ENDtrueRun improve() at session end
COGNEE_SESSION_PREFIXhermesSession ID prefix
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:
ToolDescription
cognee_recallSearch session memory and the persistent graph (query, optional scope, search_type, top_k)
cognee_rememberPersist important content into the knowledge graph (content, optional dataset)
cognee_forgetDelete 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

GitHub Repository

View source code and examples

Hermes Agent

Learn about Hermes Agent