Cognee Brain — homelab memory layer

The homelab memory layer ("the brain") is Cognee on BRAIN-MAIN at 10.0.0.23. It replaced the previous memory layer on 2026-08-29. Cognee ingests text, builds a knowledge graph (entities + relationships) and a vector index side-by-side, and exposes them through Python, CLI, MCP, and REST.

When to Use

User says "brain", "cognee", "what do we know about X", "remember this"
Before research/infra tasks — query the brain first
After research with concrete conclusions — write durable facts back

Endpoints

API: http://10.0.0.23:8080 (cognee-backend, cognee/cognee:main)
MCP: http://10.0.0.23:8001/mcp (cognee-mcp, cognee/cognee-mcp:main)
Dataset: homelab-stack (the single shared dataset — use it everywhere)
LLM: Ollama cloud-passthrough http://10.0.0.23:11434/v1 (minimax-m3:cloud)
Embed: mini http://10.0.0.30:11434/api/embed (qwen3-embedding:0.6b, 1024 dims)
Graph: Kuzu (Ladybug) files under /var/lib/cognee/system/databases
Vectors: LanceDB files under /var/lib/cognee/system/databases/cognee.lancedb

MCP tools (auto-discovered in Hermes as `mcpcognee*`)

remember — store data. Without session_id = permanent memory (add + cognify pipeline, builds the graph). With session_id = session cache only (fast, no extraction). Pass data (text) OR filename+content_base64 (file upload). dataset_name defaults to the client's agent-scoped dataset — ALWAYS pass dataset_name="homelab-stack" explicitly.
recall — search memory. query (required), optional search_type (HYBRID_COMPLETION default; CHUNKS/GRAPH_COMPLETION/RAG_COMPLETION/etc.), datasets (comma-separated), top_k.
forget — delete. dataset (name), dataset_id, data_id+dataset, or everything.

REST API (for curl / scripts)

POST /api/v1/remember (multipart: data=@file + datasetName=homelab-stack)
POST /api/v1/search (JSON: query, datasets, searchType)
DELETE /api/v1/datasets?dataset_name=...
GET /health → {"status":"ready","health":"healthy","version":"1.5.3-local"}

Field-name gotcha: the search API uses query + searchType (NOT query_text/query_type). Wrong names silently fall back to the default query "What is in the document?" and return a generic summary.

Write rules

One dataset: homelab-stack. Never create a second dataset for the same domain — the whole point is a single combined view.
remember is add+cognify in one call — no separate cognify step.
No group_id, no triplet, no temporal supersession. Cognee uses datasets. To correct a fact, remember the corrected statement; Cognee's graph merges entities by name.
Don't re-ingest the same content twice — remember is not idempotent.
Embed dim is 1024 (EMBEDDING_DIMENSIONS=1024, qwen3-embedding:0.6b). Never let it default to 3072.

Verify a write

recall with a distinctive phrase from the content; a correct answer proves the graph has it.
Check docker logs cognee-backend for api.openai.com / ProviderConfigMismatch — zero hits means the LAN-only provider pairing held.

Pitfalls

remember returns status: completed synchronously (unless background=true). A completed status means the graph is built — no async polling needed.
Search field names are query/searchType (see above).
No auth on API/MCP (REQUIRE_AUTHENTICATION=false) — LAN-trust only.
Container runs as uid 1000 — /var/lib/cognee/{system,data} must stay 1000:1000.
MCP allowed_hosts = 10.0.0.23/42/28/15 (edit MCP_ALLOWED_HOSTS in compose to add hosts).
Start/stop: sudo systemctl start|stop cognee.service (docker compose up/down).

4.0 KiB Raw Blame History