> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognee.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex

> 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:

```bash theme={null}
codex features enable hooks
codex plugin marketplace add topoteretes/cognee-integrations --ref main
codex plugin add cognee@cognee
```

<Info>
  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.
</Info>

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

## 2. Point it at Cognee Cloud

Set both variables in the shell that launches Codex, using your tenant base URL and an [API key](/cognee-cloud/ui/api-keys):

```bash theme={null}
export COGNEE_BASE_URL="https://your-tenant.aws.cognee.ai"
export COGNEE_API_KEY="<your-api-key>"
```

<Info>
  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.
</Info>

## 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:

```bash theme={null}
export COGNEE_PLUGIN_DATASET="my-project-memory"
codex
```

<Warning>
  The dataset is **fixed for the lifetime of a launch**, and recall searches only the active dataset. To switch datasets, exit Codex, change `COGNEE_PLUGIN_DATASET`, and start it again. The `dataset` key in `~/.cognee-plugin/config.json` is **informational-only** — runtime dataset selection reads the env var, not the config file.
</Warning>

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 a new `session_id` is generated on each launch. Set `COGNEE_SESSION_ID` to resume a specific named session, or to deliberately share one live session across two terminals:

```bash theme={null}
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.

<Note>
  Alongside automatic capture, the plugin ships skills you can invoke to remember or search explicitly — see the [full integration guide](/integrations/codex-integration).
</Note>

<Tip>
  Share specific datasets with connected agents from the [Connections](/cognee-cloud/connections/managing-connections) page to grant scoped read access.
</Tip>

## Configuration reference

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

| 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](/cognee-cloud/ui/api-keys) page; auto-minted only in local mode |
| `COGNEE_PLUGIN_DATASET`   | `agent_sessions`          | Dataset for writes and recall (config value is informational-only)                                |
| `COGNEE_SESSION_ID`       | auto-generated per launch | Override to resume or share a named session                                                       |
| `COGNEE_SESSION_STRATEGY` | `per-directory`           | `per-directory`, `git-branch`, or `static`                                                        |
| `COGNEE_SESSION_PREFIX`   | `codex`                   | Prefix for auto-generated session IDs                                                             |

Update the plugin with `codex plugin marketplace upgrade cognee` — the `cognee` marketplace tracks `main`, and updates are not automatic. See the [full integration guide](/integrations/codex-integration) for the idle-watcher, session-sync, and update-notification variables.

***

<CardGroup cols={2}>
  <Card title="Full integration guide" icon="book" href="/integrations/codex-integration">
    Manual config, hooks reference, and debugging
  </Card>

  <Card title="Claude Code" icon="bot" href="/cognee-cloud/agent-integrations/claude-code">
    The same memory plugin for Claude Code
  </Card>
</CardGroup>