Handle: cognee
URL: http://localhost:34761

Cognee is an open-source knowledge engine that transforms raw data into persistent, dynamic AI memory for agents. It combines vector search (LanceDB), graph databases (KuzuDB), and relational storage (SQLite) to make documents both searchable by meaning and connected by relationships. All databases are file-based by default -- no external database services required.

Harbor includes both the Cognee API server and a direct-mode Cognee MCP server for IDE integration.

# Build from source (first build takes several minutes)
harbor build cognee

# Start Cognee (API server + direct-mode MCP server)
# Also starts Ollama with Cognee's validated default models
harbor up cognee

• API documentation (Swagger UI) is available at http://localhost:34761/docs
• MCP server is available at http://localhost:34762/mcp and exposes the full upstream Harbor-validated tool set in direct mode.
• Authentication is disabled by default -- no registration or login needed.
• harbor up cognee brings up the default Ollama backend automatically so the bundled runtime is usable without extra service arguments.
• Harbor will pre-configure Open WebUI to use Cognee MCP when launched together
• For other backends, see Backend Integration

Following options can be set via harbor config:

# API port
HARBOR_COGNEE_HOST_PORT              34761

# Git reference for building from source
HARBOR_COGNEE_GIT_REF               https://github.com/topoteretes/cognee.git#main

# Workspace root for persisted Cognee state shared by the API and MCP containers
HARBOR_COGNEE_WORKSPACE              ./services/cognee/workspace

# LLM configuration (validated Ollama defaults)
HARBOR_COGNEE_LLM_API_KEY           ollama
HARBOR_COGNEE_LLM_MODEL             qwen3.5:9b
HARBOR_COGNEE_LLM_PROVIDER          ollama
HARBOR_COGNEE_LLM_ENDPOINT          http://ollama:11434/v1

# Embedding configuration (Ollama defaults)
HARBOR_COGNEE_EMBEDDING_PROVIDER    ollama
HARBOR_COGNEE_EMBEDDING_MODEL       nomic-embed-text:latest
HARBOR_COGNEE_EMBEDDING_ENDPOINT    http://ollama:11434/api/embed
HARBOR_COGNEE_EMBEDDING_DIMENSIONS  768

# HuggingFace tokenizer (used with Ollama embeddings)
HARBOR_COGNEE_HUGGINGFACE_TOKENIZER nomic-ai/nomic-embed-text-v1.5

# MCP server configuration
HARBOR_COGNEE_MCP_HOST_PORT          34762
HARBOR_COGNEE_MCP_IMAGE              cognee/cognee-mcp
HARBOR_COGNEE_MCP_VERSION            main

Cognee stores its persisted state under HARBOR_COGNEE_WORKSPACE using these subdirectories:

• ./services/cognee/workspace/data/ - Data files (LanceDB vectors, KuzuDB graphs, SQLite database)
• ./services/cognee/workspace/system/ - Shared system state used by both the API server and cognee-mcp
• ./services/cognee/workspace/cache/ - Cache files

Harbor mounts the workspace root into both containers and points Cognee at those subdirectories. That shared parent mount is required for prune to succeed.

Cognee defaults to Ollama for both LLM and embeddings. harbor up cognee starts Ollama automatically and pre-pulls Cognee's validated default models. When you add another inference backend, its cross-file overrides the LLM connection while keeping Ollama for embeddings unless you change the embedding settings too.

harbor up cognee already starts the default Ollama backend. You only need to name ollama explicitly when composing it with additional services.

# vLLM for LLM, Ollama for embeddings
harbor up cognee vllm ollama

# llama.cpp for LLM, Ollama for embeddings
harbor up cognee llamacpp ollama

# Any OpenAI-compatible backend works
harbor up cognee tabbyapi ollama
harbor up cognee aphrodite ollama
harbor up cognee sglang ollama

Supported backends: Ollama, vLLM, llama.cpp, LiteLLM, TabbyAPI, Aphrodite, SGLang, mistral.rs, KTransformers, TGI, LMDeploy, AirLLM, KoboldCpp, Modular MAX, LocalAI, Nexa.

# Change the LLM model
harbor config set cognee.llm_model qwen2.5:7b

# Change the embedding model
harbor config set cognee.embedding_model mxbai-embed-large:latest
harbor config set cognee.embedding_dimensions 1024

# Switch to OpenAI entirely
harbor config set cognee.llm_provider openai
harbor config set cognee.llm_api_key sk-your-key-here
harbor config set cognee.llm_model openai/gpt-4o-mini
harbor config set cognee.llm_endpoint ""
harbor config set cognee.embedding_provider openai
harbor config set cognee.embedding_model openai/text-embedding-3-large
harbor config set cognee.embedding_endpoint ""
harbor config set cognee.embedding_dimensions 3072

The Cognee MCP server starts automatically alongside the API server. Harbor runs it in direct mode with the same storage, cache, graph, vector, and model configuration as the API container, and serves it over streamable HTTP at http://localhost:34762/mcp.

Harbor builds a local MCP image overlay from HARBOR_COGNEE_MCP_IMAGE:HARBOR_COGNEE_MCP_VERSION and upgrades the embedded cognee package to the same HARBOR_COGNEE_GIT_REF that the API service uses. This keeps Alembic migrations aligned between cognee and cognee-mcp.

Add the following to your MCP client configuration:

Claude Code (~/.claude.json):

{
  "mcpServers": {
    "cognee": {
      "type": "streamable-http",
      "url": "http://localhost:34762/mcp"
    }
  }
}

Cursor (~/.cursor/mcp.json):

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

# API server logs
harbor logs cognee

# MCP server logs
harbor logs cognee-mcp

harbor down cognee
harbor build cognee --no-cache
harbor up cognee

harbor down cognee
rm -rf services/cognee/workspace
harbor up cognee

search only works after the dataset has been added and cognify has completed successfully. If Cognee has no processed graph data yet, the API returns 404 Search prerequisites not met.

For the API workflow, prefer CHUNKS first because it avoids completion-time JSON generation:

curl -X POST http://localhost:34761/api/v1/search \
  -H 'Content-Type: application/json' \
  -d '{"query": "your query", "search_type": "CHUNKS", "datasets": ["notes"]}'

If cognify or completion-style searches fail because the configured model cannot load or cannot produce valid structured output, switch to a working LLM model:

harbor config set cognee.llm_model qwen2.5:3b

• GitHub Repository
• Official Documentation
• API Reference
• MCP Server Docs