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

MoltBot 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 open source AI memory framework that:

• Ingests unstructured/structured data from 30+ sources
• Extracts entities (people, places, concepts) from documents
• Builds a knowledge graph of relationships backed by embeddings
• Enables semantic search with LLM-powered reasoning
• Supports multiple search modes (e.g., 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

You can use http://localhost:8000/docs to register user and login to get your token.

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

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

Step 1: Put tokens in ~/.clawdbot/.env

COGNEE_API_KEY="your-cognee-access-token"
CLAWDBOT_GATEWAY_TOKEN="your-random-gateway-token"

Step 2: Configure Cognee in ~/.clawdbot/moltbot.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 "$HOME/.clawdbot/.env"; set +a
pnpm moltbot gateway --port 18789 --token "$CLAWDBOT_GATEWAY_TOKEN" --verbose

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 is the default mode.

Learn more from cognee documentation

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

# Manually sync cognee memory for the current agent
pnpm moltbot 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	Yes (Optional cloud)	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 locally (Optional cognee configs)	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 Moltbot 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 .clawd/.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

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

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