# EverOS 1.0.0 Workshop · Local-first memory for every agent

> 40-minute hands-on onboarding to EverOS 1.0.0 — the local-first, open-source memory OS for self-evolving agents. Live deck: https://workshop-evermind-hackathon.vercel.app/

## Slide 1 — 40 minutes. Ship memory into your agent.
*EverOS 1.0.0 · Workshop · 40 min · Local-first · Markdown as Source of Truth*

### 40 minutes. Ship memory into your agent.

EverOS 1.0.0 is the local-first memory OS for self-evolving agents. This workshop goes from zero to a working memory: no Docker, no cloud signup, just Python and two API keys.

- EverOS 1.0.0
- Local-first
- Apache 2.0
- Markdown + SQLite + LanceDB

Press → for step one · F fullscreen · Esc exit

## Slide 2 — Today you only do 4 things.
*Today's Path · Your 4 steps*

No Docker, no cloud signup. Python 3.12+, two API keys, and a cup of coffee.

- **01 / INSTALL — pip install everos** (~1 min) — One command. Python 3.12+. No Docker, no MongoDB, no Redis.
- **02 / CONFIGURE — everos init → .env** (~3 min) — Drop in 2 API keys: OpenRouter (LLM) + DeepInfra (embedding).
- **03 / HELLO — Your first memory call** (~5 min) — curl POST /api/v1/memory/add → search it back. That's it.
- **04 / BUILD — Fork 20+ community projects** (~30 min) — Pick the closest demo → change 30% → ship your product.

**Core principle:** EverOS 1.0.0 is local-first — Markdown is the source of truth, SQLite + LanceDB are indexes. Your memory lives on your machine, readable in any editor.

## Slide 3 — pip install everos.
*Step 01 · Install*

One command. Python 3.12+. No Docker, no MongoDB, no Elasticsearch, no Redis. The entire memory stack runs locally.

**What you need**

- **Python 3.12+** — Check with `python3 --version` — macOS ships 3.9, you may need to upgrade
- **An OpenRouter API key** — Covers the chat LLM (memory extraction) AND multimodal LLM (image/PDF parsing) with one key
- **A DeepInfra API key** — For embedding + rerank models that OpenRouter doesn't ship
- **That's it: two keys total** — Any OpenAI-compatible endpoint plugs in via `*__BASE_URL` env vars

```
$ python3 --version
Python 3.12.8

$ pip install everos
Installing collected packages: everos, lancedb, sqlmodel, ...
Successfully installed everos-1.0.0

$ everos --version
everos 1.0.0
```

## Slide 4 — everos init → drop in 2 keys.
*Step 02 · Configure*

`everos init` generates a starter `.env` with all the slots pre-filled. You only need to paste two distinct API keys.

- **Run `everos init`** — Writes `./.env` with `0600` permissions (only you can read it)
- **Paste your OpenRouter key into `EVEROS_LLM__API_KEY`** — Same key works for `EVEROS_MULTIMODAL__API_KEY`; one key, two jobs
- **Paste your DeepInfra key into `EVEROS_EMBEDDING__API_KEY`** — Same key works for `EVEROS_RERANK__API_KEY`; one key, two jobs
- **Add .env to .gitignore immediately** — Before your first commit. Key leaks = credit zeroed out.

```env
EVEROS_LLM__API_KEY=sk-or-v1-your-openrouter-key
EVEROS_LLM__MODEL=openai/gpt-4.1-mini
EVEROS_LLM__BASE_URL=https://openrouter.ai/api/v1
EVEROS_MULTIMODAL__API_KEY=sk-or-v1-your-openrouter-key
EVEROS_MULTIMODAL__MODEL=google/gemini-3-flash-preview
EVEROS_EMBEDDING__API_KEY=your-deepinfra-key
EVEROS_EMBEDDING__MODEL=Qwen/Qwen3-Embedding-4B
EVEROS_RERANK__API_KEY=your-deepinfra-key
EVEROS_RERANK__MODEL=Qwen/Qwen3-Reranker-4B
```

**Only 2 distinct keys needed.** OpenRouter covers LLM + multimodal. DeepInfra covers embedding + rerank. Any OpenAI-compatible endpoint works — override with `*__BASE_URL` env vars.

## Slide 5 — everos server start.
*Step 03 · Start the server*

The server runs in the foreground. Open a second terminal for API calls. The cascade index daemon runs in the same process; no separate worker needed.

