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.

​
Reconnecting with saved credentials

On the Cloud path — serve() called without a url — Cognee tries the saved instance before it tries Auth0. When ~/.cognee/cloud_credentials.json holds both a service URL and an API key, the SDK health-checks that URL with the cached API key immediately, without first consulting the stored Auth0 access token’s expiry. If the instance responds, serve() connects with the cached credentials and skips Auth0 entirely, so an expired token on its own no longer forces a new browser login. Auth0 is contacted only when that first health check fails or errors:
  • Stored token still valid — Cognee goes straight to the browser device-code login.
  • Stored token expired and a refresh token is saved — Cognee refreshes the token and health-checks the saved URL again; a browser login follows only if that retry also fails.
The practical effect is that a reachable instance keeps starting up during an Auth0 outage, and a failed connection points at the instance itself rather than at token freshness.

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

​
Filenames for raw-text uploads

When you pass a raw string — or a list containing strings — to remember() or add() while connected, the remote client uploads it as a file named text_<md5_hash>.txt, where the hash is computed from that string’s UTF-8 bytes. Each string in a list gets its own hash-derived name. This matches the naming local ingestion already uses for nameless text (see Hash-based file storage, deduplication, and filename collisions), so the same text produces the same object name whether it is ingested locally or over a serve() connection. File-like objects are unaffected: they keep uploading under their own name attribute, falling back to upload when they have none.
Previously every raw-text upload was sent as data.txt. Because the name was fixed, all text uploads for a tenant landed on one remote object, so concurrent adds raced each other against the server’s content-hash read-back and could fail with a FileContentHashingError 409. Content-derived names remove that collision.Like the timeouts, this filename is a fixed value in the remote client — there is no parameter to supply your own. If you have tooling or tests that assert the uploaded name is data.txt, update them to expect text_<md5_hash>.txt. The uploaded text content itself is unchanged.

​
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