cognee-server
GitHub指导本地启动 Cognee API 服务器及 UI,配置多租户/单用户认证模式,连接 SDK/CLI 客户端,排查端口冲突与权限问题,支持安全 Cookie 设置。
触发场景
安装
npx skills add topoteretes/cognee --skill cognee-server -g -y
SKILL.md
Frontmatter
{
"name": "cognee-server",
"description": "Use when the user wants to run the cognee API server (and optional UI) on their own machine — starting it, checking it's healthy, connecting the SDK or other clients to it, and choosing the right auth posture."
}
Start the cognee server locally
From an installed cognee (no Docker)
cognee-cli -ui
launches the full local stack: FastAPI backend on http://localhost:8000
and the UI on http://localhost:3000. Needs LLM_API_KEY in the
environment or .env. The interactive API reference is at
http://localhost:8000/docs, health at /health.
For API-only serving via Docker instead, use the cognee-docker skill (the
prebuilt cognee/cognee:main image or docker compose up from the repo).
Auth posture
ENABLE_BACKEND_ACCESS_CONTROL decides everything:
true(default): multi-tenant — auth required on every API call, per user+dataset database isolation.false: single-user local mode — no auth, shared local databases. Right choice for a personal dev server; never for anything exposed.
REQUIRE_AUTHENTICATION=false is ignored while access control is on; to turn
auth off you must set ENABLE_BACKEND_ACCESS_CONTROL=false.
Behind a TLS-terminating proxy set AUTH_TOKEN_COOKIE_SECURE=true so the auth cookie
gets the Secure attribute; leave it off for plain http://localhost, where a browser
refuses to store a Secure cookie.
Connecting clients to the running server
-
SDK / CLI against the server (instead of embedded local mode):
cognee-cli serve --url http://localhost:8000 # local instance cognee-cli serve --url https://... --api-key ck_... # cognee cloud instance cognee-cli serve # reconnect to the saved keyed instance cognee-cli serve --logout # disconnectIn Python:
await cognee.serve(url="http://localhost:8000"). -
HTTP: main routes live under
/api/v1/— the memory API isremember(plusremember/entry),recall,improve,forget;sessionscovers session memory;datasets,users,visualizehandle the rest. The legacyadd,cognify,search, anddeleteroutes still exist and are what the memory routes call underneath (seecognee/api/client.pyfor the registered routers, orGET /openapi.jsonon a running server).Note there is no
/api/v1/feedbackroute —feedbackexists as a CLI command and in the SDK, but is not exposed over HTTP.
Graph visualization without the full UI
from cognee.api.v1.visualize import visualization_server
shutdown = visualization_server(port=8080) # synchronous; returns a shutdown callable
Troubleshooting
- Port 8000 already taken → stop the other service or remap (compose:
"8080:8000"). - 401/403 on every call → you're in multi-tenant mode; either authenticate or
set
ENABLE_BACKEND_ACCESS_CONTROL=falseand restart. recall/searchreturns[]instead of erroring → permission-filtered result; check dataset access rights for the calling user.
版本历史
-
525b1d1
当前 2026-11-02 22:49
新增 AUTH_TOKEN_COOKIE_SECURE 环境变量以控制安全 Cookie 属性;修复 cli serve 命令仅复用已保存的密钥连接及无密钥实例的重连逻辑。
- 37f788b 2026-10-19 05:49


