# EverOS

> EverOS is the Memory Operating System for Agentic AI. It gives LLM agents persistent, structured memory that extracts knowledge from conversations and multimodal data, resolves contradictions, and retrieves context intelligently — so agents remember, learn, and evolve across sessions.

Docs: https://docs.evermind.ai
Dashboard & API keys: https://everos.evermind.ai
GitHub (open source): https://github.com/EverMind-AI/EverOS
Python SDK: pip install everos
API base URL: https://api.evermind.ai
Auth: Bearer token in Authorization header
Contact: contact@evermind.ai | Discord: https://discord.gg/geHdX4F24B

## TL;DR (3 API Calls)

```
1. POST /api/v1/memories        — Add messages (user_id, messages[])
2. POST /api/v1/memories/flush  — Trigger memory extraction (user_id)
3. POST /api/v1/memories/search — Retrieve context (query, filters={user_id}, method="hybrid", top_k=5)
```

After these 3 calls, your agent has persistent, cross-session memory. EverOS replaces ad-hoc memory (chat history, RAG hacks) with a structured, persistent memory layer.

Note: Memory extraction is asynchronous by default. Call `/flush` to force immediate processing, or poll `GET /api/v1/tasks/{task_id}` to track status. Search results may not reflect the latest writes until extraction completes.

## Recommended Agent Loop

```
On every user interaction:

1. SEARCH  →  POST /api/v1/memories/search  (method="hybrid", top_k=5-10)
              Use returned episode summaries and profile attributes as context (not raw message logs).
              If no memories are found, proceed without memory context.

2. GENERATE  →  Call your LLM with the search results (episode summaries + profile attributes) as context.

3. ADD     →  POST /api/v1/memories  (store the user + assistant messages)
   FLUSH   →  POST /api/v1/memories/flush  (forces extraction; without this, extraction runs async on its own schedule)

Tip: Use consistent session_id values to group related interactions and avoid fragmented memory.

Repeat across sessions. EverOS handles consolidation and profile evolution automatically.
```

## When to Use EverOS

**Use EverOS if:**
- You need memory that persists across sessions
- You need user modeling (preferences, traits, history)
- You want automatic memory extraction from conversations
- You have multi-user conversations needing per-participant attribution

**Do NOT use if:**
- You only need static document retrieval (use standard RAG)
- You don't need persistence between sessions

## How It Works

EverOS implements a three-phase biological memory lifecycle:

1. **Episodic Trace Formation** — Detects semantic boundaries in dialogue (topic shifts, time gaps) and segments interactions into structured MemCells containing an episode narrative, atomic facts, foresight predictions, and metadata.
2. **Semantic Consolidation** — Clusters MemCells into thematic MemScenes, resolves contradictions between old and new facts, and maintains a dynamic User Profile. Runs asynchronously.
3. **Reconstructive Recollection** — Actively rebuilds context for the current task by activating relevant MemScenes and traversing memory graphs, rather than passively keyword-matching.

## Memory Types

| Type | API value | What it captures |
|------|-----------|-----------------|
| Episode | `episodic_memory` | Narrative summaries of conversations |
| Profile | `profile` | Persistent user attributes and preferences |
| Foresight | `foresight` | Time-bounded future predictions (assistant scene only) |
| EventLog | `eventlog` | Atomic factual event records (assistant scene only) |
| Agent Case | `agent_case` | Task approach and quality from agent trajectories |
| Agent Skill | `agent_skill` | Generalized skills distilled from agent cases |

## Scenario Modes (set once per Memory Space)

- **Personal AI Assistant** (`assistant`) — 1 human + AI. All memory types. Human-centric extraction.
- **Team Collaboration** (`group_chat`) — Multi-participant. Episode + profile only. Per-participant attribution.

## SDK Quickstart

```python
from everos import EverOS
import time

client = EverOS(api_key="your_api_key")  # or set EVEROS_API_KEY env var
memories = client.v1.memories
now_ms = int(time.time() * 1000)

# Add memories
memories.add(
    user_id="user_001", session_id="session_001",
    messages=[{"role": "user", "timestamp": now_ms, "content": "I like black coffee, no sugar."}],
)
memories.flush(user_id="user_001", session_id="session_001")  # trigger extraction

# Search memories
results = memories.search(
    filters={"user_id": "user_001"}, query="coffee preference", method="hybrid", top_k=5,
)

# Get memories by type
profile = memories.get(filters={"user_id": "user_001"}, memory_type="profile")
```

## API Endpoints (v1)

| Operation | Method & Path | Key params |
|-----------|--------------|------------|
| Add personal memories | `POST /api/v1/memories` | `user_id`, `messages[]` |
| Add group memories | `POST /api/v1/memories/group` | `group_id`, `messages[]` (each needs `sender_id`) |
| Add agent memories | `POST /api/v1/memories/agent` | `user_id`, `messages[]` (supports role: tool) |
| Flush personal | `POST /api/v1/memories/flush` | `user_id` |
| Flush group | `POST /api/v1/memories/group/flush` | `group_id` |
| Flush agent | `POST /api/v1/memories/agent/flush` | `user_id` |
| Get memories | `POST /api/v1/memories/get` | `memory_type`, `filters` |
| Search memories | `POST /api/v1/memories/search` | `query`, `filters`, `method`, `top_k` |
| Delete memories | `POST /api/v1/memories/delete` | `memory_id` or `user_id`/`group_id` filters |
| Create/get/update group | `POST/GET/PATCH /api/v1/groups` | `group_id` |
| Create/get/update sender | `POST/GET/PATCH /api/v1/senders` | `sender_id` |
| Get task status | `GET /api/v1/tasks/{task_id}` | |
| Upload file (pre-sign) | `POST /api/v1/object/sign` | `objectList[]` |
| Get/update settings | `GET/PUT /api/v1/settings` | |

## Retrieval Methods

| Method | Latency | Best for |
|--------|---------|----------|
| `keyword` | <100ms | Exact terms, known phrases (BM25) |
| `vector` | 200-500ms | Semantic similarity, paraphrased queries |
| `hybrid` | 200-600ms | **Recommended default** (keyword + vector + rerank) |
| `agentic` | 2-5s | Complex multi-part questions (LLM-guided). Use only when hybrid is insufficient. Fallback to hybrid on timeout. |

Defaults: `method="hybrid"`, `top_k=5-10` for most use cases. Always start with `hybrid` — only escalate to `agentic` for complex, multi-part queries.

## Filters DSL

Used in get and search endpoints. Always include `user_id` unless querying group-level data (then use `group_id`).

```json
{"user_id": "u1", "AND": [{"timestamp": {"gte": 1700000000}}, {"session_id": "s1"}]}
```

Supported fields: `user_id` (eq, in), `group_id` (eq, in), `session_id` (eq, in, gt, gte, lt, lte), `timestamp` (eq, gt, gte, lt, lte). Combinators: `AND`, `OR`.

## Multimodal Support

Messages accept an array of content items instead of a plain string. Upload files via `POST /api/v1/object/sign`, then reference the returned `objectKey` as `uri`. Supported types: text, image, audio, doc, pdf, html, email. The Python SDK auto-handles uploads from local paths or URLs.

## Further Reading

For full API schemas, request/response examples, cookbook patterns, and open-source deployment:
- llms-full.txt: detailed reference (same directory)
- Full docs: https://docs.evermind.ai