openclaw/docs/memory-cognee.md

summary	read_when
Cognee knowledge graph memory: setup, Docker config, and usage	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.

Setup Options

Option 1: Local Docker (Recommended)

Use the repo example compose file:

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:

curl http://localhost:8000/health

Option 2: Cognee Cloud

Use the hosted Cognee service:

1. Sign up at 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

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

{
  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

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

Cloud Configuration (tbt)

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:

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

Manual Sync and Status

# 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

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:

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

Resource Limits

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

Persistent Storage

Mount volumes for persistence:

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
• Cognee GitHub
• Clawdbot Memory Guide
• Docker Setup Guide

Feedback

Cognee integration is new. Report issues at:

• Clawdbot: github.com/clawdbot/clawdbot/issues
• Cognee: github.com/topoteretes/cognee/issues