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 cognee, and memory works automatically
Two memory tiers: Turns land in a session cache, then improve() promotes them into the permanent graph
Three connection modes: Remote/cloud (setup’s default), a local server run from a private Cognee runtime, or in-process embedded
Resilient: Built-in circuit breaker prevents cascading failures when Cognee is unreachable

Installation

Install the plugin from the Hermes plugin catalog (recommended), then run the setup in a terminal:

hermes plugins install cognee
hermes memory setup cognee     # makes Cognee the memory provider and asks for a mode

Installing alone does not turn memory on: Hermes uses a memory plugin only once it is the selected memory.provider, and hermes memory setup cognee is what selects it. hermes plugins enable cognee and the plugin toggle in Hermes Desktop enable the plugin but do not select it, so after either one hermes memory status still shows Provider: (none). 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. Or install from PyPI:

pip install cognee-integration-hermes-agent
cognee-hermes-install      # copies the plugin into $HERMES_HOME/plugins/cognee
hermes memory setup cognee

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

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 declares no dependencies, so it installs on any Hermes: remote mode is plain HTTP and needs no cognee package. Local mode runs its server from a private Cognee runtime (cognee==1.6.6) that the plugin installs only when you ask for it — see Local runtime.

Quick Start

Run setup once, then run Hermes as usual — memory is captured and recalled automatically:

hermes memory setup cognee   # one-time: remote (default) asks for URL + API key; local for an optional LLM key
hermes                       # start a new session

Memory is set up when a chat starts, so a chat that was already open keeps the memory it started with — start a new chat (or a new hermes session) after setup. Check with hermes memory status (Provider: cognee) and hermes cognee status (mode, dataset, service URL, the recall mode in effect, and a Local runtime line). 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
Remote / Cloud (setup’s default)	Set `COGNEE_BASE_URL` (and `COGNEE_API_KEY`)	Thin HTTP client to a managed or cloud Cognee instance.
Local server	No `COGNEE_BASE_URL`	Hermes is a thin HTTP client to a single-writer local Cognee server, run from the plugin’s private runtime. Safest for concurrent/background work.
Embedded	Set `COGNEE_EMBEDDED=true`	Runs Cognee in-process, so it needs `cognee==1.6.6` or newer installed into Hermes’s own environment by hand. Single-process/offline only; unsafe for concurrency.

hermes memory setup cognee offers remote first and as the default; an install that chose local sees Current mode: local above the prompt, and must type local when re-running setup, since accepting the default switches it to remote. Choosing local clears COGNEE_BASE_URL and COGNEE_API_KEY, so a Cognee Cloud key is not sent to the local server. The provider reports itself available with a service URL (remote), or once the local runtime is ready (local); it does not need LLM_API_KEY. When it is unavailable, Hermes starts the chat with its built-in memory only and its warning names the fix (hermes cognee install-runtime, or, in embedded mode, the embedded-mode wording when cognee is not in Hermes’s environment and, when it is older than the pin, the version it found and the command that upgrades it, <python> -m pip install cognee==1.6.6, or turning embedded mode off; the runtime venv never counts for embedded mode, so install-runtime does not help it).

Local runtime

Local mode never puts cognee into Hermes’s environment, where its pins conflict with Hermes extras. Instead the plugin installs cognee==1.6.6 into a venv of its own, ~/.cognee-plugin/hermes/runtime/venv (about 1 GB from PyPI), built from the interpreter running Hermes — with uv when it is on your PATH, otherwise with stdlib venv and pip. Nothing is downloaded when a session starts: hermes memory setup cognee offers the install when you choose local, and you can manage it on its own:

hermes cognee install-runtime         # install, or move it to the plugin's pinned cognee after an update
hermes cognee install-runtime --yes   # the same, stopping this plugin's server without asking
hermes cognee remove-runtime          # delete it (your data in ~/.cognee is kept)

