Cómo autoalojar Cognee con Dokploy o Docker Compose

Si estás construyendo aplicaciones de IA que necesitan memoria persistente y grafos de conocimiento, Cognee es una plataforma open source que merece la pena conocer. Convierte tus datos en grafos de conocimiento estructurados con búsqueda semántica, y funciona bien para aplicaciones RAG, chatbots y asistentes de IA. Autoalojarlo significa que los datos son tuyos y los costes se mantienen predecibles.

En esta guía te enseño a autoalojar Cognee en tu propia infraestructura usando Dokploy o Docker Compose. Montaremos un despliegue listo para producción con PostgreSQL y pgvector tanto para los metadatos como para el almacenamiento vectorial, usando OpenAI para el modelo de embeddings, además del servidor MCP para la integración con asistentes de IA.

¿Qué es Cognee?

Cognee es una plataforma de memoria para IA que organiza tus datos en grafos de conocimiento. Donde las bases de datos vectoriales se quedan en la búsqueda por similitud, Cognee mapea las relaciones entre tus puntos de datos para que las aplicaciones de IA puedan recuperar información conectada y razonar sobre ella.

Características principales de Cognee

¿Por qué autoalojar Cognee?

Ventajas del autoalojamiento:

• Privacidad total de los datos: tus documentos y embeddings nunca salen de tu infraestructura
• Sin límites de uso ni costes por usuario más allá de lo que cobre tu proveedor de LLM
• Control total sobre la elección de modelo, embeddings y almacenamiento
• Se integra con redes privadas, servicios internos y tu sistema de backups actual

Casos de uso:

• Crear asistentes de IA con memoria a largo plazo (si buscas una alternativa más ligera, también puedes desplegar la memoria para agentes Hindsight en Docker)
• Aplicaciones RAG; para un ejemplo práctico, mira cómo crear agentes de IA con memoria y RAG
• Herramientas de análisis de código y documentación
• Gestión del conocimiento y búsqueda con IA sobre documentos internos

Prerrequisitos

Antes de empezar, asegúrate de tener:

Los precios de los VPS subieron en todos los proveedores en 2026 — si estás reconsiderando una máquina alquilada, mira qué cambió y cuándo gana un mini PC.

Entender la arquitectura de almacenamiento

Antes de desplegar, ayuda ver cómo encajan las piezas:

Diagrama de despliegue de Cognee autoalojado con Dokploy, Docker Compose, PostgreSQL, pgvector y servidor MCP

Opción 1: Desplegar con Dokploy

Dokploy es una Plataforma como Servicio (PaaS) open source que simplifica el despliegue de aplicaciones Docker. Si aún no has configurado Dokploy, consulta nuestra guía de instalación de Dokploy.

Paso 1: Instalar Dokploy

Si aún no lo tienes instalado:

curl -sSL https://dokploy.com/install.sh | sh

Accede a Dokploy en http://your-vps-ip:3000 y completa la configuración.

Paso 2: Crear un proyecto nuevo

1. Inicia sesión en el panel de Dokploy
2. Haz clic en “Create Project” y dale un nombre (p. ej., “Cognee”)
3. Dentro del proyecto, haz clic en “Add Service” → “Compose”
4. Selecciona el tipo “Docker Compose” (no Stack)
5. Nómbralo “cognee-stack”

Paso 3: Añadir la configuración de Docker Compose

Ve a la pestaña General y pega la siguiente configuración de Docker Compose. Si te atascas con la parte de Dokploy, el tutorial sobre cómo desplegar una app de Docker Compose en Dokploy cubre el flujo de la interfaz en detalle.

