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

# OpenClaw

Give your [OpenClaw](https://github.com/openclaw/openclaw) agents persistent memory via plugin powered by cognee. Automatically index memory files, recall relevant context before each agent run, and search across sessions with natural language.

## Why Use This Integration

* **Auto-Index**: Memory files sync to Cognee on startup and after each agent run (add new, update changed, delete removed, skip unchanged)
* **Auto-Recall**: Relevant memories are injected as context before every prompt
* **Graph Search**: Natural language queries powered by knowledge graph traversal
* **Deletion Tracking**: Removed memory files are automatically cleaned up from Cognee during indexing
* **Zero Friction**: Works with OpenClaw's native Markdown memory files

## Installation

```bash theme={null}
openclaw plugins install @cognee/cognee-openclaw
```

Or install locally for development:

```bash theme={null}
cd integrations/openclaw
npm install && npm run build
openclaw plugins install -l .
```

## Quick Start

### 1. Start Cognee

Use the [Local Docker setup](/api-reference/introduction) to run Cognee quickly.
You can also use this [minimal Docker Compose file](https://github.com/topoteretes/cognee-integrations/blob/main/integrations/openclaw/cognee-docker-compose.yaml).

### 2. Authentication

Register a user and login to get your bearer token:

```bash theme={null}
# Register a new user
curl -X POST "http://localhost:8000/api/v1/users/register" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'

# Login to get your bearer token
curl -X POST "http://localhost:8000/api/v1/users/login" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'
```

The login response contains your bearer token — use this as your `COGNEE_API_KEY`.

<Info>
  You can also explore the API at [http://localhost:8000/docs](http://localhost:8000/docs) (Swagger UI) to register and login interactively.

  If token is not provided, the plugin authenticates via Cognee's login endpoint (`/api/v1/auth/login`). By default it uses `default_user@example.com` / `default_password`, which works out of the box with a local Cognee instance — no configuration needed.
</Info>

### 3. Enable the Plugin

Add to `~/.openclaw/config.yaml`:

```yaml theme={null}
plugins:
  entries:
    cognee-openclaw:
      enabled: true
      config:
        baseUrl: "http://localhost:8000"
        apiKey: "${COGNEE_API_KEY}"
        datasetName: "my-project"
        searchType: "GRAPH_COMPLETION"
        autoRecall: true
        autoIndex: true
```

<Info>
  You can omit `apiKey` entirely — the plugin will auto-login with the default user.
</Info>

That's it. Your OpenClaw memory files are now backed by Cognee's knowledge graph.

## How It Works

Memory persists across OpenClaw sessions automatically. The plugin syncs your `MEMORY.md` and `memory/*.md` files to Cognee, building a knowledge engine for your Claw that can traverse relationships between documents, concepts and evolve over time.

1. **On Startup**: Scans memory directory and syncs files to Cognee (add new, update changed, delete removed, skip unchanged)
2. **Before Agent Run**: Searches Cognee for memories relevant to your prompt and injects them as `<cognee_memories>` context
3. **After Agent Run**: Re-scans memory files and syncs any changes the agent made, including detecting deleted files
4. **State Tracking**: Maintains sync state at `~/.openclaw/memory/cognee/`:
   * `datasets.json` — dataset ID mapping
   * `sync-index.json` — per-file content hash and Cognee data IDs

<Info>
  The plugin uses hash-based change detection to minimize API calls. Only new or modified files are synced. For changed files with a known data ID, the plugin uses Cognee's update endpoint.
</Info>

## Configuration Reference

| Option               | Type    | Default                    | Description                                                                   |
| -------------------- | ------- | -------------------------- | ----------------------------------------------------------------------------- |
| `baseUrl`            | string  | `http://localhost:8000`    | Cognee API base URL                                                           |
| `apiKey`             | string  | `$COGNEE_API_KEY`          | Bearer token for authentication (optional if using default username/password) |
| `username`           | string  | `default_user@example.com` | Cognee login username(if COGNEE\_API\_KEY is not provided)                    |
| `password`           | string  | `default_password`         | Cognee login password (if COGNEE\_API\_KEY is not provided)                   |
| `datasetName`        | string  | `openclaw`                 | Dataset name for storing memories                                             |
| `searchType`         | string  | `GRAPH_COMPLETION`         | Search mode (see below)                                                       |
| `searchPrompt`       | string  | `""`                       | System prompt sent to Cognee to guide search query processing                 |
| `deleteMode`         | string  | `soft`                     | `soft` removes raw data only; `hard` also removes degree-one graph nodes      |
| `maxResults`         | number  | `6`                        | Max memories to inject per recall                                             |
| `minScore`           | number  | `0`                        | Minimum relevance score filter                                                |
| `maxTokens`          | number  | `512`                      | Token cap for recall context                                                  |
| `autoRecall`         | boolean | `true`                     | Inject memories before each agent run                                         |
| `autoIndex`          | boolean | `true`                     | Sync memory files on startup and after agent runs                             |
| `autoCognify`        | boolean | `true`                     | Run cognify after new memories are added                                      |
| `requestTimeoutMs`   | number  | `60000`                    | HTTP timeout for general Cognee requests (ms)                                 |
| `ingestionTimeoutMs` | number  | `300000`                   | HTTP timeout for add/update (ingestion) requests (ms)                         |

### Search Types

Available search types for the `searchType` option:

* `GRAPH_COMPLETION` — traverses the knowledge graph and generates a completion-style answer
* `CHUNKS` — returns matching text chunks from ingested content
* `SUMMARIES` — returns summary-level results

You can learn more in [Search Types](/core-concepts/main-operations/legacy-operations/search) and extend these if you want from the source.

### Delete Modes

When memory files are removed from disk, the plugin deletes them from Cognee:

* `soft` — removes only the raw data from Cognee (default)
* `hard` — also removes degree-one graph nodes connected to the deleted data

## CLI Commands

```bash theme={null}
# Manually sync memory files to Cognee
openclaw cognee index

# Check sync status (indexed files, pending changes, dataset info)
openclaw cognee status
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="autoIndex not triggering after upgrade">
    If memory files stopped syncing at gateway startup after upgrading to OpenClaw v2026.4.5 and cognee-openclaw 2026.3.4, first verify the installed plugin version:

    ```bash theme={null}
    openclaw plugins list
    ```

    Confirm `cognee-openclaw@2026.3.4` (or later) is listed. If not, reinstall:

    ```bash theme={null}
    openclaw plugins install @cognee/cognee-openclaw@latest
    ```

    Then verify your `~/.openclaw/config.yaml` still includes `autoIndex: true` under the plugin's `config` block — the upgrade does not migrate existing config files automatically.
  </Accordion>

  <Accordion title="Verifying the auto-sync service is running">
    After starting OpenClaw, check sync state with:

    ```bash theme={null}
    openclaw cognee status
    ```

    Healthy output shows the dataset ID, number of indexed files, and a recent last-sync timestamp. If the file count is `0` while memory files exist on disk, the startup sync did not run.

    On the Cognee side, confirm the server is ready by looking for this line in its logs (Docker: `docker compose logs cognee`):

    ```
    Backend server has started
    ```

    If this line is absent, Cognee is not yet accepting requests. Wait for it to finish initializing before starting OpenClaw.
  </Accordion>

  <Accordion title="Manual fallback">
    You can trigger the same sync that `autoIndex` runs at any time:

    ```bash theme={null}
    openclaw cognee index
    ```

    This is useful both as a workaround and to verify the plugin can reach your Cognee instance. If this command fails, check that `baseUrl` in your config points to a reachable Cognee server and that your `apiKey` (or default credentials) are valid.
  </Accordion>
</AccordionGroup>

***

<CardGroup cols={3}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/topoteretes/cognee-integrations/tree/main/integrations/openclaw">
    View source code and examples
  </Card>

  <Card title="Blog Post" icon="newspaper" href="https://www.cognee.ai/blog/integrations/what-is-openclaw-ai-and-how-we-give-it-memory-with-cognee">
    Deep dive into building this plugin
  </Card>

  <Card title="OpenClaw Docs" icon="book" href="https://docs.openclaw.ai/concepts/memory">
    Learn about OpenClaw's memory system
  </Card>
</CardGroup>