diff --git a/README.md b/README.md index 95d5913..ccdba2f 100644 --- a/README.md +++ b/README.md @@ -1,198 +1,94 @@ -# EverOS Cloud SDK for Python +
-Official Python client for the **EverOS Cloud Memory API** (v2). +![EverOS banner](https://github.com/user-attachments/assets/8e217d39-5d15-4c6c-9b54-3e83add4e0f2) -> **This code is generated** from the EverOS OpenAPI contract. Please file bugs and -> feature requests as issues โ€” pull requests against the generated source will be -> overwritten on the next release. Corrections flow through the internal SDK factory. +

โ˜๏ธ Managed long-term memory for AI agents โ€” the official Cloud Python SDK

-## Install +

+ X + HuggingFace + Discord +

-```sh -pip install everos-cloud -``` +

+ PyPI + Python + License +

-Release candidates need `--pre`: `pip install --pre everos-cloud==1.0.0rc1`. +[Website](https://evermind.ai) ยท [Documentation](https://docs.evermind.ai) ยท [Dashboard](https://everos.evermind.ai) -> **Upgrading from 0.4.x?** `everos-cloud` 1.0.0 is a **rewrite, not an increment**. The -> 0.x line was a different client (httpx-based, hand-maintained); 1.x is generated from -> the EverOS OpenAPI contract and has a different API surface โ€” client classes, method -> names, and model types all changed. The import path (`everos_cloud`) is unchanged. -> Pin `everos-cloud<1` if you are not ready to migrate. +
-## Authentication +
-All requests use your EverOS API key as a bearer token: +> **Which package?** This is **EverOS Cloud** โ€” the managed SaaS client (`pip install everos-cloud`). +> Want to self-host? Use the open-source [`everos`](https://pypi.org/project/everos/) library instead. -```python -from everos_cloud import Configuration -config = Configuration(access_token="sk-...") # sent as: Authorization: Bearer sk-... +# EverOS Cloud โ€” Python SDK + +Give your AI agents memory that persists across sessions โ€” managed, searchable, and typed. +Add a conversation; EverOS turns it into structured, retrievable memory you can query in one call. + +## Why EverOS Cloud + +- **Self-evolving memory** โ€” memory doesn't just pile up, it improves. Background + consolidation merges related episodes and refines user profiles over time, so recall + gets sharper the more your agent is used. +- **Structured memory, not chat logs** โ€” extracts episodes, user profiles, and reusable + agent cases & skills from raw conversations, so retrieval returns meaning, not transcripts. +- **Retrieval that fits the query** โ€” keyword, vector, hybrid (default), or agentic multi-step search. +- **Multimodal** โ€” attach images, audio, and documents to any message. +- **Built for production** โ€” fully managed (no vector DB or extraction pipeline to run), + with low-latency retrieval and high-concurrency throughput. The engineering guarantees + you don't get from self-hosting. +- **Fully typed (pydantic v2)** โ€” every request/response is a typed model with full hints, + so you get editor autocomplete and validation instead of raw dicts. + +## Install + +```sh +pip install everos-cloud ``` -The default host is `https://api.evermind.ai`; override with `Configuration(host=...)`. +> Pre-releases need `--pre`: `pip install --pre everos-cloud`. +> Upgrading from the 0.4.x client? 1.x is a rewrite with a new API surface โ€” see the +> [migration guide](https://docs.evermind.ai/api-reference/sdk-migration). Pin +> `everos-cloud<1` to stay on the old client. ## Quickstart -The snippet below exercises the six Memory endpoints. Every Memory call takes a -single typed input model and returns a typed response envelope (`result.data`). -Object storage lives on a separate `StorageApi` (see below). +Get an API key from the [dashboard](https://everos.evermind.ai), then: ```python from everos_cloud import ApiClient, Configuration, MemoryApi -from everos_cloud.models import ( - AddInput, MessageItem, Content, SearchInput, GetInput, DeleteInput, - EditInput, AddOperation, EditInputOperationsInner, FlushInput, -) +from everos_cloud.models import AddInput, MessageItem, Content, SearchInput config = Configuration(access_token="sk-...") with ApiClient(config) as client: memory = MemoryApi(client) - # โ”€โ”€ Add messages โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ - # Async by default: returns HTTP 202 with status "queued" and extraction runs - # in the background. Pass async_mode=False to write synchronously and surface - # write errors directly. memory.add_memory(AddInput( session_id="session-1", - messages=[ - MessageItem( - sender_id="user-1", - role="user", # user | assistant | tool - timestamp=1700000000, - content=Content("I love hiking in the mountains"), - ) - ], + messages=[MessageItem( + sender_id="user-1", role="user", timestamp=1700000000, + content=Content("I love hiking in the mountains"), + )], )) - # โ”€โ”€ Search memories โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ - # method: keyword | vector | hybrid (default) | agentic - result = memory.search_memory(SearchInput( - query="outdoor hobbies", - method="hybrid", - top_k=10, - include_profile=True, - )) + result = memory.search_memory(SearchInput(query="outdoor hobbies", method="hybrid")) print(result.data) - - # โ”€โ”€ Get memories (paginated) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ - # memory_type: episode | profile | agent_case | agent_skill - page = memory.get_memory(GetInput( - memory_type="episode", - page=1, - page_size=20, - sort_order="desc", # by timestamp (default) - )) - print(page.data) - - # โ”€โ”€ Edit profile (bulk, Cloud-only) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ - # 1โ€“50 operations; each must be wrapped in EditInputOperationsInner. - # action: add | update | delete ยท type: explicit_info | implicit_traits - memory.edit_profile(EditInput( - user_id="user-1", - operations=[ - EditInputOperationsInner(AddOperation( - action="add", - type="explicit_info", - data={"category": "hobby", "description": "Enjoys hiking in the mountains"}, - reason="Stated in session-1", - )), - ], - )) - - # โ”€โ”€ Delete memories (scoped soft-delete, Cloud-only) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ - # Scope the delete by any combination of user_id / agent_id / session_id. - memory.delete_memory(DeleteInput(user_id="user-1", session_id="session-1")) - - # โ”€โ”€ Flush a session (force boundary detection + extraction) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ - # Extraction is normally async; flush forces it for a session and returns - # status "extracted" or "no_extraction". The generated method name mirrors - # the operationId. - flushed = memory.flush_api_v2_memory_flush_post(FlushInput(session_id="session-1")) - print(flushed.data.status) # "extracted" | "no_extraction" ``` -## Uploading multimodal data (`StorageApi`) - -Attaching images, audio, or documents to a message is a two-step flow: ask the -API to presign an upload, then `POST` the bytes directly to S3 using the returned -form fields. The sign endpoint lives on `StorageApi`. - -Unlike the Memory endpoints, `sign_objects` returns the raw MMS envelope: business -outcome is carried in `status` (`0` means success) and the payload in -`result.data` โ€” check `status == 0` before reading it. - -```python -import requests -from everos_cloud import ApiClient, Configuration, StorageApi -from everos_cloud.models import SignRequest, SignObjectItem - -config = Configuration(access_token="sk-...") - -with ApiClient(config) as client: - storage = StorageApi(client) - - # โ”€โ”€ Presign uploads (โ‰ค 50 objects; each file_id unique) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ - # file_type: image | file | video - envelope = storage.sign_objects(SignRequest( - object_list=[ - SignObjectItem(file_id="file-1", file_name="photo.jpg", file_type="image"), - ], - )) - - if envelope.status != 0: # 0 == success; see status codes below - raise RuntimeError(f"sign failed: status={envelope.status} error={envelope.error}") - - # โ”€โ”€ Upload the bytes straight to S3 with the presigned POST form โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ - for obj in envelope.result.data.object_list: - signed = obj.object_signed_info # url + fields + maxSize - with open("photo.jpg", "rb") as fh: - resp = requests.post( - signed.url, - data=signed.fields, # presigned form fields - files={"file": fh}, - ) - resp.raise_for_status() # 204 from S3 on success - print(obj.object_key) # reference this key back in /add -``` - -Non-zero `status` values surface business errors rather than raising โ€” common -ones are `2018` (validation failed), `1012` (bad/expired token), `1002` -(unsupported `file_type`), and `1007` (more than 50 objects). See the `signObjects` -description in `openapi.json` for the full list. - -## Methods - -`MemoryApi` mirrors the v2 endpoints: - -| Method | Endpoint | Notes | -|---|---|---| -| `add_memory(AddInput)` | `POST /api/v2/memory/add` | Async by default (202 `queued`); `async_mode=False` for sync 200. | -| `search_memory(SearchInput)` | `POST /api/v2/memory/search` | Keyword / vector / hybrid / agentic. | -| `get_memory(GetInput)` | `POST /api/v2/memory/get` | Paginated list by `memory_type`. | -| `delete_memory(DeleteInput)` | `POST /api/v2/memory/delete` | Scoped soft-delete. | -| `edit_profile(EditInput)` | `POST /api/v2/memory/edit` | Bulk profile add/update/delete operations. | -| `flush_api_v2_memory_flush_post(FlushInput)` | `POST /api/v2/memory/flush` | Force boundary detection + extraction for a session. | - -`StorageApi` covers object upload: - -| Method | Endpoint | Notes | -|---|---|---| -| `sign_objects(SignRequest)` | `POST /api/v1/object/sign` | Presign โ‰ค 50 objects for direct-to-S3 upload; returns the MMS envelope (`status == 0` on success). | - -### A note on message `content` - -`MessageItem.content` accepts either a plain string or a list of content items. In -this SDK both are passed through the `Content` wrapper: - -```python -Content("hello") # plain text (shorthand) -Content([ContentItem(type="text", text="hello")]) # explicit item list -``` +**Full usage** โ€” all six Memory endpoints, profile editing, deletion, and multimodal +uploads โ€” is in **[quickstart.md](quickstart.md)**. -Either serializes to the correct wire shape. +## Documentation -## Links +- [Full SDK usage](quickstart.md) +- [Quickstart](https://docs.evermind.ai/cloud/quickstart) +- [API Reference](https://docs.evermind.ai/api-reference/introduction) +- [Core Concepts](https://docs.evermind.ai/cloud/concepts/memory-lifecycle) -- API reference: per-endpoint and model docs under [`docs/`](docs/). -- Issues: https://github.com/EverMind-AI/everos-cloud-sdk-python/issues +

back to top