Claude Code

Add persistent memory to Claude Code with the Cognee memory plugin — no code and no pip install. The plugin hooks into Claude Code’s lifecycle, so it:

captures your prompts, tool traces, and assistant responses into session memory
injects relevant context on every prompt submit
syncs the session into your knowledge graph on session end

Sessions are disposable; your memory isn’t.

Install

Install from the Claude Code marketplace. Run these in your terminal (or type the equivalent /plugin … slash commands directly in the Claude Code chat):

claude plugin marketplace add topoteretes/cognee-integrations
claude plugin install cognee-memory@cognee

On startup you’ll see a “Cognee Memory Connected” message, and the status line shows cognee: <dataset> · <mode>.

Configure your backend

Set environment variables in the shell that launches Claude Code.

Cognee Cloud / remote
Local (default)

Point the plugin at Cognee Cloud or a remote server by setting both:

export COGNEE_BASE_URL="https://your-tenant.aws.cognee.ai"
export COGNEE_API_KEY="ck_..."

When COGNEE_BASE_URL is unset, the plugin bootstraps a local Cognee API at http://localhost:8011. Only an LLM key is required — COGNEE_API_KEY is auto-minted if absent:

export LLM_API_KEY="sk-..."

Cognee’s LLM calls do not run through Claude Code. Your Claude Code plan pays only for your conversation with Claude. Everything Cognee does on its own — entity and relationship extraction during cognify, summarization, embeddings, and search-time completions — happens inside the Cognee backend against the LLM provider configured there, and is billed by that provider. In local mode you configure it with LLM_API_KEY; in Cloud/remote mode your tenant holds the key server-side, so no local LLM key is needed.

In local mode, the single LLM_API_KEY above covers extraction, summarization, and embeddings: 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. To use another provider, set LLM_PROVIDER, LLM_MODEL, and — for Azure, Ollama, or OpenAI-compatible endpoints — LLM_ENDPOINT. Changing only the LLM leaves embeddings on OpenAI, so also set the EMBEDDING_* variables or set EMBEDDING_API_KEY to an OpenAI key so the default embeddings keep working. See LLM providers and embedding providers. You can also persist settings in ~/.cognee-plugin/claude-code/config.json:

{
  "base_url": "https://your-tenant.aws.cognee.ai",
  "dataset": "agent_sessions"
}

Use it

Just use Claude Code as usual — memory is captured and recalled automatically. You can also invoke the skills explicitly:

Skill	Purpose
`/cognee-memory:cognee-remember`	Store something in memory now
`/cognee-memory:cognee-search`	Query your memory
`/cognee-memory:cognee-sync`	Persist the current session into the graph

To verify the connection, open a fresh session and ask: “What do you know from cognee?”

With the plugin active, Cognee is the preferred memory: the SessionStart hook steers Claude to treat Cognee as authoritative over Claude Code’s built-in MEMORY.md. Set COGNEE_PREFER_MEMORY=false to turn the steer off.

Sessions & datasets

Sessions — set COGNEE_SESSION_ID before launching Claude Code to resume or share a named live session across terminals. If you do not set it, the plugin chooses a session id from its configured session strategy.
Datasets — all writes and recall are scoped to one dataset (agent_sessions by default). Set COGNEE_PLUGIN_DATASET to use a custom one. The Claude Code and Codex plugins share the default dataset, so memory carries across both.

How It Works

The plugin registers Claude Code lifecycle hooks:

Hook	Fires	What it does
`SessionStart`	Session launch	Selects local or remote mode, sets up session identity, prepares the dataset, and starts the background idle watcher
`UserPromptSubmit`	Each prompt you submit	Recalls relevant, dataset-scoped context from Cognee and injects it, then stages the prompt in session memory in the background
`PostToolUse`	After each tool call	Stores the tool call as a trace entry in session memory, without blocking the tool
`Stop`	Turn end	Stores the assistant’s answer in session memory, paired with the prompt it answered
`PreCompact`	Before context compaction	Builds a memory anchor so relevant context survives the compacted history
`SessionEnd`	Session exit	Starts a detached worker that runs the final sync of the session into your knowledge graph

