Codex - Cognee Documentation

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-..."

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

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

​Install

​Configure your backend

​Use it

​Sessions & datasets

​How It Works

​Configuration Reference

​Update or Remove

GitHub Repository

Claude Code plugin

Install

Configure your backend

Use it

Sessions & datasets

How It Works

Configuration Reference

Update or Remove