---
name: cognee-brain
description: "Use when user says brain or cognee. Cognee memory brain (Kuzu+LanceDB)."
version: 1.0.0
author: Hermes Agent
license: MIT
platforms: [linux]
metadata:
  hermes:
    tags: [cognee, brain, memory, knowledge-graph, kuzu, lancedb]
    related_skills: [ai-vault-kb, save, memory-ingest]
---

# 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 `mcp__cognee__*`)

- `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).