> ## 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.
# Your First Memory in 5 Minutes
> Store a conversation, extract it into memory, and search it back with EverOS
Get EverOS working in under 5 minutes.
By the end you'll have stored a short conversation, extracted it into a memory,
and searched it back: the full memory loop, in one script.
These guides use **EverOS Cloud** and the everos-cloud Python SDK.
The underlying v2 Memory API is the same on Cloud and self-hosted, so the
patterns here apply to both:
* **Cloud:** use the everos-cloud SDK, as shown in these guides.
* **Self-hosted (OSS):** call the same v2 endpoints on your own host. See [Open Source](/open-source/overview).
## Prerequisites
```bash theme={null}
pip install everos-cloud
export EVEROS_API_KEY="your_api_key"
```
Get a key from the [EverOS Console](https://everos.evermind.ai/api-keys).
The EverOS client reads `EVEROS_API_KEY` automatically.
## Step 1: Store a conversation
Send a few messages into a session.
Each message carries a `sender_id`: the participant the memory is attributed to.
```python theme={null}
from everos_cloud import EverOS
client = EverOS() # reads EVEROS_API_KEY
client.add(
session_id="quickstart_001",
messages=[
{"sender_id": "user_alice", "role": "user",
"content": "I prefer working in the morning, usually 6am to 10am — that's when I'm most productive."},
{"sender_id": "assistant", "role": "assistant",
"content": "Got it — I'll keep mornings free for your deep work."},
{"sender_id": "user_alice", "role": "user",
"content": "Afternoons are for meetings, never before noon."},
],
async_mode=False, # wait for the write to land so we can extract immediately
)
```
**Why `async_mode=False`?**
By default writes are asynchronous. Add returns immediately and EverOS ingests
in the background.
This demo sets `async_mode=False` so the messages are stored before the next
step runs.
In production, leave it on the default and let extraction run in the background.
## Step 2: Extract the memory
Extraction normally waits for a conversation boundary, such as a topic change or
a time gap.
Call flush to run boundary detection now and extract what's ready.
```python theme={null}
client.flush("quickstart_001")
```
In production you don't need to flush every turn. Let EverOS batch and extract on its own.
Flush when you need a memory available *now*: the end of a session, or right
before a search that depends on the latest turn.
## Step 3: Search your memory
Search within a user's memories.
Search requires a `user_id` (or `agent_id`) and returns ranked episodes, each
with a full narrative and a relevance score.
```python theme={null}
results = client.search(
"when does alice prefer to work",
user_id="user_alice",
method="hybrid",
top_k=5,
)
episodes = results.episodes or []
print(f"Found {len(episodes)} relevant memories:\n")
for ep in episodes:
print(f"Summary: {ep.summary}")
print(f"Score: {ep.score:.3f}")
print("-" * 40)
```
**Example output:**
```
Found 1 relevant memories:
Summary: Alice told the assistant she prefers working in the morning from 6 AM
to 10 AM because that is when she is most productive. She stated that afternoons
are for meetings, never before noon.
Score: 0.352
----------------------------------------
```
**Nothing came back?**
Episodes only exist once extraction has run, and a very short exchange may not
form one at all.
To make extraction happen now, write with `async_mode=False` and then call
flush, as Steps 1 and 2 do.
To read the turns that haven't been extracted yet, pin the session in your
search:
```python theme={null}
results = client.search(
"when does alice prefer to work",
user_id="user_alice",
filters={"session_id": "quickstart_001"},
)
for msg in (results.unprocessed_messages or []):
print(msg.role, msg.content)
```
That returns the session's raw buffered messages alongside any episodes, so a
live agent sees the latest turns instead of a gap. It only works when you pin
one session this way. Searching by `user_id` alone never returns them.
## Complete script
Copy, set your key, and run:
```python theme={null}
# pip install everos-cloud -U
# export EVEROS_API_KEY="your_api_key"
from everos_cloud import EverOS
client = EverOS()
# 1. Store a conversation (async_mode=False so it lands before we extract)
print("1. Storing conversation...")
client.add(
session_id="quickstart_bob",
messages=[
{"sender_id": "user_bob", "role": "user",
"content": "I love hiking on weekends, especially in the mountains."},
{"sender_id": "assistant", "role": "assistant",
"content": "Nice — I'll suggest mountain trails for your weekend plans."},
{"sender_id": "user_bob", "role": "user",
"content": "Please do. I try to get out every Saturday."},
],
async_mode=False,
)
# 2. Force extraction
print("2. Extracting memory...")
client.flush("quickstart_bob")
# 3. Search
print("3. Searching memories...\n")
results = client.search(
"outdoor activities bob enjoys",
user_id="user_bob",
method="hybrid",
top_k=5,
)
episodes = results.episodes or []
print(f"Found {len(episodes)} memories:")
for ep in episodes:
print(f"Summary: {ep.summary}")
print(f"Score: {ep.score:.3f}")
print("-" * 40)
```
## What's next?
Build a 1:1 assistant that remembers preferences and context across sessions.
Attribute memory per participant in group chats and meetings.
Production patterns: error handling, retries, and clean client setup.
Full v2 endpoint docs with request/response schemas.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.