871 lines
30 KiB
Markdown
871 lines
30 KiB
Markdown
<div align="center" id="readme-top">
|
||
|
||
|
||
|
||
<p align="center">
|
||
<a href="https://x.com/evermind"><img src="https://img.shields.io/badge/EverMind-000000?labelColor=gray&style=for-the-badge&logo=x&logoColor=white" alt="X"></a>
|
||
<a href="https://huggingface.co/EverMind-AI"><img src="https://img.shields.io/badge/🤗_HuggingFace-EverMind-F5C842?labelColor=gray&style=for-the-badge" alt="HuggingFace"></a>
|
||
<a href="https://discord.gg/gYep5nQRZJ"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fdiscord.com%2Fapi%2Fv10%2Finvites%2FgYep5nQRZJ%3Fwith_counts%3Dtrue&query=%24.approximate_presence_count&suffix=%20online&label=Discord&color=404EED&labelColor=gray&style=for-the-badge&logo=discord&logoColor=white" alt="Discord"></a>
|
||
<a href="https://github.com/EverMind-AI/EverOS/discussions/67"><img src="https://img.shields.io/badge/WeCom-EverMind_社区-07C160?labelColor=gray&style=for-the-badge&logo=wechat&logoColor=white" alt="WeChat"></a>
|
||
</p>
|
||
|
||
[Website](https://evermind.ai) · [Documentation](https://docs.evermind.ai) · [Blog](https://evermind.ai/blogs) · [中文](README.zh-CN.md)
|
||
|
||
</div>
|
||
|
||
|
||
<br>
|
||
|
||
<details>
|
||
<summary><kbd>Table of Contents</kbd></summary>
|
||
|
||
<br>
|
||
|
||
- [EverOS 1.0.0](#everos-100)
|
||
- [Why Ever OS](#why-ever-os)
|
||
- [Quick Start](#quick-start)
|
||
- [Use Cases](#use-cases)
|
||
- [Architecture At A Glance](#architecture-at-a-glance)
|
||
- [Storage Layout](#storage-layout)
|
||
- [Features](#features)
|
||
- [Project Structure](#project-structure)
|
||
- [Documentation](#documentation)
|
||
- [Watch EverOS](#watch-everos)
|
||
- [EverMind Ecosystems](#evermind-ecosystems)
|
||
- [Contributing](#contributing)
|
||
|
||
<br>
|
||
|
||
</details>
|
||
|
||
|
||
## EverOS 1.0.0
|
||
|
||
> [!IMPORTANT]
|
||
>
|
||
> **EverOS 1.0.0 is a major release for self-evolving memory.** It brings a
|
||
> local-first runtime, Markdown as the source of truth, hybrid retrieval,
|
||
> multimodal ingestion, user and agent memory scopes, and modular algorithms
|
||
> through [EverAlgo](https://github.com/EverMind-AI/EverAlgo).
|
||
>
|
||
> **Coming next:** Knowledge Wiki will turn memory into editable,
|
||
> source-backed Markdown knowledge pages. Reflection will run when the
|
||
> system is idle or offline to connect signals, compress
|
||
> history, and improve profiles and skills between sessions.
|
||
|
||
<br>
|
||
<div align="right">
|
||
|
||
[](#readme-top)
|
||
|
||
</div>
|
||
|
||
|
||
## Why Ever OS
|
||
|
||
EverOS is the local memory operating system for agents and makers. It gives
|
||
one portable memory layer across coding assistants, apps, devices, and
|
||
workflows. Today it stores conversations, files, and agent trajectories as
|
||
readable Markdown, then syncs local SQLite and LanceDB indexes for fast
|
||
retrieval and self-evolving reuse.
|
||
|
||
<table>
|
||
<tr>
|
||
<th width="28%">Title</th>
|
||
<th width="36%">EverOS</th>
|
||
<th width="36%">Other Agent Memory Libraries</th>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>Markdown source of truth</strong></td>
|
||
<td>✅ Canonical <code>.md</code> files that are readable, editable, diffable, and Git-versioned</td>
|
||
<td>❌ Usually API, vector, graph, dashboard, or database state</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>Direct file editing</strong></td>
|
||
<td>✅ Edit <code>.md</code> files; cascade watcher syncs</td>
|
||
<td>❌ Usually SDK, API, dashboard, or backend update paths</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>Local three-part stack</strong></td>
|
||
<td>✅ Markdown + SQLite + LanceDB; no MongoDB, Elasticsearch, or Redis required</td>
|
||
<td>❌ Often depends on managed services, vector DBs, graph DBs, or server stacks</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>User + agent tracks</strong></td>
|
||
<td>✅ User <code>episodes/profile</code> and agent <code>cases/skills</code> are separate first-class surfaces</td>
|
||
<td>❌ Usually centered on chat history, profiles, entities, facts, or retrieval records</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>Orthogonal retrieval</strong></td>
|
||
<td>✅ Search by <code>user_id</code>, <code>agent_id</code>, <code>app_id</code>, <code>project_id</code>, and <code>session_id</code></td>
|
||
<td>❌ Usually app, namespace, tenant, thread, or graph scoped</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>Knowledge Wiki</strong></td>
|
||
<td>✅ Coming next: editable, source-backed Markdown knowledge pages built from memory</td>
|
||
<td>❌ Usually retrieval, graph, dashboards, or generated summaries instead of editable source-backed pages</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>Reflection</strong></td>
|
||
<td>✅ Coming next: Reflection that runs when the system is idle or offline to connect signals, compress history, and improve profiles and skills between sessions</td>
|
||
<td>❌ Usually online read/write APIs, retrieval records, or summaries rather than idle-time memory consolidation</td>
|
||
</tr>
|
||
</table>
|
||
|
||
<br>
|
||
<div align="right">
|
||
|
||
[](#readme-top)
|
||
|
||
</div>
|
||
|
||
|
||
## Quick Start
|
||
|
||
> Goal: start EverOS, write one memory, and search it back.
|
||
|
||
### 0. Prerequisites
|
||
|
||
- Python 3.12+
|
||
- API keys for the default providers: OpenRouter for chat / multimodal, and
|
||
DeepInfra for embedding / rerank. You can use other OpenAI-compatible
|
||
providers by changing the matching `*__BASE_URL` fields in `.env`.
|
||
|
||
### 1. Install
|
||
|
||
```bash
|
||
uv pip install everos
|
||
# or: pip install everos
|
||
```
|
||
|
||
### 2. Configure
|
||
|
||
Generate a starter `.env` file, then fill the four API key slots shown in the
|
||
generated comments. Only two distinct keys are needed with the defaults:
|
||
OpenRouter for `LLM` / `MULTIMODAL`, and DeepInfra for `EMBEDDING` / `RERANK`.
|
||
|
||
```bash
|
||
everos init
|
||
# or, from a source checkout:
|
||
cp .env.example .env
|
||
```
|
||
|
||
`everos init` writes `./.env` by default. Use `everos init --xdg` to
|
||
write `${XDG_CONFIG_HOME:-~/.config}/everos/.env` instead.
|
||
|
||
### 3. Start EverOS
|
||
|
||
```bash
|
||
everos server start
|
||
```
|
||
|
||
Keep the server running, then open a second terminal and check it:
|
||
|
||
```bash
|
||
curl http://127.0.0.1:8000/health
|
||
```
|
||
|
||
Expected response:
|
||
|
||
```json
|
||
{"status":"ok"}
|
||
```
|
||
|
||
`everos server start` searches for `.env` in this order: `--env-file <path>` →
|
||
`./.env` (cwd) → `${XDG_CONFIG_HOME:-~/.config}/everos/.env` → `~/.everos/.env`.
|
||
The endpoint stack is OpenAI-protocol compatible (OpenAI / OpenRouter / vLLM /
|
||
Ollama / DeepInfra) - override `*__BASE_URL` in the generated `.env` to point
|
||
at any of them.
|
||
|
||
### 4. Try Your First Memory
|
||
|
||
Add a tiny conversation:
|
||
|
||
```bash
|
||
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\",
|
||
\"app_id\": \"default\",
|
||
\"project_id\": \"default\",
|
||
\"messages\": [
|
||
{\"sender_id\": \"alice\", \"role\": \"user\", \"timestamp\": $TS, \"content\": \"I love climbing in Yosemite every spring.\"},
|
||
{\"sender_id\": \"alice\", \"role\": \"user\", \"timestamp\": $((TS+10000)), \"content\": \"My favorite coffee shop is Blue Bottle in SOMA.\"}
|
||
]
|
||
}"
|
||
```
|
||
|
||
Force extraction for the local demo:
|
||
|
||
```bash
|
||
curl -X POST http://127.0.0.1:8000/api/v1/memory/flush \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"session_id":"demo-001","app_id":"default","project_id":"default"}'
|
||
```
|
||
|
||
Search it back:
|
||
|
||
```bash
|
||
curl -X POST http://127.0.0.1:8000/api/v1/memory/search \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{
|
||
"user_id": "alice",
|
||
"app_id": "default",
|
||
"project_id": "default",
|
||
"query": "Where do I like to climb?",
|
||
"top_k": 5
|
||
}'
|
||
```
|
||
|
||
You should see the Yosemite memory in the response. If the result is empty on
|
||
the first try, wait a moment and retry; Markdown is written synchronously, while
|
||
the local index catches up in the background.
|
||
|
||
> [!TIP]
|
||
> **First memory unlocked.**
|
||
> You just gave EverOS a fact, flushed it into durable Markdown-backed memory,
|
||
> and searched it back through the local index. That is the core loop.
|
||
> Want to see the source of truth? Open `~/.everos` and inspect the generated
|
||
> Markdown files.
|
||
|
||
For annotated responses and the Markdown files EverOS creates, see
|
||
[QUICKSTART.md](QUICKSTART.md).
|
||
|
||
### Optional: Ingest Multimodal Files
|
||
|
||
To ingest non-text content (image / pdf / audio / office documents)
|
||
through `/api/v1/memory/add` `content` items, install the optional
|
||
extra:
|
||
|
||
```bash
|
||
uv pip install 'everos[multimodal]' # or: pip install 'everos[multimodal]'
|
||
```
|
||
|
||
This pulls in `everalgo-parser` (with the `[svg]` bundle for SVG
|
||
support via cairosvg) and wires up the multimodal LLM client
|
||
(`EVEROS_MULTIMODAL__*` fields in `.env`, defaults to
|
||
`google/gemini-3-flash-preview` via OpenRouter).
|
||
|
||
**Office document support requires LibreOffice as a system dependency.**
|
||
The parser shells out to `soffice` (LibreOffice's headless renderer) to
|
||
convert `.doc` / `.docx` / `.ppt` / `.pptx` / `.xls` / `.xlsx` to PDF
|
||
before feeding the result into the multimodal LLM. Without LibreOffice,
|
||
office uploads return HTTP 415 with a clear error message; PDF / image
|
||
/ audio / HTML / email parsing is unaffected.
|
||
|
||
Install on the host before serving office documents:
|
||
|
||
```bash
|
||
brew install --cask libreoffice # macOS
|
||
sudo apt-get install -y libreoffice # Debian / Ubuntu
|
||
```
|
||
|
||
### For Contributors
|
||
|
||
```bash
|
||
git clone https://github.com/EverMind-AI/EverOS.git
|
||
cd EverOS
|
||
uv sync # creates ./.venv and installs deps
|
||
source .venv/bin/activate # or prefix commands with `uv run`
|
||
everos init # fill the four API key slots in .env (two distinct keys)
|
||
|
||
everos --help
|
||
make test
|
||
```
|
||
|
||
<br>
|
||
<div align="right">
|
||
|
||
[](#readme-top)
|
||
|
||
</div>
|
||
|
||
## Use Cases
|
||
|
||
Now that you have had your first successful EverOS moment, explore what people
|
||
are building with persistent memory across agents, apps, and community
|
||
integrations.
|
||
|
||
Use cases show what persistent memory makes possible in real products and
|
||
workflows. Some examples are packaged in this repository; others point to
|
||
external demos or integrations you can study and adapt.
|
||
|
||
<table>
|
||
<tr>
|
||
<td width="50%" valign="top">
|
||
|
||
[](https://evermind.ai/usecase_reunite)
|
||
|
||
#### Reunite - Find With EverOS
|
||
|
||
Parents describe what they remember. Children describe what they recall. Reunite uses semantic memory to surface the connections.
|
||
|
||
[Learn more](https://evermind.ai/usecase_reunite)
|
||
|
||
</td>
|
||
<td width="50%" valign="top">
|
||
|
||
[](https://github.com/tt-a1i/hive)
|
||
|
||
#### Hive Orchestrator
|
||
|
||
Browser-native hive-mind for CLI coding agents - Claude Code, Codex, Gemini, and OpenCode collaborate as real PTY processes via a team protocol.
|
||
|
||
[Code](https://github.com/tt-a1i/hive)
|
||
|
||
</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td width="50%" valign="top">
|
||
|
||
[](https://github.com/tt-a1i/evermemos-mcp)
|
||
|
||
#### AI Coding Assistants With EverOS
|
||
|
||
Universal long-term memory layer for AI coding assistants, powered by EverOS.
|
||
|
||
[Code](https://github.com/tt-a1i/evermemos-mcp)
|
||
|
||
</td>
|
||
<td width="50%" valign="top">
|
||
|
||
[](https://github.com/yuansui123/AI-Data-Technician-EverMemOS)
|
||
|
||
#### AI Data Technician
|
||
|
||
An agentic AI system that learns from scientist interaction to inspect, analyze, and classify high-dimensional time series data - with persistent memory that improves across sessions.
|
||
|
||
[Code](https://github.com/yuansui123/AI-Data-Technician-EverMemOS)
|
||
|
||
</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td width="50%" valign="top">
|
||
|
||
|
||
|
||
#### Rokid AI Assistant With EverOS
|
||
|
||
Connect to EverOS within Rokid Glasses enabling long-term memory for all of your smart activities.
|
||
|
||
Coming soon
|
||
|
||
</td>
|
||
<td width="50%" valign="top">
|
||
|
||
|
||
|
||
#### Creative Assistant With Memory
|
||
|
||
Creative assistant with long-term memory, so your creative context stays available across sessions.
|
||
|
||
Coming soon
|
||
|
||
</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td colspan="2" align="right">
|
||
<a href="#readme-top"><img src="https://img.shields.io/badge/-Back_to_top-gray?style=flat-square" alt="Back to top"></a>
|
||
</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td width="50%" valign="top">
|
||
|
||
[](https://github.com/xunyud/Earth-Online)
|
||
|
||
#### Earth Online Memory Game
|
||
|
||
Earth Online is a memory-aware productivity game that turns everyday planning into a living quest log.
|
||
|
||
[Code](https://github.com/xunyud/Earth-Online)
|
||
|
||
</td>
|
||
<td width="50%" valign="top">
|
||
|
||
[](https://github.com/golutra/golutra)
|
||
|
||
#### Multi-Agent Orchestration Platform
|
||
|
||
Golutra presents a multi-agent workforce for engineering teams, extending the IDE model from a single assistant to coordinated agents.
|
||
|
||
[Code](https://github.com/golutra/golutra)
|
||
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td width="50%" valign="top">
|
||
|
||
[](https://github.com/Yangtze-Seventh/taste-verse)
|
||
|
||
#### Your Personal Tasting Universe
|
||
|
||
Record, visualize, and explore your tasting journey through an immersive 3D star map.
|
||
|
||
[Code](https://github.com/Yangtze-Seventh/taste-verse)
|
||
|
||
</td>
|
||
<td width="50%" valign="top">
|
||
|
||
[](https://github.com/kellyvv/OpenHer)
|
||
|
||
#### EverOS Open Her
|
||
|
||
Build AI that feels. Open-source persona engine - personality emerges from neural drives, not prompts. Inspired by Her.
|
||
|
||
[Code](https://github.com/kellyvv/OpenHer)
|
||
|
||
</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td width="50%" valign="top">
|
||
|
||
[](https://chromewebstore.google.com/detail/ruminer-browser-agent/lbccjohfpdpimbhpckljimgolndfmfif)
|
||
|
||
#### Browser Agent For Personal Memory
|
||
|
||
Ruminer brings persistent memory to a browser agent so it can carry personal context across web tasks.
|
||
|
||
[Plugin](https://chromewebstore.google.com/detail/ruminer-browser-agent/lbccjohfpdpimbhpckljimgolndfmfif)
|
||
|
||
</td>
|
||
<td width="50%" valign="top">
|
||
|
||
[](https://github.com/nanxingw/EverMem)
|
||
|
||
#### EverMem Sync With EverOS
|
||
|
||
One command to connect any AI coding CLI to EverMemOS long-term memory.
|
||
|
||
[Code](https://github.com/nanxingw/EverMem)
|
||
|
||
</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td colspan="2" align="right">
|
||
<a href="#readme-top"><img src="https://img.shields.io/badge/-Back_to_top-gray?style=flat-square" alt="Back to top"></a>
|
||
</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td width="50%" valign="top">
|
||
|
||
[](https://github.com/mco-org/mco)
|
||
|
||
#### MCO - Orchestrate AI Coding Agents
|
||
|
||
MCO equips your primary agent with an agent team that can work together to solve complex tasks.
|
||
|
||
[Code](https://github.com/mco-org/mco)
|
||
|
||
</td>
|
||
<td width="50%" valign="top">
|
||
|
||
[](https://github.com/onenewborn/StudyBuddy-public)
|
||
|
||
#### Study Buddy With Self-Evolving Memory
|
||
|
||
Study proactively with an agent that has self-evolving memory.
|
||
|
||
[Code](https://github.com/onenewborn/StudyBuddy-public)
|
||
|
||
</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td width="50%" valign="top">
|
||
|
||
[](https://github.com/TonyLiangDesign/MemoCare)
|
||
|
||
#### Alzheimer's Memory Assistant
|
||
|
||
Empowering individuals with advanced memory support and daily assistance.
|
||
|
||
[Code](https://github.com/TonyLiangDesign/MemoCare)
|
||
|
||
</td>
|
||
<td width="50%" valign="top">
|
||
|
||
[](https://github.com/AlexL1024/NeuralConnect)
|
||
|
||
#### Memory-Driven Multi-Agent NPC Experience
|
||
|
||
An iOS sci-fi mystery game where players explore and uncover the truth.
|
||
|
||
[Code](https://github.com/AlexL1024/NeuralConnect)
|
||
|
||
</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td width="50%" valign="top">
|
||
|
||
[](https://github.com/elontusk5219-prog/Mobi)
|
||
|
||
#### Mobi Companion
|
||
|
||
An iOS app where users create, nurture, and live with a personalized AI companion called Mobi.
|
||
|
||
[Code](https://github.com/elontusk5219-prog/Mobi)
|
||
|
||
</td>
|
||
<td width="50%" valign="top">
|
||
|
||
[](https://github.com/JaMesLiMers/EvermemCompetition-Spiro)
|
||
|
||
#### AI Wearable With Memory
|
||
|
||
A context-native AI wearable that listens to everyday life and converts conversations into memory.
|
||
|
||
[Code](https://github.com/JaMesLiMers/EvermemCompetition-Spiro)
|
||
|
||
</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td colspan="2" align="right">
|
||
<a href="#readme-top"><img src="https://img.shields.io/badge/-Back_to_top-gray?style=flat-square" alt="Back to top"></a>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td width="50%" valign="top">
|
||
|
||
[](docs/migration-to-1.0.0.md)
|
||
|
||
#### Legacy OpenClaw Agent Memory
|
||
|
||
Archived pre-1.0.0 plugin reference. New integrations should use the EverOS 1.0.0 API.
|
||
|
||
[Learn more](docs/migration-to-1.0.0.md)
|
||
|
||
</td>
|
||
<td width="50%" valign="top">
|
||
|
||
[](https://github.com/TEN-framework/ten-framework/tree/04cb80601374fa9e35b4e544b2dbd23286ca7763/ai_agents/agents/examples/voice-assistant-with-EverMemOS)
|
||
|
||
#### Live2D Character With Memory
|
||
|
||
Add long-term memory to a real-time Live2D character, powered by [TEN Framework](https://github.com/TEN-framework/ten-framework).
|
||
|
||
[Code](https://github.com/TEN-framework/ten-framework/tree/04cb80601374fa9e35b4e544b2dbd23286ca7763/ai_agents/agents/examples/voice-assistant-with-EverMemOS)
|
||
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td width="50%" valign="top">
|
||
|
||
[](https://screenshot-analysis-vercel.vercel.app/)
|
||
|
||
#### Computer-Use With Memory
|
||
|
||
Run screenshot-based analysis with computer-use and store the results in memory.
|
||
|
||
[Live Demo](https://screenshot-analysis-vercel.vercel.app/)
|
||
|
||
</td>
|
||
<td width="50%" valign="top">
|
||
|
||
[](use-cases/game-of-throne-demo)
|
||
|
||
#### Game Of Thrones Memories
|
||
|
||
A demonstration of AI memory infrastructure through an interactive Q&A experience with *A Game of Thrones*.
|
||
|
||
[Code](use-cases/game-of-throne-demo)
|
||
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td width="50%" valign="top">
|
||
|
||
[](use-cases/claude-code-plugin)
|
||
|
||
#### Claude Code Plugin
|
||
|
||
Persistent memory for Claude Code. Automatically saves and recalls context from past coding sessions.
|
||
|
||
[Code](use-cases/claude-code-plugin)
|
||
|
||
</td>
|
||
<td width="50%" valign="top">
|
||
|
||
[](https://main.d2j21qxnymu6wl.amplifyapp.com/graph.html)
|
||
|
||
#### Memory Graph Visualization
|
||
|
||
Explore stored entities and relationships in a graph interface. Frontend demo; backend integration is in progress.
|
||
|
||
[Live Demo](https://main.d2j21qxnymu6wl.amplifyapp.com/graph.html)
|
||
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
|
||
<br>
|
||
<div align="right">
|
||
|
||
[](#readme-top)
|
||
|
||
</div>
|
||
|
||
## Architecture At A Glance
|
||
|
||
```
|
||
┌───────────────────────────────────────────────┐
|
||
│ entrypoints/ (CLI + HTTP API) │ presentation
|
||
├───────────────────────────────────────────────┤
|
||
│ service/ (use cases: memorize/retrieve) │ application
|
||
├───────────────────────────────────────────────┤
|
||
│ memory/ (extract + search + cascade) │ domain
|
||
├───────────────────────────────────────────────┤
|
||
│ infra/ (markdown / sqlite / lancedb) │ infrastructure
|
||
└───────────────────────────────────────────────┘
|
||
↑ ↑
|
||
component/ core/
|
||
(LLM/Embedding) (observability/lifespan)
|
||
```
|
||
|
||
DDD 5 layers, single-direction dependency. See [docs/architecture.md](docs/architecture.md).
|
||
|
||
<br>
|
||
<div align="right">
|
||
|
||
[](#readme-top)
|
||
|
||
</div>
|
||
|
||
## Storage Layout
|
||
|
||
```
|
||
~/.everos/
|
||
├── default_app/ # app_id ("default" → "default_app" on disk)
|
||
│ └── default_project/ # project_id ("default" → "default_project")
|
||
│ ├── users/<user_id>/
|
||
│ │ ├── user.md # profile
|
||
│ │ ├── episodes/ # daily-log episodes (visible)
|
||
│ │ ├── .atomic_facts/ # nested facts (dotfile-hidden)
|
||
│ │ └── .foresights/ # predictive memory (dotfile-hidden)
|
||
│ └── agents/<agent_id>/
|
||
│ ├── agent.md
|
||
│ ├── .cases/ # one task case per entry
|
||
│ └── skills/ # named procedural memories
|
||
├── .index/ # derived indexes (rebuildable from md)
|
||
│ ├── sqlite/system.db # state + queue + audit
|
||
│ └── lancedb/*.lance/ # vector + BM25 + scalar
|
||
└── .tmp/ # transient working files
|
||
```
|
||
|
||
Open any `<app>/<project>/users/<user_id>/` folder in Obsidian — your
|
||
agent's brain is just files. The dotfile directories (`.atomic_facts/`,
|
||
`.foresights/`, `.cases/`) stay hidden by default so the visible folder
|
||
is the user-facing memory surface, while extracted derivatives sit
|
||
quietly alongside.
|
||
|
||
<br>
|
||
<div align="right">
|
||
|
||
[](#readme-top)
|
||
|
||
</div>
|
||
|
||
## Features
|
||
|
||
- **Hybrid retrieval**: BM25 + cosine vector ANN + scalar filters, backed by LanceDB
|
||
- **Cascade index sync**: edit a `.md` → file watcher → entry-level diff → LanceDB sync, sub-second
|
||
- **Multi-source extraction**: conversations / agent trajectories / file knowledge
|
||
- **Dual-track memory**: user-track (Episodes / Profiles) + agent-track (Cases / Skills)
|
||
- **Async-first**: full asyncio, single event loop
|
||
- **Multi-modal**: text + small image / audio inline; large media via S3/OSS reference
|
||
|
||
<br>
|
||
<div align="right">
|
||
|
||
[](#readme-top)
|
||
|
||
</div>
|
||
|
||
## Project Structure
|
||
|
||
```
|
||
everos/ # repo root
|
||
├── src/everos/ # main package (src layout)
|
||
│ ├── entrypoints/ # cli + api
|
||
│ ├── service/ # use case orchestration
|
||
│ ├── memory/ # domain: extract + search + cascade + prompt_slots
|
||
│ ├── infra/ # storage: markdown + lancedb + sqlite
|
||
│ ├── component/ # cross-cutting: llm / embedding / config / utils
|
||
│ ├── core/ # runtime: observability / lifespan / context
|
||
│ └── config/ # configuration data + Settings schema
|
||
├── tests/ # unit / integration / golden / fixtures
|
||
├── docs/ # design docs
|
||
└── .claude/ # team-shared rules + skills (auto-loaded by Claude Code)
|
||
```
|
||
<br>
|
||
<div align="right">
|
||
|
||
[](#readme-top)
|
||
|
||
</div>
|
||
|
||
## Documentation
|
||
|
||
- [docs/overview.md](docs/overview.md) — Project overview & vision
|
||
- [docs/architecture.md](docs/architecture.md) — DDD layered architecture & dependency rules
|
||
- [docs/engineering.md](docs/engineering.md) — Engineering & dev-efficiency infrastructure (CI / tooling / Claude Code)
|
||
- [docs/use-cases.md](docs/use-cases.md) — Full use-case gallery and integration examples
|
||
- [docs/migration-to-1.0.0.md](docs/migration-to-1.0.0.md) — Legacy API and infrastructure migration notes
|
||
- [CHANGELOG.md](CHANGELOG.md) — Release notes
|
||
- [CONTRIBUTING.md](CONTRIBUTING.md) — How to contribute
|
||
- [.claude/rules/](.claude/rules/) — Detailed coding conventions (auto-loaded by Claude Code)
|
||
|
||
<br>
|
||
<div align="right">
|
||
|
||
[](#readme-top)
|
||
|
||
</div>
|
||
|
||
|
||
|
||
## Watch EverOS
|
||
|
||
EverOS 1.0.0 is the first release of a larger memory-system roadmap.
|
||
Watch this repository for upcoming work on deeper idle-time and offline evolution,
|
||
benchmark releases, and more real-world agent integrations.
|
||
|
||
<table>
|
||
<tr>
|
||
<td width="50%" valign="top">
|
||
<strong>Knowledge Wiki</strong><br>
|
||
<br>
|
||
Turns scattered episodes, files, facts, and agent traces into source-backed
|
||
Markdown pages for people, projects, topics, decisions, and workflows. Memory
|
||
becomes something users can read, correct, link, version, and open in their
|
||
existing Markdown tools.
|
||
</td>
|
||
<td width="50%" valign="top">
|
||
<strong>Reflection</strong><br>
|
||
<br>
|
||
Runs when the system is idle or offline to revisit stored memory, connect weak
|
||
signals, compress noisy history into durable patterns, and improve profiles and
|
||
skills. The agent gets better between active sessions, not only while you prompt
|
||
it.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
|
||
Most memory systems stop at chat history, opaque profiles, or vector recall.
|
||
EverOS keeps memory local, Markdown-native, auditable, and self-evolving: raw
|
||
memory stays readable, derived knowledge becomes a wiki, and Reflection turns
|
||
repeated experience into more useful long-term behavior.
|
||
|
||
If EverOS is useful to your agent stack, starring the repo helps more
|
||
builders discover it.
|
||
|
||
### Star History
|
||
|
||
[](https://www.star-history.com/#EverMind-AI/EverOS&Date)
|
||
|
||
<br>
|
||
<div align="right">
|
||
|
||
[](#readme-top)
|
||
|
||
</div>
|
||
|
||
## EverMind Ecosystems
|
||
|
||
EverMind is an open-source ecosystem for long-term memory, self-evolving agents, and memory evaluation.
|
||
|
||
<table>
|
||
<tr>
|
||
<th colspan="2">EverMind Open-Source Ecosystem</th>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>Core Memory Architecture</strong></td>
|
||
<td><a href="https://github.com/EverMind-AI/EverOS">EverOS</a> - the local memory operating system and research-backed runtime for agent and user memory.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>Algorithm Engine</strong></td>
|
||
<td><a href="https://github.com/EverMind-AI/EverAlgo">EverAlgo</a> - stateless extraction, ranking, parsing, and memory operators that power EverOS.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>Alternative Architecture</strong></td>
|
||
<td><a href="https://github.com/EverMind-AI/HyperMem">HyperMem</a> - hypergraph memory for long-term conversations, with its own benchmark-backed topic -> episode -> fact retrieval method.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>Benchmarks</strong></td>
|
||
<td><a href="https://github.com/EverMind-AI/EverMemBench">EverMemBench</a> · <a href="https://github.com/EverMind-AI/EvoAgentBench">EvoAgentBench</a> - evaluation suites for conversational memory and agent self-evolution.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>Long-Context Research</strong></td>
|
||
<td><a href="https://github.com/EverMind-AI/MSA">MSA</a> - Memory Sparse Attention for scalable latent memory and 100M-token contexts.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>Personal Memory Layer</strong></td>
|
||
<td><a href="https://github.com/EverMind-AI/EverMe">EverMe</a> - CLI and agent plugin suite for cross-device, cross-agent personal memory.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><strong>Developer Integrations</strong></td>
|
||
<td><a href="https://github.com/EverMind-AI/evermem-claude-code">evermem-claude-code</a> · <a href="https://github.com/EverMind-AI/everos-plugins">everos-plugins</a> - plugins, skills, and migration tooling for AI coding agents.</td>
|
||
</tr>
|
||
</table>
|
||
|
||
Together, these repositories form EverMind's research-to-runtime stack: new memory methods, reusable algorithms, benchmark evidence, and practical agent integrations.
|
||
|
||
<br>
|
||
<div align="right">
|
||
|
||
[](#readme-top)
|
||
|
||
</div>
|
||
|
||
<br>
|
||
|
||
## Contributing
|
||
|
||
Contributions are welcome across the whole repository: architecture methods, benchmark coverage, use-case examples, documentation, and bug fixes. Browse [Issues](https://github.com/EverMind-AI/EverOS/issues) to find a good entry point, then open a PR when you are ready.
|
||
|
||
<br>
|
||
|
||
> [!TIP]
|
||
>
|
||
> **Welcome all kinds of contributions** 🎉
|
||
>
|
||
> Help make EverOS better. Code, documentation, benchmark reports, use-case write-ups, and integration examples are all valuable. Share your projects on social media to inspire others.
|
||
>
|
||
> Connect with one of the EverOS maintainers [@elliotchen200](https://x.com/elliotchen200) on 𝕏 or [@cyfyifanchen](https://github.com/cyfyifanchen) on GitHub for project updates, discussions, and collaboration opportunities.
|
||
|
||
|
||
|
||
|
||
### Code Contributors
|
||
|
||
[](https://github.com/EverMind-AI/EverOS/graphs/contributors)
|
||
|
||
|
||
|
||
|
||
### License
|
||
|
||
[Apache License 2.0](LICENSE) — see [NOTICE](NOTICE) for third-party attributions.
|
||
|
||
### Citation
|
||
|
||
If you use EverOS in research, see [CITATION.md](CITATION.md).
|
||
|
||
<br>
|
||
|
||
<div align="right">
|
||
|
||
[](#readme-top)
|
||
|
||
</div>
|