> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognee.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Serve

> Connect the Cognee SDK to Cognee Cloud or a remote Cognee instance.

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

```python theme={null}
import cognee

await cognee.serve()
```

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](/core-concepts/main-operations/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](/cognee-cloud/connections/syncing-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()`](/core-concepts/main-operations/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.

<Note>
  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.
</Note>

### 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](/core-concepts/main-operations/legacy-operations/add#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.

<Note>
  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.
</Note>

## Connection modes

<Tabs>
  <Tab title="Cognee Cloud">
    Call `serve()` without arguments to use the Cognee Cloud login flow.

    ```python theme={null}
    import cognee

    await cognee.serve()
    ```

    After login, Cognee stores reusable credentials at `~/.cognee/cloud_credentials.json`.
  </Tab>

  <Tab title="Explicit credentials">
    For self-hosted, staging, or non-interactive environments, pass the remote URL and API key directly.

    ```python theme={null}
    await cognee.serve(
        url="https://your-instance.cognee.ai",
        api_key="your-api-key",
    )
    ```
  </Tab>

  <Tab title="Environment variables">
    Use environment variables when you do not want credentials in code.

    ```bash theme={null}
    export COGNEE_SERVICE_URL="https://your-instance.cognee.ai"
    export COGNEE_API_KEY="your-api-key"
    ```

    ```python theme={null}
    await cognee.serve()
    ```
  </Tab>

  <Tab title="Local backend">
    Start a local backend with the CLI, then connect the SDK to it.

    ```bash theme={null}
    cognee serve
    ```

    ```python theme={null}
    await cognee.serve(url="http://localhost:8000")
    ```
  </Tab>
</Tabs>

## After serve connects

Supported SDK operations run on the connected remote instance.

```python theme={null}
await cognee.serve(
    url="https://your-instance.cognee.ai",
    api_key="your-api-key",
)

await cognee.remember("Einstein developed general relativity in 1915.")
results = await cognee.recall("What did Einstein develop?")

await cognee.disconnect()
```

<Note>
  `serve()` changes where SDK operations execute. It does not copy local datasets to the remote instance by itself. Use [Push](/core-concepts/main-operations/push) to upload an already-built local graph, or run `remember()` while connected to ingest data directly into the remote instance.
</Note>

## Examples and details

<Accordion title="Cloud login" defaultOpen>
  ```python theme={null}
  import cognee

  # Opens the browser login flow and discovers your Cloud tenant.
  await cognee.serve()

  await cognee.remember("Cloud memory note")
  results = await cognee.recall("What notes are stored?")
  ```
</Accordion>

<Accordion title="Self-hosted server">
  ```python theme={null}
  import cognee

  await cognee.serve(
      url="https://memory.example.com",
      api_key="ck_live_...",
  )

  await cognee.remember("Runbook: deploys happen on Tuesdays.")
  ```
</Accordion>

<Accordion title="Return to local mode">
  ```python theme={null}
  await cognee.disconnect()

  # This now runs against local Cognee storage again.
  await cognee.remember("Local-only note")
  ```
</Accordion>

## See also

* [Push](/core-concepts/main-operations/push)
* [Syncing a local instance](/cognee-cloud/connections/syncing-local-instance)
* [Cloud SDK](/cognee-cloud/connections/cloud-sdk)
* [Deploy REST API server](/guides/deploy-rest-api-server)