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

# Upgrade Python SDK to 1.x

> Migrate the everos-cloud Python SDK from the 0.4.x client to 1.x (the v2 Memory API).

`everos-cloud` **1.x is a rewrite**, not an increment. The 0.4.x line was a
hand-maintained httpx client targeting the v1 API; 1.x is generated from the
EverOS OpenAPI contract and ships an ergonomic `EverOS` wrapper over it, targeting
the **v2 Memory API**. Client classes, method names, parameters, and memory-type
values all changed. The import path (`everos_cloud`) is unchanged.

<Note>
  Your API key works on both versions, and v1 keeps serving until it retires.

  The two versions hold separate memory stores, so what you wrote through v1 is not visible
  through v2 until your data is migrated. We migrate it as part of the retirement. If you want
  it in v2 earlier, contact us and we will schedule it for a date you choose.

  See [v1 API Retirement](/api-reference/v1-sunset) for what the retirement means for you.
</Note>

<Tip>
  Prefer not to do this by hand? The [migration tool](/api-reference/sdk-migration) applies
  every change on this page and reports what it could not. Start with
  `/everos-sdk-upgrade --scan`, which edits nothing.
</Tip>

## Install

```sh theme={null}
pip install -U everos-cloud        # 1.x
```

Not ready yet? Pin to the old client:

```sh theme={null}
pip install "everos-cloud<1"
```

## At a glance

| | 0.4.x | 1.x |
| - | - | - |
| Client | `EverOS(api_key=..., base_url=...)` | `EverOS(api_key=..., host=...)` |
| Calls | `client.v1.memories.add(...)` | `client.add(...)` (no `v1.memories`) |
| Add owner | `add(user_id=..., ...)` | `sender_id` inside each message |
| Search scope | `search(filters={"user_id": ...}, ...)` | `search(query, user_id=...)` |
| Memory types | `episodic_memory / profile / raw_message / agent_memory` | `episode / profile / agent_case / agent_skill` |
| Errors | `everos_cloud.APIError` (and subclasses) | `EverOSError` (`EverOSAPIError`, `EverOSStorageError`) |
| API | `/api/v1/memories/*` | `/api/v2/memory/*` |

## Client initialization

```python theme={null}
from everos_cloud import EverOS

client = EverOS(
    api_key="sk-...",        # required: 1.x does NOT read EVEROS_API_KEY
    host="https://...",      # was base_url=; NOT read from EVER_OS_BASE_URL either
)
```

Three things changed here, and two of them are easy to miss.

**`api_key` is now required.** In 0.4.x it defaulted to `None` and the client read
`EVEROS_API_KEY` from the environment. 1.x reads no environment variables at all, so
`EverOS()` raises `TypeError`. This one fails loudly.

<Warning>
  **`EVER_OS_BASE_URL` is no longer read either, and this one fails silently.** 0.4.x
  picked the base URL up from the environment. 1.x only honours `host=`. If you point at
  a non-production host through the environment and do not pass `host=` explicitly, the
  client falls back to production and starts reading and writing real data with no error.

  Search your `.env` files, CI configuration, Dockerfiles and compose files for
  `EVER_OS_BASE_URL` before you upgrade.
</Warning>

**Some constructor options are gone.** 1.x accepts only
`api_key`, `host`, `app_id`, `project_id` and `timeout`. `max_retries`,
`http_client`, `default_headers` and `default_query` have no equivalent. Note that
0.4.x retried twice by default and 1.x does not retry at all, so if you relied on that,
add your own retry layer.

**There is no async client.** `AsyncEverOS` was removed with no replacement. Run the
synchronous client in a thread, or call `/api/v2/memory/*` with your own async HTTP
client.

## Add memories

`user_id` moved off the call and onto each message as `sender_id`; `session_id` is
now required. Messages are plain dicts, and `timestamp` (if you set it) must be a
**unix millisecond** value. Omit it and the SDK stamps `now` for you.

```python theme={null}
# 0.4.x
client.v1.memories.add(
    user_id="user-1",
    session_id="session-1",
    messages=[{"role": "user", "content": "I love hiking"}],
)

# 1.x
client.add(
    session_id="session-1",
    messages=[{"sender_id": "user-1", "role": "user", "content": "I love hiking"}],
)
```

## Search

`filters={"user_id": ...}` becomes a `user_id` (or `agent_id`) argument (exactly one is
required), and the response `.data` is returned directly.

```python theme={null}
# 0.4.x
client.v1.memories.search(
    filters={"user_id": "user-1"},
    query="outdoor hobbies",
    method="vector",
    top_k=5,
)

# 1.x
client.search(
    "outdoor hobbies",
    user_id="user-1",
    method="vector",     # keyword | vector | hybrid (default) | agentic
    top_k=5,
)
```

## Get, flush, delete

```python theme={null}
# 1.x
client.get("episode", user_id="user-1")      # episode | profile | agent_case | agent_skill
client.flush("session-1")                     # force extraction for a session
client.delete(user_id="user-1", session_id="session-1")
```

<Note>
  Memory-type values changed: `episodic_memory` → `episode`, `agent_memory` splits
  into `agent_case` / `agent_skill`, and `raw_message` is no longer a retrievable type.
</Note>

## Errors

All failures now derive from a single `EverOSError` hierarchy:

```python theme={null}
from everos_cloud import EverOSError

try:
    client.add(session_id="s1", messages=[...])
except EverOSError as e:
    ...   # EverOSAPIError (HTTP errors) or EverOSStorageError (uploads)
```

## Prefer the typed low-level client?

The generated `MemoryApi` / `StorageApi` are still available for full control,
exposed as `client.memory` / `client.storage`. See the
[SDK quickstart](https://github.com/EverMind-AI/everos-cloud-sdk-python/blob/v1/quickstart.md)
for the typed usage.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.