- **Server starts on `127.0.0.1:8000`** — Loopback only; your memory stays local. Put your own auth gateway in front for remote access.
- **SQLite + LanceDB initialize automatically** — Stored at `~/.everos/`; Markdown files are the source of truth, indexes are rebuildable
- **Cascade daemon watches for new Markdown** — Drop a `.md` file in `~/.everos/` and it gets indexed automatically
- **Ctrl+C to stop** — Graceful shutdown; all in-flight extractions finish before exit

```
$ everos server start
starting everos on 127.0.0.1:8000
INFO:     Uvicorn running on http://127.0.0.1:8000

# In a second terminal, verify:
$ curl http://127.0.0.1:8000/health
{"status":"ok"}
```

## Slide 6 — Two APIs. Just these two.
*Step 04 · Store your first memory*

EverOS makes "memory" into CRUD: `POST /api/v1/memory/add` to store · `POST /api/v1/memory/search` to query. 99% of what you'll use is these two endpoints.

**curl:**
```bash
# 1) Store a memory
TS=$(($(date +%s)*1000))
curl -X POST http://127.0.0.1:8000/api/v1/memory/add \
  -H "Content-Type: application/json" \
  -d '{"session_id":"demo-001","messages":[{"sender_id":"user_001",
    "role":"user","timestamp":'"$TS"',
    "content":"I love playing soccer on weekends"}]}'
# → {"data":{"message_count":1,"status":"accumulated"}}

# 2) Flush to force extraction (boundary detector)
curl -X POST http://127.0.0.1:8000/api/v1/memory/flush \
  -H "Content-Type: application/json" \
  -d '{"session_id":"demo-001"}'
# → {"data":{"status":"extracted"}}

# 3) Search with natural language — hybrid retrieval (vector + BM25)
curl -X POST http://127.0.0.1:8000/api/v1/memory/search \
  -H "Content-Type: application/json" \
  -d '{"user_id":"user_001","query":"What sports does the user like?",
    "method":"hybrid"}'
```

**Python:**
```python
import httpx, time
API = "http://127.0.0.1:8000/api/v1"
httpx.post(f"{API}/memory/add", json={"session_id":"demo-001","messages":[
    {"sender_id":"user_001","role":"user","timestamp":int(time.time()*1000),
     "content":"I love playing soccer on weekends"}]})
httpx.post(f"{API}/memory/flush", json={"session_id":"demo-001"})
res = httpx.post(f"{API}/memory/search", json={"user_id":"user_001",
    "query":"What sports does the user like?","method":"hybrid"})
print(res.json())
```

**Success = add returns "accumulated" + flush returns "extracted" + search returns episodes with a score.** If you don't see it, first `curl http://127.0.0.1:8000/health` — if it's not running, go back to Step 03.

## Slide 7 — This is what a working memory looks like.
*Step 04 · What you should see*

EverOS isn't chat completion; it extracts raw content into structured memory with episodes / atomic facts / timestamps. Markdown files are the source of truth.

```
$ TS=$(($(date +%s)*1000))
$ curl -s -X POST http://127.0.0.1:8000/api/v1/memory/add \
  -H 'Content-Type: application/json' \
  -d "{\"session_id\":\"demo-001\",\"messages\":[{\"sender_id\":\"user\",
  \"role\":\"user\",\"timestamp\":$TS,
  \"content\":\"I love playing soccer on weekends\"}]}"
{"request_id":"a1b2c3...","data":{"message_count":1,"status":"accumulated"}}

$ curl -s -X POST http://127.0.0.1:8000/api/v1/memory/flush \
  -H 'Content-Type: application/json' \
  -d '{"session_id":"demo-001"}'
{"request_id":"d4e5f6...","data":{"status":"extracted"}}

$ curl -s -X POST http://127.0.0.1:8000/api/v1/memory/search \
  -H 'Content-Type: application/json' \
  -d '{"user_id":"user_001","query":"sports hobbies","method":"hybrid"}'
{
  "request_id": "g7h8i9...",
  "data": {
    "episodes": [{
      "id": "user_001_ep_20260612_001",
      "session_id": "demo-001",
      "summary": "User loves playing soccer on weekends",
      "episode": "I love playing soccer on weekends",
      "score": 0.628,
      "timestamp": "2026-06-12T10:30:00Z"
    }],
    "profiles": [],
    "agent_cases": [],
    "agent_skills": [],
    "unprocessed_messages": []
  }
}

# Check the Markdown source of truth (app_id/project_id form dirs):
$ cat ~/.everos/default_app/default_project/users/user_001/episodes/*.md
---
id: episode_log_user_001_2026-06-12
type: episode_daily
session_id: demo-001
timestamp: 2026-06-12T10:30:00Z
---
I love playing soccer on weekends
```

