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

<Warning>
  1.x calls the **v2 Memory API**. Your account must be enabled for v2. A v1-only
  account gets `403 VERSION_NOT_ALLOWED`. Check with your EverOS contact before upgrading.
</Warning>

## 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=...)`                                    | `EverOS(api_key=...)`, **same**                        |
| 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: unchanged

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

client = EverOS(api_key="sk-...")     # still reads EVEROS_API_KEY if omitted
```

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