Skip to main content

​
What is the serve operation

The .serve operation connects your local Cognee Python SDK to Cognee Cloud or another remote Cognee instance. After cognee.serve() connects, SDK calls such as remember(), recall(), improve(), and forget() run against the remote instance instead of local storage. This lets the same Python code work with local Cognee during development and with a hosted or self-hosted Cognee backend in production.
The CLI command cognee serve starts a local Cognee backend process. The Python function cognee.serve() connects the SDK client to a remote or local backend.

​
Where serve fits

  • Use serve() when you want SDK operations to target Cognee Cloud.
  • Use it when you want to connect to a self-hosted Cognee API server.
  • Use it before Push when you want push() to reuse saved or active remote credentials.
  • Use disconnect() when you want the SDK to return to local execution.
  • Use syncing a local instance for a cloud-focused walkthrough of the same connection flow.

​
What happens under the hood

  1. Resolve connection settings - Cognee looks for an explicit URL/API key, environment variables, saved credentials, or a browser login flow.
  2. Create a remote client - the SDK stores a client that knows how to call the remote Cognee API.
  3. Route SDK operations remotely - supported high-level operations execute against the connected instance.
  4. Persist credentials when applicable - Cloud login credentials can be saved and reused on later runs.
  5. Disconnect on request - cognee.disconnect() clears the active remote client and returns the SDK to local mode.

​
Request timeouts

Remote calls are bounded so a stalled connection cannot hang your process indefinitely:
  • Ordinary operations (remember(), recall(), improve(), add(), cognify(), search(), forget()) allow up to 600 seconds total per request, with connection failures surfacing after 30 seconds. The 600 second total gives long blocking server-side work — for example cognify() over a large dataset — room to finish.
  • Archive uploads used by push() have no total cap, and are instead bounded by 600 seconds of read inactivity. An upload plus its synchronous server-side import can legitimately outlast any fixed total, so the upload is cut off only when the server stops sending data.
These timeouts are fixed values in the remote client. There is no environment variable or serve() parameter to change them. If a blocking cognify() run is likely to exceed 600 seconds, submit it as a background run and poll for status instead of holding the request open.

​
Connection modes

Call serve() without arguments to use the Cognee Cloud login flow.
After login, Cognee stores reusable credentials at ~/.cognee/cloud_credentials.json.

​
After serve connects

Supported SDK operations run on the connected remote instance.
serve() changes where SDK operations execute. It does not copy local datasets to the remote instance by itself. Use Push to upload an already-built local graph, or run remember() while connected to ingest data directly into the remote instance.

​
Examples and details

Cloud login

​
See also