How to use the Run the cognee Server agent skill

What does the cognee-server skill make the agent do?

An agent skill is a folder with a SKILL.md file that gives an AI agent task-specific instructions. This one covers running the cognee API server locally. The agent can start the full local stack, check the health endpoint, connect the cognee SDK or CLI to the running server, and pick an auth posture.

The skill also covers common errors such as a port conflict or search results that come back empty because of permissions.

• Start the FastAPI backend on http://localhost:8000 and the UI on http://localhost:3000
• Find the interactive API reference at http://localhost:8000/docs and health at /health
• Point the SDK or CLI at a server instead of embedded local mode
• Decide between multi-user access control and single-user local mode

How do you install the cognee-server skill?

Download the ZIP for the skill from this page. Then install it in one of two ways.

For Claude Code, unzip it into ~/.claude/skills/ for all your projects, or into a project's .claude/skills/ folder for that project only. In the Claude apps, upload the ZIP under Settings → Capabilities → Skills.

• Personal: unzip into ~/.claude/skills/
• Project only: unzip into .claude/skills/ inside your project
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

How do you trigger the skill with a natural request?

You do not need a special command. Describe what you want in plain language and the agent will load the skill when the request matches its description. Good triggers mention running, starting, or checking the cognee server, or connecting a client to it.

Tell the agent what you want, and it will follow the steps in SKILL.md, including checking your environment for LLM_API_KEY before it starts the server.

• "Start a local cognee server with the UI so I can look at my graph."
• "Is my cognee server healthy on port 8000?"
• "Connect my cognee SDK script to http://localhost:8000."
• "My cognee search returns an empty list. Why?"

How do you start the server and check it is running?

If cognee is already installed without Docker, the skill uses the cognee-cli command to launch the full local stack. The LLM_API_KEY variable must be set in the environment or in a .env file.

Once the server is running, open the API reference at /docs or call /health to confirm it responds. For API-only serving through Docker, the skill points you to the separate cognee-docker skill.

• Requirement: cognee installed, so the cognee-cli command is available
• Requirement: LLM_API_KEY in the environment or .env

How do you choose between auth on and auth off?

The ENABLE_BACKEND_ACCESS_CONTROL setting decides the mode. When it is true, which is the default, the server is multi-tenant: every API call needs authentication, and each user and dataset gets an isolated database. When it is false, the server runs in single-user local mode with no login and shared local databases.

Single-user mode suits a personal development server. Never use it for anything reachable from a network or the internet. REQUIRE_AUTHENTICATION=false is ignored while access control is on, so to turn auth off you must set ENABLE_BACKEND_ACCESS_CONTROL=false.

• true (default): multi-tenant, auth required on every call
• false: single-user local mode, no auth, shared databases

How do you connect the SDK or CLI to the running server?

By default the SDK and CLI can run in embedded local mode. To talk to a running server instead, use the serve command with a URL. You can also disconnect with the logout flag. In Python, the equivalent is the serve call with a url argument.

Main HTTP routes live under /api/v1/. The memory API includes remember (plus remember/entry), recall, improve and forget, with sessions, datasets, users and visualize for the rest. There is no /api/v1/feedback route; feedback is available as a CLI command and in the SDK only.

• Local instance: cognee-cli serve --url http://localhost:8000
• Cognee cloud (device flow): cognee-cli serve
• Disconnect: cognee-cli serve --logout
• Full route list: GET /openapi.json on a running server

What should you do when something goes wrong?

Most problems come from three causes: a port already in use, a 401 or 403 response because the server is in multi-tenant mode, or an empty result from recall or search because permissions filter it out. The skill lists a fix for each.

• Port 8000 already taken: stop the other service or remap the port (in compose, for example "8080:8000")
• 401 or 403 on every call: authenticate, or set ENABLE_BACKEND_ACCESS_CONTROL=false and restart
• recall or search returns [] instead of an error: check the calling user's dataset access rights