Syncing a Local Instance

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

Install Cognee, then pass your tenant URL and API key:

pip install cognee

import cognee

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

The SDK saves the connection at ~/.cognee/cloud_credentials.json. A later bare cognee.serve() health-checks the saved URL, probes an authenticated endpoint with the saved API key, and reconnects when the instance responds and accepts the key. Only a saved connection with an API key is reused. If the saved instance does not respond or rejects the key, or nothing is saved, serve() raises CogneeConfigurationError that explains how to connect. There is no browser login. Or use environment variables:

export COGNEE_SERVICE_URL="https://your-tenant.aws.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", api_key="your-api-key")

# Local network
await cognee.serve(url="http://192.168.1.50:8000", api_key="your-api-key")

Start the local server (for example with uvicorn cognee.api.client:app --port 8000) 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:

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

Agent Integrations

Connections

Connect to Cognee Cloud

Local-to-local connections

Usage after connection

Push a prebuilt graph instead of raw data

​Connect to Cognee Cloud

​Local-to-local connections

​Usage after connection

​Push a prebuilt graph instead of raw data

Connect to Cognee Cloud

Local-to-local connections

Usage after connection

Push a prebuilt graph instead of raw data