Skip to content

Commit 6d145bc

Browse files
Daniclaude
andcommitted
docs(v1): rewrite README as a concise overview
Marketing-style landing: hero, value props (self-evolving memory, structured memory, retrieval modes, multimodal, production, typed), install, minimal quickstart. Full usage moves to quickstart.md. Reuses the EverOS brand banner with a prominent 'Cloud' subtitle and a 'which package?' pointer to distinguish from the OSS everos library. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent ef167fb commit 6d145bc

1 file changed

Lines changed: 61 additions & 165 deletions

File tree

‎README.md‎

Lines changed: 61 additions & 165 deletions
Original file line numberDiff line numberDiff line change
@@ -1,198 +1,94 @@
1-
# EverOS Cloud SDK for Python
1+
<div align="center" id="readme-top">
22

3-
Official Python client for the **EverOS Cloud Memory API** (v2).
3+
![EverOS banner](https://github.com/user-attachments/assets/8e217d39-5d15-4c6c-9b54-3e83add4e0f2)
44

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>
86

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>
1012

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>
1418

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)
1620

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>
2222

23-
## Authentication
23+
<br>
2424

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.
2627
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
3052
```
3153

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.
3358
3459
## Quickstart
3560

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:
3962

4063
```python
4164
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
4666

4767
config = Configuration(access_token="sk-...")
4868

4969
with ApiClient(config) as client:
5070
memory = MemoryApi(client)
5171

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.
5672
memory.add_memory(AddInput(
5773
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+
)],
6678
))
6779

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"))
7681
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"
11382
```
11483

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)**.
19286

193-
Either serializes to the correct wire shape.
87+
## Documentation
19488

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)
19693

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

Comments
 (0)