One runtime serves every Hermes profile, as the server does. Local mode needs the runtime even when another Cognee plugin’s server is already running on the port, because Hermes decides availability before anything connects. After a plugin update that moves the pinned cognee (as 1.4.3 did, from 1.6.5 to 1.6.6), local mode stays off until you run hermes cognee install-runtime: the plugin never starts a server on a cognee it was not written against, and never downloads one behind your back. Hermes reports Cognee as unavailable with that command, and hermes cognee status shows the runtime as outdated. install-runtime upgrades the venv in place; a failed or interrupted install leaves local mode off rather than half-upgraded, and the next install-runtime repairs it. Once it has finished, start a new Hermes session. install-runtime stops the local server this plugin started before it installs, so the venv is never upgraded under a running process. It finds that server by the pidfile the plugin writes when it starts one (~/.cognee-plugin/hermes/runtime/servers/<port>.pid, checked to still run cognee.api.client:app, so a reused pid is left alone), says which server it will stop, and asks Continue? (y/n) (default yes); without a terminal it goes ahead only with --yes. The setup wizard’s install question names the pid too. The server gets SIGTERM only, never SIGKILL, and up to 60 seconds to finish; one still running after that is left running and the install stops without changing anything. The server is shared, so other Cognee plugins using it (Claude Code, Codex, OpenClaw) start a new one on their next request. While install-runtime runs, a Hermes session that would start a server reports Cognee as unavailable instead. If a cognee server the plugin cannot stop still answers on the local port and reports a cognee older than the pin, or no version at all (for example one started by plugin 1.4.2 or earlier, or by another plugin on an older cognee; on Windows the plugin stops nothing), install-runtime changes nothing and names the port, the version and, when lsof is installed, the pid to stop before you re-run it. A server on the pinned cognee or newer does not block the install. At session start the plugin also reads the version the server on the local port reports on /health. If it is older than the pinned cognee (for example a 1.6.5 server another plugin started), Hermes reports Cognee as unavailable and names the port until that server is replaced. A server that reports no version is used.

Upgrading from 1.3.x in local mode: run hermes cognee install-runtime. Earlier versions installed cognee into Hermes’s environment as a dependency; from 1.4.0 the plugin declares none, so local mode reports unavailable until the runtime is installed. Your data in ~/.cognee is untouched. A cognee installed into Hermes’s environment by hand is also used when it is the pinned version or newer; an older one — such as the 1.6.5 that 1.3.x installed and pip install -U leaves behind — keeps local mode off, and hermes cognee status shows it as outdated. Hermes removes a hand-installed cognee whenever it rebuilds that environment.

Session start waits up to 90 seconds for the local server. If the server it started is alive but not answering yet — typically a first start migrating an existing ~/.cognee — the session starts anyway, Cognee’s tools answer that the server is still starting (pointing at ~/.cognee-plugin/hermes/server.log), and Cognee turns on in that session once the server is ready.

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 Cognee uses 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
Remote / Cloud (default)	`COGNEE_BASE_URL` + `COGNEE_API_KEY`; no LLM key, since the server side holds the provider key
Local server	Optional `LLM_API_KEY` — the local server does extraction and embeddings itself, with local models when no key is set
Embedded	`LLM_API_KEY` — Cognee runs in-process and calls the provider directly

Credentials come through Hermes only. hermes memory setup cognee stores LLM_API_KEY, COGNEE_API_KEY and COGNEE_BASE_URL in the profile’s .env through Hermes’ own writer, and the plugin reads them back with Hermes’ get_secret, so a gateway serving several profiles hands each one its own keys. get_secret returns the active profile’s value and falls back to the environment unless a multi-profile gateway is routing the turn, so exported variables still work in a single-profile setup (on a Hermes without get_secret, the plugin reads the environment). The same goes for every other API key the local server uses (EMBEDDING_API_KEY, LLM_EXTRACTION_API_KEY, LLM_QUERY_API_KEY, LLM_SUMMARIZATION_API_KEY) and for COGNEE_USER_EMAIL / COGNEE_USER_PASSWORD, so put those in Hermes’ .env too. Non-secret settings such as LLM_PROVIDER, LLM_MODEL and LLM_ENDPOINT still come from the environment. The local server the plugin spawns starts in ~/.cognee-plugin/hermes, so a .env in the directory you start Hermes from doesn’t reach it. It also starts with COGNEE_ENV_FILE pointing at an empty file of its own (~/.cognee-plugin/hermes/cognee-server.env), which stops Cognee’s upward .env search — so a .env above the plugin’s state directory, such as ~/.cognee-plugin/.env, does not override the keys and settings Hermes hands over. A COGNEE_ENV_FILE you set yourself still wins.

~/.cognee/.env, the file the Claude Code, Codex and OpenClaw plugins share, is not read by this plugin. If your keys live only there, run hermes memory setup cognee once or put them in Hermes’ .env. A remote server or Cognee Cloud always needs COGNEE_API_KEY configured in Hermes — a key left behind by another Cognee plugin no longer stands in.