services:
  cognee:
    image: cognee/cognee:main
    networks:
      - dokploy-network
      - cognee-network
    volumes:
      - cognee-data:/app/.cognee_system
    environment:
      - HOST=0.0.0.0
      - ENVIRONMENT=production
      - LOG_LEVEL=INFO
      # Authentication (REQUIRED for public deployment)
      - REQUIRE_AUTHENTICATION=true
      # LLM Configuration
      - LLM_API_KEY=${LLM_API_KEY}
      - LLM_PROVIDER=${LLM_PROVIDER:-openai}
      - LLM_MODEL=${LLM_MODEL:-gpt-4o-mini}
      # Embedding Configuration (OpenAI)
      - EMBEDDING_PROVIDER=${EMBEDDING_PROVIDER:-openai}
      - EMBEDDING_MODEL=${EMBEDDING_MODEL:-openai/text-embedding-3-small}
      - EMBEDDING_DIMENSIONS=${EMBEDDING_DIMENSIONS:-1536}
      - EMBEDDING_API_KEY=${LLM_API_KEY}
      # Database Configuration (PostgreSQL for relational data)
      - DB_PROVIDER=postgres
      - DB_HOST=cognee-postgres
      - DB_PORT=5432
      - DB_NAME=cognee_db
      - DB_USERNAME=cognee
      - DB_PASSWORD=${DB_PASSWORD}
      # Vector Database (pgvector - uses SAME PostgreSQL instance)
      - VECTOR_DB_PROVIDER=pgvector
      # Graph Database (default Kuzu - file-based)
      - GRAPH_DATABASE_PROVIDER=${GRAPH_DATABASE_PROVIDER:-kuzu}
    depends_on:
      cognee-postgres:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    deploy:
      resources:
        limits:
          cpus: "2.0"
          memory: 4GB

  cognee-mcp:
    image: cognee/cognee-mcp:main
    networks:
      - dokploy-network
      - cognee-network
    environment:
      - TRANSPORT_MODE=http
      - API_URL=http://cognee:8000
      - LOG_LEVEL=INFO
    depends_on:
      cognee:
        condition: service_healthy
    restart: unless-stopped

  cognee-postgres:
    image: pgvector/pgvector:pg17
    networks:
      - cognee-network
    environment:
      - POSTGRES_USER=cognee
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=cognee_db
    volumes:
      - cognee-postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U cognee -d cognee_db"]
      interval: 5s
      timeout: 5s
      retries: 5
    restart: unless-stopped

networks:
  cognee-network:
    name: cognee-network
  dokploy-network:
    external: true

volumes:
  cognee-data:
  cognee-postgres-data:

Paso 4: Configurar las variables de entorno

Ve a la pestaña Environment y añade estas variables:

# OpenAI API Key (required for LLM and embeddings)
LLM_API_KEY=sk-your-openai-api-key-here

# Database Password (generate a strong password)
DB_PASSWORD=your-secure-database-password-here

# Optional: LLM Configuration
LLM_PROVIDER=openai
LLM_MODEL=gpt-4o-mini

# Optional: Embedding Configuration
EMBEDDING_PROVIDER=openai
EMBEDDING_MODEL=openai/text-embedding-3-small
EMBEDDING_DIMENSIONS=1536

# Optional: Graph Database (kuzu is default, can use neo4j or falkordb)
GRAPH_DATABASE_PROVIDER=kuzu

Genera una contraseña segura para la base de datos:

openssl rand -base64 32

Paso 5: Configurar el DNS

Antes de desplegar, configura tus registros DNS tipo A:

1. cognee.yourdomain.com → La IP de tu VPS
2. mcp.yourdomain.com → La IP de tu VPS

Paso 6: Desplegar y configurar los dominios

1. Haz clic en “Deploy” y espera a que arranquen los servicios
2. Vigila los logs en la pestaña Deployments o Logs
3. Ve a la pestaña Domains y añade los dominios para cada servicio (ver notas anteriores)
4. Espera unos 30 segundos a que Traefik genere los certificados SSL

Una vez desplegado, verifica:

# Check API health (expect HTTP 200)
curl https://cognee.yourdomain.com/health

# Per-component status (database, vector store, etc.)
curl https://cognee.yourdomain.com/health/detailed

# Check MCP health
curl https://mcp.yourdomain.com/health

# Access API documentation
open https://cognee.yourdomain.com/docs

Si /health devuelve 200, todo va bien. Si se queda colgado o devuelve 502, el contenedor aún está arrancando o se ha caído; revisa la pestaña Logs en Dokploy. Si /health/detailed marca algún componente como caído, normalmente significa que las credenciales o el host de la base de datos no coinciden, que es la primera entrada de la sección de solución de problemas.

Opción 2: Desplegar solo con Docker Compose

Para un control más manual o para prescindir de Dokploy, así se despliega directamente con Docker Compose.

Paso 1: Preparar el servidor

Actualiza el sistema e instala Docker:

# Update packages
sudo apt update && sudo apt upgrade -y

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Install Docker Compose plugin
sudo apt install docker-compose-plugin -y

Paso 2: Crear el directorio del proyecto

mkdir -p ~/cognee
cd ~/cognee

Paso 3: Crear el archivo Docker Compose

nano docker-compose.yml

Pega la siguiente configuración:

services:
  cognee:
    image: cognee/cognee:main
    container_name: cognee
    networks:
      - cognee-network
    volumes:
      - cognee-data:/app/.cognee_system
    environment:
      - HOST=0.0.0.0
      - ENVIRONMENT=production
      - LOG_LEVEL=INFO
      # Authentication (REQUIRED for public deployment)
      - REQUIRE_AUTHENTICATION=true
      # LLM Configuration
      - LLM_API_KEY=${LLM_API_KEY}
      - LLM_PROVIDER=${LLM_PROVIDER:-openai}
      - LLM_MODEL=${LLM_MODEL:-gpt-4o-mini}
      # Embedding Configuration (OpenAI)
      - EMBEDDING_PROVIDER=${EMBEDDING_PROVIDER:-openai}
      - EMBEDDING_MODEL=${EMBEDDING_MODEL:-openai/text-embedding-3-small}
      - EMBEDDING_DIMENSIONS=${EMBEDDING_DIMENSIONS:-1536}
      - EMBEDDING_API_KEY=${LLM_API_KEY}
      # Database Configuration (PostgreSQL for relational data)
      - DB_PROVIDER=postgres
      - DB_HOST=postgres
      - DB_PORT=5432
      - DB_NAME=cognee_db
      - DB_USERNAME=cognee
      - DB_PASSWORD=${DB_PASSWORD}
      # Vector Database (pgvector - uses SAME PostgreSQL instance)
      - VECTOR_DB_PROVIDER=pgvector
      # Graph Database
      - GRAPH_DATABASE_PROVIDER=${GRAPH_DATABASE_PROVIDER:-kuzu}
    ports:
      - "8000:8000"
    depends_on:
      postgres:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    restart: unless-stopped
    deploy:
      resources:
        limits:
          cpus: "2.0"
          memory: 4GB

  cognee-mcp:
    image: cognee/cognee-mcp:main
    container_name: cognee-mcp
    networks:
      - cognee-network
    environment:
      - TRANSPORT_MODE=http
      - API_URL=http://cognee:8000
      - LOG_LEVEL=INFO
    ports:
      - "8001:8000"
    depends_on:
      cognee:
        condition: service_healthy
    restart: unless-stopped

  postgres:
    image: pgvector/pgvector:pg17
    container_name: cognee-postgres
    networks:
      - cognee-network
    environment:
      - POSTGRES_USER=cognee
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=cognee_db
    volumes:
      - cognee-postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U cognee -d cognee_db"]
      interval: 5s
      timeout: 5s
      retries: 5
    restart: unless-stopped

networks:
  cognee-network:
    name: cognee-network

volumes:
  cognee-postgres-data:
  cognee-data:

Paso 4: Crear el archivo de entorno

nano .env

Añade tu configuración:

# OpenAI API Key (required)
LLM_API_KEY=sk-your-openai-api-key-here

# LLM Configuration
LLM_PROVIDER=openai
LLM_MODEL=gpt-4o-mini

# Embedding Configuration
EMBEDDING_PROVIDER=openai
EMBEDDING_MODEL=openai/text-embedding-3-small
EMBEDDING_DIMENSIONS=1536

# Database Configuration
DB_PASSWORD=your-secure-database-password

# Graph Database Provider (kuzu, neo4j, or falkordb)
GRAPH_DATABASE_PROVIDER=kuzu

Paso 5: Arrancar Cognee

# Start services
docker compose up -d

# View logs
docker compose logs -f

# Check status
docker compose ps

Paso 6: Configurar el proxy inverso con Nginx

Para producción con dominios personalizados y SSL:

sudo apt install nginx certbot python3-certbot-nginx -y

Crea la configuración de Nginx:

sudo nano /etc/nginx/sites-available/cognee

Pega:

# Cognee API
server {
    listen 80;
    server_name cognee.yourdomain.com;

    location / {
        proxy_pass http://localhost:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 300;
        proxy_connect_timeout 300;
        proxy_send_timeout 300;
    }
}

# MCP Server
server {
    listen 80;
    server_name mcp.yourdomain.com;

    location / {
        proxy_pass http://localhost:8001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 300;
        proxy_connect_timeout 300;
        proxy_send_timeout 300;
    }
}

Activa el sitio y consigue el SSL:

# Enable site
sudo ln -s /etc/nginx/sites-available/cognee /etc/nginx/sites-enabled/

# Test configuration
sudo nginx -t

# Reload Nginx
sudo systemctl reload nginx

