cognee.serve()

async def serve(
    url: Optional[str] = None,
    api_key: Optional[str] = None,
    *,
    management_url: Optional[str] = None,
    auth0_domain: Optional[str] = None,
    auth0_client_id: Optional[str] = None,
    auth0_audience: Optional[str] = None,
) -> CloudClient

Description

Connect the local Cognee Python SDK to Cognee Cloud or another remote Cognee API server. After serve() connects, high-level SDK operations route to the remote instance instead of local storage. You can call methods on the returned CloudClient, or continue using top-level operations such as cognee.remember(), cognee.recall(), cognee.improve(), and cognee.forget(). Use cognee.disconnect() to clear the active remote client and return the SDK to local mode.

serve() changes where SDK operations execute. It does not copy existing local datasets to the remote instance. Use push() to upload an already-built local graph, or call remember() after connecting to ingest directly into the remote instance.

Connection resolution

serve() resolves the remote target in this order:

Explicit url and api_key arguments
COGNEE_SERVICE_URL and COGNEE_API_KEY environment variables
Saved credentials from a previous Cognee Cloud login
Device login flow when connecting to Cognee Cloud interactively — available only when a device client ID is configured (the COGNEE_AUTH0_DEVICE_CLIENT_ID environment variable, or the auth0_client_id argument). There is no built-in default.

A resolved url — from either of the first two steps — takes the direct path: no device login, no tenant discovery. Only a bare serve() reaches steps 3 and 4.

Credentials are verified at connect time

/health is unauthenticated, so it cannot tell a working API key from a rejected one. serve() therefore also probes an authenticated endpoint (GET /api/v1/datasets) before it reports a connection, so a bad key fails here instead of on your first real operation. When a url is resolved (the direct path):

What the probe sees	What `serve()` does
`401` or `403`	Raises `CogneeConfigurationError` and saves nothing. With an `api_key` passed, the message says the key was rejected; without one, it explains how to supply one (including minting a key on a self-hosted server with `POST /api/v1/auth/api-keys`).
Instance unreachable	Logs a warning and continues — an instance that is merely down is not a configuration error.
Anything else	Connects, and saves the credentials so a later `serve()` reconnects without arguments.

Saved credentials go through the same probe, with one difference: on that path both a rejected key and an unreachable instance fall through to re-authentication (a token refresh when possible, otherwise the device login) rather than to a connection that 401s on every call. When no device client ID is configured, that fall-through becomes the third error below.

Errors

serve() raises CogneeConfigurationError (importable from cognee.exceptions) in these cases:

The instance rejected the key — name="ServeAuthenticationError", the 401/403 case above. The same error, with a message calling it a provisioning problem, is raised when a fresh Cloud login succeeds but the tenant instance rejects the API key that was just provisioned for it; nothing is saved in either case.
Nothing to connect with — a bare serve() with no saved credentials, no environment variables, and no device client ID. name="ServeConfigurationError"; the message lists the ways to connect.
Saved credentials no longer work and cannot be renewed — a bare serve() whose saved instance is unreachable or whose credentials were rejected, with no device client ID to re-authenticate through. Also name="ServeConfigurationError"; the message names the credentials file and the account on it, and suggests deleting the file if the credentials are stale.

Passing url to a server that requires authentication without also passing api_key is a configuration error, not a silent downgrade: the probe returns 401 and serve() raises. A server with its default posture requires authentication — REQUIRE_AUTHENTICATION inherits from ENABLE_BACKEND_ACCESS_CONTROL, which is on by default, and setting it to false alone is ignored while access control is on — so serve(url="http://localhost:8000") needs an API key there. Only a server running with ENABLE_BACKEND_ACCESS_CONTROL=false, which also turns the auth requirement off, falls back to its default user and answers the probe without a key.

Parameters

Optional[str]

default:"None"

Remote Cognee instance URL. When omitted, Cognee reads COGNEE_SERVICE_URL, saved Cloud credentials, or starts the Cloud login flow.

Optional[str]

default:"None"

API key for the remote instance. When omitted, Cognee reads COGNEE_API_KEY or saved Cloud credentials. A server running with ENABLE_BACKEND_ACCESS_CONTROL=false does not require it.

Optional[str]

default:"None"

Keyword-only. Override the Cognee Cloud Management API URL used for tenant discovery. Cloud path only; defaults to COGNEE_CLOUD_URL.

Optional[str]

default:"None"

Keyword-only. Override the Auth0 domain used by the device login flow. Cloud path only.

