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 (insights, chunks, summaries)

Learn more at docs.cognee.ai.

Setup Options

Option 1: Local Docker (Recommended)

Run Cognee locally using Docker Compose:

Step 1: Create docker-compose.yml

version: '3.8'

services:
  cognee:
    image: topoteretes/cognee:latest
    container_name: cognee
    ports:
      - "8000:8000"
    environment:
      # Optional: Set API key for authentication
      - COGNEE_API_KEY=your-local-api-key
      # Database configuration
      - DATABASE_URL=postgresql://cognee:cognee@postgres:5432/cognee
    volumes:
      - cognee_data:/app/data
    depends_on:
      - postgres
    restart: unless-stopped

  postgres:
    image: postgres:15-alpine
    container_name: cognee-postgres
    environment:
      - POSTGRES_USER=cognee
      - POSTGRES_PASSWORD=cognee
      - POSTGRES_DB=cognee
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: unless-stopped

volumes:
  cognee_data:
  postgres_data:

Step 2: Start Cognee

docker-compose up -d

Step 3: Verify

curl http://localhost:8000/status
# Should return: {"status":"healthy"}

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

Add Cognee memory configuration to your ~/.clawdbot/config.yaml:

Basic Configuration (Docker Local)

agents:
  defaults:
    memorySearch:
      enabled: true
      provider: cognee
      sources: [memory]  # or [memory, sessions]
      cognee:
        baseUrl: http://localhost:8000
        datasetName: clawdbot
        searchType: insights  # or "chunks", "summaries"
        maxResults: 6
        autoCognify: true

Cloud Configuration

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: insights
        maxResults: 8
        autoCognify: true
        timeoutSeconds: 60

Configuration Options

Option	Type	Default	Description
baseUrl	string	http://localhost:8000	Cognee API endpoint
apiKey	string	-	API key (required for cloud, optional for local)
datasetName	string	"clawdbot"	Dataset name for organizing memories
searchType	string	"insights"	Search mode: insights, 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	30	Request timeout in seconds

Search Types

Cognee offers three search modes:

Insights (Recommended)

Best for: High-level understanding and reasoning

• Returns AI-generated insights from knowledge graph
• Combines multiple related facts
• 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

Force a memory sync:

# Not yet implemented - coming soon
clawdbot memory sync --provider cognee

Check Status

# Not yet implemented - coming soon
clawdbot memory status --provider cognee

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/status
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

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: insights
          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/status"]
      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/data
  - ./cognee_logs:/app/logs

Roadmap

Planned features:

• clawdbot memory status --provider cognee command
• clawdbot memory sync --provider cognee command
• 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