Codex with Cognee Cloud

Connect Codex to your Cognee Cloud tenant with the memory plugin.

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)

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

Windows (PowerShell)

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"

Windows (cmd.exe)

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. On your tenant that sharing is real rather than nominal: each plugin authenticates as its own agent sub-user, and they join one cognee-agent role holding read and write on your datasets, which the plugins then address by canonical UUID. Set COGNEE_SHARED_AGENT_MEMORY=false for separated, per-plugin memory.

Set a custom dataset at launch:

export COGNEE_PLUGIN_DATASET="my-project-memory"
codex

Recall searches only the active dataset — though Codex can run a one-off search in another one without switching, see below. COGNEE_PLUGIN_DATASET seeds the active dataset 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.

Searching another dataset without switching. When you ask Codex to recall something the active dataset did not have, it offers the other datasets your API key can read — read-only ones included, since a search needs no write access — as a numbered list, and runs a one-off graph-only search on the one you pick without moving the session. The prompt hook names those datasets on the session’s first prompt, if the server answered it, and again on any prompt where memory came back empty; set COGNEE_RECALL_DATASET_HINT=off to stop it; see Sessions & datasets for the full flow.

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, improve existing memory, and search another readable dataset when the active one comes back empty
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
cognee-standup, cognee-digest, cognee-timeline	Recap the sessions your tenant recorded: a standup, a multi-day digest, or one topic’s history — see Recaps

What reaches your tenant. Prompts, tool traces, and answers are captured automatically, with credential paths (.env, *.pem, */.ssh/*, and the rest) skipped outright and common secrets redacted before anything is sent. COGNEE_CAPTURE=false stops automatic capture entirely while leaving recall and explicit remember working — see What gets captured.

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. A dataset you can only read still shows up as a search target in the flow above.

When the workspace balance runs out, every billable operation is refused with HTTP 402 and memory goes quiet. The status line says so rather than leaving you guessing, in three shapes:

• credits: $0.61 · top up: https://platform.cognee.ai/billing — a dollar or less left. The link tracks the balance, so it appears before anything has actually been refused.
• credits: $2.04 (not enough for recall) — a request was refused while the balance still read healthy. The refused operation is named only above that one-dollar threshold; below it you get the top-up link instead.
• credits: not enough for recall · top up: … — refused with no balance to print, because the billing lookup itself failed.

Recall, session saves, /remember, and background improve runs each report themselves this way. The next billable operation that succeeds clears the note, so a top-up shows through on the following prompt. See When credits run out.

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
COGNEE_SHARED_AGENT_MEMORY	true	All your Cognee plugins share one canonical dataset through a cognee-agent role on your tenant; false separates them
COGNEE_CAPTURE	true	false stops automatic prompt, trace, and answer capture

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