Syncing a Local Instance

Connect your local Cognee SDK to Cognee Cloud

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

pip install cognee

import cognee

# Opens browser for authentication; discovers your cloud tenant automatically
await cognee.serve()

After login, the SDK stores credentials at ~/.cognee/cloud_credentials.json. Subsequent calls to cognee.serve() first health-check the saved instance URL using the cached API key, and reconnect without re-authenticating whenever that instance responds — even if the stored Auth0 access token has expired. Re-authentication (a token refresh when possible, otherwise a browser login) runs only when no usable credentials are cached or the saved instance does not respond.

Because reuse is gated on the instance being reachable rather than on token lifetime, an expired token by itself no longer blocks 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:

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

Or use environment variables:

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

await cognee.serve()  # Reads from environment

Local-to-local connections

Connect to a Cognee backend on the same machine or local network:

# Same machine
await cognee.serve(url="http://localhost:8000")

# Local network
await cognee.serve(url="http://192.168.1.50:8000")

Start the local server with cognee serve before connecting.

Usage after connection

Once connected, all SDK operations execute on the remote instance:

# Ingested into the remote tenant
await cognee.remember("Einstein developed general relativity in 1915.")

# Queries the remote knowledge graph
results = await cognee.recall("What did Einstein develop?")

# Disconnect when done
await cognee.disconnect()

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:

# Build locally, then upload the graph itself
await cognee.push("my_dataset")

The same operation is available from the terminal as cognee push.