**✓ Seeing this means** EverOS server is running, LLM + embedding keys are wired up, memory is stored as readable Markdown in `~/.everos/`.

**✗ If you don't see it** `Connection refused` → run `everos server start`. `500 + LLM error` → check OpenRouter key. Empty memories → wait 5 seconds; extraction has async lag.

## Slide 8 — Markdown + SQLite + LanceDB.
*Architecture · The 3-part local stack*

EverOS 1.0.0 is local-first. No MongoDB, no Elasticsearch, no Redis. Your memory lives on your machine as readable Markdown files.

**5.6k+ GitHub Stars · Apache 2.0 · 93.05% LoCoMo SOTA · 20+ Use Cases**

- **Markdown · Source of Truth** — All memory persisted as `.md` files: readable, editable, grep-able, Git-versioned, openable in Obsidian. Stored at `~/.everos/`.
- **SQLite · State & Metadata** — Cascade work queue, change tracking, conversation status. Single-file DB at `~/.everos/.index/sqlite/`.
- **LanceDB · Vectors + BM25** — Hybrid retrieval: vector similarity + full-text BM25 + scalar filters. Rebuildable from Markdown. At `~/.everos/.index/lancedb/`.

**SOTA benchmarks, open-source verifiable:** 93.05% LoCoMo · 83.00% LongMemEval · 93.04% HaluMem

## Slide 9 — Images, PDFs, audio → searchable memory.
*Features · Multimodal ingestion*

EverOS turns non-text content into the same structured memory as plain text. Attach an asset at ingest time; a vision/audio LLM parses it, and it flows through the same extraction → Markdown → index pipeline.

- **Images** — PNG · JPG · GIF · WebP · SVG
- **Documents** — PDF · DOC · PPT · XLS
- **Audio** — MP3 · WAV · voice notes
- **HTML & Email** — HTML · EML · MSG

```bash
curl -X POST http://127.0.0.1:8000/api/v1/memory/add \
  -H "Content-Type: application/json" \
  -d '{"session_id":"mm-001","messages":[
    {"sender_id":"alice","role":"user","timestamp":1748390400000,
     "content":[
       {"type":"text","text":"Here is the whiteboard from today."},
       {"type":"image","uri":"https://example.com/whiteboard.png"}
     ]}]}'
```

**Install the extra:** `pip install 'everos[multimodal]'` pulls in `everalgo-parser[svg]`. The multimodal LLM is configured separately from the chat LLM — one OpenRouter key covers both.

## Slide 10 — Stand on 20 shoulders.
*Use Cases · 20+ real demos · Pick the closest to your product*

All 20 from github.com/EverMind-AI/EverOS#use-cases — Click any tile to open the repo — Fork → 30% change → submit.

Use cases include: Claude Code Plugin, Game of Thrones, OpenHer, Reunite, Hive Orchestrator, Ruminer Browser, EverMem Sync, Earth Online, Golutra, MCO Coding Agents, Study Buddy, MemoCare, NeuralConnect, Mobi Companion, Spiro Wearable, Live2D + TEN, Computer-Use, Taste Verse, Memory Graph, EverMemOS MCP.

## Slide 11 — From demo to your product.
*Build · Fork → Modify → Ship*

EverOS ships 20+ runnable use cases. Pick the one closest to your product, swap 30%, and you have a working memory-powered app.

1. **Pick a use case from the wall** — Claude Code Plugin, Game of Thrones, OpenHer, Study Buddy: pick the closest to your idea
2. **Fork the repo on GitHub** — github.com/EverMind-AI/EverOS → top-right Fork → your account
3. **Get the local server running** — `pip install everos` → `everos init` → `everos server start`
4. **Modify → your product** — Swap prompts · swap user_id structure · plug in your frontend · add multimodal inputs
5. **Record a 2:30 demo video** — Show a working memory cycle: add → extract → search → recall

```
# 1. Install
$ pip install everos

# 2. Configure
$ everos init
  → writes .env with API key slots

# 3. Start server
$ everos server start
  → Uvicorn running on http://127.0.0.1:8000

# 4. Verify
$ curl http://127.0.0.1:8000/health
  → {"status":"ok"}
```

**Pro tip:** Check `~/.everos/` after your first memory add — you'll see the Markdown files. Open them in Obsidian or any editor. That's your memory, human-readable.

## Slide 12 — 5 lessons from teams who shipped with EverOS.
*Tips · Battle-tested*

