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

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() reconnect without re-authenticating until the token expires.

​
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.