In local mode the plugin keeps no API key file: at each process’s first connect it logs in to the local server and reuses the key the server already has (creating one only when none exists), so it still lands on the same key as the other Cognee plugins. A configured COGNEE_API_KEY that the local server rejects with 401/403 (for example one left by an earlier remote setup) is replaced by the local server’s own key. If it starts the server without an LLM key, it logs a warning that Cognee will use local models, naming hermes memory setup cognee for adding a key. Without an LLM key, cognee builds memory with local models — the GLiNER extractor for the graph and the fastembed BAAI/bge-small-en-v1.5 embedder — installed into the runtime and downloaded on the first graph build (about 1.5 GB). Recall then returns the stored text that matches rather than a generated answer. The embedder sticks to the store: adding an LLM key later switches the default embedder to OpenAI, which a keyless store refuses with EmbeddingDimensionMismatchError, so also set EMBEDDING_PROVIDER=fastembed and EMBEDDING_MODEL=BAAI/bge-small-en-v1.5, or start a new store (COGNEE_DATA_ROOT, COGNEE_SYSTEM_ROOT). A server shared by several profiles keeps the LLM key of the profile that started it, so profiles that must not share an LLM bill need their own COGNEE_LOCAL_PORT. 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, with any API key among them in Hermes’ .env. See LLM providers and embedding providers.

To use your host’s own model instead of local models or a separate key, 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 cognee, 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 cognee always writes the mode and dataset there — so after running setup, change those by running setup again, not by exporting a variable. The one exception is the recall mode: an exported COGNEE_PLUGIN_RECALL_MODE overrides recall_mode in cognee.json, which setup always writes. 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 keep Hermes’s saves in a dataset of its own; recall stays on that dataset while no recall mode is set (see Recall mode).

Recall mode

