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
Today's Path · Your 4 steps

Today you only do 4 things.

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

01 / INSTALL
pip install everos

One command. Python 3.12+. No Docker, no MongoDB, no Redis.

~ 1 min
02 / CONFIGURE
everos init → .env

Drop in 2 API keys: OpenRouter (LLM) + DeepInfra (embedding).

~ 3 min
03 / HELLO
Your first memory call

curl POST /api/v1/memory/add → search it back. That's it.

~ 5 min
04 / BUILD
Fork 20+ community projects

Pick the closest demo → change 30% → ship your product.

~ 30 min
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.
Step 01 · Install

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_URL env vars
terminal
$ 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
Step 02 · Configure

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 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 · generated by everos init
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.
Step 03 · Start the server

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: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
terminal 1 · server
$ 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"}
Step 04 · Store your first memory

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.

POST /api/v1/memory/add · POST /api/v1/memory/search
# 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"
  }'
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.
Step 04b · Verify your memory

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.

~/my-project — bash · add + search roundtrip
$ 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
Step 04b · What this means

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. Run everos server start
  • 500 + LLM error → OpenRouter key not set or wrong model
  • Empty memories → wait 5 seconds; extraction has async lag from boundary detection
Architecture · The 3-part local stack

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.

7,300 GitHub stars and 726 forks. SOTA on 93.05% LoCoMo, 83.00% LongMemEval, and 93.04% HaluMem. Apache 2.0 licensed.
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
Features · Multimodal ingestion

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.

Images
PNG · JPG · GIF · WebP · SVG
Documents
PDF · DOC · PPT · XLS
Audio
MP3 · WAV · voice notes
HTML & Email
HTML · EML · MSG
curl · send an image for memory extraction
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]. LibreOffice also needed for .doc/.ppt/.xls. The multimodal LLM is configured separately from the chat LLM — one OpenRouter key covers both.
Use Cases · 20+ real demos · Pick the closest to your product

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

Build · Fork → Modify → Ship

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 everoseveros initeveros 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
terminal · quick start
# 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.
Tips · Battle-tested

5 lessons from teams who shipped with EverOS.

1

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.

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.

Features · Self-evolution & OME

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.

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.

terminal · check what EverOS learned
# 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
Features · Dual-track memory & orthogonal retrieval

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.

Agent Memory Track
Cases
Successful task completions — "how we solved X last time"
Skills
Extracted patterns from repeated cases — reusable workflows
~/.everos/{app}/{project}/agents/{id}/cases/
~/.everos/{app}/{project}/agents/{id}/skills/
User Memory Track
Episodes
Conversation segments with timestamps — "what happened when"
Profile
Clustered user facts — preferences, habits, context
~/.everos/{app}/{project}/users/{id}/episodes/
~/.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.

Resources · Where to go when you're stuck

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

People — EverOS maintainer: X @elliotchen200 · GitHub @cyfyifanchen · Email: contact@evermind.ai · deepwiki.com/EverMind-AI/EverOS for AI Q&A.
EverOS 1.0.0 · Local-first · Markdown as source of truth

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 · SOTA benchmarks
93.05% LoCoMo · 83.00% LongMemEval
EverOS 1.0.0 · three pillars
Use CasesMethodsBenchmarks
QR: luma.com/kxnzm12b
Event · Luma
QR: discord.gg/cswGFwFumn
Hackathon Discord
discord.gg/cswGFwFumn
QR: github.com/EverMind-AI/EverOS
EverOS Repo
github.com/EverMind-AI/EverOS
QR: everos.evermind.ai
EverOS Cloud
everos.evermind.ai

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