Codex

Add persistent memory to Codex with the Cognee memory plugin — no code and no pip install. It works in the Codex CLI and can also be activated through the Codex IDE plugin. The plugin hooks into Codex’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

The Cognee memory plugin depends on Codex lifecycle hooks. Enable hooks before installing it.

CLI
Manual

Enable hooks, then install from the Codex marketplace with the Codex CLI:

codex features enable hooks
codex plugin marketplace add topoteretes/cognee-integrations --ref main
codex plugin add cognee@cognee

If you prefer to manage Codex config directly, add this to ~/.codex/config.toml:

[features]
hooks = true

[marketplaces.cognee]
source_type = "git"
source = "https://github.com/topoteretes/cognee-integrations.git"
ref = "main"

[plugins."cognee@cognee"]
enabled = true

Make sure Cognee hooks are enabled for both the Codex CLI and the Codex IDE plugin. If Codex asks you to review hooks, open /hooks and allow or trust the Cognee hooks. Until hooks are enabled and trusted, Codex will not call the plugin on prompt submit, tool use, stop, compaction, or session end.

On startup the status line shows cognee: <dataset> · <mode> to confirm the plugin is active.

Configure your backend

Set environment variables in the shell that launches Codex.

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 Codex. Your Codex plan pays only for your conversation with the model. 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/config.json:

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

Use it

Use Codex as usual — memory is captured and recalled automatically. To verify, end a session with /exit (which syncs it into Cognee), then start a fresh session and ask: “What do you know from cognee?” Answering from a clean session proves it’s recalling from your memory.

Sessions & datasets

Sessions — set COGNEE_SESSION_ID before launching Codex 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 Codex and Claude Code plugins share the default dataset, so memory carries across both.

How It Works

The plugin registers Codex 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 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 Codex, not a durable job queue: events that happen while hooks are disabled or untrusted, or while the plugin cannot reach the backend, are not replayed later. When memory does not appear, check these layers first:

Layer	What it controls	How to verify
Codex hooks	Whether Codex calls the plugin on prompt submit, tool use, stop, compaction, and session end	Run `codex features enable hooks`, then open `/hooks` if Codex asks you to review or trust hooks
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 Codex and keep COGNEE_PLUGIN_DATASET unchanged, otherwise the resumed work lands in a new session. After changing hook trust, credentials, dataset, or session id, restart Codex 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 with a “hook failure” error and no session is ever created. Run python3 --version or python --version in the same shell that launches Codex to confirm one is available, or reinstall Python with “Add python.exe to PATH” checked.

Exit Codex normally (for example with /exit) when you want SessionEnd to 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/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

Update or Remove

Reinstall to pull a new plugin version:

codex plugin remove cognee@cognee
codex plugin add cognee@cognee

GitHub Repository

View source code and the full configuration reference

Claude Code plugin

The same memory plugin for Claude Code

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

Claude Code 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

Claude Code 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