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

> Give the Codex CLI persistent memory with the Cognee plugin.

Add persistent memory to the [Codex CLI](https://developers.openai.com/codex/cli/) with the **Cognee memory plugin** — no code and no `pip install`. 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 Codex plugin requires hooks. Enable them, 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 `[features]\nhooks = true` to `~/.codex/config.toml`.
</Info>

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.

<Tabs>
  <Tab title="Cognee Cloud / remote">
    Point the plugin at [Cognee Cloud](/cognee-cloud/overview) or a remote server by setting both:

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

  <Tab title="Local (default)">
    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:

    ```bash theme={null}
    export LLM_API_KEY="sk-..."
    ```
  </Tab>
</Tabs>

You can also persist settings in `~/.cognee-plugin/config.json`:

```json theme={null}
{
  "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** — by default a new `session_id` is generated each launch. Set `COGNEE_SESSION_ID` to resume or share a named session across terminals.
* **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               | Behavior                                                          |
| ------------------ | ----------------------------------------------------------------- |
| `SessionStart`     | mode select, identity setup, dataset readiness, watcher bootstrap |
| `UserPromptSubmit` | context lookup + async prompt staging                             |
| `PostToolUse`      | async trace write                                                 |
| `Stop`             | assistant answer write                                            |
| `PreCompact`       | memory anchor build before compaction                             |
| `SessionEnd`       | trigger detached final sync worker                                |

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.

## 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`        | per-launch              | Override 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:

```bash theme={null}
codex plugin remove cognee@cognee
codex plugin add cognee@cognee
```

***

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/topoteretes/cognee-integrations/tree/main/integrations/codex">
    View source code and the full configuration reference
  </Card>

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