Skip to main content
Add persistent memory to Claude Code backed by your Cognee Cloud tenant with the Cognee memory plugin — no code and no pip install. The plugin hooks into Claude Code’s lifecycle: it 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. Install the plugin

Install from the Claude Code marketplace before launching Claude Code, so the first claude launch is a clean session that runs the plugin bootstrap automatically:
These CLI subcommands use the same plugin manager as the in-chat /plugin commands. If you instead install from inside the chat with /plugin, restart Claude Code (start a new session) before memory connects — /reload-plugins loads the skills but does not run SessionStart.
Install scope defaults to user (global); pass --scope project or --scope local to confine the plugin to a single repo. On the first clean launch you’ll see a “Cognee Memory Connected” message, and the status line shows cognee: <dataset> · <mode>.

​
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 Codex plugin, and its values act like shell exports — except you only set them once, and they survive closing the terminal:
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 claude 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 Claude Code and Codex 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 memory, and pair it with COGNEE_PLUGIN_IDENTITY=true — on its own it leaves a fresh install running as your own user, which sees everything anyway. See Sessions & datasets. Set a custom dataset at launch:
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, use /cognee-memory:cognee-switch-datasets — 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 Claude Code (via the SDK or the server) is visible in Claude Code through the plugin. You only need a switch to work in another dataset. To look something up in one, Claude can run a one-off, graph-only search against any dataset your API key can read — including datasets shared with you read-only — and it is told which ones those are on the session’s first prompt and whenever memory comes back empty, so it can offer them when the active dataset does not answer. The session, the active dataset and where writes go stay put. See Sessions & datasets.

​
4. Pick a session (optional)

By default the session_id is derived from the Claude Code session, so a new conversation starts a new one and claude --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:
The name is normalized before it reaches your tenant: anything outside the ASCII set A-Z a-z 0-9 - _ . — accented and non-Latin letters included — becomes _, and the result is capped at 120 characters. The rule is the same in every Cognee agent integration, so one name pins the same session from Claude Code and Codex alike.

​
5. Verify

Restart Claude Code so SessionStart runs with the new credentials, then open a fresh session and ask:
What do you know from cognee?
Answering from a clean session confirms it’s recalling from your Cloud memory. You can also invoke the skills explicitly: 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_TOOLS and COGNEE_CAPTURE_DENY_TOOLS narrow which tool calls are sent, down to individual Bash commands (Bash(git:*)). 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 /cognee-memory:cognee-code 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. For the same reason, the file’s code map from file context on Read, which Claude gets before it reads a file, is not available for a repository indexed by URL. 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.
Against a tenant, the status line carries your workspace credit balance next to the dataset and mode — cognee: agent_sessions · cloud · credits: $2.04. Every billable request the plugin makes — recall, session saves, /cognee-memory:cognee-remember, and distillation runs — is refused with HTTP 402 when the balance is too low, and the line says which of them that happened to (a refused distillation renders as not enough for improve):
  • refused with credit left: credits: $2.04 (not enough for recall) — the refusal is red, the balance is not;
  • $1.00 or less left: the balance itself turns red, followed by top up: https://platform.cognee.ai/billing. The threshold is a dollar rather than zero because the tenant stops serving before the balance reaches zero;
  • refused with no balance reading at all: credits: not enough for recall, with the same top-up link.
The note clears as soon as a billable operation succeeds again, so a top-up shows through on your next prompt. The balance is read from the platform API for your tenant’s environment (api.<env>.cognee.ai alongside tenant-<id>.<env>.cognee.ai), which you can override with COGNEE_PLATFORM_API_URL; staging and dev tenants should also set COGNEE_BILLING_URL, since the top-up link defaults to the production billing page. 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_CLAUDE_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. 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

Hooks reference, session sync, and debugging

Codex

The same memory plugin for the Codex CLI