Cognee Plugin for Claude Code

Add persistent memory to Claude Code with the Cognee memory plugin — no code and no pip install. The plugin hooks into Claude Code’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

Install from the Claude Code marketplace. Run these in your terminal (or type the equivalent /plugin … slash commands directly in the Claude Code chat):

claude plugin marketplace add topoteretes/cognee-integrations
claude plugin install cognee-memory@cognee

On startup you’ll see a “Cognee Memory Connected” message, and the status line shows cognee: <dataset> · <mode>.

Configure your backend

Configure the plugin once in ~/.cognee/.env. The file is created with a commented template on the first session start, and its values act exactly like shell exports — a real export in your shell still wins, per terminal. It is shared with the Codex plugin, so both read the same configuration.

Cognee Cloud / remote
Local (default)
Windows (PowerShell)

Point the plugin at Cognee Cloud or a remote server by setting both:

mkdir -p ~/.cognee
cat >> ~/.cognee/.env <<'EOF'
COGNEE_BASE_URL="https://your-tenant.aws.cognee.ai"
COGNEE_API_KEY="ck_..."
EOF
chmod 600 ~/.cognee/.env

Cloud mode is a pure thin client: it talks to your remote server over HTTP only and does not install a local Cognee runtime.If COGNEE_BASE_URL points at a server you run yourself and you leave COGNEE_API_KEY unset, the plugin logs in as COGNEE_USER_EMAIL / COGNEE_USER_PASSWORD to mint a key. On cognee 1.6.0 and later, start that server with DEFAULT_USER_PASSWORD set to the same value as COGNEE_USER_PASSWORD, or set COGNEE_API_KEY so the plugin skips the login.

When COGNEE_BASE_URL is unset, the plugin bootstraps a local Cognee API at http://localhost:8011. COGNEE_API_KEY is auto-minted if absent. The server needs an LLM for cognify. Give it a provider key of your own:

mkdir -p ~/.cognee
cat >> ~/.cognee/.env <<'EOF'
LLM_API_KEY="sk-..."
EOF
chmod 600 ~/.cognee/.env

Or set no key at all: with no LLM_API_KEY configured and the claude CLI on PATH, the local server runs its LLM calls on your Claude subscription through the Claude observer.The plugin mints COGNEE_API_KEY by logging in as the server’s default user (default_user@example.com / default_password). Cognee 1.6.0 and later create that user only when the server starts with DEFAULT_USER_PASSWORD set, so the plugin starts its local server with DEFAULT_USER_EMAIL and DEFAULT_USER_PASSWORD set to those values. A fresh install needs no manual step. If you export DEFAULT_USER_EMAIL or DEFAULT_USER_PASSWORD yourself, your values win. COGNEE_USER_EMAIL / COGNEE_USER_PASSWORD choose which user the plugin logs in as, and any user other than the default must already exist.

Same file, same keys:

New-Item -ItemType Directory -Force "$env:USERPROFILE\.cognee" | Out-Null
@'
COGNEE_BASE_URL="https://your-tenant.aws.cognee.ai"
COGNEE_API_KEY="ck_..."
'@ | Add-Content "$env:USERPROFILE\.cognee\.env"

Re-running any of these blocks is safe: when a key appears more than once the last value wins, so pasting again with a new value updates the setting. Editing the file directly (nano ~/.cognee/.env) works too. Either way, changes apply on the next launch. The file format:

Comments are whole lines starting with # — a trailing # note after a value becomes part of the value.
Quotes around values are optional, and a leading export is tolerated so existing shell profile lines paste verbatim.
Every variable in the Configuration Reference can live here, so there is nothing else to persist. The one exception is COGNEE_ENV_FILE itself: the plugin reads it before it opens the file, so it only works as a shell export.

Which mode wins, and how to switch

You can configure both modes at once — keep COGNEE_BASE_URL + COGNEE_API_KEY and LLM_API_KEY in the file together. The mode is then decided per terminal, by three rules in order:

A COGNEE_BACKEND export wins. export COGNEE_BACKEND=local (or =cloud) pins that terminal to that mode.
Otherwise, cloud wins when configured. If COGNEE_BASE_URL is set — in the file or the shell — the plugin connects to it.
Otherwise, local. With no URL anywhere, the plugin boots the local server.

So with both modes in ~/.cognee/.env:

claude  # → cloud: a configured URL selects it
COGNEE_BACKEND=local claude  # → local, this launch only
export COGNEE_BACKEND=local  # → local for every launch from this shell

To go local, use the switch — not unset COGNEE_BASE_URL. Unsetting does not work: the env file re-injects the URL at the next launch. Export COGNEE_BACKEND=local instead. (Deleting the line from the file works too, but that changes the default for every terminal.)

Details worth knowing:

The switch is pinned. COGNEE_BACKEND=cloud with no COGNEE_BASE_URL configured still counts as cloud — the plugin does not silently fall back to local, and the status line shows ✕ (missing_cognee_base_url) so you know exactly what to fix.
A forced-local switch blanks COGNEE_BASE_URL and COGNEE_API_KEY in the process environment, so the per-prompt hooks and every spawned worker resolve the same local endpoint — not just SessionStart. They are emptied rather than deleted on purpose: a child process that reloads the env file must not re-inject the cloud values.
The shared COGNEE_BACKEND flips both the Claude Code and Codex plugins in that terminal. To flip only one, use the plugin-specific name — COGNEE_CLAUDE_BACKEND or COGNEE_CODEX_BACKEND — which beats the shared one.
Accepted values: local (aliases native, sdk) and cloud (aliases http, api, server). Anything else is ignored.
COGNEE_BACKEND can also live in ~/.cognee/.env to make a mode the durable default; a shell export still overrides it per terminal.
Not sure what a terminal resolved? The status line’s mode field shows it live.

Cognee’s LLM calls do not run through your coding agent — with one exception: Claude Code’s local mode with no LLM key configured, which runs them on your Claude subscription through the Claude observer. Otherwise, your Claude Code or Codex plan pays only for your conversation with the model. Everything Cognee does on its own — entity and relationship extraction during cognify, summarization, embeddings, and search-time completions — happens inside the Cognee backend against the LLM provider configured there, and is billed by that provider. In local mode you configure it with LLM_API_KEY; in Cloud/remote mode your tenant holds the key server-side, so no local LLM key is needed.

In local mode, the single LLM_API_KEY above covers extraction, summarization, and embeddings: Cognee defaults to openai/gpt-5.6-luna for the LLM and openai/text-embedding-3-large for embeddings, and embeddings reuse LLM_API_KEY when EMBEDDING_API_KEY is unset. To use another provider, set LLM_PROVIDER, LLM_MODEL, and — for Azure, Ollama, or OpenAI-compatible endpoints — LLM_ENDPOINT. Changing only the LLM leaves embeddings on OpenAI, so also set the EMBEDDING_* variables or set EMBEDDING_API_KEY to an OpenAI key so the default embeddings keep working. See LLM providers and embedding providers.

Local mode without an LLM key: the Claude observer