A background idle watcher persists the session cache after periods of inactivity, and a final sync on session end bridges the session into the permanent graph.

Session distillation (self-improvement)

The Cognee coding-agent plugins (Claude Code, Codex) run session distillation for you — you never call improve() by hand. A distillation pass fires on three triggers:

Trigger	When it fires	How
Session end	You quit the agent	The `SessionEnd` hook drains buffered turns into the server session cache, then fires `POST /api/v1/improve` for the session id in the background. A launch-exit watcher covers exits where the hook never fires — a hard exit, or Codex CLI shutdowns that skip `SessionEnd`.
Every N tool calls	Long sessions, incrementally	A per-session counter fires an improve every `COGNEE_AUTO_IMPROVE_EVERY` stored tool calls/stops (default 150), so a long session bridges into the graph without waiting for the end.
On idle	The session goes quiet	A background idle watcher polls every `COGNEE_IDLE_POLL` seconds and fires an improve after `COGNEE_IDLE_THRESHOLD` seconds of inactivity, then waits at least `COGNEE_IMPROVE_COOLDOWN` seconds before the next idle run.

Overlapping triggers are safe. A per-session improve lock on the server serializes concurrent runs, and unchanged session content dedups server-side by content hash — so a repeat improve over content that hasn’t changed is a cheap no-op, not duplicated work.

Configuration

All triggers are tuned through environment variables read by the plugin. The defaults are chosen so distillation stays out of your way; you rarely need to change them.

Variable	Default	What it controls
`COGNEE_AUTO_IMPROVE_EVERY`	`150`	Stored tool calls/stops between automatic mid-session improves
`COGNEE_IDLE_THRESHOLD`	`60`	Seconds of inactivity before an idle improve fires
`COGNEE_IMPROVE_COOLDOWN`	`600`	Minimum seconds between idle improve runs
`COGNEE_IDLE_POLL`	`10`	How often the idle watcher checks for inactivity
`COGNEE_IMPROVE_SUBMIT_TIMEOUT`	`420` (Claude Code) / `180` (Codex)	Read timeout for the improve POST (distillation runs inside the request). The Claude Code plugin raises this to `420` at startup to clear cognee’s LLM-retry floor; Codex uses the `180` fallback.
`COGNEE_IDLE_DISABLED`	unset	Set to `1` / `true` to turn off the idle-watcher trigger entirely

The plugin READMEs document additional advanced knobs — timing (poll deadlines, busy-retry intervals for a held session lock), session-sync retries, and the update-notification variables (COGNEE_UPDATE_CHECK, COGNEE_UPDATE_CHECK_INTERVAL). You almost never need them — reach for the table above first.

Turning it down or off

Stop idle-triggered improves: set COGNEE_IDLE_DISABLED=1 before launching the agent. Session-end and per-turn improves still run.
Reduce mid-session improves: raise COGNEE_AUTO_IMPROVE_EVERY to a large value so the per-turn trigger effectively never fires within a session.
Session-end distillation always runs when the plugin is active — it’s how a finished session reaches permanent memory.

Confirming it happened

Cloud UI: the Self-improvement card at the top of a session on the Sessions page shows the status of the last graph enrichment and the dataset it wrote to.
Plugin hook log: each automatic run emits an improve_fired event you can grep for when debugging (in local SDK mode, where the plugin calls the library directly instead of the HTTP endpoint, look for auto_improve_fired instead).
improve-unsupported.json marker: if this file appears in the plugin’s shared state directory (24h TTL), the server rejected the improve endpoint and the plugin fell back to the legacy remember bridge for that window — a signal the server predates session-aware improve.

Debugging & Resuming Sessions

