|
1 | | -# EverOS Cloud SDK for Python |
| 1 | +<div align="center" id="readme-top"> |
2 | 2 |
|
3 | | -Official Python client for the **EverOS Cloud Memory API** (v2). |
| 3 | + |
4 | 4 |
|
5 | | -> **This code is generated** from the EverOS OpenAPI contract. Please file bugs and |
6 | | -> feature requests as issues — pull requests against the generated source will be |
7 | | -> overwritten on the next release. Corrections flow through the internal SDK factory. |
| 5 | +<h3 align="center">☁️ Managed long-term memory for AI agents — the official <b>Cloud</b> Python SDK</h3> |
8 | 6 |
|
9 | | -## Install |
| 7 | +<p align="center"> |
| 8 | + <a href="https://x.com/evermind"><img src="https://img.shields.io/badge/EverMind-000000?labelColor=gray&style=for-the-badge&logo=x&logoColor=white" alt="X"></a> |
| 9 | + <a href="https://huggingface.co/EverMind-AI"><img src="https://img.shields.io/badge/🤗_HuggingFace-EverMind-F5C842?labelColor=gray&style=for-the-badge" alt="HuggingFace"></a> |
| 10 | + <a href="https://discord.gg/gYep5nQRZJ"><img src="https://img.shields.io/badge/Discord-EverMind-404EED?labelColor=gray&style=for-the-badge&logo=discord&logoColor=white" alt="Discord"></a> |
| 11 | +</p> |
10 | 12 |
|
11 | | -```sh |
12 | | -pip install everos-cloud |
13 | | -``` |
| 13 | +<p align="center"> |
| 14 | + <a href="https://pypi.org/project/everos-cloud/"><img src="https://img.shields.io/pypi/v/everos-cloud?color=2DABC2&style=for-the-badge" alt="PyPI"></a> |
| 15 | + <img src="https://img.shields.io/pypi/pyversions/everos-cloud?style=for-the-badge" alt="Python"> |
| 16 | + <img src="https://img.shields.io/badge/license-Apache--2.0-green?style=for-the-badge" alt="License"> |
| 17 | +</p> |
14 | 18 |
|
15 | | -Release candidates need `--pre`: `pip install --pre everos-cloud==1.0.0rc1`. |
| 19 | +[Website](https://evermind.ai) · [Documentation](https://docs.evermind.ai) · [Dashboard](https://everos.evermind.ai) |
16 | 20 |
|
17 | | -> **Upgrading from 0.4.x?** `everos-cloud` 1.0.0 is a **rewrite, not an increment**. The |
18 | | -> 0.x line was a different client (httpx-based, hand-maintained); 1.x is generated from |
19 | | -> the EverOS OpenAPI contract and has a different API surface — client classes, method |
20 | | -> names, and model types all changed. The import path (`everos_cloud`) is unchanged. |
21 | | -> Pin `everos-cloud<1` if you are not ready to migrate. |
| 21 | +</div> |
22 | 22 |
|
23 | | -## Authentication |
| 23 | +<br> |
24 | 24 |
|
25 | | -All requests use your EverOS API key as a bearer token: |
| 25 | +> **Which package?** This is **EverOS Cloud** — the managed SaaS client (`pip install everos-cloud`). |
| 26 | +> Want to self-host? Use the open-source [`everos`](https://pypi.org/project/everos/) library instead. |
26 | 27 |
|
27 | | -```python |
28 | | -from everos_cloud import Configuration |
29 | | -config = Configuration(access_token="sk-...") # sent as: Authorization: Bearer sk-... |
| 28 | +# EverOS Cloud — Python SDK |
| 29 | + |
| 30 | +Give your AI agents memory that persists across sessions — managed, searchable, and typed. |
| 31 | +Add a conversation; EverOS turns it into structured, retrievable memory you can query in one call. |
| 32 | + |
| 33 | +## Why EverOS Cloud |
| 34 | + |
| 35 | +- **Self-evolving memory** — memory doesn't just pile up, it improves. Background |
| 36 | + consolidation merges related episodes and refines user profiles over time, so recall |
| 37 | + gets sharper the more your agent is used. |
| 38 | +- **Structured memory, not chat logs** — extracts episodes, user profiles, and reusable |
| 39 | + agent cases & skills from raw conversations, so retrieval returns meaning, not transcripts. |
| 40 | +- **Retrieval that fits the query** — keyword, vector, hybrid (default), or agentic multi-step search. |
| 41 | +- **Multimodal** — attach images, audio, and documents to any message. |
| 42 | +- **Built for production** — fully managed (no vector DB or extraction pipeline to run), |
| 43 | + with low-latency retrieval and high-concurrency throughput. The engineering guarantees |
| 44 | + you don't get from self-hosting. |
| 45 | +- **Fully typed (pydantic v2)** — every request/response is a typed model with full hints, |
| 46 | + so you get editor autocomplete and validation instead of raw dicts. |
| 47 | + |
| 48 | +## Install |
| 49 | + |
| 50 | +```sh |
| 51 | +pip install everos-cloud |
30 | 52 | ``` |
31 | 53 |
|
32 | | -The default host is `https://api.evermind.ai`; override with `Configuration(host=...)`. |
| 54 | +> Pre-releases need `--pre`: `pip install --pre everos-cloud`. |
| 55 | +> Upgrading from the 0.4.x client? 1.x is a rewrite with a new API surface — see the |
| 56 | +> [migration guide](https://docs.evermind.ai/api-reference/sdk-migration). Pin |
| 57 | +> `everos-cloud<1` to stay on the old client. |
33 | 58 |
|
34 | 59 | ## Quickstart |
35 | 60 |
|
36 | | -The snippet below exercises the six Memory endpoints. Every Memory call takes a |
37 | | -single typed input model and returns a typed response envelope (`result.data`). |
38 | | -Object storage lives on a separate `StorageApi` (see below). |
| 61 | +Get an API key from the [dashboard](https://everos.evermind.ai), then: |
39 | 62 |
|
40 | 63 | ```python |
41 | 64 | from everos_cloud import ApiClient, Configuration, MemoryApi |
42 | | -from everos_cloud.models import ( |
43 | | - AddInput, MessageItem, Content, SearchInput, GetInput, DeleteInput, |
44 | | - EditInput, AddOperation, EditInputOperationsInner, FlushInput, |
45 | | -) |
| 65 | +from everos_cloud.models import AddInput, MessageItem, Content, SearchInput |
46 | 66 |
|
47 | 67 | config = Configuration(access_token="sk-...") |
48 | 68 |
|
49 | 69 | with ApiClient(config) as client: |
50 | 70 | memory = MemoryApi(client) |
51 | 71 |
|
52 | | - # ── Add messages ────────────────────────────────────────────────────────── |
53 | | - # Async by default: returns HTTP 202 with status "queued" and extraction runs |
54 | | - # in the background. Pass async_mode=False to write synchronously and surface |
55 | | - # write errors directly. |
56 | 72 | memory.add_memory(AddInput( |
57 | 73 | session_id="session-1", |
58 | | - messages=[ |
59 | | - MessageItem( |
60 | | - sender_id="user-1", |
61 | | - role="user", # user | assistant | tool |
62 | | - timestamp=1700000000, |
63 | | - content=Content("I love hiking in the mountains"), |
64 | | - ) |
65 | | - ], |
| 74 | + messages=[MessageItem( |
| 75 | + sender_id="user-1", role="user", timestamp=1700000000, |
| 76 | + content=Content("I love hiking in the mountains"), |
| 77 | + )], |
66 | 78 | )) |
67 | 79 |
|
68 | | - # ── Search memories ─────────────────────────────────────────────────────── |
69 | | - # method: keyword | vector | hybrid (default) | agentic |
70 | | - result = memory.search_memory(SearchInput( |
71 | | - query="outdoor hobbies", |
72 | | - method="hybrid", |
73 | | - top_k=10, |
74 | | - include_profile=True, |
75 | | - )) |
| 80 | + result = memory.search_memory(SearchInput(query="outdoor hobbies", method="hybrid")) |
76 | 81 | print(result.data) |
77 | | - |
78 | | - # ── Get memories (paginated) ────────────────────────────────────────────── |
79 | | - # memory_type: episode | profile | agent_case | agent_skill |
80 | | - page = memory.get_memory(GetInput( |
81 | | - memory_type="episode", |
82 | | - page=1, |
83 | | - page_size=20, |
84 | | - sort_order="desc", # by timestamp (default) |
85 | | - )) |
86 | | - print(page.data) |
87 | | - |
88 | | - # ── Edit profile (bulk, Cloud-only) ─────────────────────────────────────── |
89 | | - # 1–50 operations; each must be wrapped in EditInputOperationsInner. |
90 | | - # action: add | update | delete · type: explicit_info | implicit_traits |
91 | | - memory.edit_profile(EditInput( |
92 | | - user_id="user-1", |
93 | | - operations=[ |
94 | | - EditInputOperationsInner(AddOperation( |
95 | | - action="add", |
96 | | - type="explicit_info", |
97 | | - data={"category": "hobby", "description": "Enjoys hiking in the mountains"}, |
98 | | - reason="Stated in session-1", |
99 | | - )), |
100 | | - ], |
101 | | - )) |
102 | | - |
103 | | - # ── Delete memories (scoped soft-delete, Cloud-only) ────────────────────── |
104 | | - # Scope the delete by any combination of user_id / agent_id / session_id. |
105 | | - memory.delete_memory(DeleteInput(user_id="user-1", session_id="session-1")) |
106 | | - |
107 | | - # ── Flush a session (force boundary detection + extraction) ──────────────── |
108 | | - # Extraction is normally async; flush forces it for a session and returns |
109 | | - # status "extracted" or "no_extraction". The generated method name mirrors |
110 | | - # the operationId. |
111 | | - flushed = memory.flush_api_v2_memory_flush_post(FlushInput(session_id="session-1")) |
112 | | - print(flushed.data.status) # "extracted" | "no_extraction" |
113 | 82 | ``` |
114 | 83 |
|
115 | | -## Uploading multimodal data (`StorageApi`) |
116 | | - |
117 | | -Attaching images, audio, or documents to a message is a two-step flow: ask the |
118 | | -API to presign an upload, then `POST` the bytes directly to S3 using the returned |
119 | | -form fields. The sign endpoint lives on `StorageApi`. |
120 | | - |
121 | | -Unlike the Memory endpoints, `sign_objects` returns the raw MMS envelope: business |
122 | | -outcome is carried in `status` (`0` means success) and the payload in |
123 | | -`result.data` — check `status == 0` before reading it. |
124 | | - |
125 | | -```python |
126 | | -import requests |
127 | | -from everos_cloud import ApiClient, Configuration, StorageApi |
128 | | -from everos_cloud.models import SignRequest, SignObjectItem |
129 | | - |
130 | | -config = Configuration(access_token="sk-...") |
131 | | - |
132 | | -with ApiClient(config) as client: |
133 | | - storage = StorageApi(client) |
134 | | - |
135 | | - # ── Presign uploads (≤ 50 objects; each file_id unique) ──────────────────── |
136 | | - # file_type: image | file | video |
137 | | - envelope = storage.sign_objects(SignRequest( |
138 | | - object_list=[ |
139 | | - SignObjectItem(file_id="file-1", file_name="photo.jpg", file_type="image"), |
140 | | - ], |
141 | | - )) |
142 | | - |
143 | | - if envelope.status != 0: # 0 == success; see status codes below |
144 | | - raise RuntimeError(f"sign failed: status={envelope.status} error={envelope.error}") |
145 | | - |
146 | | - # ── Upload the bytes straight to S3 with the presigned POST form ─────────── |
147 | | - for obj in envelope.result.data.object_list: |
148 | | - signed = obj.object_signed_info # url + fields + maxSize |
149 | | - with open("photo.jpg", "rb") as fh: |
150 | | - resp = requests.post( |
151 | | - signed.url, |
152 | | - data=signed.fields, # presigned form fields |
153 | | - files={"file": fh}, |
154 | | - ) |
155 | | - resp.raise_for_status() # 204 from S3 on success |
156 | | - print(obj.object_key) # reference this key back in /add |
157 | | -``` |
158 | | - |
159 | | -Non-zero `status` values surface business errors rather than raising — common |
160 | | -ones are `2018` (validation failed), `1012` (bad/expired token), `1002` |
161 | | -(unsupported `file_type`), and `1007` (more than 50 objects). See the `signObjects` |
162 | | -description in `openapi.json` for the full list. |
163 | | - |
164 | | -## Methods |
165 | | - |
166 | | -`MemoryApi` mirrors the v2 endpoints: |
167 | | - |
168 | | -| Method | Endpoint | Notes | |
169 | | -|---|---|---| |
170 | | -| `add_memory(AddInput)` | `POST /api/v2/memory/add` | Async by default (202 `queued`); `async_mode=False` for sync 200. | |
171 | | -| `search_memory(SearchInput)` | `POST /api/v2/memory/search` | Keyword / vector / hybrid / agentic. | |
172 | | -| `get_memory(GetInput)` | `POST /api/v2/memory/get` | Paginated list by `memory_type`. | |
173 | | -| `delete_memory(DeleteInput)` | `POST /api/v2/memory/delete` | Scoped soft-delete. | |
174 | | -| `edit_profile(EditInput)` | `POST /api/v2/memory/edit` | Bulk profile add/update/delete operations. | |
175 | | -| `flush_api_v2_memory_flush_post(FlushInput)` | `POST /api/v2/memory/flush` | Force boundary detection + extraction for a session. | |
176 | | - |
177 | | -`StorageApi` covers object upload: |
178 | | - |
179 | | -| Method | Endpoint | Notes | |
180 | | -|---|---|---| |
181 | | -| `sign_objects(SignRequest)` | `POST /api/v1/object/sign` | Presign ≤ 50 objects for direct-to-S3 upload; returns the MMS envelope (`status == 0` on success). | |
182 | | - |
183 | | -### A note on message `content` |
184 | | - |
185 | | -`MessageItem.content` accepts either a plain string or a list of content items. In |
186 | | -this SDK both are passed through the `Content` wrapper: |
187 | | - |
188 | | -```python |
189 | | -Content("hello") # plain text (shorthand) |
190 | | -Content([ContentItem(type="text", text="hello")]) # explicit item list |
191 | | -``` |
| 84 | +**Full usage** — all six Memory endpoints, profile editing, deletion, and multimodal |
| 85 | +uploads — is in **[quickstart.md](quickstart.md)**. |
192 | 86 |
|
193 | | -Either serializes to the correct wire shape. |
| 87 | +## Documentation |
194 | 88 |
|
195 | | -## Links |
| 89 | +- [Full SDK usage](quickstart.md) |
| 90 | +- [Quickstart](https://docs.evermind.ai/cloud/quickstart) |
| 91 | +- [API Reference](https://docs.evermind.ai/api-reference/introduction) |
| 92 | +- [Core Concepts](https://docs.evermind.ai/cloud/concepts/memory-lifecycle) |
196 | 93 |
|
197 | | -- API reference: per-endpoint and model docs under [`docs/`](docs/). |
198 | | -- Issues: https://github.com/EverMind-AI/everos-cloud-sdk-python/issues |
| 94 | +<p align="right"><a href="#readme-top">back to top</a></p> |
0 commit comments