Codex with Cognee Cloud

Add persistent memory to the Codex CLI backed by your Cognee Cloud tenant with the Cognee memory plugin — no code and no pip install. The plugin captures your prompts, tool traces, and answers into session memory, injects relevant context on every prompt, and syncs the session into your knowledge graph on session end. Sessions are disposable; your memory isn’t.

1. Enable hooks and install

The plugin depends on Codex lifecycle hooks. Enable them first, then install from the Codex marketplace:

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

You can enable hooks manually instead by adding a [features] section with hooks = true to ~/.codex/config.toml. If Codex prompts you to review the hooks, approve the Cognee hooks so it can call the plugin on prompt submit, tool use, stop, compaction, and session end.

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

2. Point it at Cognee Cloud

Write both variables once into ~/.cognee/.env, using your tenant base URL and an API key. The file is created with a commented template on the first session start, is shared with the Claude Code plugin, and its values act like shell exports — except you only set them once, and they survive closing the terminal:

macOS / Linux (bash, zsh)
Windows (PowerShell)
Windows (cmd.exe)

mkdir -p ~/.cognee
cat >> ~/.cognee/.env <<'EOF'
COGNEE_BASE_URL="https://your-tenant.aws.cognee.ai"
COGNEE_API_KEY="<your-api-key>"
EOF
chmod 600 ~/.cognee/.env

New-Item -ItemType Directory -Force "$env:USERPROFILE\.cognee" | Out-Null
@'
COGNEE_BASE_URL="https://your-tenant.aws.cognee.ai"
COGNEE_API_KEY="<your-api-key>"
'@ | Add-Content "$env:USERPROFILE\.cognee\.env"

if not exist "%USERPROFILE%\.cognee" mkdir "%USERPROFILE%\.cognee"
(echo COGNEE_BASE_URL=https://your-tenant.aws.cognee.ai)>>"%USERPROFILE%\.cognee\.env"
(echo COGNEE_API_KEY=your-api-key)>>"%USERPROFILE%\.cognee\.env"

Re-running the block is safe — when a key appears more than once the last value wins, so pasting again updates the credentials instead of stacking duplicates. Changes apply on the next codex launch.

When COGNEE_BASE_URL is set, the plugin runs as a pure thin HTTP client to your tenant — it does not install a local Cognee runtime. When COGNEE_BASE_URL is unset, the plugin instead bootstraps a local API at http://localhost:8011. Setting the Cloud URL and key is what routes memory to your tenant.

Keeping a local-mode LLM_API_KEY in the same file is fine: cloud still wins, because a configured URL is what selects cloud. To send one terminal to local instead, export COGNEE_BACKEND=local before launching — unset COGNEE_BASE_URL does not work, because the env file re-injects the URL at the next launch. See Which mode wins.

3. Choose a dataset

All writes and recall are scoped to a single dataset, selected with the COGNEE_PLUGIN_DATASET environment variable. By default both the Codex and Claude Code plugins use agent_sessions, so memory is shared across both integrations automatically. Set a custom dataset at launch:

export COGNEE_PLUGIN_DATASET="my-project-memory"
codex

Recall searches only the active dataset. COGNEE_PLUGIN_DATASET seeds it at launch and is read only then, so changing the variable mid-session does nothing. To move the running session to another dataset, ask Codex to switch datasets (the cognee-switch-datasets skill) — it syncs the current session into its dataset first, then registers a fresh session on the chosen one, and its choice beats COGNEE_PLUGIN_DATASET for the rest of the launch.

Data added to the same dataset outside Codex (via the SDK or the server) is visible in Codex through the plugin.

4. Pick a session (optional)

By default the session_id is derived from the Codex thread, so a new conversation starts a new one and codex resume continues the same one. Set COGNEE_SESSION_ID to pin a specific named session, or to deliberately share one live session across two terminals:

export COGNEE_SESSION_ID="my-project"
codex

5. Verify

Quit Codex — the SessionEnd hook syncs the session into Cognee (an exit-watcher fallback covers a hard exit). Then start a fresh session and ask:

What do you know from cognee?

Answering from a clean session confirms it’s recalling from your Cloud memory. Alongside automatic capture, the plugin ships skills for explicit requests — ask for what you want and Codex picks the matching one:

Skill	Purpose
`memory`	Remember something now, search or recall memory, and improve existing memory
`cognee-forget`	Delete memory you ask to forget, along with its derived graph knowledge. Irreversible
`codebase`	Index a repository into the code graph and query it. Against a tenant this is explicit only — see below
`cognee-switch-datasets`	Move the running session to another dataset — see Choose a dataset

Two things about the code graph differ against a Cloud tenant. Repositories are not indexed automatically — the plugin only auto-indexes against a local server, so a private checkout is never shipped to a hosted tenant on its own initiative. Ask for it with the codebase skill and give it a git URL: your tenant clones the repo rather than reading your disk, which is also why the graph reflects your last pushed commit rather than your working tree. A local path is not an option here — the server cannot see it. See Code graph.

Memory is captured and synced from your sessions over time, and writes build the graph in the background — so a brand-new setup may recall nothing until at least one session has synced. An empty first recall is expected.

Share specific datasets with connected agents from the Connections page to grant scoped read access.

Configuration reference

Precedence: environment variables → ~/.cognee/.env → defaults. There is no config.json; older versions wrote one, and SessionStart now deletes a leftover file. The COGNEE_BACKEND / COGNEE_CODEX_BACKEND mode switch follows the same precedence. Wherever it is set, it pins that terminal’s mode regardless of where the connection variables are defined.

Env var	Default	Notes
`COGNEE_BASE_URL`	unset	Your tenant URL; enables Cloud/managed-endpoint mode
`COGNEE_API_KEY`	unset	Cloud API key from the API Keys page; auto-minted only in local mode
`COGNEE_BACKEND`	unset	`local` or `cloud` — pins this terminal’s mode; `COGNEE_CODEX_BACKEND` does the same for this plugin only and beats it
`COGNEE_ENV_FILE`	`~/.cognee/.env`	Read the one-time setup file from somewhere else
`COGNEE_PLUGIN_DATASET`	`agent_sessions`	Dataset for writes and recall at launch; switchable mid-session
`COGNEE_SESSION_ID`	derived from the Codex thread	Override to pin a named session, or share one across terminals
`COGNEE_SESSION_PREFIX`	`codex`	Prefix on auto-derived session IDs (`<prefix>_<codex-thread-id>`)
`COGNEE_SESSION_STRATEGY`	`per-directory`	Currently inert — the plugin derives session IDs from the Codex thread and never reads this

Update the plugin with codex plugin marketplace upgrade cognee — the cognee marketplace tracks main, and updates are not automatic. See the full integration guide for the session-distillation and idle-watcher variables; the advanced session-sync and update-notification knobs are covered in the plugin README.

Full integration guide

Manual config, hooks reference, and debugging

Claude Code

The same memory plugin for Claude Code

Getting Started

Local UI

Navigating the UI

Cloud Functionality

Agent Integrations

Connections

Reference

1. Enable hooks and install

2. Point it at Cognee Cloud

3. Choose a dataset

4. Pick a session (optional)

5. Verify

Configuration reference

Full integration guide

Claude Code

​1. Enable hooks and install

​2. Point it at Cognee Cloud

​3. Choose a dataset

​4. Pick a session (optional)

​5. Verify

​Configuration reference

Full integration guide

Claude Code

1. Enable hooks and install

2. Point it at Cognee Cloud

3. Choose a dataset

4. Pick a session (optional)

5. Verify

Configuration reference