> [!NOTE] > 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 > [English](./README.en.md) · [原始项目](https://github.com/EverMind-AI/EverOS) · [上游 README](https://github.com/EverMind-AI/EverOS/blob/HEAD/README.md) > 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

![EverOS banner](https://github.com/user-attachments/assets/8e217d39-5d15-4c6c-9b54-3e83add4e0f2)

[官网](https://evermind.ai) · [文档](https://docs.evermind.ai) · [博客](https://evermind.ai/blogs) · [English](README.md)

目录

- [为什么选择 EverOS](#为什么选择-everos) - [快速开始](#快速开始) - [使用场景](#使用场景) - [文档](#文档) - [Star 支持](#star-支持) - [EverMind 生态](#evermind-生态) - [参与贡献](#参与贡献)

## 为什么选择 EverOS EverOS 是面向 agents 和 makers 的 Python library 与 local-first memory runtime。它从 day one 开始就提供一层可携带的记忆层，让记忆穿过 coding assistants、apps、devices 和 workflows。它会把 conversations、files 和 agent trajectories 保存为可读 Markdown，并同步本地 SQLite 与 LanceDB 索引，用于快速检索和自进化复用。

Title	EverOS	Other Agent Memory Libraries
Markdown source of truth	✅ 标准 `.md` 文件：可读、可编辑、可 diff、可 Git 版本化	❌ 通常是 API、vector、graph、dashboard 或 database state
直接文件编辑	✅ 编辑 `.md`；cascade watcher 同步	❌ 通常需要 SDK、API、dashboard 或 backend update path
本地三件套	✅ Markdown + SQLite + LanceDB；不需要 MongoDB、Elasticsearch 或 Redis	❌ 常依赖 managed service、vector DB、graph DB 或 server stack
用户 + Agent 双轨	✅ 用户 `episodes/profile` 与 Agent `cases/skills` 是分离的一等记忆表面	❌ 通常围绕 chat history、profiles、entities、facts 或 retrieval records
正交检索作用域	✅ 按 `user_id`、`agent_id`、`app_id`、`project_id` 和 `session_id` 检索	❌ 通常按 app、namespace、tenant、thread 或 graph 来组织
Knowledge Wiki	✅ 可编辑、可溯源的 Markdown 知识页，支持 taxonomy、CRUD APIs 和 topic search	❌ 通常和 memory 分离，被锁在 dashboard 里，或者无法回溯到源文件
Reflection	✅ 离线记忆进化：在 session 之间合并 episode clusters，并持续改进 profiles 和 skills	❌ 通常只是 retrieval-only memory，缺少后台 consolidation 和长周期改进

## 快速开始 > 目标：先体验 memory visualizer，然后启动 EverOS，写入一条真实记忆， > 再把它搜索回来。 ### 0. 前置条件 - Python 3.12+ - `everos demo` 不需要 API keys。 - 如果要运行真正的 server-backed memory flow，中文默认推荐先在 [阿里云百炼控制台](https://bailian.console.aliyun.com/) 创建一个 DashScope API Key： | 能力 | 默认 Provider | 用途 | 填入这些 `.env` 字段 | | --- | --- | --- | --- | | Chat / extraction | [阿里云百炼 / DashScope](https://bailian.console.aliyun.com/) | `LLM` | `EVEROS_LLM__API_KEY` | | Embedding | [阿里云百炼 / DashScope](https://bailian.console.aliyun.com/) | `EMBEDDING` | `EVEROS_EMBEDDING__API_KEY` | | Re-rank | [阿里云百炼 / DashScope](https://bailian.console.aliyun.com/) | `RERANK` | `EVEROS_RERANK__API_KEY` | 同一个 DashScope API Key 可以填到这三个 slot。多模态文件摄取仍通过 `EVEROS_MULTIMODAL__*` 单独配置；如果只跑下面的文本记忆闭环，不需要先配置它。 ### 1. 安装 ```bash uv pip install everos # or: pip install everos ``` ### 2. 体验 Demo 在配置 API keys 或启动 server 之前，先运行： ```bash everos demo ``` 这个命令会询问一条记忆和一个召回问题，然后打开一个全屏 terminal UI。这是一个 educational visualizer：它是 hardcoded 的，只在 CLI 本地运行，不会连接 EverOS server。它的作用是把 memory lifecycle 变成可感知的过程： conversation -> memory sphere -> recall -> source proof -> confetti。Demo 范围和 TUI 代码结构见 [docs/everos-demo.md](docs/everos-demo.md)。 Sphere 会经历 ingest、extraction、indexing、recall、source reveal，并在第一条记忆落地后进入 confetti successful moment。按 `r` 可以 replay，按 `q` 可以退出。

Animated EverOS demo preview showing the memory sphere moving through recall and confetti states

README 媒体使用的循环 showroom view 可以这样运行： ```bash everos demo --cinematic ``` 如果 shell 不是 interactive，或者你只想看一个可复制的静态预览： ```bash everos demo --plain ``` ### 3. 配置生成一个 starter `.env` 文件，然后根据生成的注释填入对应的 API key 字段。中文 quick start 默认推荐使用 [阿里云百炼控制台](https://bailian.console.aliyun.com/) 的 DashScope API Key 配置 `LLM` / `EMBEDDING` / `RERANK` 三个核心能力。 ```bash everos init # or, from a source checkout: cp .env.example .env ``` `everos init` 默认写入 `./.env`。也可以使用 `everos init --xdg` 写入 `${XDG_CONFIG_HOME:-~/.config}/everos/.env`。百炼三件套示例： ```env EVEROS_LLM__MODEL=qwen-plus EVEROS_LLM__API_KEY= EVEROS_LLM__BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 EVEROS_EMBEDDING__MODEL=text-embedding-v4 EVEROS_EMBEDDING__API_KEY= EVEROS_EMBEDDING__BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 EVEROS_RERANK__MODEL=gte-rerank-v2 EVEROS_RERANK__API_KEY= EVEROS_RERANK__BASE_URL=https://dashscope.aliyuncs.com ``` ### 4. 启动 EverOS ```bash everos server start ``` 保持服务运行，然后打开第二个 terminal 检查： ```bash curl http://127.0.0.1:8000/health ``` 预期响应： ```json {"status":"ok"} ``` `everos server start` 会按以下顺序查找 `.env`：`--env-file ` → `./.env`（当前目录）→ `${XDG_CONFIG_HOME:-~/.config}/everos/.env` → `~/.everos/.env`。端点栈兼容 OpenAI protocol（OpenAI / OpenRouter / vLLM / Ollama / DeepInfra）。你可以覆盖生成的 `.env` 中的 `*__BASE_URL` 来指向任意这些模型服务。现在可以把 demo 跑成真实 server flow。在第二个 terminal 里运行： ```bash everos demo --live ``` Live demo mode 会连接正在运行的 server，并在打开同一个 memory sphere UI 之前真实执行 `/health` -> `/api/v1/memory/add` -> `/api/v1/memory/flush` -> `/api/v1/memory/search`。如果 server 不在 `http://127.0.0.1:8000`，可以使用 `--server-url `。 ### 5. 试写第一条记忆添加一个很小的 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.\"} ] }" ``` 为了本地 demo，手动触发一次 extraction： ```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"}' ``` 再把这条记忆搜索回来： ```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 }' ``` 响应里应该能看到 Yosemite 相关记忆。如果第一次搜索为空，稍等片刻再试； Markdown 会同步写入，本地索引会在后台追上。 > [!TIP] > **第一条记忆已经写入。** > 你刚刚把一个事实交给 EverOS，把它整理进可持久化的 Markdown-backed memory， > 并通过本地索引把它搜索回来。这就是 EverOS 的核心闭环。 > 想看看 source of truth？打开 `~/.everos`，直接检查生成的 Markdown 文件。带完整响应和 Markdown 文件说明的 walkthrough 见 [QUICKSTART.md](QUICKSTART.md)。 ### 可选：摄取多模态文件如果要通过 `/api/v1/memory/add` 的 `content` items 摄取非文本内容（image / pdf / audio / office documents），安装可选 extra： ```bash uv pip install 'everos[multimodal]' # or: pip install 'everos[multimodal]' ``` 这会引入 `everalgo-parser`（包含用于 SVG 支持的 `[svg]` bundle，通过 cairosvg）并接入多模态 LLM client（`.env` 中的 `EVEROS_MULTIMODAL__*` 字段，默认通过 OpenRouter 使用 `google/gemini-3-flash-preview`）。 **Office 文档支持需要 LibreOffice 作为系统依赖。** parser 会调用 `soffice`（LibreOffice 的 headless renderer），先把 `.doc` / `.docx` / `.ppt` / `.pptx` / `.xls` / `.xlsx` 转换为 PDF，再交给多模态 LLM。如果没有 LibreOffice，office 上传会返回 HTTP 415，并带有明确错误信息； PDF / image / audio / HTML / email 解析不受影响。在提供 office 文档服务前，请先在宿主机安装： ```bash brew install --cask libreoffice # macOS sudo apt-get install -y libreoffice # Debian / Ubuntu ``` ### 贡献者开发 ```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 demo --plain # 先体验本地 educational demo；不需要 API keys everos init # 把百炼 DashScope API Key 填进 .env everos --help make test ```