1. **Check ~/.everos/ early** — After your first memory add, look at the Markdown files. Understanding the storage layout helps you debug everything downstream.
2. **Boundary detection needs a few messages** — EverOS waits for a conversation boundary before extracting. Send 3-5 messages in a session before searching. Or use `/api/v1/memory/flush` to force extraction.
3. **Use session_id consistently** — Same `session_id` = same conversation thread. Different `session_id` = independent memories. Structure your sessions to match your product's UX.
4. **Markdown is your debug tool** — Can't figure out what EverOS extracted? Read the `.md` files directly. `grep -r "your keyword" ~/.everos/` beats any API debug endpoint.
5. **Local-first means no rate limits on your memory** — The only rate limits are on the LLM API calls (OpenRouter/DeepInfra). Your memory storage and retrieval are unlimited and instant. Experiment freely.

## Slide 13 — Your agent gets smarter over time.
*Features · Self-evolution & OME*

EverOS doesn't just store memories; it evolves them. The Offline Memory Engine (OME) extracts common skills from real usage, clusters repeated patterns, and builds reusable workflows; no retraining required.

- **Skill Extraction** — Repeated interaction patterns are automatically identified and stored as reusable `agent_skill` entries. Your agent learns from its own trajectory.
- **Profile Clustering** — User facts are clustered into a coherent `user_profile`. Atomic facts from conversations get organized into a structured profile over time.
- **Foresight** — Predictive memory entries that anticipate what the user might need next based on patterns. The agent becomes proactive, not just reactive.

```
# Skills extracted from agent usage:
$ ls ~/.everos/default_app/default_project/agents/*/skills/
skill-2026-06-12-git-workflow.md
skill-2026-06-12-api-patterns.md

# User profile (auto-clustered from conversations):
$ cat ~/.everos/default_app/default_project/users/user_001/user.md
---
kind: profile
---
# User Profile
- Prefers Python over JavaScript
- Works on web backend projects
- Usually codes in the evening
```

## Slide 14 — Agent memory ≠ user memory.
*Features · Dual-track memory & orthogonal retrieval*

EverOS extracts two independent tracks: agent memory (cases & skills from trajectories) and user memory (episodes & profile from conversations). Search by any dimension independently.

**Agent Memory Track**
- Cases — Successful task completions — "how we solved X last time"
- Skills — Extracted patterns from repeated cases — reusable workflows
- Storage: `~/.everos/{app}/{project}/agents/{id}/cases/` and `~/.everos/{app}/{project}/agents/{id}/skills/`

**User Memory Track**
- Episodes — Conversation segments with timestamps — "what happened when"
- Profile — Clustered user facts — preferences, habits, context
- Storage: `~/.everos/{app}/{project}/users/{id}/episodes/` and `~/.everos/{app}/{project}/users/{id}/user.md`

**Orthogonal retrieval — search by any dimension:** `user_id` · `agent_id` · `app_id` · `project_id` · `session_id`

Each filter is independent. Search one user across all agents, or one agent across all users. Mix and match.

## Slide 15 — Docs, community, and the code itself.
*Resources · Where to go when you're stuck*

- **Documentation** — `docs.evermind.ai` — Full API reference, architecture, quick start, multimodal guide. `QUICKSTART.md` in the repo; 5 min from zero to working memory.
- **GitHub** — `github.com/EverMind-AI/EverOS` — 5.6k+ stars · Apache 2.0 · 20+ use cases in-repo. `github.com/EverMind-AI/EverAlgo` — Modular algorithm library.
- **Community** — Discord: `discord.gg/gYep5nQRZJ` (biweekly AMA). X: `@evermind`. Reddit: r/EverMindAI.
- **People** — EverOS Maintainer: X `@elliotchen200` · GitHub `@cyfyifanchen`. Email: contact@evermind.ai.

## Slide 16 — Keep in Mind. Evolve over Time.
*EverOS 1.0.0 · Local-first · Markdown as source of truth*

Memory is your unfair advantage. EverOS makes it local-first, readable, and self-evolving. Build something that remembers.

**EverOS 1.0.0 · SOTA benchmarks:** 93.05% LoCoMo · 83.00% LongMemEval

**EverOS 1.0.0 · three pillars:** Use Cases · Methods · Benchmarks

**Links:**
- X: @evermind
- HF: EverMind-AI
- Discord: discord.gg/gYep5nQRZJ
- WeCom: Community
- GitHub: EverMind-AI

**EverOS Repo:** github.com/EverMind-AI/EverOS
**EverOS Cloud:** everos.evermind.ai

EverOS 1.0.0 · Local-first · Markdown as source of truth · Apache 2.0