docs(readme): sync chinese onboarding

2026-06-23 19:02:29 +08:00 · 2026-06-23 19:02:29 +08:00 · 27a3396d23
parent cdcf4ad0ad
commit 27a3396d23
3 changed files with 77 additions and 264 deletions
--- a/README.md
+++ b/README.md
@ -46,6 +46,8 @@
 > signals, compresses history, and improves profiles and skills between
 > sessions.

+<br>
+
 ## 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.
 </tr>
 </table>

+<br>
+
 ## Quick Start

 > Goal: play with the memory visualizer first, then start EverOS, write one
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@ -21,17 +21,12 @@

 <br>

- [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 @@
 </details>


-## 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。

 <br>
-<div align="right">

-[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top)
+## 为什么选择 EverOS

-</div>
-
-
-## EverOS: One Memory For All
-
-EverOS 是面向 agents 和 makers 的本地记忆操作系统。它提供一层可携带的
-统一记忆层，让记忆穿过 coding assistants、apps、devices 和 workflows。
-目前它会把对话、文件和 Agent 轨迹保存为可读 Markdown，并同步本地 SQLite
-和 LanceDB 索引，用于快速检索和自进化复用。
-
-<table>
-<tr>
-<td width="33%" valign="top">
-<strong>Markdown As Source Of Truth</strong><br>
-<br>
-所有记忆持久化为 <code>.md</code> 文件：可读、可改、可 grep、可 Git 版本化，也可直接用 Obsidian 打开。
-</td>
-<td width="33%" valign="top">
-<strong>Local Three-Part Stack</strong><br>
-<br>
-Markdown + SQLite + LanceDB 在本地完成向量、BM25 和标量过滤检索，无需 MongoDB、Elasticsearch 或 Redis。
-</td>
-<td width="33%" valign="top">
-<strong>Dual-Track Memory</strong><br>
-<br>
-Agent 记忆（<code>cases</code> / <code>skills</code>）与用户记忆（<code>episodes</code> / <code>profile</code>）独立提取，互不污染。
-</td>
-</tr>
-<tr>
-<td width="33%" valign="top">
-<strong>Multimodal Ingestion</strong><br>
-<br>
-文本、图像、音频、文档、PDF、HTML 和邮件统一抽取为可检索的记忆形态。
-</td>
-<td width="33%" valign="top">
-<strong>Self-Evolution</strong><br>
-<br>
-从真实使用经验中自动抽取共性 skills，重复模式沉淀为可复用流程，无需重训。
-</td>
-<td width="33%" valign="top">
-<strong>Orthogonal Retrieval</strong><br>
-<br>
-按 <code>user_id</code>、<code>agent_id</code>、<code>app_id</code>、<code>project_id</code> 和 <code>session_id</code> 五维独立检索。
-</td>
-</tr>
-</table>
-
-<br>
-<div align="right">
-
-[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top)
-
-</div>
-
-
-## EverOS 的差异
+EverOS 是面向 agents 和 makers 的 Python library 与 local-first memory
+runtime。它从 day one 开始就提供一层可携带的记忆层，让记忆穿过 coding
+assistants、apps、devices 和 workflows。它会把 conversations、files 和
+agent trajectories 保存为可读 Markdown，并同步本地 SQLite 与 LanceDB
+索引，用于快速检索和自进化复用。

 <table>
 <tr>
@ -146,37 +85,23 @@ Agent 记忆（<code>cases</code> / <code>skills</code>）与用户记忆（<cod
 <td>✅ 按 <code>user_id</code>、<code>agent_id</code>、<code>app_id</code>、<code>project_id</code> 和 <code>session_id</code> 检索</td>
 <td>❌ 通常按 app、namespace、tenant、thread 或 graph 来组织</td>
 </tr>
-<tr>
-<td><strong>Knowledge Wiki</strong></td>
-<td>✅ 即将推出：由记忆形成可编辑、可溯源的 Markdown 知识页</td>
-<td>❌ 通常是 retrieval、graph、dashboard 或 generated summaries，而不是可编辑、可溯源的知识页</td>
-</tr>
-<tr>
-<td><strong>Reflection</strong></td>
-<td>✅ 即将推出：在系统空闲或离线时运行，用来连接信号、压缩历史，并在 session 之间改进 profiles 和 skills</td>
-<td>❌ 通常是在线读写 API、retrieval records 或 summaries，而不是空闲态记忆整理</td>
-</tr>
 </table>

 <br>
-<div align="right">
-
-[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top)
-
-</div>
-

 ## 快速开始

-> 目标：启动 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` 可以退出。下面的优化动图托管在外部，避免仓库变重：
+
+<p align="center">
+  <img src="https://gist.githubusercontent.com/cyfyifanchen/afa2cf40bf138a3ec96d917e8f2791a2/raw/d4ce82a6ddd7b3ebaf221e4825af993aeca5a7ce/everos-demo-tui-animation.svg" alt="Animated EverOS demo preview showing the memory sphere moving through recall and confetti states" width="720">
+</p>
+
+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=<DASHSCOPE_API_KEY>
-EVEROS_LLM__BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
-
-EVEROS_EMBEDDING__MODEL=text-embedding-v4
-EVEROS_EMBEDDING__API_KEY=<DASHSCOPE_API_KEY>
-EVEROS_EMBEDDING__BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
-
-EVEROS_RERANK__MODEL=gte-rerank-v2
-EVEROS_RERANK__API_KEY=<DASHSCOPE_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

 </div>

-## 架构概览
-
-```
-┌───────────────────────────────────────────────┐
-│  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)。
-
-<br>
-<div align="right">
-
-[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top)
-
-</div>
-
-## 存储布局
-
-```
-~/.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
-```
-
-在 Obsidian 中打开任意 `<app>/<project>/users/<user_id>/` 文件夹即可。
-你的 Agent 大脑本质上就是一组文件。dotfile 目录（`.atomic_facts/`、
-`.foresights/`、`.cases/`）默认保持隐藏，因此可见文件夹仍然是面向用户的
-记忆表面，而提取出的衍生信息则安静地放在旁边。
-
-<br>
-<div align="right">
-
-[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top)
-
-</div>
-
-## 功能
-
- **混合检索**: 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
-
-<br>
-<div align="right">
-
-[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top)
-
-</div>
-
-## 项目结构
-
-```
-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">
-
-[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top)
-
-</div>
-
 ## 文档

- [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 会自动加载）

 <br>
 <div align="right">
@ -795,38 +632,10 @@ everos/                        # repo root

 </div>

+## Star 支持

-
-## 关注 EverOS
-
-EverOS 1.0.0 是更大规模记忆系统路线图的第一个发布版本。Watch 这个仓库，
-即可持续关注更深入的空闲态和离线进化、benchmark releases，以及更多真实 Agent 集成。
-
-<table>
-<tr>
-<td width="50%" valign="top">
-<strong>Knowledge Wiki</strong><br>
-<br>
-把分散的 episodes、files、facts 和 Agent traces 整理成有来源的 Markdown
-知识页，覆盖 people、projects、topics、decisions 和 workflows。记忆不再只是
-向量召回结果，而是用户可以阅读、修正、链接、版本化，并用现有 Markdown 工具打开的知识层。
-</td>
-<td width="50%" valign="top">
-<strong>Reflection</strong><br>
-<br>
-在系统空闲或离线时运行，重新审视已存储记忆，连接弱信号，把嘈杂历史压缩成稳定模式，
-并持续改进 profile 和 skills。目标是让 Agent 在活跃 session 之间也能变得更好，
-而不是只在你 prompt 它时才进步。
-</td>
-</tr>
-</table>
-
-许多记忆系统停留在聊天历史、黑盒 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 和记忆评测的开源
 <th colspan="2">EverMind 开源生态</th>
 </tr>
 <tr>
-<td><strong>核心记忆架构</strong></td>
-<td><a href="https://github.com/EverMind-AI/EverOS">EverOS</a> - 本地记忆操作系统，以及有研究支撑的 Agent 和用户记忆运行时。</td>
+<td><strong>Memory Runtime</strong></td>
+<td><a href="https://github.com/EverMind-AI/EverOS">EverOS</a> - 本地记忆操作系统，以及有研究支撑的 Agent 和用户记忆 runtime。</td>
 </tr>
 <tr>
 <td><strong>算法引擎</strong></td>
 <td><a href="https://github.com/EverMind-AI/EverAlgo">EverAlgo</a> - stateless extraction、ranking、parsing 和 memory operators，为 EverOS 提供算法能力。</td>
 </tr>
 <tr>
-<td><strong>替代架构</strong></td>
+<td><strong>Hypergraph Memory</strong></td>
 <td><a href="https://github.com/EverMind-AI/HyperMem">HyperMem</a> - 面向长期对话的 hypergraph memory，拥有独立的 benchmark-backed topic -> episode -> fact 检索方法。</td>
 </tr>
 <tr>
@ -877,8 +686,8 @@ EverMind 是一个面向长期记忆、自进化 Agent 和记忆评测的开源
 </tr>
 </table>

-这些仓库共同构成 EverMind 的 research-to-runtime stack：新的记忆方法、可复用算法、
-benchmark evidence，以及可落地的 Agent 集成。
+这些仓库共同构成 EverMind 的 research-to-runtime stack：新的记忆方法、
+可复用算法、benchmark evidence，以及可落地的 Agent 集成。

 <br>
 <div align="right">
--- 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)