OpenClaw

Give your 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):

openclaw plugins install @cognee/cognee-openclaw@2026.6.11

Or install locally for development:

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:

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

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:

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"

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.

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 instead of a local instance, set mode to "cloud":

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

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.

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.

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:

<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

On startup: Health check, then scan memory/ and call /remember (one batched upload per scope). Cognee runs add + cognify + improve server-side.
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.
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.
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

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.

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 for details.

CLI Commands

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

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:

openclaw gateway stop && openclaw gateway start

Verifying the plugin can reach Cognee

Check connectivity and sync state:

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.

Manual fallback

Trigger the same sync autoIndex runs at any time:

openclaw cognee index

If this fails, verify baseUrl points to a reachable Cognee server and that your apiKey (or default credentials) are valid.

GitHub Repository

View source code and examples

Blog Post

Deep dive into building this plugin

OpenClaw Docs

Learn about OpenClaw’s memory system

Overview

Cloud LLM Providers

Observability

Evaluation

Data Ingestion

Agent Frameworks

Coding Agents

No-Code & Low-Code

Why Use This Integration

Installation

Quick Start

1. Start Cognee

2. Run setup

3. Configure the connection

Cognee Cloud

Multi-Scope Memory

How It Works

Configuration Reference

Connection

Search

Automation

Timeouts

Search Types

CLI Commands

Troubleshooting

GitHub Repository

Blog Post

OpenClaw Docs

​Why Use This Integration

​Installation

​Quick Start

​1. Start Cognee

​2. Run setup

​3. Configure the connection

​Cognee Cloud

​Multi-Scope Memory

​How It Works

​Configuration Reference

​Connection

​Search

​Automation

​Timeouts

​Search Types

​CLI Commands

​Troubleshooting

GitHub Repository

Blog Post

OpenClaw Docs

Why Use This Integration

Installation

Quick Start

1. Start Cognee

2. Run setup

3. Configure the connection

Cognee Cloud

Multi-Scope Memory

How It Works

Configuration Reference

Connection

Search

Automation

Timeouts

Search Types

CLI Commands

Troubleshooting