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

# Claude Code

> Give Claude Code persistent memory with the Cognee plugin.

Add persistent memory to [Claude Code](https://www.anthropic.com/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):

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

Set environment variables in the shell that launches Claude Code.

<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/claude-code/config.json`:

```json theme={null}
{
  "base_url": "https://your-tenant.aws.cognee.ai",
  "dataset": "agent_sessions"
}
```

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

To verify the connection, open a fresh session and ask: *"What do you know from cognee?"*

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

## 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 Claude Code and Codex plugins share the default dataset, so memory carries across both.

## How It Works

The plugin registers Claude Code lifecycle hooks:

| Hook               | Behavior                                                          |
| ------------------ | ----------------------------------------------------------------- |
| `SessionStart`     | mode select, identity setup, dataset readiness, watcher bootstrap |
| `UserPromptSubmit` | dataset-scoped 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/claude-code/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                 |
| Prefer Cognee memory | `COGNEE_PREFER_MEMORY`     | `true`                  | Inject the SessionStart memory steer    |

## Update or Remove

There's no automatic update — reinstall to pull a new plugin version:

```bash theme={null}
claude plugin uninstall cognee-memory@cognee
claude plugin install cognee-memory@cognee
```

***

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

  <Card title="Codex plugin" icon="terminal" href="/integrations/codex-integration">
    The same memory plugin for the Codex CLI
  </Card>
</CardGroup>