In local mode, with no LLM_API_KEY and no LLM_PROVIDER configured and the claude CLI on PATH, session start routes the local server’s LLM calls through Claude Code itself instead of asking for a key. It points cognee’s custom provider at a loopback OpenAI-compatible shim (http://127.0.0.1:8017/v1), and each completion the server requests becomes one claude -p --safe-mode run. Embeddings switch to a local model (fastembed, BAAI/bge-small-en-v1.5, 384 dimensions) unless you configured an embedder of your own. Cloud mode never uses the observer — your tenant owns its LLM.

The observer spends your Claude usage. This is the one exception to the note above: with the observer on, every cognify and improve call is a real claude -p run billed to your Claude subscription and counted against its usage limits, and building the graph is token-heavy. Session start says so every time it is in use (⚠ LLM: Claude Code (observer) …). Set LLM_API_KEY to use a provider of your own, or COGNEE_LLM_OBSERVER=false to turn the observer off.

A key or provider counts as configured wherever it is set: your shell, ~/.cognee/.env, or the .env the server itself loads. The switch takes effect on the next launch, but a server that is already running keeps the LLM config it booted with until every session using it has closed. Because a dataset is tied to the embedder that built it, switch to a new dataset (/cognee-memory:cognee-switch-datasets or COGNEE_PLUGIN_DATASET) when you move between the observer and a key of your own. The shim listens on loopback only, requires a bearer token (~/.cognee-plugin/observer/token) on every endpoint except /health, and refuses requests that carry an Origin header. The diagnostic shows whether the observer is in use in its LLM row, and the status line reports a Claude login problem as ✕ (claude_not_logged_in) rather than as an incorrect key. Each completion is logged in ~/.cognee-plugin/observer/observer-events.log.

Env var	Default	Effect
`COGNEE_LLM_OBSERVER`	`auto`	`auto`: use the observer when no key or provider is configured and `claude` is found · `true`: in local mode, even when a key or provider is configured (a missing CLI is reported at session start) · `false`: never — local mode then needs `LLM_API_KEY`
`COGNEE_OBSERVER_MODEL`	`haiku`	Claude model for the server’s LLM calls (`haiku`, `sonnet`, `opus`, or a full model id). A value that cannot be a model name is ignored with a warning, and `haiku` is used
`COGNEE_OBSERVER_CLAUDE`	found on `PATH` or in the installer’s default location	Path to the `claude` executable
`COGNEE_OBSERVER_PORT`	`8017`	Loopback port of the shim
`COGNEE_OBSERVER_CONCURRENCY`	`2`	Parallel `claude -p` runs the shim allows
`COGNEE_OBSERVER_TIMEOUT`	`240`	Seconds per completion before the shim gives up

Use it

Just use Claude Code as usual — memory is captured and recalled automatically. You can also invoke the skills explicitly:

Skill	Purpose
`/cognee-memory:cognee-remember`	Store something in memory now
`/cognee-memory:cognee-search`	Query your memory
`/cognee-memory:cognee-sync`	Persist the current session into the graph
`/cognee-memory:cognee-forget`	Delete memory you ask to forget — the raw data, its derived graph knowledge, and, best-effort, the session Q&A that cited it. Irreversible
`/cognee-memory:cognee-code`	Index a repository into the code graph and query it (callers, impact analysis, paths, endpoints)
`/cognee-memory:cognee-switch-datasets`	Move the running session to another dataset, syncing the current one first

The plugin also ships a cognee-recall subagent. Claude delegates to it when a prompt needs a deeper or differently worded search than the per-prompt recall already ran — it reaches the permanent graph and can filter by category (user, project, agent). It runs on Haiku with a three-turn cap, so the detour stays cheap. To verify the connection, open a fresh session and ask: “What do you know from cognee?”

With the plugin active, Cognee is the preferred memory: the SessionStart hook steers Claude to treat Cognee as authoritative over Claude Code’s built-in MEMORY.md. Set COGNEE_PREFER_MEMORY=false to turn the steer off.

Sessions & datasets

Sessions — by default the plugin derives the Cognee session id from the Claude Code session, so a new conversation (or /clear) starts a new one and claude --resume continues the same one automatically. Set COGNEE_SESSION_ID before launching to pin a named session, or to deliberately share one live session across two terminals. Whatever you pin is normalized to the ASCII set A-Z a-z 0-9 - _ ., with every other character — accented and non-Latin letters included — replaced by _, then trimmed of leading and trailing ./_ and cut to 120 characters. Every Cognee agent integration applies that same rule, so one value names the same session in Claude Code as it does in Codex.
Datasets — all writes and recall are scoped to one dataset (agent_sessions by default). Set COGNEE_PLUGIN_DATASET to use a custom one. The Claude Code and Codex plugins default to the same one, so memory carries across both.

Sharing a dataset takes more than agreeing on a name. Where the server supports it, each plugin authenticates as its own agent sub-user, and grants only flow child to parent: your user sees what an agent writes, but an agent sees nothing your user or another plugin’s agent owns. Shared agent memory — on by default — closes that gap. Every plugin agent of your user joins one cognee-agent role holding read and write on your datasets, and the launch’s dataset is addressed by its canonical UUID rather than by name, which is what makes “the same dataset” mean the same rows in Claude Code and in Codex. Grants are backfilled at every session start and roughly every 60 seconds by the idle watcher, so a dataset another plugin creates becomes visible here without a restart. Set COGNEE_SHARED_AGENT_MEMORY=false to opt out. Nothing already written moves, but the agent leaves the shared role, so on an install that already has an agent identity the datasets your user owns stop being readable from it — the memory stays, this plugin just no longer reaches it. What separation rests on is the agent identity, so it is worth knowing which one you get: under the default COGNEE_PLUGIN_IDENTITY=auto an identity is provisioned only in service of shared memory, so opting out on a fresh install simply runs the plugin as your own user — which sees everything anyway. Set COGNEE_PLUGIN_IDENTITY=true to insist on a dedicated agent sub-user and get genuinely per-plugin memory. To move a running session to another dataset, run /cognee-memory:cognee-switch-datasets (optionally with a name). Without a name it lists the datasets you can write to; a name that is not listed is created for you. Because a Cognee session never spans two datasets, the switch first syncs the current session into its dataset — and aborts if that fails, changing nothing — then registers a fresh session on the chosen one. The choice lives in the launch record, so it survives --resume and beats COGNEE_PLUGIN_DATASET for the rest of the launch — as does the session it registers, which outranks a pinned COGNEE_SESSION_ID so a shell export cannot drag a switched launch back. Switching is only needed to work in another dataset — not to look something up in one. On every prompt the server answers, the recall hook appends an “Other Cognee datasets you can search” block to the injected context, naming every other dataset your identity can read (read-only ones included, since searching needs no write access) with their UUIDs. So when you ask Claude to recall something the active dataset does not hold, it can offer those datasets as a picker, run a one-off, graph-only search on the one you choose, and tell you which dataset the answer came from. If the server rejects that search with an HTTP error (other than an auth failure, or a 404, which reads as an empty result), the error names the dataset id it searched and adds the server’s own reason from the response, instead of a bare HTTP status. The active dataset, the Cognee session, and where writes go are untouched. The search runs without the session id, because a session belongs to the active dataset. The /cognee-memory:cognee-search skill offers the same choice when an explicit search comes back empty. Set COGNEE_RECALL_DATASET_HINT=off to stop the per-prompt hook from listing the other datasets — the skill flow is unaffected. The listing is cached in ~/.cognee-plugin/claude-code/readable-datasets.json and refreshed at most every COGNEE_DATASETS_CACHE_TTL seconds (default 300), within what is left of the recall budget, so a prompt never waits on it.

How It Works

The plugin registers Claude Code lifecycle hooks:

Hook	Fires	What it does
`SessionStart`	Session launch	Selects local or remote mode, sets up session identity, prepares the dataset, and starts the background idle watcher
`UserPromptSubmit`	Each prompt you submit	Recalls relevant, dataset-scoped context from Cognee and injects it, then stages the prompt in session memory in the background
`PreToolUse`	Before a `Read` call	Injects what the code graph knows about the file about to be read — see File context on Read. Never blocks or alters the read
`PostToolUse`	After a `Bash`, `Agent`, `Read`, `Write`, `Edit`, `Grep`, or `Glob` call	Stores the tool call as a trace entry in session memory, without blocking the tool. Other tools, MCP ones included, are not matched
`Stop`	Turn end	Stores the assistant’s answer in session memory, paired with the prompt it answered, and refreshes the credit balance the status line shows
`PreCompact`	Before context compaction	Builds a memory anchor so relevant context survives the compacted history
`SessionEnd`	Session exit	Starts a detached worker that runs the final sync of the session into your knowledge graph

A StopFailure hook refreshes the credit balance as well, so a turn that ends in an error still updates the line. 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. Stop carries one more command, off by default and meant for demos. Because a hook cannot call /clear itself, COGNEE_CLAUDE_CLEAR_AFTER_MESSAGE=true empties Claude Code’s transcript file after every answer and shows “Cognee demo: Claude transcript context was emptied.” The answer is saved from the hook payload rather than the transcript, so clearing doesn’t affect what reaches session memory. Turn it on to show that the plugin carries a conversation without the transcript. Each prompt then leans on what the recall hook injects, which on cognee 1.6.0 and later includes the session’s conversation history (see Reading the memory header). The cost is that the transcript file is overwritten with nothing and no copy is kept. From then on, all that remains of the conversation is what session memory captured, so leave it off for everyday work.

What gets captured

Automatic capture is what fills session memory: your prompts, the tool calls Claude makes, and its answers. Explicit requests — /cognee-memory:cognee-remember, or cognee-remember.sh — are independent of every switch below and always store what you asked for. Two filters run before a captured value is stored:

Credential paths are skipped entirely. A tool call whose path arguments point at .env, .env.*, *.pem, *.key, id_rsa*, id_ed25519*, .netrc, .npmrc, */.ssh/*, */.aws/credentials, *.p12, *.pfx, secrets.*, or credentials.* is not captured at all. Extend the list with COGNEE_CAPTURE_DENY_PATHS, and narrow which tools are captured at all with COGNEE_CAPTURE_TOOLS (pipe-separated names or globs).
Common secrets are redacted. Private key blocks, database connection URLs, Bearer and Basic credentials wherever they appear, secret / token / password / api_key assignments, vendor key prefixes (sk-, ghp_, xoxb-, whsec_, and similar) and bcrypt hashes become [redacted:<kind>], and a value under a credential-looking key is replaced wholesale with [redacted:credential]. This runs on prompts, traces, and answers alike, and before truncation — so a clipped secret cannot slip past the pattern that would have matched it. Add your own regexes with COGNEE_CAPTURE_REDACT_PATTERNS, or turn redaction off with COGNEE_CAPTURE_REDACT=false.

COGNEE_CAPTURE=false stops automatic capture altogether: nothing is captured, buffered, or replayed, while recall and explicit remember keep working. It does not erase memory already stored.

Redaction is best effort, and the path filter reads structured tool path arguments rather than arbitrary shell command text — a secret typed into a Bash command line is still captured. COGNEE_CAPTURE=false is the strict opt-out.

Session distillation (self-improvement)

The Cognee coding-agent plugins (Claude Code, Codex) run session distillation for you — you never call improve() by hand. A distillation pass fires on three triggers:

Trigger	When it fires	How
Session end	You quit the agent	The `SessionEnd` hook drains buffered turns into the server session cache, then fires `POST /api/v1/improve` for the session id in the background. A launch-exit watcher covers exits where the hook never fires — a hard exit, or Codex CLI shutdowns that skip `SessionEnd`.
Every N tool calls	Long sessions, incrementally	A per-session counter fires an improve every `COGNEE_AUTO_IMPROVE_EVERY` stored tool calls/stops (default 150), so a long session bridges into the graph without waiting for the end.
On idle	The session goes quiet	A background idle watcher polls every `COGNEE_IDLE_POLL` seconds and fires an improve after `COGNEE_IDLE_THRESHOLD` seconds of inactivity.

The idle and every-N triggers share one per-session cooldown: after an automatic improve, the next one waits at least COGNEE_IMPROVE_COOLDOWN seconds (default 1800, 30 minutes), and a failed attempt starts the same wait as a backoff. Session end, the sync skill, and a dataset switch improve regardless of it.

Overlapping triggers are safe. A per-session improve lock on the server serializes concurrent runs, and unchanged session content dedups server-side by content hash — so a repeat improve over content that hasn’t changed is a cheap no-op, not duplicated work.

Configuration

All triggers are tuned through environment variables read by the plugin. The defaults are chosen so distillation stays out of your way; you rarely need to change them.

Variable	Default	What it controls
`COGNEE_AUTO_IMPROVE_EVERY`	`150`	Stored tool calls/stops between automatic mid-session improves
`COGNEE_IDLE_THRESHOLD`	`60`	Seconds of inactivity before an idle improve fires
`COGNEE_IMPROVE_COOLDOWN`	`1800`	Minimum seconds between automatic (idle and every-N) improves of one session
`COGNEE_IDLE_POLL`	`10`	How often the idle watcher checks for inactivity
`COGNEE_IMPROVE_SUBMIT_TIMEOUT`	`420` (Claude Code) / `180` (Codex)	Read timeout for the improve POST (distillation runs inside the request). The Claude Code plugin raises this to `420` at startup to clear cognee’s LLM-retry floor; Codex uses the `180` fallback.
`COGNEE_IDLE_DISABLED`	unset	Set to `1` / `true` to turn off the idle-watcher trigger entirely

The plugin READMEs document additional advanced knobs — timing (poll deadlines, busy-retry intervals for a held session lock), session-sync retries, and the update-notification variables (COGNEE_UPDATE_CHECK, COGNEE_UPDATE_CHECK_INTERVAL). You almost never need them — reach for the table above first.

Turning it down or off

Stop idle-triggered improves: set COGNEE_IDLE_DISABLED=1 before launching the agent. Session-end and per-turn improves still run.
Reduce mid-session improves: raise COGNEE_AUTO_IMPROVE_EVERY to a large value so the per-turn trigger effectively never fires within a session.
Session-end distillation always runs when the plugin is active — it’s how a finished session reaches permanent memory.

Confirming it happened

Cloud UI: the Self-improvement card at the top of a session on the Sessions page shows the status of the last graph enrichment and the dataset it wrote to.
Plugin hook log: each automatic run emits an improve_fired event you can grep for when debugging (in local SDK mode, where the plugin calls the library directly instead of the HTTP endpoint, look for auto_improve_fired instead).
improve-unsupported.json marker: if this file appears in the plugin’s shared state directory (24h TTL), the server rejected the improve endpoint and the plugin fell back to the legacy remember bridge for that window — a signal the server predates session-aware improve.

Code graph

Repositories can be indexed into a deterministic code graph — symbols, calls, imports, endpoints, dependencies. Indexing makes no LLM or embedding calls by default, so it is fast and costs no tokens. It requires a Cognee server ≥ 1.5.4. Starting a session inside a git repository indexes it automatically — but only when the server is local, so a private checkout is never shipped to a hosted tenant on the plugin’s own initiative. Auto-indexing runs in the background, never blocks the first prompt, and re-indexes after any turn that changed the working tree. Index explicitly when automation won’t: against a Cloud tenant, for a different repo, or for a git URL. The simplest route is to ask the agent to index the repository — its code skill (/cognee-memory:cognee-code in Claude Code, codebase in Codex) runs this command:

${CLAUDE_PLUGIN_ROOT}/scripts/cognee-index-repo.sh <repo-path-or-git-url> [--dataset <name>] [--index-vectors] [--wait <seconds>]

The plugin-root variable is expanded only inside the plugin’s skills, so from your own terminal substitute the plugin’s install path. An explicit request is its own consent, so it bypasses every auto-index gate below. Add --index-vectors to also embed the extracted code facts so semantic search can see them — that is the one flag that makes embedding calls. Query the graph through the same code skill. Prompts that mention an identifier-shaped token from an indexed repo also get code facts injected automatically by the per-prompt recall hook. Each indexed repository gets its own dataset, named codebase-<repo-name>-<digest>, where the digest identifies the indexed path or git URL — two checkouts that share a basename would otherwise share one graph and delete each other’s nodes. Code-graph searches resolve the dataset from the current checkout, so the generated name rarely needs typing. Indexing writes its snapshot into the repository itself at <repo>/.enola/ (untracked) — add .enola/ to the repository’s .gitignore or your global excludes.

Freshness depends on where the server runs. A local server indexes the repository path on this machine, so the graph reflects your working tree, including uncommitted and untracked changes. A cloud or remote server clones a git URL — it cannot read your disk, so the graph reflects only the last pushed commit, and the plugin does not re-submit URL-indexed repositories after local edits. The output looks identical either way, so push before relying on code answers about work in progress, or use a local server for branches you are actively editing.

Env var	Default	Effect
`COGNEE_CODE_AUTOINDEX`	`auto`	`auto`: auto-index new repositories only when the server is local, so code never leaves the machine · `always`: also auto-index against a remote server — note that it submits the local path, which only a server sharing your filesystem can read, so a hosted tenant still needs an explicit git URL · `off`: never auto-index new repositories (explicitly indexed ones still refresh)

always also accepts 1, true, yes, and on; off also accepts 0, false, and no. Any other value means auto. Automatic indexing skips directories that are not git repositories, hold no source files, or exceed 3000 source files. Explicit indexing has no size cap.

Repository indexing needs a Cognee server ≥ 1.5.4: 1.5.4 renamed the field that carries the repository spec on /api/v1/remember to raw_data, and the plugin now sends only the new name. Local mode installs the pinned 1.6.0 server for you, so this only affects a remote or self-hosted deployment. When the server rejects an index request, the plugin reports the server’s own HTTP 400 verbatim; only the server’s “Unsupported content_type” wording is reported as a too-old deployment.

File context on Read

Before every Read of a source file inside a repository indexed from a local path, a PreToolUse hook injects what the code graph knows about that file: its symbols grouped by kind with line numbers, the cross-file calls it makes, and its imports. The model gets a map of the file before its contents, so it can jump to the right line and see which other files it leans on:

## Cognee: about base_config.py
Symbols in cognee/base_config.py (name:line):
  classes: BaseConfig:22
  functions: _tracing_explicitly_disabled:15 (private), get_base_config:168
  methods: BaseConfig.validate_personalization_knobs:60, BaseConfig.validate_paths:78, BaseConfig.to_dict:156
Calls out to: cognee/root_dir (ensure_absolute_path, get_absolute_path); cognee/shared/logging_utils (get_logger)
Imports: base64, cognee.modules.observability.observers, cognee.root_dir, ...
(Cognee file context — from the code graph; for callers or impact use `cognee-search.sh "<symbol>" --code`.)

The lookup is deterministic — a code-graph fact query filtered to the file, with no LLM or embedding call — and bounded by a time budget. A file is served again only after COGNEE_FILE_CONTEXT_TTL in the same session; a lookup that timed out or failed is retried on the next read. When the file changed after the repository was last indexed, the map notes that line numbers may have shifted. The hook stays silent for files outside every indexed repository, non-code files, credential paths, and while the server is known to be down. A repository indexed by git URL has no local path to match, so it gets no file context.

Env var	Default	Effect
`COGNEE_FILE_CONTEXT`	`true`	`false` turns the hook off
`COGNEE_FILE_CONTEXT_SCOPES`	`code`	Add `graph` (`code,graph`) to also inject up to 3 knowledge-graph hits about the file from the session dataset. The graph lane is not limited to indexed repositories or code files, and it costs a graph search on every first read of a file
`COGNEE_FILE_CONTEXT_BUDGET`	`3.0`	Seconds for the whole hook; a lane that cannot finish inside it is dropped
`COGNEE_FILE_CONTEXT_TTL`	`1800`	Seconds before the same file is served again in the same session
`COGNEE_FILE_CONTEXT_MAX_SYMBOLS`	`40`	Cap on listed symbols; the rest is summarized as a count

Debugging & Resuming Sessions

Hooks are callbacks from Claude Code, not a durable job queue: whatever happens while the plugin is uninstalled or failing never reaches it at all, and nothing replays it later. A backend the plugin cannot reach is the milder case — tool traces and answers are buffered on disk instead and replayed in order on a later prompt, so an outage costs you visibility rather than memory. (A prompt is staged locally and travels as the question half of that answer entry, so it is buffered along with it; there is just no separate buffered-prompt lane.) The memory header tells the two apart. When memory does not appear, check these layers first:

Layer	What it controls	How to verify
Claude Code hooks	Whether Claude Code calls the plugin on prompt submit, tool use, stop, compaction, and session end	Confirm the plugin is installed and the startup message says “Cognee Memory Connected”
Cognee backend	Where the plugin writes session memory and recalls graph context	In Cloud/remote mode, confirm `COGNEE_BASE_URL` and `COGNEE_API_KEY`; in local mode, confirm `LLM_API_KEY` is set, or that the diagnostic’s `LLM` row shows the Claude observer
Session identity	Which live session receives staged prompts, traces, and answers	A resume keeps the session on its own; when you expect two terminals to share one, confirm both set the same `COGNEE_SESSION_ID` and `COGNEE_PLUGIN_DATASET`
Mode	Which backend this terminal writes to and recalls from — memory written in one mode is not visible from the other	Read the mode field in the status line; if it is not what you expect, check for a forgotten `COGNEE_BACKEND` / `COGNEE_CLAUDE_BACKEND` export in the shell or in `~/.cognee/.env`, and see Which mode wins

A claude --resume of the same conversation continues the same live session on its own — the session id is derived from the Claude Code session, and a dataset chosen with /cognee-memory:cognee-switch-datasets is remembered too. COGNEE_SESSION_ID is what you need for the other case: making a second terminal, or a different conversation, write into one shared live session. Set it in both terminals and keep COGNEE_PLUGIN_DATASET the same, otherwise each lands in its own session. After changing credentials, dataset, or session id, restart Claude Code so SessionStart can run with the new state.

Hook commands run with python3, falling back to python if python3 isn’t found. Any Python 3.9 or newer will do — the hooks are stdlib-only HTTP clients and never import cognee, so the 3.9 that ships with macOS’s Command Line Tools is enough. Local mode does not run the server on it either: the plugin fetches uv into ~/.cognee-plugin/uv and builds its own Python 3.12 virtualenv, falling back to the host interpreter (3.10+) only when uv is neither present nor downloadable. If neither python3 nor python resolves on PATH — most commonly on Windows, where the python.org installer doesn’t always register a python3 alias — every hook fails and no memory is ever captured. Run python3 --version or python --version in the same shell that launches Claude Code to confirm one is available, or reinstall Python with “Add python.exe to PATH” checked.

Two failures that look the same from the outside were fixed in 1.5.7, so if you haven’t updated since, a plugin older than that is worth updating before debugging further. An install path containing a space used to kill every hook: hook commands run through a shell, the plugin root was interpolated unquoted, and the path word-split so the interpreter died on a truncated filename. Managed installs were the common case, because their default roots contain a space on both platforms. Only PreCompact was loud about it, failing so Claude Code refused to compact; everything else failed silently. Separately, on the Windows desktop app the session-exit watcher latched onto the short-lived hook runner rather than the Claude session, so the final sync ran seconds after launch and dropped the live connection. Since 1.6.1, a hook that crashes is reported rather than failing silently. Some installs made before 2026-09-27 also report 1.6.1 but predate this change, and Claude Code won’t offer them an update. If scripts/hook_runner.py is missing from your plugin root, reinstall the plugin. Every hook runs through scripts/hook_runner.py, which writes an uncaught exception’s traceback to ~/.cognee-plugin/claude-code/hook-crash.log and shows it as a one-line Cognee memory: hook <script> failed (...) message, once per hour for the same crash. The hook then exits 0, so the python fallback no longer runs it a second time. This also covers failures that happen before the hook’s own error handling runs, such as an import error or a Python older than 3.9. Before this change these exited with no traceback, and async hooks (prompt, tool, and Stop capture, and the credits refresh) showed nothing at all. If memory stops appearing, check that file first. The runner also switches the hooks’ input and output to UTF-8, because Windows pipes default to the ANSI code page. The plugin also ships a read-only diagnostic: "${CLAUDE_PLUGIN_ROOT}/scripts/cognee-doctor.sh" — ask Claude to run it, or substitute the plugin’s install path and run it from your own terminal (add --json for machine-readable output). It reports the resolved mode, which env file was read, the server URL and whether it answers, where the API key came from, whether memory is shared or separated, the local and server cognee versions, where the local server’s LLM calls go (a provider key or the Claude observer), the embedding model, and the circuit-breaker state. It never writes anything. For a clean handoff into long-term memory, run /cognee-memory:cognee-sync or exit Claude Code normally so SessionEnd can trigger the final graph sync. If the process is killed instead, recent session cache entries may exist, but the final session-to-graph sync may not have run yet.

Reading the memory header

Every prompt’s recalled context opens with a one-line header, which is the quickest read on whether memory is working:

Cognee memory: recall 1 memory; saved last turn 1 prompt / 3 trace / 1 answer

The recall count is how many memory blocks this turn’s lookup injected under === Cognee memory ===. The plugin makes one graph recall per prompt. On a cognee 1.6.0 or later server, each block is the full prompt cognee would have answered from: this session’s conversation history, the retrieved graph context, and the session’s agent guidance. It is injected whole, not truncated. An older server returns only the retrieved context. The header adds / N code whenever the prompt armed the code-graph lane, even when N is 0. saved last turn is what the previous turn wrote: the trace and answer counts are server-confirmed, while the prompt count is bumped as soon as the prompt is staged locally — which is why it still reads 1 in the outage line below. The same numbers are written to ~/.cognee-plugin/claude-code/last_recall.json, and per session under recall/. When the server cannot be reached, the header names the outage instead of going quiet:

Cognee memory: recall skipped (server unreachable); saved last turn 1 prompt / 0 trace / 0 answer; buffered last turn 6 trace / 1 answer (not saved yet); 7 awaiting replay, oldest 20d

Buffered writes are never counted as saved. They sit in ~/.cognee-plugin/claude-code/bridge/ and replay in order on a later prompt once the server answers again, so awaiting replay falling to zero is what confirms the backlog cleared. oldest is worth a look: a buffer belonging to an earlier session only drains when that session runs again, so entries can wait weeks with nothing pointing at them. Both segments disappear once the buffer has drained.

Configuration Reference

Precedence:

Environment variables (shell exports)
~/.cognee/.env — the one-time setup file, shared with the Codex plugin; loaded into the environment at process start, so every variable below except COGNEE_ENV_FILE itself can live in it
Defaults

The COGNEE_BACKEND / COGNEE_CLAUDE_BACKEND mode switch follows the same precedence — it is an ordinary variable, and a shell export of it beats a value in the file. What makes it special is its effect: wherever it is set, it pins the mode regardless of where the connection variables are defined.

There is no config.json. Older plugin versions wrote ~/.cognee-plugin/claude-code/config.json, and SessionStart read a base_url from it while the per-turn hooks did not — so a stale URL there could point the two halves of the plugin at different servers. SessionStart now deletes a leftover file. Put everything in ~/.cognee/.env instead.

Setting	Env var	Default	Notes
Dataset	`COGNEE_PLUGIN_DATASET`	`agent_sessions`	Dataset for writes and recall at launch; `/cognee-memory:cognee-switch-datasets` changes it mid-session
Session ID	`COGNEE_SESSION_ID`	derived from the Claude Code session	Override to pin a named session, or share one across terminals; normalized to `A-Za-z0-9._-` and capped at 120 characters. A mid-session dataset switch outranks it
Session prefix	`COGNEE_SESSION_PREFIX`	`claude`	Prefix on auto-derived session ids (`<prefix>_<claude-session-id>`)
Session strategy	`COGNEE_SESSION_STRATEGY`	`per-directory`	Currently inert — the plugin derives session ids from the Claude Code session and never reads this
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
Mode switch	`COGNEE_BACKEND`	unset	`local` or `cloud` — pins the terminal’s mode, overriding the URL rule; flips the Claude Code and Codex plugins
Mode switch (this plugin only)	`COGNEE_CLAUDE_BACKEND`	unset	Same, for this plugin only; beats `COGNEE_BACKEND`
Env file location	`COGNEE_ENV_FILE`	`~/.cognee/.env`	Read the one-time setup file from somewhere else
Login user	`COGNEE_USER_EMAIL`, `COGNEE_USER_PASSWORD`	`default_user@example.com`, `default_password`	User the plugin logs in as to mint an API key when `COGNEE_API_KEY` is unset; any user other than the default must already exist
Local API URL	`COGNEE_LOCAL_API_URL`	`http://localhost:8011`	Local API base URL
Local LLM	`LLM_API_KEY`, `LLM_MODEL`	unset	Without `LLM_API_KEY`, local mode uses the Claude observer when `claude` is on `PATH`; `LLM_MODEL` is optional
Claude observer	`COGNEE_LLM_OBSERVER`	`auto`	`auto`, `true`, or `false` — see the Claude observer for its other variables
Code auto-indexing	`COGNEE_CODE_AUTOINDEX`	`auto`	`auto`, `always`, or `off` — see Code graph
File context on Read	`COGNEE_FILE_CONTEXT`	`true`	`false` turns off the `PreToolUse` file map — see File context on Read
Other-datasets hint	`COGNEE_RECALL_DATASET_HINT`	`on`	Set `off` to stop the per-prompt hook from naming the other datasets you can search; the `/cognee-memory:cognee-search` flow is unaffected
Readable-datasets cache	`COGNEE_DATASETS_CACHE_TTL`	`300`	Seconds the cached listing behind that hint is served before one bounded refresh
Prefer Cognee memory	`COGNEE_PREFER_MEMORY`	`true`	Inject the SessionStart memory steer
Shared agent memory	`COGNEE_SHARED_AGENT_MEMORY`	`true`	All your Cognee plugins share one canonical dataset through a `cognee-agent` role; `false` separates them — see Sessions & datasets
Plugin identity	`COGNEE_PLUGIN_IDENTITY`	`auto`	`auto` provisions an agent sub-user only in service of shared memory; `true` always, `false` never
Automatic capture	`COGNEE_CAPTURE`	`true`	`false` stops automatic prompt, trace, and answer capture — see What gets captured
Capture deny paths	`COGNEE_CAPTURE_DENY_PATHS`	built-in credential patterns	Comma-separated patterns, or a JSON array, added to the built-in list
Capture redaction	`COGNEE_CAPTURE_REDACT`	`true`	`false` stores captured values unredacted; `COGNEE_CAPTURE_REDACT_PATTERNS` adds your own regexes
Update check	`COGNEE_UPDATE_CHECK`	on	`off` stops the hourly check behind the update notice — see Update or Remove
Status line	`COGNEE_STATUSLINE`	`true`	`false` stops the plugin auto-configuring the `cognee: <dataset> · <mode>` status line

Update or Remove

The plugin checks for a new version about once an hour. When one is published, the next session start shows “Cognee update available X → Y” and the status line shows an update badge. Nothing installs by itself: run /plugin update cognee-memory@cognee, or enable auto-update for the marketplace. Set COGNEE_UPDATE_CHECK=off to stop the check. If an update doesn’t take, reinstall:

claude plugin uninstall cognee-memory@cognee
claude plugin install cognee-memory@cognee

GitHub Repository

View source code and the full configuration reference

Codex plugin

The same memory plugin for the Codex CLI

Overview

Cloud LLM Providers

Observability

Evaluation

Data Ingestion

Agent Frameworks

Coding Agents

No-Code & Low-Code

Team Chat

Install

Configure your backend

Which mode wins, and how to switch

Local mode without an LLM key: the Claude observer

Use it

Sessions & datasets

How It Works

What gets captured

Session distillation (self-improvement)

Configuration

Turning it down or off

Confirming it happened

Code graph

File context on Read

Debugging & Resuming Sessions

Reading the memory header

Configuration Reference

Update or Remove

GitHub Repository

Codex plugin

​Install

​Configure your backend

​Which mode wins, and how to switch

​Local mode without an LLM key: the Claude observer

​Use it

​Sessions & datasets

​How It Works

​What gets captured

​Session distillation (self-improvement)

​Configuration

​Turning it down or off

​Confirming it happened

​Code graph

​File context on Read

​Debugging & Resuming Sessions

​Reading the memory header

​Configuration Reference

​Update or Remove

GitHub Repository

Codex plugin

Install

Configure your backend

Which mode wins, and how to switch

Local mode without an LLM key: the Claude observer

Use it

Sessions & datasets

How It Works

What gets captured

Session distillation (self-improvement)

Configuration

Turning it down or off

Confirming it happened

Code graph

File context on Read

Debugging & Resuming Sessions

Reading the memory header

Configuration Reference

Update or Remove