Skip to content
Skills Library
AI & agents · Tool integration

setup

/setup

Use when configuring the Cognee connection, checking whether Cognee is ready or connected, or diagnosing a local or cloud Cognee instance from Cursor.

Licence
Apache-2.0
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
4
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Use when configuring the Cognee connection, checking whether Cognee is ready or connected, or diagnosing a local or cloud Cognee instance from Cursor.

Original author description

Use when configuring the Cognee connection, checking whether Cognee is ready or connected, or diagnosing a local or cloud Cognee instance from Cursor.

How it works

  1. Rules
  2. 1. Check the mode and the connection
  3. 2. Probe the server directly (optional)
  4. Configure the connection
  5. Fallback — cognee-cli, local mode with a cognee checkout only
Original SKILL.md headings · 156 lines, 962 words
SKILL.md preview
---
name: setup
description: Use when configuring the Cognee connection, checking whether Cognee is ready or connected, or diagnosing a local or cloud Cognee instance from Cursor.
---

# Cognee Connection And Status

> **Plugin root.** The commands below use `${CURSOR_PLUGIN_ROOT}`, which Cursor
> does not set in your shell. Take the path from the `Cognee plugin root:` line
> in the session context (or use the directory two levels above this `SKILL.md`,
> the one holding `scripts/`) and run `export CURSOR_PLUGIN_ROOT="<that path>"`
> in the same shell command, before the skill command.

Use this skill when the user asks to configure Cognee, check whether Cognee is
ready or connected, switch between local and cloud mode, or diagnose a
connection problem.

## Rules

- **Server first.** Answer every question here from the plugin's own diagnostic
  and the running Cognee server over HTTP. That is the authoritative path in
  both local and cloud mode.
- **`cognee-cli` is a last resort, not an alternative.** It is reachable only on
  a machine holding a cognee **source checkout**: `scripts/cognee-cli.sh` exits
  64 ("Run this from the Cognee repository root or set COGNEE_REPO_ROOT")
  anywhere else, and in cloud mode the plugin's venv is never built at all. Never
  reach for it before the two steps below have actually failed.
- **Never run `uv sync` or any dependency install.** On a plugin install there is
  no cognee repository to sync, and in the user's own project it would rebuild
  their dependencies.
- Do not print secret values from `.env`, config files, shell history, or command
  output. Report whether a key *appears configured*, never the value.
- If a command may create, delete, or overwrite durable Cognee state, say what it
  will affect before running it.
- Do not use MCP for this plugin.

## 1. Check the mode and the connection

One command answers "is Cognee ready?", "which mode am I in?", and "what is
wrong?" — it imports no cognee, makes one `/health` probe, and works from any
directory:

```bash
python3 "${CURSOR_PLUGIN_ROOT}/scripts/doctor.py" --json
```

The JSON carries:

| Field | Meaning |
|-------|---------|
| `mode` | `Local` or `Cloud`, plus an annotation naming what forced the decision (e.g. `forced by COGNEE_BACKEND=local`) |
| `server_url` | The endpoint this terminal actually resolved |
| `reachable` | Whether the health probe succeeded |
| `latency_ms` | Round-trip time, or `null` when unreachable |
| `api_key_source` | Which credential the plugin is using (plugin identity, env var, cached, minted) |
| `memory_sharing` | Shared-agent-memory state |
| `circuit_breaker` | Whether recall is currently short-circuited |

Read `mode` **before** doing anything mode-specific. In particular: in `Cloud`
mode there is no local server to start and no local UI to launch — see the
**local-ui** skill, which stops on cloud by design.

Drop `--json` for a human-readable table when reporting to the user.

## 2. Probe the server directly (optional)

When you need to confirm the endpoint yourself, or the doctor's verdict looks
stale:

```bash
curl -sS -i "${COGNEE_BASE_URL:-http://localhost:8011}/health"
```

`http://localhost:8011` is the plugin's local server. Do **not** substitute
`:8000` — that is the `cognee-cli`'s own default for a server it would start
itself, unrelated to the one the plugin runs and talks to.

For an authenticated check of the resolved credential (cloud, or any server with
auth enabled), use the forget helper's credential resolver rather than guessing
where the key lives:

```bash
eval "$(${CURSOR_PLUGIN_ROOT}/scripts/cognee-forget.sh env)" && \
curl -sS -o /dev/null -w '%{http_code}\n' \
  -H "X-Api-Key: ${COGNEE_API_KEY}" "${COGNEE_BASE_URL}/api/v1/users/me"
```

`200` means the key is accepted; `401`/`403` means it was rejected by that
server. In local mode the key is never exported to the shell, so a raw request
without this resolver will 401 misleadingly.

## Configure the connection

