Skip to main content
The Cognee Python SDK can connect to a remote Cognee instance using cognee.serve(). Once connected, all operations (remember, recall, forget, improve) route to the remote instance instead of running locally.

​
Connect to Cognee Cloud

After login, the SDK stores credentials at ~/.cognee/cloud_credentials.json. Subsequent calls to cognee.serve() first health-check the saved instance URL and probe an authenticated endpoint with the cached API key, and reconnect without re-authenticating whenever that instance responds and accepts the key — even if the stored Auth0 access token has expired. Re-authentication (a token refresh when possible, otherwise the device login) runs only when no usable credentials are cached, the saved instance does not respond, or it rejects the cached key. The device login itself needs COGNEE_AUTH0_DEVICE_CLIENT_ID; without it, serve() raises CogneeConfigurationError rather than attempting to log in.
Because reuse is gated on the instance accepting your key rather than on token lifetime, an expired token by itself does not block startup: a healthy instance keeps accepting your cached credentials through an Auth0 outage.

​
Connect to any instance

For self-hosted or staging environments, pass the URL and API key directly:
Or use environment variables:

​
Local-to-local connections

Connect to a Cognee backend on the same machine or local network:
Start the local server with cognee serve before connecting. A server with its default posture requires authentication, and serve() raises when the key is missing or rejected; omit api_key only when the server runs with ENABLE_BACKEND_ACCESS_CONTROL=false.

​
Usage after connection

Once connected, all SDK operations execute on the remote instance:
The local UI in Cognee Cloud automatically detects running local instances on localhost:8000 and shows their connection status.

​
Push a prebuilt graph instead of raw data

Connecting with serve() and re-running remember() makes the remote instance rebuild the knowledge graph. If you have already built the graph locally and want to avoid re-deriving it (and the LLM cost that comes with it), use cognee.push() instead. It exports the dataset’s graph as a COGX archive and imports it on the remote instance, preserving your local entities and relationships:
The same operation is available from the terminal as cognee push.