From 27a3396d23188d09529e3ff3918e998196e6b0ba Mon Sep 17 00:00:00 2001 From: Elliot Chen Date: Tue, 23 Jun 2026 19:02:29 +0800 Subject: [PATCH] docs(readme): sync chinese onboarding --- README.md | 4 + README.zh-CN.md | 335 ++++++++++------------------------------------ docs/use-cases.md | 2 +- 3 files changed, 77 insertions(+), 264 deletions(-) diff --git a/README.md b/README.md index 4661420..af896ef 100644 --- a/README.md +++ b/README.md @@ -46,6 +46,8 @@ > signals, compresses history, and improves profiles and skills between > sessions. +
+ ## Why Ever OS EverOS is a Python library and local-first memory runtime for agents and @@ -87,6 +89,8 @@ for fast retrieval and self-evolving reuse. +
+ ## Quick Start > Goal: play with the memory visualizer first, then start EverOS, write one diff --git a/README.zh-CN.md b/README.zh-CN.md index 8e67939..5267e56 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -21,17 +21,12 @@
-- [EverOS 1.0.0](#everos-100) -- [EverOS: One Memory For All](#everos-one-memory-for-all) -- [EverOS 的差异](#everos-的差异) +- [即将推出](#即将推出) +- [为什么选择 EverOS](#为什么选择-everos) - [快速开始](#快速开始) - [使用场景](#使用场景) -- [架构概览](#架构概览) -- [存储布局](#存储布局) -- [功能](#功能) -- [项目结构](#项目结构) - [文档](#文档) -- [关注 EverOS](#关注-everos) +- [Star 支持](#star-支持) - [EverMind 生态](#evermind-生态) - [参与贡献](#参与贡献) @@ -40,80 +35,24 @@ -## EverOS 1.0.0 +## 即将推出 > [!IMPORTANT] > -> **EverOS 1.0.0 是面向自进化记忆的一次重要发布。** 它带来了 -> local-first 运行时、Markdown 作为 source of truth、混合检索、 -> 多模态摄取、用户记忆与 Agent 记忆作用域，以及由 -> [EverAlgo](https://github.com/EverMind-AI/EverAlgo) 支撑的模块化算法。 +> **Knowledge Wiki：** 由记忆生成可编辑、可溯源的 Markdown 知识页。 > -> **即将推出：** Knowledge Wiki 会把记忆整理成可编辑、可溯源的 -> Markdown 知识页。Reflection 会在系统空闲或离线时 -> 连接信号、压缩历史，并持续改进 profile 和 skills。 +> **Reflection：** 在系统空闲或离线时运行，连接信号、压缩历史， +> 并在 session 之间持续改进 profiles 和 skills。
-
-[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top) +## 为什么选择 EverOS -
- - -## EverOS: One Memory For All - -EverOS 是面向 agents 和 makers 的本地记忆操作系统。它提供一层可携带的 -统一记忆层，让记忆穿过 coding assistants、apps、devices 和 workflows。 -目前它会把对话、文件和 Agent 轨迹保存为可读 Markdown，并同步本地 SQLite -和 LanceDB 索引，用于快速检索和自进化复用。 - - - - - - - - - - - - -
-Markdown As Source Of Truth
-
-所有记忆持久化为 .md 文件：可读、可改、可 grep、可 Git 版本化，也可直接用 Obsidian 打开。 -		 -Local Three-Part Stack
-
-Markdown + SQLite + LanceDB 在本地完成向量、BM25 和标量过滤检索，无需 MongoDB、Elasticsearch 或 Redis。 -		 -Dual-Track Memory
-
-Agent 记忆（cases / skills）与用户记忆（episodes / profile）独立提取，互不污染。 -
-Multimodal Ingestion
-
-文本、图像、音频、文档、PDF、HTML 和邮件统一抽取为可检索的记忆形态。 -		 -Self-Evolution
-
-从真实使用经验中自动抽取共性 skills，重复模式沉淀为可复用流程，无需重训。 -		 -Orthogonal Retrieval
-
-按 user_id、agent_id、app_id、project_id 和 session_id 五维独立检索。 -
- -
-
- -[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top) - -
- - -## EverOS 的差异 +EverOS 是面向 agents 和 makers 的 Python library 与 local-first memory +runtime。它从 day one 开始就提供一层可携带的记忆层，让记忆穿过 coding +assistants、apps、devices 和 workflows。它会把 conversations、files 和 +agent trajectories 保存为可读 Markdown，并同步本地 SQLite 与 LanceDB +索引，用于快速检索和自进化复用。 @@ -146,37 +85,23 @@ Agent 记忆（cases / skills）与用户记忆（✅ 按 user_id、agent_id、app_id、project_id 和 session_id 检索 - - - - - - - - - -
❌ 通常按 app、namespace、tenant、thread 或 graph 来组织
Knowledge Wiki✅ 即将推出：由记忆形成可编辑、可溯源的 Markdown 知识页❌ 通常是 retrieval、graph、dashboard 或 generated summaries，而不是可编辑、可溯源的知识页
Reflection✅ 即将推出：在系统空闲或离线时运行，用来连接信号、压缩历史，并在 session 之间改进 profiles 和 skills❌ 通常是在线读写 API、retrieval records 或 summaries，而不是空闲态记忆整理

-
- -[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top) - -
- ## 快速开始 -> 目标：启动 EverOS，写入一条记忆，然后把它搜索回来。 +> 目标：先体验 memory visualizer，然后启动 EverOS，写入一条真实记忆， +> 再把它搜索回来。 ### 0. 前置条件 - Python 3.12+ -- 默认 provider 需要 API keys：[OpenRouter](https://openrouter.ai/) 用于 - chat / multimodal，[DeepInfra](https://deepinfra.com/) 用于 embedding / - rerank。也可以通过 `.env` 里的 `*__BASE_URL` 字段切换到其他 - OpenAI-compatible providers。 +- `everos demo` 不需要 API keys。 +- server-backed memory flow 需要 API keys：默认使用 OpenRouter 负责 + chat / multimodal，DeepInfra 负责 embedding / rerank。也可以通过 + `.env` 中对应的 `*__BASE_URL` 字段切换到其他 OpenAI-compatible + providers。 ### 1. 安装 @@ -185,21 +110,47 @@ uv pip install everos # or: pip install everos ``` -### 2. 配置 +### 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 字段。 默认配置需要分别提供 [OpenRouter](https://openrouter.ai/) 和 [DeepInfra](https://deepinfra.com/) 的 API key：OpenRouter 用于 `LLM` / `MULTIMODAL`，DeepInfra 用于 `EMBEDDING` / `RERANK`。 -EverOS 也支持通过 -[阿里云百炼控制台](https://bailian.console.aliyun.com/) 创建一个 -DashScope API Key，统一配置 `LLM` / `EMBEDDING` / `RERANK` -三个核心能力。把同一个值填到 -`EVEROS_LLM__API_KEY`、`EVEROS_EMBEDDING__API_KEY`、`EVEROS_RERANK__API_KEY`， -并把对应 model/base_url 切到生成模板里的 Bailian / DashScope 示例。 -当前 EverOS 的百炼 rerank 路线推荐并支持 `gte-rerank-v2`。 - ```bash everos init # or, from a source checkout: @@ -209,23 +160,7 @@ 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 -``` - -### 3. 启动 EverOS +### 4. 启动 EverOS ```bash everos server start @@ -249,7 +184,7 @@ curl http://127.0.0.1:8000/health vLLM / Ollama / DeepInfra）。你可以覆盖生成的 `.env` 中的 `*__BASE_URL` 来指向任意这些模型服务。 -### 4. 试写第一条记忆 +### 5. 试写第一条记忆 添加一个很小的 conversation： @@ -335,7 +270,8 @@ 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 API key fields in .env +everos demo --plain # 先体验本地 educational demo；不需要 API keys +everos init # fill the four API key slots in .env (two distinct keys) everos --help make test @@ -605,7 +541,7 @@ MCO 为你的主 Agent 配备一个 agent team，让它们可以一起处理复 #### Legacy OpenClaw Agent 记忆 -已归档的 pre-1.0.0 plugin reference。新的集成应使用 EverOS 1.0.0 API。 +已归档的 pre-1.0.0 plugin reference。新的集成应使用当前 EverOS API。 [了解更多](docs/migration-to-1.0.0.md) @@ -679,114 +615,15 @@ Claude Code 的持久记忆插件。自动保存并回忆过去 coding sessions -## 架构概览 - -``` -┌───────────────────────────────────────────────┐ -│ 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 层架构，单向依赖。详见 [docs/architecture.md](docs/architecture.md)。 - -
-
- -[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top) - -
- -## 存储布局 - -``` -~/.everos/ -├── default_app/ # app_id ("default" → "default_app" on disk) -│ └── default_project/ # project_id ("default" → "default_project") -│ ├── users// -│ │ ├── user.md # profile -│ │ ├── episodes/ # daily-log episodes (visible) -│ │ ├── .atomic_facts/ # nested facts (dotfile-hidden) -│ │ └── .foresights/ # predictive memory (dotfile-hidden) -│ └── agents// -│ ├── 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 -``` - -在 Obsidian 中打开任意 `//users//` 文件夹即可。 -你的 Agent 大脑本质上就是一组文件。dotfile 目录（`.atomic_facts/`、 -`.foresights/`、`.cases/`）默认保持隐藏，因此可见文件夹仍然是面向用户的 -记忆表面，而提取出的衍生信息则安静地放在旁边。 - -
-
- -[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top) - -
- -## 功能 - -- **混合检索**: BM25 + vector（HNSW/IVF-PQ）+ scalar filter，在 LanceDB 中完成单次查询 -- **级联索引同步**: 编辑 `.md` → file watcher → entry-level diff → LanceDB sync，亚秒级同步 -- **多源提取**: conversations / agent trajectories / file knowledge -- **双轨记忆**: user-track（Episodes / Profiles）+ agent-track（Cases / Skills） -- **异步优先**: 完整 asyncio，单一 event loop -- **多模态**: text + 小图片 / audio inline；大媒体通过 S3/OSS reference - -
-
- -[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top) - -
- -## 项目结构 - -``` -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) -``` -
-
- -[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top) - -
- ## 文档 -- [docs/overview.md](docs/overview.md) - 项目概览与愿景 -- [docs/architecture.md](docs/architecture.md) - DDD 分层架构与依赖规则 -- [docs/engineering.md](docs/engineering.md) - 工程与开发效率基础设施（CI / tooling / Claude Code） +- [docs/everos-demo.md](docs/everos-demo.md) - Demo 范围与 TUI 源码布局 +- [docs/how-memory-works.md](docs/how-memory-works.md) - Markdown、SQLite、LanceDB 与 recall flow - [docs/use-cases.md](docs/use-cases.md) - 完整使用场景 gallery 和集成示例 -- [docs/migration-to-1.0.0.md](docs/migration-to-1.0.0.md) - Legacy API 与基础设施迁移说明 +- [docs/engineering.md](docs/engineering.md) - 工程与 CI tooling +- [docs/migration-to-1.0.0.md](docs/migration-to-1.0.0.md) - Legacy API 迁移说明 - [CHANGELOG.md](CHANGELOG.md) - 发布记录 - [CONTRIBUTING.md](CONTRIBUTING.md) - 如何贡献 -- [.claude/rules/](.claude/rules/) - 详细代码规范（Claude Code 会自动加载）
@@ -795,38 +632,10 @@ everos/ # repo root
+## Star 支持 - -## 关注 EverOS - -EverOS 1.0.0 是更大规模记忆系统路线图的第一个发布版本。Watch 这个仓库， -即可持续关注更深入的空闲态和离线进化、benchmark releases，以及更多真实 Agent 集成。 - - - - - - -
-Knowledge Wiki
-
-把分散的 episodes、files、facts 和 Agent traces 整理成有来源的 Markdown -知识页，覆盖 people、projects、topics、decisions 和 workflows。记忆不再只是 -向量召回结果，而是用户可以阅读、修正、链接、版本化，并用现有 Markdown 工具打开的知识层。 -		 -Reflection
-
-在系统空闲或离线时运行，重新审视已存储记忆，连接弱信号，把嘈杂历史压缩成稳定模式， -并持续改进 profile 和 skills。目标是让 Agent 在活跃 session 之间也能变得更好， -而不是只在你 prompt 它时才进步。 -
- -许多记忆系统停留在聊天历史、黑盒 profile 或向量召回。EverOS 的差异在于： -记忆保持本地、Markdown-native、可审计、可自进化；原始记忆仍然可读， -衍生知识沉淀为 wiki，Reflection 则把重复经验转化为更有用的长期行为。 - -如果 EverOS 对你的 Agent stack 有帮助，Star 这个仓库也会帮助更多 builders -发现它。 +如果 EverOS 对你的 Agent stack 有帮助，请 Star 这个仓库。它会帮助更多 +builders 发现这个项目，也会给 memory ecosystem 一个更强的信号，让它持续改进。 ### Star 趋势 @@ -848,15 +657,15 @@ EverMind 是一个面向长期记忆、自进化 Agent 和记忆评测的开源 EverMind 开源生态 -核心记忆架构 -EverOS - 本地记忆操作系统，以及有研究支撑的 Agent 和用户记忆运行时。 +Memory Runtime +EverOS - 本地记忆操作系统，以及有研究支撑的 Agent 和用户记忆 runtime。 算法引擎 EverAlgo - stateless extraction、ranking、parsing 和 memory operators，为 EverOS 提供算法能力。 -替代架构 +Hypergraph Memory HyperMem - 面向长期对话的 hypergraph memory，拥有独立的 benchmark-backed topic -> episode -> fact 检索方法。 @@ -877,8 +686,8 @@ EverMind 是一个面向长期记忆、自进化 Agent 和记忆评测的开源 -这些仓库共同构成 EverMind 的 research-to-runtime stack：新的记忆方法、可复用算法、 -benchmark evidence，以及可落地的 Agent 集成。 +这些仓库共同构成 EverMind 的 research-to-runtime stack：新的记忆方法、 +可复用算法、benchmark evidence，以及可落地的 Agent 集成。
diff --git a/docs/use-cases.md b/docs/use-cases.md index 37fdd64..05d015d 100644 --- a/docs/use-cases.md +++ b/docs/use-cases.md @@ -235,7 +235,7 @@ A context-native AI wearable that listens to everyday life and converts conversa #### Legacy OpenClaw Agent Memory -Archived pre-1.0.0 plugin reference. New integrations should use the EverOS 1.0.0 API. +Archived pre-1.0.0 plugin reference. New integrations should use the current EverOS API. [Learn more](migration-to-1.0.0.md)