openclaw/docs/memory-cognee.md

---
summary: "Cognee knowledge graph memory: setup, Docker config, and usage"
read_when:
  - Setting up Cognee memory provider
  - Configuring knowledge graph memory
  - Running Cognee with Docker
---

# Cognee Memory Provider

Clawdbot supports **Cognee** as an optional memory provider. Unlike the default SQLite-based vector memory, Cognee builds a knowledge graph with entity extraction and semantic relationships, providing richer contextual memory for your AI agent.

## What is Cognee?

Cognee is an AI memory framework that:
- Extracts entities (people, places, concepts) from documents
- Builds a knowledge graph of relationships
- Enables semantic search with LLM-powered reasoning
- Supports multiple search modes (GRAPH_COMPLETION, chunks, summaries)

Learn more at [docs.cognee.ai](https://docs.cognee.ai/).

## Setup Options

### Option 1: Local Docker (Recommended)

Use the repo example compose file:

```bash
docker compose -f examples/cognee-docker-compose.yaml up -d
```

This binds to `127.0.0.1:8000`, so Cognee is only reachable from your machine.

**Verify:**

```bash
curl http://localhost:8000/health
```

### Option 2: Cognee Cloud

Use the hosted Cognee service:

1. Sign up at [platform.cognee.ai](https://platform.cognee.ai/)
2. Get your API key from the dashboard
3. Use base URL: `https://cognee--cognee-saas-backend-serve.modal.run`

## Configuration

Clawdbot reads `~/.clawdbot/clawdbot.json` (JSON5). For local + secure setup, use an env var for the Cognee token and reference it in config.

### Step 1: Put tokens in `examples/.env`

```bash
LLM_API_KEY="your-llm-api-key"
COGNEE_API_KEY="your-cognee-access-token"
CLAWDBOT_GATEWAY_TOKEN="your-random-gateway-token"
```

### Step 2: Configure Cognee in `~/.clawdbot/clawdbot.json`

```json5
{
  agents: {
    defaults: {
      memorySearch: {
        enabled: true,
        provider: "cognee",
        sources: ["memory", "sessions"],
        experimental: { sessionMemory: true },
        cognee: {
          baseUrl: "http://localhost:8000",
          apiKey: "${COGNEE_API_KEY}",
          datasetName: "clawdbot",
          searchType: "GRAPH_COMPLETION",
          maxResults: 6,
          autoCognify: true,
          timeoutSeconds: 180
        }
      }
    }
  }
}
```

### Step 3: Start the gateway with env loaded

```zsh
set -a; source "examples/.env"; set +a; pnpm clawdbot gateway --port 18789 --token "$CLAWDBOT_GATEWAY_TOKEN" --verbose
```

### Cloud Configuration (tbt)

```yaml
agents:
  defaults:
    memorySearch:
      enabled: true
      provider: cognee
      sources: [memory, sessions]
      cognee:
        baseUrl: https://cognee--cognee-saas-backend-serve.modal.run
        apiKey: your-api-key-here  # Required for cloud
        datasetName: clawdbot
        searchType: GRAPH_COMPLETION
        maxResults: 8
        autoCognify: true
        timeoutSeconds: 60
```

## Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `baseUrl` | string | `http://localhost:8000` | Cognee API endpoint |
| `apiKey` | string | - | Access token (required if Cognee auth is enabled) |
| `datasetName` | string | `"clawdbot"` | Dataset name for organizing memories |
| `searchType` | string | `"GRAPH_COMPLETION"` | Search mode: `GRAPH_COMPLETION`, `chunks`, or `summaries` |
| `maxResults` | number | `6` | Maximum search results returned |
| `autoCognify` | boolean | `true` | Auto-process documents after adding |
| `cognifyBatchSize` | number | `100` | Batch size for processing |
| `timeoutSeconds` | number | `180` | Request timeout in seconds |

## Search Types

Cognee offers these modes:

### GRAPH_COMPLETION
Best for: **High-level understanding and reasoning**
- Returns graph-completion outputs over the knowledge graph
- Good for: "What projects am I working on?" or "Summarize my notes about X"

### Chunks
Best for: **Specific text matching**
- Returns raw document chunks
- Similar to traditional vector search
- Good for: Finding exact quotes or specific information

### Summaries
Best for: **Document overviews**
- Returns condensed summaries
- Good for: Quick scanning of content

## Usage

### Memory Files

Cognee automatically syncs your memory files:
- `MEMORY.md` or `memory.md` in workspace root
- All `*.md` files in `memory/` directory

### Session Transcripts (Optional)

Enable session memory to index conversation history:

```yaml
agents:
  defaults:
    memorySearch:
      provider: cognee
      sources: [memory, sessions]  # Include sessions
      experimental:
        sessionMemory: true
```

### Manual Sync and Status

```bash
# Force sync + cognify for the current agent
clawdbot memory status --index --json
```

## How It Works

1. **Add**: Memory files are sent to Cognee with metadata
2. **Cognify**: Cognee processes documents:
   - Extracts entities (people, places, concepts)
   - Identifies relationships
   - Builds knowledge graph
3. **Search**: Agent queries use semantic search:
   - Searches knowledge graph
   - Returns relevant insights/chunks/summaries
   - Includes metadata and scores

## Comparison: Cognee vs SQLite Memory

| Feature | Cognee | SQLite (Default) |
|---------|--------|------------------|
| **Setup** | Requires Docker/cloud | Built-in, no setup |
| **Offline** | No (needs service) | Yes (fully local) |
| **Search** | Knowledge graph + LLM | Vector + BM25 hybrid |
| **Entities** | Extracted automatically | Not available |
| **Relationships** | Yes (graph-based) | No |
| **Speed** | Slower (API calls) | Faster (local DB) |
| **Memory** | Stored externally | SQLite file |
| **Best for** | Rich context, reasoning | Fast lookup, privacy |

## Troubleshooting

### Connection Failed

**Error**: `Failed to connect to Cognee at http://localhost:8000`

**Solutions**:
1. Verify Docker is running: `docker ps | grep cognee`
2. Check Cognee logs: `docker logs cognee`
3. Test manually: `curl http://localhost:8000/health`
4. Ensure port 8000 is not blocked

### Slow Performance

**Solutions**:
1. Reduce `maxResults` (try 3-5 instead of 10+)
2. Use `searchType: "chunks"` for faster results
3. Set `autoCognify: false` and cognify manually
4. Check Docker resource limits

### Out of Memory

**Solutions**:
1. Increase Docker memory limit (Docker Desktop settings)
2. Reduce `cognifyBatchSize` (try 50 instead of 100)
3. Process fewer files at once
4. Clear old datasets via Cognee API

### 401 Unauthorized (Cognee auth)

**Cause**: Cognee auth is enabled, but Clawdbot is missing/using an invalid `COGNEE_API_KEY`.

**Fix**:
1. Log in to Cognee and get a fresh access token.
2. Update `COGNEE_API_KEY` in `examples/.env`.
3. Restart the gateway with env loaded (see Step 3 above).

## Advanced Configuration

### Per-Agent Override

```yaml
agents:
  defaults:
    memorySearch:
      provider: openai  # Default for all agents

  agents:
    research-bot:
      memorySearch:
        provider: cognee  # Override for this agent
        cognee:
          searchType: GRAPH_COMPLETION
          maxResults: 10
```

### Hybrid Setup (Not Yet Supported)

Future versions may support using both Cognee and SQLite:
- Cognee for semantic understanding
- SQLite for fast local lookup

## Docker Production Tips

### Health Checks

Add health checks to docker-compose.yml:

```yaml
services:
  cognee:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
```

### Resource Limits

```yaml
services:
  cognee:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 4G
        reservations:
          cpus: '1'
          memory: 2G
```

### Persistent Storage

Mount volumes for persistence:

```yaml
volumes:
  - ./cognee_data:/app/cognee/.cognee_system
  - ./cognee_logs:/app/logs
```

## Roadmap

Planned features:
- [ ] Hybrid mode (Cognee + SQLite)
- [ ] Graph visualization export
- [ ] Manual entity management

## Resources

- [Cognee Documentation](https://docs.cognee.ai/)
- [Cognee GitHub](https://github.com/topoteretes/cognee)
- [Clawdbot Memory Guide](/memory)
- [Docker Setup Guide](/install/docker)

## Feedback

Cognee integration is new. Report issues at:
- Clawdbot: [github.com/clawdbot/clawdbot/issues](https://github.com/clawdbot/clawdbot/issues)
- Cognee: [github.com/topoteretes/cognee/issues](https://github.com/topoteretes/cognee/issues)