Upgrade Python SDK to 1.x

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.

The v1 API retires soon. This upgrade is no longer optional for anyone still on 0.4.x. See v1 API Retirement for the timeline, what happens to your data, and how to get help with the migration.

1.x calls the v2 Memory API. If a call returns 403 VERSION_NOT_ALLOWED, your account is not enabled for v2 yet. Contact us and we will sort it out.

Install

pip install -U everos-cloud        # 1.x

Not ready yet? Pin to the old client:

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

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.

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.

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.

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

# 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

# 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")

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

Errors

All failures now derive from a single EverOSError hierarchy:

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 for the typed usage.

Getting Started

Migration

Memory

Knowledge Bases

Async Tasks

Storage

Upgrade Python SDK to 1.x

Install

At a glance

Client initialization

Add memories

Search

Get, flush, delete

Errors

Prefer the typed low-level client?

​Install

​At a glance

​Client initialization

​Add memories

​Search

​Get, flush, delete

​Errors

​Prefer the typed low-level client?

Install

At a glance

Client initialization

Add memories

Search

Get, flush, delete

Errors

Prefer the typed low-level client?