Durable configuration (`COGNEE_BASE_URL`, `COGNEE_API_KEY`, `LLM_API_KEY`, ...)
belongs in `~/.cognee/.env` — a one-time setup file shared with the Claude Code
plugin, loaded at session start. Guide the user to edit that file rather than
exporting in every shell; never echo its secret values. Shell exports still
override it per terminal. Changes apply on the next `cursor` launch.

**Cloud or a remote server** — both values:

```bash
mkdir -p ~/.cognee
cat >> ~/.cognee/.env <<'EOF'
COGNEE_BASE_URL="https://your-instance.cognee.ai"
COGNEE_API_KEY="ck_..."
EOF
chmod 600 ~/.cognee/.env
```

**Local** (default when `COGNEE_BASE_URL` is unset) — the plugin bootstraps a
local Cognee API on `http://localhost:8011` and auto-mints `COGNEE_API_KEY`, so
only the LLM key is required:

```bash
mkdir -p ~/.cognee
cat >> ~/.cognee/.env <<'EOF'
LLM_API_KEY="sk-..."
EOF
chmod 600 ~/.cognee/.env
```

Re-pasting either block is safe — the last value of a repeated key wins.

### Which mode wins

The file may hold **both** modes' variables at once. The mode is then decided
per terminal, in this order:

1. An exported `COGNEE_BACKEND` (or the plugin-specific `COGNEE_CURSOR_BACKEND`,
   which beats it) pins that terminal: `local` or `cloud`.
2. Otherwise cloud wins when `COGNEE_BASE_URL` is set anywhere.
3. Otherwise local.

A forced mode is **pinned**: `COGNEE_BACKEND=cloud` with no URL configured stays
cloud and fails visibly (`✕ (missing_cognee_base_url)`) rather than silently
falling back. `unset COGNEE_BASE_URL` is **not** a way to go local — the env file
re-injects it on the next launch; use the switch.

`COGNEE_BACKEND` may also live in `~/.cognee/.env` to make a mode the durable
default. The doctor's `mode` field always reports what the terminal actually
resolved, with the cause.

## Fallback — `cognee-cli`, local mode with a cognee checkout only

Only if steps 1 and 2 both failed, the mode is `Local`, **and** the machine has a
cognee source checkout. Route it through the wrapper so a missing checkout fails
with a clear message instead of an opaque `uv` error:

```bash
"${CURSOR_PLUGIN_ROOT}/scripts/cognee-cli.sh" config list
```

Set `COGNEE_REPO_ROOT` to the checkout path if the wrapper cannot find it. Use
`config get <KEY>` only for non-secret settings.

Exit code 64 means there is no cognee checkout here — that is expected on a
normal install, and it is **not** a Cognee fault to report. Say the server is
unreachable and give the user the doctor output instead.

Versions

RepositoryScoreLicence
This page · topoteretes/cognee-integrations100Apache-2.0
HwangSlater/harness-fit100MIT
nesquikm/dev-process-toolkit100MIT
userKael/rastro100MIT
als-apg/osprey100BSD-3-Clause
dedujeong/gemba100Apache-2.0
eigenwise/eigenwise-toolshed100MIT
awrshift/agent-memory-kit100MIT
lifecycle-innovations-limited/claude-ops100MIT

Database snapshot: 13.11.2026 · package version 27677c03964e (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100local-ui
    Use only when the user explicitly asks to launch or inspect the LOCAL Cognee UI (the cognee-cli dev UI). For "is Cognee running/connected" or any configuration question, use the setup skill instead. Does not apply in cloud mode.
  • 100local-ui
    Use only when the user explicitly asks to launch or inspect the LOCAL Cognee UI (the cognee-cli dev UI). For "is Cognee running/connected" or any configuration question, use the setup skill instead. Does not apply in cloud mode.
  • 90cognee:store
    Use when the user says 'cognee store', 'push to cognee', 'save to graph', 'remember this' or 'log this decision', or when session decisions must be stored. Writes entities, decisions and events over POST /api/v1/remember.
  • 100cognee
    Use when the user says 'cognee', asks about knowledge graph or graph memory, wants to switch memory backends, or needs a status check, dataset init, or graph view. Covers Cognee endpoints plus the Brain fallback.
  • 100oms-cognee
    Builds apps on cognee v1.6.2, the knowledge-graph memory engine for AI agents. Use when ingesting text/files/URLs into memory, building knowledge graphs, searching memory with SearchType modes, enriching graphs with memify/improve, scoping memory with datasets and node_sets,…
  • 100cursor-setup
    Configure and verify the Cursor backend for Claude Code Harness. Use when user invokes cursor:setup, wants Cursor as the local default implementation backend, or asks to check Cursor plugin/agent readiness. Distribution default remains opt-in; only local env/user settings are…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.