On the default dataset, recall is auto: the per-prompt memory recall and cognee_recall name no dataset, and the server picks the best-matching one among those you can read. Routing needs a cognee 1.6.6 server; an older one searches every dataset you can read. Saves still go to the conversation’s dataset, and the guidance lane, cognee_code_search and recaps keep their datasets. recall_mode / COGNEE_PLUGIN_RECALL_MODE sets it: auto lets the server pick, pinned keeps recall on the active dataset, and any other value means auto. Set it with the variable, recall_mode in cognee.json, or the recall-mode question hermes memory setup cognee asks. With no mode set, the default dataset is auto and a configured non-default dataset stays pinned, so a dataset chosen to keep agents or projects apart keeps recall apart too; setup offers pinned for such a dataset. A user in that last case gets a one-time line appended to the first reply of a session (once per machine and dataset) saying that Cognee can also pick the dataset, and how to turn that on; it is never stored with the answer. A conversation can override the configured mode with cognee_switch_dataset. COGNEE_PLUGIN_DATASET=auto (any case) means the default dataset and says nothing about the recall mode.

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`. `auto` also means `agent_sessions`
`COGNEE_PLUGIN_RECALL_MODE`	unset: `auto` for the default dataset, `pinned` for any other configured dataset	Which datasets recall reads: `auto` (the server picks) or `pinned` (the active dataset); see Recall mode. Overrides `recall_mode` in `cognee.json`
`COGNEE_AUTO_ROUTE`	`true`	Whether Cognee picks the search type for a recall that names none (`false`: graph completion). Not the same setting as the recall mode, which picks datasets. Not asked by `hermes memory setup cognee`; set it in `cognee.json` (`auto_route`) or the environment
`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. Read through Hermes, like the API keys
`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_RECALL_BUDGET`	`20`	Deadline in seconds for the per-prompt recall
`COGNEE_RECALL_PASSAGE_CHARS`	`2000`	Cap on each recalled passage, cut at a paragraph break (`0` = no cap)
`COGNEE_RECALL_CONTEXT_CHARS`	`12000`	Cap on the whole injected recall (`0` = no cap)
`COGNEE_CAPTURE`	`true`	Automatic capture of turns, tool calls and mirrored Hermes memory writes; `false` turns it off, and with nothing captured the session-end and pre-compress improves are skipped. What you store with `cognee_remember` is never filtered
`COGNEE_CAPTURE_TOOLS` / `COGNEE_CAPTURE_DENY_TOOLS`	`*` / —	Which tool calls are captured: a name, an fnmatch glob, or `tool(prefix:)` matched against the start of a shell command (`terminal(git:)`); tool names match case-insensitively. Separate several with a pipe character or give a JSON array
`COGNEE_CAPTURE_DENY_PATHS`	—	Extra secret-file globs; separate several with commas or give a JSON array. Calls touching `.env`, `.pem`, `.key`, ssh and cloud credentials, `secrets.` or `credentials.*` are never captured, nor are calls to the Cognee tools or shell commands that mention `cognee`
`COGNEE_CAPTURE_REDACT`	`true`	Scrub private keys, tokens, database URLs, credential assignments, vendor keys and secret-named fields from captured turns, tool calls and mirrored Hermes memory writes
`COGNEE_CAPTURE_REDACT_PATTERNS`	—	Extra redaction regexes, one per line or as a JSON array. A capture pattern the plugin cannot parse fails closed: nothing is captured until it is fixed
`COGNEE_CHUNK_SIZE`	—	Tokens per chunk for `cognee_remember` writes and mirrored Hermes memory writes, for embedding models whose input limit is below the server default; unset leaves it to the server
`COGNEE_MEMORY_STEER`	`true`	Tell the agent, in the system prompt and again on each prompt’s Cognee memory block, that Cognee is the primary memory, that Hermes’ `MEMORY.md` / `USER.md` are the fallback when Cognee has nothing, and that on a disagreement it goes with Cognee and points out the difference. `false` turns both off; `COGNEE_MEMORY_STEER_TEXT` replaces the system-prompt wording. While Cognee is unavailable nothing is added
`COGNEE_PLUGIN_CITE_MEMORY`	on	Memory credit in the answer (see Memory credit); `off` turns it off
`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, hermes cognee install-runtime [--yes] / hermes cognee remove-runtime (the local-mode runtime), and hermes cognee version (plugin version and update availability). hermes cognee standup, hermes cognee digest and hermes cognee timeline <topic> print a recap of the sessions recorded into the configured dataset (--since, --projects, --all-sessions, --dataset, --json). 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> (dots in the repo name become -), and --wait <seconds> to wait for indexing to finish) and needs a Cognee server >= 1.5.4.hermes cognee keys list and hermes cognee keys revoke <key_id> --plugin <plugin> manage the API keys of your other Cognee plugin agents (Claude Code, Codex, …). Every machine a plugin runs on holds its own key for that plugin’s agent, and the server caps them, so an agent that is full refuses a new machine a key until an old machine’s key is revoked. keys list shows every plugin agent’s keys, most recently used first (never-used keys last), with their ids; narrow it with --plugin <plugin> (for example claude-code) or add --json. keys revoke needs the --plugin that holds the key. On a server without these key routes, such as cognee 1.6.5 and earlier, keys list reports no keys.

Tools

The plugin exposes six tools to the agent:

Tool	Description
`cognee_recall`	Search the persistent knowledge graph (`query`, optional `search_type`, `top_k`); no session id is sent, so the server doesn’t add this conversation’s history to the result
`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 or set its recall mode (`action`: `list`, `current`, `pin`, `switch`, `auto`, `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_recap`	Recap recorded sessions (`kind`: `standup`, `digest`, `timeline`; plus `topic` for a timeline, `since`, `projects`, `all_sessions`)

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). It also refuses the name auto. The conversation’s own recall choice wins over the configured recall mode. action="pin" pins recall to the active dataset without starting a new session; a switch pins recall to its target, and a switch to the dataset already in use behaves as pin. action="auto" lets the server pick for that conversation, lifting a configured pin too (the result names it in lifted). reset returns to the configured dataset and recall mode. current reports the mode in effect and, when pinned, a reason: dataset_picked for the conversation’s own pin, configured_pin for the configured mode or a configured non-default dataset with no mode set. The results of current, pin, auto, switch and reset carry a message line for the agent to relay. A pin without a switch is stored as the mode only, so if the configured dataset later changes, the conversation is pinned to the new one. cognee_recap and the matching hermes cognee commands build a standup (what was worked on and left open), a digest (sessions plus the lessons distilled into memory) or a dated timeline of one topic from the sessions Cognee recorded, grouped by the repository their edited files live in. A recap only covers sessions recorded into the active dataset, so on a shared server it never shows other users’ conversations; all_sessions adds other clients’ sessions in that dataset. It reads up to 2,500 of the newest sessions and says so when the server had more, and it lists the newest 25 of them (--max-sessions on the commands raises that). Recaps need the HTTP transport (local server or remote mode); in embedded mode they fail. Set COGNEE_DATASET_SWITCH_TOOL=false, COGNEE_CODE_SEARCH_TOOL=false or COGNEE_RECAP_TOOL=false to withhold any of the last three tools; all are exposed by default.

How It Works