# Get SSL certificates (add --dry-run the first time to avoid rate limits)
sudo certbot --nginx -d cognee.yourdomain.com -d mcp.yourdomain.com

Dos apuntes sobre certbot antes de ejecutarlo. Primero, añade --dry-run en tu primer intento: Let’s Encrypt limita las validaciones fallidas a 5 por semana y dominio, y el dry-run usa el servidor de staging. Segundo, si prefieres no mantener archivos de configuración de Nginx en absoluto, un proxy inverso Traefik para servicios Docker detecta los contenedores mediante etiquetas, que es el mismo modelo que usa Dokploy.

Paso 7: Verificar el despliegue

# All three containers should show "healthy" or "running"
docker compose ps

# API, direct and through the proxy
curl http://localhost:8000/health
curl https://cognee.yourdomain.com/health

# MCP server
curl http://localhost:8001/health

# Swagger UI should load in your browser
open https://cognee.yourdomain.com/docs

El aspecto de un sistema sano: docker compose ps lista cognee, cognee-mcp y postgres sin contadores de reinicio, y ambas llamadas a /health devuelven HTTP 200. Si cognee aparece como unhealthy o se reinicia constantemente, salta a la sección de solución de problemas más abajo.

Opción 3: Ejecutar el servidor MCP de Cognee en standalone (sin la API completa)

Si solo necesitas el servidor MCP para asistentes de codificación con IA como Cursor o Claude Code, puedes ejecutar el servidor MCP en standalone sin el stack completo de la API de Cognee. Es una opción ligera perfecta para entornos de desarrollo personales.

Inicio rápido con Docker

# Set your API key
export LLM_API_KEY=your_openai_api_key_here

# Create env file
echo "LLM_API_KEY=$LLM_API_KEY" > .env

# Start MCP server
docker run -e TRANSPORT_MODE=http --env-file ./.env -p 8000:8000 --rm -it cognee/cognee-mcp:main

Verificar el servidor

curl http://localhost:8000/health

Conectar con clientes de IA

Una vez en marcha, conecta tu asistente de codificación con IA:

Cursor IDE:

{
  "mcpServers": {
    "cognee": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Claude Code:

claude mcp add --transport http cognee http://localhost:8000/mcp -s project

Otros editores compatibles con MCP como Windsurf hablan el mismo protocolo, así que el patrón es idéntico: apunta el cliente a la URL del servidor terminada en /mcp.

Docker Compose para solo MCP (con persistencia)

Para almacenamiento persistente con el servidor MCP standalone:

services:
  cognee-mcp:
    image: cognee/cognee-mcp:main
    container_name: cognee-mcp
    environment:
      - TRANSPORT_MODE=http
      - LLM_API_KEY=${LLM_API_KEY}
      - LLM_PROVIDER=${LLM_PROVIDER:-openai}
      - LLM_MODEL=${LLM_MODEL:-gpt-4o-mini}
      - LOG_LEVEL=INFO
    volumes:
      - cognee-mcp-data:/app/.cognee_system
    ports:
      - "8000:8000"
    restart: unless-stopped

volumes:
  cognee-mcp-data:

Crea el archivo .env:

LLM_API_KEY=sk-your-openai-api-key-here
LLM_PROVIDER=openai
LLM_MODEL=gpt-4o-mini

Arráncalo con:

docker compose up -d

La diferencia entre los dos modos, en visual:

Modo MCP standalone de Cognee frente a modo API con almacenamiento PostgreSQL compartido

Opciones de configuración

Cognee es muy configurable. Estas son las opciones clave que puedes personalizar.

Proveedores de LLM

Cognee soporta varios proveedores de LLM. Actualiza las variables de entorno según corresponda:

LLM_PROVIDER=openai
LLM_MODEL=gpt-4o-mini
LLM_API_KEY=sk-your-key

LLM_PROVIDER=anthropic
LLM_MODEL=claude-3-5-sonnet-20241022
LLM_API_KEY=sk-ant-your-key

LLM_PROVIDER=gemini
LLM_MODEL=gemini/gemini-2.0-flash
LLM_API_KEY=AIza-your-key

LLM_PROVIDER=ollama
LLM_MODEL=llama3.1:8b
LLM_ENDPOINT=http://host.docker.internal:11434/v1
LLM_API_KEY=ollama

extra_hosts:
  - "host.docker.internal:host-gateway"

Proveedores de embeddings

Configura los modelos de embeddings para la búsqueda vectorial:

EMBEDDING_PROVIDER=openai
EMBEDDING_MODEL=openai/text-embedding-3-small
EMBEDDING_DIMENSIONS=1536

EMBEDDING_PROVIDER=openai
EMBEDDING_MODEL=openai/text-embedding-3-large
EMBEDDING_DIMENSIONS=3072

EMBEDDING_PROVIDER=gemini
EMBEDDING_MODEL=gemini/text-embedding-004
EMBEDDING_DIMENSIONS=768
EMBEDDING_API_KEY=AIza-your-key

Para una configuración totalmente local, Cognee también soporta Fastembed, que ejecuta modelos de embeddings ligeros para CPU en el mismo host. Puedes mezclar proveedores, por ejemplo un LLM local de Ollama con embeddings de OpenAI.

Opciones de base de datos de grafos

Cognee soporta distintas bases de datos de grafos para el almacenamiento del grafo de conocimiento:

Kuzu (predeterminada - basada en archivos):

GRAPH_DATABASE_PROVIDER=kuzu

Neo4j (para producción/multi-agente):

GRAPH_DATABASE_PROVIDER=neo4j
GRAPH_DATABASE_URL=bolt://neo4j:7687
GRAPH_DATABASE_USERNAME=neo4j
GRAPH_DATABASE_PASSWORD=your-password

Para añadir Neo4j a tu Docker Compose:

  neo4j:
    image: neo4j:latest
    container_name: cognee-neo4j
    networks:
      - cognee-network
    ports:
      - "7474:7474"
      - "7687:7687"
    environment:
      - NEO4J_AUTH=neo4j/your-password
      - NEO4J_PLUGINS=["apoc", "graph-data-science"]
    volumes:
      - neo4j-data:/data

Mi recomendación: empieza con Kuzu, ya que está basada en archivos y no necesita ningún servicio extra. Pasa a Neo4j cuando tengas escritores concurrentes, varios agentes consultando el grafo a la vez, o grafos lo bastante grandes como para querer las herramientas operativas de Neo4j.

Solución de errores comunes

La mayoría de los problemas al desplegar Cognee se reducen a dos cosas: un desajuste entre las variables de entorno y lo que ya hay en un volumen, o problemas de alcance de red entre contenedores. Empieza cada diagnóstico de la misma forma:

docker compose logs -f cognee        # API container
docker compose logs -f cognee-mcp    # MCP container
docker compose ps                    # health/restart status

Estos son los fallos con los que más probablemente te encontrarás, con la solución de cada uno.

Postgres rechaza la contraseña después de cambiar DB_PASSWORD

Síntoma: los logs de cognee muestran fallos de autenticación repetidos:

FATAL: password authentication failed for user "cognee"

Causa: POSTGRES_PASSWORD solo tiene efecto la primera vez que se inicializa el volumen cognee-postgres-data. Editar DB_PASSWORD en tu .env después cambia lo que Cognee envía, pero la base de datos sigue teniendo la contraseña antigua.

Solución (conservando tus datos): cambia la contraseña dentro de Postgres para que coincida con tu .env:

docker compose exec postgres psql -U cognee -d cognee_db \
  -c "ALTER USER cognee WITH PASSWORD 'your-secure-database-password';"

Solución (borrar y empezar de cero): si no te importan los datos, elimina el volumen para que Postgres se reinicialice con la nueva contraseña:

docker compose down
docker volume rm cognee_cognee-postgres-data   # project prefix may differ; check `docker volume ls`
docker compose up -d

Esto elimina todos los usuarios, datasets y embeddings. Haz primero un pg_dump si tienes cualquier duda (ver Mantenimiento más abajo).

Verificación: docker compose logs cognee deja de mostrar errores de autenticación y curl http://localhost:8000/health devuelve 200.

port is already allocated en el 8000 o el 8001

Síntoma: docker compose up -d falla con:

Error response from daemon: driver failed programming external connectivity on endpoint cognee:
Bind for 0.0.0.0:8000 failed: port is already allocated

Causa: otro contenedor o servicio ya ocupa el puerto del host. El sospechoso habitual es un contenedor obsoleto de un proyecto compose anterior; en segundo lugar, algo más escuchando en el 8000.

Solución: encuentra quién lo ocupa y deténlo o mueve Cognee:

# What's using the port?
docker ps --format '{{.Names}}\t{{.Ports}}' | grep 8000
sudo ss -ltnp | grep 8000

# If it's a stale compose project
docker compose down && docker compose up -d

# Or change only the host-side port in docker-compose.yml
#   ports:
#     - "18000:8000"

Verificación: docker compose ps muestra todos los servicios activos y curl http://localhost:8000/health devuelve 200. Si cambiaste el puerto del host, recuerda actualizar el proxy_pass de Nginx para que coincida.

El contenedor de Cognee se reinicia o falla su health check al arrancar

Síntoma: docker compose ps muestra cognee como unhealthy o Restarting, o sale con el código 137.

Causas comunes y soluciones:

• Falta la clave de API: los logs muestran un error de validación sobre LLM_API_KEY. Comprueba que la variable llegó al contenedor: docker compose exec cognee env | grep LLM_API_KEY. Con Dokploy, confirma que la pestaña Environment se guardó antes de desplegar.
• OOM kill (salida 137): el límite de memoria de 4 GB es un techo, y un VPS de 4 GB ejecutando Postgres, Cognee y MCP dentro del mismo presupuesto va justo. Compruébalo con docker inspect cognee --format '{{.State.OOMKilled}}'. Soluciones: añade swap (fallocate -l 4G /swapfile && chmod 600 /swapfile && mkswap /swapfile && swapon /swapfile), o pásate a un VPS de 8 GB si los trabajos de cognify mueren con regularidad.
• Primer arranque lento: el primer inicio inicializa el esquema de la base de datos y descarga artefactos del modelo, lo que puede superar el start_period de 40 s en discos lentos. Si los logs muestran la app viva pero los health checks fallan de forma intermitente, sube start_period a 120s.

Verificación: tras la corrección, docker compose ps muestra (healthy) en un par de minutos y la interfaz Swagger en /docs carga.

Ollama connection refused desde dentro del contenedor (Linux)

Síntoma: cognify falla con httpx.ConnectError: [Errno 111] Connection refused mientras LLM_ENDPOINT=http://host.docker.internal:11434/v1 funciona bien desde la shell de tu host.

Causa: Docker en Linux no proporciona el nombre DNS host.docker.internal por defecto (macOS y Windows sí).

Solución: añade el mapeo host-gateway al servicio cognee:

extra_hosts:
  - "host.docker.internal:host-gateway"

Después, docker compose up -d para recrear el contenedor. Si Ollama solo escucha en 127.0.0.1, reconfigúralo para escuchar en 0.0.0.0 o usa la IP del bridge de Docker (172.17.0.1) en LLM_ENDPOINT.

Verificación:

docker compose exec cognee curl -s http://host.docker.internal:11434/api/tags

Una lista de modelos en JSON significa que el camino está libre; Connection refused significa que Ollama no está escuchando en la interfaz a la que llegó el contenedor.

Desajuste de dimensiones de embeddings tras cambiar de modelo

Síntoma: cognify o la búsqueda fallan con un error de pgvector sobre el número de dimensiones, p. ej. quejándose de que el vector tiene 768 dimensiones cuando se esperaban 1536 (o viceversa).

Causa: las tablas de vectores en Postgres se crearon con las dimensiones del modelo anterior. Las columnas de pgvector son de ancho fijo; no se redimensionan.

Solución: reinicia el almacenamiento vectorial y vuelve a ingerir. Los pasos exactos están en la entrada de FAQ “¿Cómo reinicio la base de datos y empiezo de cero?” más abajo. Tras el reinicio, ejecuta cognify de nuevo para que los documentos se re-embeban con el nuevo modelo.

Prevención: elige tu modelo de embeddings antes de cargar datos reales, y trata un cambio de EMBEDDING_DIMENSIONS como una migración, no como un ajuste de configuración.

El cliente MCP no alcanza https://mcp.yourdomain.com/mcp

Tres formas de fallo distintas aquí, en el orden en que las comprobaría:

• 404 en la URL: la URL del cliente debe terminar en /mcp. Apuntar Cursor o Claude Code al dominio pelado te da un servidor válido sin herramientas.
• Errores de TLS o de conexión justo después de desplegar: puede que el certificado aún no exista. Dale a Traefik o certbot unos 30 segundos, y luego curl -v https://mcp.yourdomain.com/health para ver el resultado real del handshake.
• Servicio activo pero las herramientas fallan: el contenedor MCP no alcanza la API. Revisa docker compose logs cognee-mcp y confirma API_URL=http://cognee:8000 (el nombre de red de Docker, no localhost).

Usar la API de Cognee

Una vez desplegado, puedes interactuar con Cognee a través de su API REST. Con la autenticación activada, primero necesitas registrarte e iniciar sesión.

Comprobar el estado

curl https://cognee.yourdomain.com/health

Registrar un usuario

curl -X POST "https://cognee.yourdomain.com/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "your-strong-password"}'

Iniciar sesión y obtener el token

TOKEN=$(curl -s -X POST "https://cognee.yourdomain.com/api/v1/auth/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "[email protected]&password=your-strong-password" | jq -r .access_token)

echo $TOKEN

Crear un dataset

curl -X POST "https://cognee.yourdomain.com/api/v1/datasets" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name": "my_documents"}'

Añadir datos

curl -X POST "https://cognee.yourdomain.com/api/v1/add" \
  -H "Authorization: Bearer $TOKEN" \
  -F "data=@/path/to/document.pdf" \
  -F "datasetName=my_documents"

Construir el grafo de conocimiento (Cognify)

curl -X POST "https://cognee.yourdomain.com/api/v1/cognify" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"datasets": ["my_documents"]}'

Cognify se ejecuta de forma asíncrona; en un VPS de 4 GB, espera que un conjunto pequeño de documentos tarde unos minutos, ya que cada fragmento pasa por el LLM y la API de embeddings. Sigue el progreso en docker compose logs -f cognee o consulta el endpoint de estado del dataset.

Buscar

curl -X POST "https://cognee.yourdomain.com/api/v1/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"query": "What are the main topics?", "datasets": ["my_documents"], "top_k": 10}'

Ver la documentación de la API (interfaz Swagger)

La interfaz Swagger es tu principal punto de entrada para explorar y probar la API:

https://cognee.yourdomain.com/docs

Esta documentación interactiva te permite:

• Explorar todos los endpoints disponibles
• Probar llamadas a la API directamente en el navegador
• Ver los esquemas de petición/respuesta
• Autenticarte y gestionar tu sesión

Usar MCP con Cognee autoalojado

La integración del Model Context Protocol (MCP) de Cognee permite que asistentes de codificación con IA como Cursor, Claude Code y las extensiones de VS Code usen Cognee como memoria persistente.

¿Qué es MCP?

MCP (Model Context Protocol) es un estándar para conectar asistentes de IA con herramientas y fuentes de datos externas. El servidor MCP de Cognee expone un conjunto de herramientas de memoria. Las que más usarás:

• add: guarda documentos y datos en la memoria
• cognify: transforma datos en grafos de conocimiento
• search: búsqueda semántica sobre tu conocimiento
• codify: analiza e indexa repositorios de código
• save_interaction: guarda el contexto de la conversación
• get_developer_rules: recupera patrones y reglas de codificación
• list_datasets: muestra todos los datasets almacenados
• prune: borra toda la memoria para empezar de cero

¡MCP ya viene incluido!

Si seguiste las configuraciones de Docker Compose anteriores, el servidor MCP ya se está ejecutando como parte de tu despliegue:

• Dokploy: disponible en https://mcp.yourdomain.com
• Docker Compose: disponible en http://localhost:8001 (o tu dominio configurado)

El servidor MCP se conecta al backend de Cognee internamente a través de la red de Docker (http://cognee:8000).

Conectar Cursor IDE

1. Abre Cursor Settings → Tools & MCP
2. Haz clic en + Add MCP Server
3. Añade esta configuración a mcp.json:

Para desarrollo local:

{
  "mcpServers": {
    "cognee": {
      "url": "http://localhost:8001/mcp"
    }
  }
}

Para tu servidor MCP público:

{
  "mcpServers": {
    "cognee": {
      "url": "https://mcp.yourdomain.com/mcp"
    }
  }
}

4. Actualiza la conexión MCP en Cursor
5. Usa el modo Agent para acceder a las herramientas de Cognee

Conectar Claude Code

# For local development
claude mcp add --transport http cognee http://localhost:8001/mcp -s project

# For remote server
claude mcp add --transport http cognee https://mcp.yourdomain.com/mcp -s project

Usar las herramientas MCP

Una vez conectado, puedes pedirle a tu asistente de IA cosas como:

• “Añade este archivo a la memoria de Cognee”
• “Busca patrones de autenticación en Cognee”
• “Ejecuta codify sobre este repositorio para construir un grafo de conocimiento”
• “Guarda nuestra conversación como reglas de desarrollador”
• “Lista todos mis datasets de Cognee”

La IA usará automáticamente las herramientas MCP de Cognee apropiadas.

Mantenimiento y backups

Backups periódicos

Para despliegues con Dokploy, configura los backups automáticos desde la interfaz de Dokploy o sigue nuestra guía de backups en Dokploy.

Para Docker Compose con PostgreSQL:

# Manual backup (includes both relational data AND vector embeddings)
docker compose exec postgres pg_dump -U cognee cognee_db > backup-$(date +%Y%m%d).sql

# Restore backup
cat backup-20241127.sql | docker compose exec -T postgres psql -U cognee cognee_db

Script de backup automático (backup.sh):

#!/bin/bash
BACKUP_DIR="/backups/cognee"
DATE=$(date +%Y%m%d-%H%M)
mkdir -p $BACKUP_DIR

# Backup PostgreSQL (contains both relational and vector data)
docker compose exec -T postgres pg_dump -U cognee cognee_db | gzip > $BACKUP_DIR/cognee-$DATE.sql.gz

# Keep only last 7 days
find $BACKUP_DIR -name "cognee-*.sql.gz" -mtime +7 -delete

Añádelo al crontab:

chmod +x backup.sh
crontab -e
# Add: 0 2 * * * /path/to/backup.sh

Una laguna que debes conocer: pg_dump captura los datos relacionales y vectoriales, pero los archivos del grafo Kuzu viven en el volumen cognee-data. Si tus grafos de conocimiento importan, haz backup también de ese directorio del volumen (o saca todo fuera del servidor con la ruta de backups de Dokploy, que cubre los volúmenes).

Actualizar Cognee

Con Dokploy:

1. Ve a tu servicio
2. Haz clic en “Redeploy”
3. Dokploy descarga la imagen más reciente

El mismo flujo aplica para actualizar stacks de Docker Compose en Dokploy cuando has editado el propio archivo compose.

Con Docker Compose:

cd ~/cognee
docker compose pull
docker compose up -d

Como los datos viven en volúmenes con nombre, una actualización de imagen no toca tus datos. También es la razón por la que haces un backup primero: un salto de versión mayor puede cambiar el esquema que Cognee espera.

image: cognee/cognee:1.5.4
image: cognee/cognee-mcp:latest

Desmontar Cognee de forma segura

Cuando necesites eliminar el despliegue (o reconstruirlo desde cero):

# Stop and remove containers + networks, KEEP all data
docker compose down

# Stop and remove containers AND volumes (destroys all data)
docker compose down -v

En Dokploy, eliminar el servicio compose desde el panel tira los contenedores, pero los volúmenes con nombre pueden quedar rezagados; límpialos manualmente desde la vista de volúmenes de Dokploy o con docker volume ls | grep cognee. Termina el desmontaje eliminando los registros DNS de cognee.yourdomain.com y mcp.yourdomain.com, y revocando cualquier clave de API que hayas creado para este despliegue.

Si estás migrando en lugar de eliminando, la ruta es: haz un pg_dump nuevo, ejecuta el mismo archivo Compose en el nuevo host y vuelca el dump de vuelta (cat backup.sql | docker compose exec -T postgres psql -U cognee cognee_db). Copia también el contenido del volumen cognee-data si tus grafos importan.

Buenas prácticas de seguridad

Conclusión

Con esta configuración, los datos son tuyos y eliges la infraestructura que se ajusta a tus necesidades. PostgreSQL con pgvector mantiene las cosas simples al gestionar tanto los datos relacionales como los embeddings vectoriales en una sola base de datos, y OpenAI cubre la parte de los embeddings.

Lo que obtienes:

• Una única instancia de PostgreSQL con pgvector gestiona tanto los metadatos COMO el almacenamiento vectorial
• Servidor MCP incluido para que los asistentes de IA se conecten nada más instalar
• Autenticación activada para un despliegue público seguro
• Listo para producción con health checks, límites de recursos y una red bien montada

Dokploy o Docker Compose a pelo — en ambos casos puedes tener Cognee funcionando en minutos. El servidor MCP es la verdadera ventaja aquí: tus asistentes de codificación mantienen memoria persistente entre sesiones sin configuración extra.

Próximos pasos

¿Tienes preguntas sobre autoalojar Cognee? ¡Deja un comentario abajo!

Preguntas frecuentes

# Stop services
docker compose down

# Remove volumes (WARNING: deletes all data including vectors)
docker volume rm cognee_cognee-postgres-data
docker volume rm cognee_cognee-data

# Start fresh
docker compose up -d

curl -X POST "https://cognee.yourdomain.com/api/v1/prune" \
  -H "Authorization: Bearer $TOKEN"