Hooks are callbacks from Claude Code, not a durable job queue: events that happen while the plugin is uninstalled, failing, or unable to reach the backend are not replayed later. When memory does not appear, check these layers first:

Layer	What it controls	How to verify
Claude Code hooks	Whether Claude Code calls the plugin on prompt submit, tool use, stop, compaction, and session end	Confirm the plugin is installed and the startup message says “Cognee Memory Connected”
Cognee backend	Where the plugin writes session memory and recalls graph context	In Cloud/remote mode, confirm `COGNEE_BASE_URL` and `COGNEE_API_KEY`; in local mode, confirm `LLM_API_KEY` is set so the plugin-managed local API can start
Session identity	Which live session receives staged prompts, traces, and answers	Keep the same `COGNEE_SESSION_ID` and `COGNEE_PLUGIN_DATASET` when you expect a resumed terminal to continue the same session

A resumed or second terminal continues the same live session only when the session id and dataset match: set COGNEE_SESSION_ID before launching Claude Code and keep COGNEE_PLUGIN_DATASET unchanged, otherwise the resumed work lands in a new session. After changing credentials, dataset, or session id, restart Claude Code so SessionStart can run with the new state.

Hook commands run with python3, falling back to python if python3 isn’t found. If neither resolves on PATH — most commonly on Windows, where the python.org installer doesn’t always register a python3 alias — every hook fails and no memory is ever captured. Run python3 --version or python --version in the same shell that launches Claude Code to confirm one is available, or reinstall Python with “Add python.exe to PATH” checked.

For a clean handoff into long-term memory, run /cognee-memory:cognee-sync or exit Claude Code normally so SessionEnd can trigger the final graph sync. If the process is killed instead, recent session cache entries may exist, but the final session-to-graph sync may not have run yet.

Configuration Reference

Precedence: environment variables → ~/.cognee-plugin/claude-code/config.json → defaults.

Setting	Env var	Default	Notes
Dataset	`COGNEE_PLUGIN_DATASET`	`agent_sessions`	Dataset for writes and recall
Session ID	`COGNEE_SESSION_ID`	strategy-derived	Override the configured strategy to resume a named session
Session strategy	`COGNEE_SESSION_STRATEGY`	`per-directory`	`per-directory`, `git-branch`, `static`
Base URL	`COGNEE_BASE_URL`	unset	Set to use a managed/remote endpoint
API key	`COGNEE_API_KEY`	unset	Auto-minted if absent in local mode
Local API URL	`COGNEE_LOCAL_API_URL`	`http://localhost:8011`	Local API base URL
Local LLM	`LLM_API_KEY`, `LLM_MODEL`	unset	Required for local mode
Prefer Cognee memory	`COGNEE_PREFER_MEMORY`	`true`	Inject the SessionStart memory steer

Update or Remove

There’s no automatic update — reinstall to pull a new plugin version:

claude plugin uninstall cognee-memory@cognee
claude plugin install cognee-memory@cognee

GitHub Repository

View source code and the full configuration reference

Codex plugin

The same memory plugin for the Codex CLI

Overview

Cloud LLM Providers

Observability

Evaluation

Data Ingestion

Agent Frameworks

Coding Agents

No-Code & Low-Code

Team Chat

Install

Configure your backend

Use it

Sessions & datasets

How It Works

Session distillation (self-improvement)

Configuration

Turning it down or off

Confirming it happened

Debugging & Resuming Sessions

Configuration Reference

Update or Remove

GitHub Repository

Codex plugin

​Install

​Configure your backend

​Use it

​Sessions & datasets

​How It Works

​Session distillation (self-improvement)

​Configuration

​Turning it down or off

​Confirming it happened

​Debugging & Resuming Sessions

​Configuration Reference

​Update or Remove

GitHub Repository

Codex plugin

Install

Configure your backend

Use it

Sessions & datasets

How It Works

Session distillation (self-improvement)

Configuration

Turning it down or off

Confirming it happened

Debugging & Resuming Sessions

Configuration Reference

Update or Remove