Prefetch: Before each turn, a background recall requests the knowledge graph and the session’s guidance, plus a code-graph lookup when the query names indexed symbols
Capture: Each completed turn is synced to the session cache automatically, and its tool calls are stored as traces under the capture policy (see the COGNEE_CAPTURE_* settings in Configuration). After redaction, each side of a turn is capped at 8,000 characters, tool arguments at 4,000 and tool results at 8,000. Tool traces need the HTTP transport (local server or remote mode); embedded mode stores the turns only
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. Either improve is skipped when nothing was stored for the session since the last one, so a session that ends right after a compaction, with nothing new stored, pays for one improve, not two. An improve the server refuses with 402 (its LLM budget is spent, cognee 1.6.3 and later) is logged and not retried, and doesn’t count toward the circuit breaker
Resilience: After repeated failures the provider trips a circuit breaker, pausing briefly before retrying so errors don’t cascade

The prefetch requests are dispatched together under one deadline (COGNEE_RECALL_BUDGET, default 20 seconds), and none of them runs an LLM on the server:

Memory: a graph-scope HYBRID_COMPLETION recall with only_context=true, sent without the session id so the answer doesn’t carry the conversation Hermes already has, and with no dataset while recall is auto (the active dataset when pinned). The plugin keeps only the retrieved context — the question template goes, passages recorded in this session go, each passage is capped at COGNEE_RECALL_PASSAGE_CHARS, and entity lines that say nothing are pruned — and injects it as a <cognee_memory> block. Text it cannot parse (an older server’s bare context) is injected whole.
Guidance: a session_context request with the session id, against the active dataset, injected as <cognee_guidance> — the lessons the server distilled from this session.
Code: the code-graph lookup, when armed.

COGNEE_RECALL_CONTEXT_CHARS then caps the whole injection (guidance first, then memory, then code facts). A lane that fails or misses the deadline is dropped without costing the others. After three prompts in a row whose recall only timed out, each prompt first spends a 3-second /health probe and skips recall while the server doesn’t answer. Recall never searches the server’s raw session-cache scopes; turns are still written there for improve() to promote. A turn or tool trace that never reached the server — the connection could not be opened (it was booting or down) or it answered 503 — is queued in ~/.cognee-plugin/hermes/pending-entries.json (newest 500, kept a week) and replayed after the next successful write, when a session starts, and before the pre-compress and session-end improves. While the circuit breaker is open, writes go straight to the queue. A write that timed out or was cut off mid-request is not replayed, since the server may already have stored it. The queue needs the HTTP transport (local server or remote mode); in embedded mode a failed write is dropped.

Memory credit

When an answer uses recalled memory, the agent ends it with one credit line, and the credit is stripped before the turn is stored in Cognee. Every recalled item the agent is given — the per-prompt memory block and cognee_recall results — is tagged m1, m2… with where it came from, numbered across the conversation; an instruction asks the agent to add the credit only when the answer used a tagged item. When the recall was auto, each item’s tag carries the dataset the server reports for it ([m1 · Cognee memory · dataset shop_support]), and the credit names the datasets of the items the answer used (“based on dataset shop_support and dataset returns”); when the server reports no dataset (an older server), the credit says “based on Cognee memory”. When recall is pinned, the credit names the dataset. How the line looks depends on where you chat:

Hermes Desktop: the agent writes > Cognee: <what it remembered>, based on dataset <name>., and the plugin replaces Cognee: with the Cognee logo in brand purple and sets each credited dataset name in inline code. The rewritten answer is what Hermes keeps in its chat history.
Terminal chats (hermes --tui and hermes): the agent writes the line without the Cognee: label, and the Cognee logo in braille is printed under it, reading COGNEE based on <name> dataset (“a and b datasets” for several); a line crediting only “Cognee memory” keeps the logo alone. In the classic chat the logo follows the answer’s closing line with no blank lines in between. With display.streaming off in the classic chat, the logo replaces the quote marker instead, with the sentence beside it.
Messaging apps: the plain > Cognee: … line.

Set COGNEE_PLUGIN_CITE_MEMORY=off to turn it off.

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

Local runtime

Authentication

Configuration

Recall mode

Tools

How It Works

Memory credit

GitHub Repository

Hermes Agent

​Why Use This Integration

​Installation

​Quick Start

​Connection Modes

​Local runtime

​Authentication

​Configuration

​Recall mode

​Tools

​How It Works

​Memory credit

GitHub Repository

Hermes Agent

Why Use This Integration

Installation

Quick Start

Connection Modes

Local runtime

Authentication

Configuration

Recall mode

Tools

How It Works

Memory credit