Optional[str]

default:"None"

Keyword-only. Auth0 device-login client ID. Without this or COGNEE_AUTH0_DEVICE_CLIENT_ID, a bare serve() cannot start the device login flow and raises CogneeConfigurationError when no saved credentials work.

Optional[str]

default:"None"

Keyword-only. Override the Auth0 API audience requested by the device login flow. Cloud path only.

Returns

A CloudClient configured for the connected instance. The returned client exposes the main remote operations:

method

Ingest data and build memory on the remote instance.

method

Write a single session-memory entry on the remote instance.

method

Query memory from the remote instance.

method

Run enrichment or session-bridging on remote memory.

method

Delete remote data, datasets, or memory state.

method

Ingest data on the remote instance without building the graph.

method

Build the knowledge graph on the remote instance.

method

Query the remote knowledge graph.

method

Replace one document in place on the remote instance via PATCH /api/v1/update.

method

List the documents in a remote dataset via GET /api/v1/datasets/{dataset_id}/data.

Operations that route to the remote instance

While a connection is active, these top-level SDK calls are proxied to the remote instance instead of touching local storage — you do not have to call the CloudClient method yourself:

SDK call	Remote route
`cognee.remember()`	`POST /api/v1/remember`
`cognee.recall()`	`POST /api/v1/recall`
`cognee.improve()`	`POST /api/v1/improve`
`cognee.forget()`	`POST /api/v1/forget`
`cognee.add()`	`POST /api/v1/add`
`cognee.cognify()`	`POST /api/v1/cognify`
`cognee.search()`	`POST /api/v1/search`
`cognee.update()`	`PATCH /api/v1/update`
`cognee.datasets.list_data()`	`GET /api/v1/datasets/{dataset_id}/data`

Routing happens before any local resolution, so these calls work against datasets that exist only on the remote instance, and they write nothing to the local store.

The remote routes accept a narrower parameter surface than their local counterparts. update() proxies only data_id, data, dataset_id, node_set, and chunk_level_diff; anything else you pass is dropped and the server applies its own configuration. Most of the dropped parameters are named in a logged warning, but user, incremental_loading, and data_cache go silently. See update() for the full list.

Examples

Cognee Cloud
Explicit credentials
Environment variables
Local server

The interactive Cloud login needs a device client ID; without it a bare serve() raises instead of opening the login flow.

export COGNEE_AUTH0_DEVICE_CLIENT_ID="your-device-client-id"

import cognee

# Opens the device login flow and saves reusable credentials.
client = await cognee.serve()

await client.remember("Cognee Cloud stores memory remotely.", dataset_name="docs")
results = await client.recall("Where is memory stored?")

await cognee.disconnect()

import cognee

client = await cognee.serve(
    url="https://your-tenant.aws.cognee.ai",
    api_key="your-api-key",
)

await client.remember("Runbook: deploys happen on Tuesdays.", dataset_name="ops")
results = await client.recall("When do deploys happen?")

await cognee.disconnect()

export COGNEE_SERVICE_URL="https://your-tenant.aws.cognee.ai"
export COGNEE_API_KEY="your-api-key"

import cognee

client = await cognee.serve()
await client.recall("What is stored in this tenant?")

Start a local Cognee backend first:

cognee serve

Then connect the SDK to it. A server with its default posture requires authentication, so pass an API key minted with POST /api/v1/auth/api-keys; omit it only when the server runs with ENABLE_BACKEND_ACCESS_CONTROL=false:

import cognee

client = await cognee.serve(url="http://localhost:8000", api_key="your-api-key")
await client.remember("Cognee turns documents into AI memory.", dataset_name="docs")

await cognee.disconnect()

Disconnecting

await cognee.disconnect()

disconnect() closes the active remote connection for the current SDK process. Saved credentials are not deleted, so a later serve() call can reconnect without requiring a new login when the credentials are still valid.

Reference

serve()

cognee.serve()

Description

Connection resolution

Credentials are verified at connect time

Errors

Parameters

Returns

Operations that route to the remote instance

Examples

Disconnecting

See also

​cognee.serve()

​Description

​Connection resolution

​Credentials are verified at connect time

​Errors

​Parameters

​Returns

​Operations that route to the remote instance

​Examples

​Disconnecting

​See also

cognee.serve()

Description

Connection resolution

Credentials are verified at connect time

Errors

Parameters

Returns

Operations that route to the remote instance

Examples

Disconnecting

See also