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

> Add persistent memory to OpenClaw agents with a Cognee plugin.

Give your [OpenClaw](https://github.com/openclaw/openclaw) agents Cognee-backed memory with **multi-scope support** (company / user / agent), session tracking, and automatic recall. The plugin indexes your Markdown memory files, recalls relevant context before each run, and searches across sessions with natural language.

## Why Use This Integration

* **Multi-scope memory**: Separate datasets for company-wide knowledge, per-user preferences, and per-agent context, routed automatically by file path
* **Auto-recall**: Relevant memories are injected as labeled `<cognee_memories>` context before every prompt
* **Auto-index**: Memory files sync to Cognee (add new, update changed, forget removed, skip unchanged)
* **Session tracking**: Each turn is captured in Cognee's session cache and bridged into the graph on session end
* **14 search types**: From semantic vector search to chain-of-thought graph reasoning
* **One-command setup**: `openclaw cognee setup` configures Cognee as the memory provider

## Installation

Once published, pin to an exact version (supply-chain best practice):

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

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

Run a local Cognee server with this [minimal Docker Compose file](https://github.com/topoteretes/cognee-integrations/blob/main/integrations/openclaw/cognee-docker-compose.yaml):

```bash theme={null}
export LLM_API_KEY="your-openai-api-key"
docker compose -f ./integrations/openclaw/cognee-docker-compose.yaml up -d
curl http://localhost:8000/health
```

### 2. Run setup

```bash theme={null}
openclaw cognee setup              # Cognee only (replaces built-in memory)
openclaw cognee setup --hybrid     # Keep built-in memory enabled in config
```

### 3. Configure the connection

Add the Cognee connection to `~/.openclaw/openclaw.json`:

```yaml theme={null}
plugins:
  entries:
    cognee-openclaw:
      enabled: true
      hooks:
        allowConversationAccess: true   # required for after-run file sync — see note
      config:
        baseUrl: "http://localhost:8000"
        apiKey: "${COGNEE_API_KEY}"
        datasetName: "my-project"
```

<Warning>
  OpenClaw ≥ 2026.4.27 blocks non-bundled plugins from registering the `agent_end` hook unless `hooks.allowConversationAccess: true` is set. Without it, file sync after each agent turn is silently disabled until the next manual `openclaw cognee index` or gateway start. Restart the gateway after adding the flag: `openclaw gateway stop && openclaw gateway start`.
</Warning>

That's it. Your OpenClaw memory files are now backed by Cognee's knowledge graph. If you omit `apiKey`, the plugin auto-logs in with the default local credentials (`default_user@example.com` / `default_password`).

## Cognee Cloud

To use [Cognee Cloud](/cognee-cloud/overview) instead of a local instance, set `mode` to `"cloud"`:

```yaml theme={null}
plugins:
  entries:
    cognee-openclaw:
      enabled: true
      config:
        mode: "cloud"
        baseUrl: "https://tenant-xxx.aws.cognee.ai/api"
        apiKey: "${COGNEE_API_KEY}"
```

<Info>
  Cloud mode supports `remember` (new files), `recall`, and per-item `forget`. Updating an existing file in place is **not** supported in cloud mode (`PATCH /update` is self-hosted only) — delete and re-add the file instead.
</Info>

## Multi-Scope Memory

For production use, enable multi-scope mode by setting any scope-specific dataset name. Memory files are routed to the right dataset by path.

```yaml theme={null}
plugins:
  entries:
    cognee-openclaw:
      enabled: true
      config:
        baseUrl: "http://localhost:8000"
        apiKey: "${COGNEE_API_KEY}"

        # Multi-scope datasets
        companyDataset: "acme-shared"
        userDatasetPrefix: "acme-user"
        agentDatasetPrefix: "acme-agent"
        userId: "${OPENCLAW_USER_ID}"
        agentId: "code-assistant"

        # Search all scopes during recall (in priority order)
        recallScopes:
          - agent
          - user
          - company

        defaultWriteScope: "agent"
```

| Scope       | Purpose                                     | Example files                  |
| ----------- | ------------------------------------------- | ------------------------------ |
| **Company** | Shared knowledge across all users/agents    | `memory/company/policies.md`   |
| **User**    | Per-user preferences, feedback, corrections | `memory/user/preferences.md`   |
| **Agent**   | Per-agent learned behaviors, tool outputs   | `memory/tools.md`, `MEMORY.md` |

Default routing: `memory/company/**` → company, `memory/user/**` → user, `memory/**` and `MEMORY.md` → agent (catch-all). Override it with a `scopeRouting` list of `{ pattern, scope }` rules.

During recall, each scope is searched independently and injected with labels:

```xml theme={null}
<cognee_memories>
  <agent_memory>[agent-specific results]</agent_memory>
  <user_memory>[user preference results]</user_memory>
  <company_memory>[shared knowledge results]</company_memory>
</cognee_memories>
```

## How It Works

1. **On startup**: Health check, then scan `memory/` and call `/remember` (one batched upload per scope). Cognee runs add + cognify + improve server-side.
2. **Before each prompt**: Call `/recall` for each configured scope in parallel, merge results with scope labels, and inject them as context. The session id is passed through so Cognee captures the turn as a session QA.
3. **After each agent run**: Re-scan memory files — new files batch into `/remember`, changed files go through `PATCH /update` (self-hosted), removed files are dropped via `/forget`.
4. **On session end**: Final sync sweep; with `improveOnSessionEnd` on, dispatches `/improve` for the ended session to bridge session QAs into the permanent graph.

State is tracked under `~/.openclaw/memory/cognee/` (`datasets.json`, `scoped-sync-indexes.json`, legacy `sync-index.json`). Files are stored using sanitized relative paths (e.g. `MEMORY.md.txt`, `memory.tools.md.txt`).

## Configuration Reference

### Connection

| Option    | Type   | Default                 | Description                                     |
| --------- | ------ | ----------------------- | ----------------------------------------------- |
| `baseUrl` | string | `http://localhost:8000` | Cognee API base URL                             |
| `apiKey`  | string | `$COGNEE_API_KEY`       | API key (optional; falls back to default login) |
| `mode`    | string | `local`                 | `local` or `cloud`                              |

### Search

| Option         | Type   | Default            | Description                              |
| -------------- | ------ | ------------------ | ---------------------------------------- |
| `searchType`   | string | `GRAPH_COMPLETION` | Search strategy (see below)              |
| `maxResults`   | number | `3`                | Max memories per scope (sent as `top_k`) |
| `minScore`     | number | `0.3`              | Minimum relevance score filter           |
| `searchPrompt` | string | `""`               | System prompt to guide search            |

### Automation

| Option                | Type    | Default | Description                                                  |
| --------------------- | ------- | ------- | ------------------------------------------------------------ |
| `autoRecall`          | boolean | `true`  | Inject memories before agent runs                            |
| `autoIndex`           | boolean | `true`  | Sync memory files on startup, after runs, and on session end |
| `improveOnSessionEnd` | boolean | `true`  | Bridge session-cache QAs into the graph on `session_end`     |

### Timeouts

| Option               | Type   | Default  | Description                          |
| -------------------- | ------ | -------- | ------------------------------------ |
| `requestTimeoutMs`   | number | `60000`  | HTTP timeout for general requests    |
| `ingestionTimeoutMs` | number | `300000` | HTTP timeout for add/update requests |

<Info>
  **Deprecated options** (silently ignored if set): `maxTokens` — use `maxResults`; `autoCognify` and `autoMemify` — now run server-side via `/remember`; `deleteMode` — `/forget` is always a soft delete.
</Info>

### Search Types

The plugin supports all of Cognee's search types, including `GRAPH_COMPLETION` (default), `GRAPH_COMPLETION_COT`, `GRAPH_COMPLETION_CONTEXT_EXTENSION`, `GRAPH_SUMMARY_COMPLETION`, `RAG_COMPLETION`, `TRIPLET_COMPLETION`, `CHUNKS`, `CHUNKS_LEXICAL`, `SUMMARIES`, `TEMPORAL`, `NATURAL_LANGUAGE`, `CYPHER`, `CODING_RULES`, and `FEELING_LUCKY` (auto-selects per query). See [Search Types](/core-concepts/main-operations/legacy-operations/search) for details.

## CLI Commands

```bash theme={null}
openclaw cognee setup                          # configure Cognee as the memory provider
openclaw cognee setup --hybrid                 # keep built-ins enabled in config
openclaw cognee index                          # manually sync memory files
openclaw cognee status                         # files indexed, dataset info, per-scope breakdown
openclaw cognee health                         # verify Cognee API connectivity
openclaw cognee scopes                         # show scope routing for current workspace files
openclaw cognee forget --dataset <name>        # wipe a dataset
openclaw cognee forget --everything --confirm  # wipe all of this user's data
openclaw cognee improve                        # bridge captured QAs into the permanent graph
openclaw cognee improve --session-id <id>      # scope to one session
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="File sync not running after each agent turn">
    OpenClaw ≥ 2026.4.27 requires `hooks.allowConversationAccess: true` under the plugin entry for the `agent_end` hook to register. Add it to `~/.openclaw/openclaw.json`, then restart the gateway:

    ```bash theme={null}
    openclaw gateway stop && openclaw gateway start
    ```
  </Accordion>

  <Accordion title="Verifying the plugin can reach Cognee">
    Check connectivity and sync state:

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

    Healthy status shows the dataset ID, indexed file count, and a recent last-sync timestamp. On the Cognee side, confirm the server logs show `Backend server has started` (Docker: `docker compose logs cognee`) before starting OpenClaw.
  </Accordion>

  <Accordion title="Manual fallback">
    Trigger the same sync `autoIndex` runs at any time:

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

    If this fails, verify `baseUrl` 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>