Skip to main content

​
cognee.serve()

async def serve(
    url: Optional[str] = None,
    api_key: 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:
  1. Explicit url and api_key arguments
  2. COGNEE_SERVICE_URL and COGNEE_API_KEY environment variables
  3. Saved credentials from a previous Cognee Cloud login
  4. Browser login flow when connecting to Cognee Cloud interactively
If authentication is required and no usable credentials are found, the connection fails with an authentication error.

​
Parameters

​
url
Optional[str]
default:"None"
Remote Cognee instance URL. When omitted, Cognee reads COGNEE_SERVICE_URL, saved Cloud credentials, or starts the Cloud login flow.
​
api_key
Optional[str]
default:"None"
API key for the remote instance. When omitted, Cognee reads COGNEE_API_KEY or saved Cloud credentials. Local unauthenticated servers may not require it.

​
Returns

A CloudClient configured for the connected instance. The returned client exposes the main remote operations:
​
remember
method
Ingest data and build memory on the remote instance.
​
recall
method
Query memory from the remote instance.
​
improve
method
Run enrichment or session-bridging on remote memory.
​
forget
method
Delete remote data, datasets, or memory state.

​
Examples

import cognee

# Opens the Cloud 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()

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

​
See also