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.
Press → for step one · F fullscreen · Esc exit
Today you only do 4 things.
No Docker, no cloud signup. Python 3.12+, two API keys, and a cup of coffee.
One command. Python 3.12+. No Docker, no MongoDB, no Redis.
Drop in 2 API keys: OpenRouter (LLM) + DeepInfra (embedding).
curl POST /api/v1/memory/add → search it back. That's it.
Pick the closest demo → change 30% → ship your product.
pip install everos.
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_URLenv 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
everos init → drop in 2 keys.
everos init generates a starter .env with all the slots pre-filled. You only need to paste two distinct API keys.
- Run
everos initWrites./.envwith0600permissions (only you can read it) - Paste your OpenRouter key into
EVEROS_LLM__API_KEYSame key works forEVEROS_MULTIMODAL__API_KEY; one key, two jobs - Paste your DeepInfra key into
EVEROS_EMBEDDING__API_KEYSame key works forEVEROS_RERANK__API_KEY; one key, two jobs - Add .env to .gitignore immediately Before your first commit. Key leaks = credit zeroed out.
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
*__BASE_URL env vars.
everos server start.
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.
What happens
- Server starts on
127.0.0.1:8000Loopback 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
.mdfile 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"}
Two APIs. Just these two.
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.
# 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" }'
# EverOS 1.0.0 · local-first memory API import httpx, time API = "http://127.0.0.1:8000/api/v1" # 1) Store a memory 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", }], }) # 2) Flush to force extraction httpx.post(f"{API}/memory/flush", json={"session_id": "demo-001"}) # 3) Search it back res = httpx.post(f"{API}/memory/search", json={ "user_id": "user_001", "query": "What sports does the user like?", "method": "hybrid", }) print(res.json())
// EverOS 1.0.0 · Node 18+ · requires .mjs or "type":"module" in package.json const API = "http://127.0.0.1:8000/api/v1"; // 1) Store a memory await fetch(`${API}/memory/add`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ session_id: "demo-001", messages: [{ sender_id: "user_001", role: "user", timestamp: Date.now(), content: "I love playing soccer on weekends", }], }), }); // 2) Flush to force extraction await fetch(`${API}/memory/flush`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ session_id: "demo-001" }), }); // 3) Search const res = await fetch(`${API}/memory/search`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ user_id: "user_001", query: "What sports does the user like?", method: "hybrid", }), }); console.log(await res.json());
curl http://127.0.0.1:8000/health — if it's not running, go back to Step 03.
This is what a working memory looks like.
EverOS isn't chat completion; it extracts raw content into structured memory with episodes / atomic facts / timestamps. The /flush endpoint forces extraction before search.
$ 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_001\", \"role\":\"user\",\"timestamp\":$TS, \"content\":\"I love playing soccer on weekends\"}]}" {"request_id":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4","data":{"message_count":1,"status":"accumulated"}} # Flush to force extraction (boundary detector needs this for single-message sessions): $ 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":"d4e5f6a7b8c9d4e5f6a7b8c9d4e5f6a7","data":{"status":"extracted"}} # Now search — hybrid retrieval (vector + BM25): $ 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": "a7b8c9d0e1f2a7b8c9d0e1f2a7b8c9d0", "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
Your memory is now searchable Markdown.
✓ Seeing this means
- EverOS server is running on localhost:8000
- LLM + embedding keys are wired up correctly
- Memory is stored as readable Markdown in
~/.everos/
✗ If you don't see it
Connection refused→ server isn't running. Runeveros server start500 + LLM error→ OpenRouter key not set or wrong model- Empty memories → wait 5 seconds; extraction has async lag from boundary detection
Markdown + SQLite + LanceDB.
EverOS 1.0.0 is local-first. No MongoDB, no Elasticsearch, no Redis. Your memory lives on your machine as readable Markdown files.
All memory persisted as .md files: readable, editable, grep-able, Git-versioned, openable in Obsidian. Stored at ~/.everos/.
Cascade work queue, change tracking, conversation status. Single-file DB at ~/.everos/.index/sqlite/.
Hybrid retrieval: vector similarity + full-text BM25 + scalar filters. Rebuildable from Markdown. At ~/.everos/.index/lancedb/.
Images, PDFs, audio → searchable memory.
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.
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"} ] }] }'
pip install 'everos[multimodal]' pulls in everalgo-parser[svg]. LibreOffice also needed for .doc/.ppt/.xls. The multimodal LLM is configured separately from the chat LLM — one OpenRouter key covers both.
Stand on 20 shoulders.
↑ All 20 from github.com/EverMind-AI/EverOS#use-cases · Click any tile to open the repo · Fork → 30% change → submit
From demo to your product.
EverOS has 20+ community projects to learn from. 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"}
~/.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.
5 lessons from teams who shipped with EverOS.
Check ~/.everos/ early
After your first memory add, look at the Markdown files in ~/.everos/default_app/default_project/. Understanding the storage layout helps you debug everything downstream.
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.
Use session_id consistently
Same session_id = same conversation thread. Different session_id = independent memories. Structure your sessions to match your product's UX.
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.
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.
Your agent gets smarter over time.
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.
Repeated interaction patterns are automatically identified and stored as reusable agent_skill entries. Your agent learns from its own trajectory.
User facts are clustered into a coherent user_profile. Atomic facts from conversations get organized into a structured profile over time.
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 (single-file rewrite, auto-clustered): $ 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
Agent memory ≠ user memory.
EverOS extracts two independent tracks: agent memory (cases & skills from trajectories) and user memory (episodes & profile from conversations). Search by any dimension independently.
~/.everos/{app}/{project}/agents/{id}/cases/~/.everos/{app}/{project}/agents/{id}/skills/
~/.everos/{app}/{project}/users/{id}/episodes/~/.everos/{app}/{project}/users/{id}/user.md
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.
Docs, community, and the code itself.
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
7.3k stars · 726 forks · Apache 2.0
github.com/EverMind-AI/EverAlgo
Modular algorithm library
Community
Discord: discord.gg/gYep5nQRZJ
Biweekly AMA; talk directly with maintainers
X: @evermind
Reddit: r/EverMindAI
deepwiki.com/EverMind-AI/EverOS for AI Q&A.
Keep
in Mind.
Evolve
over Time.
Memory is your unfair advantage. EverOS makes it local-first, readable, and self-evolving. Build something that remembers.
EverOS 1.0.0 · Local-first · Markdown as source of truth · Apache 2.0