EverOS/README.zh-CN.md at 649046b0df97f4936e293691be260b477537f86f

26 KiB

Raw Blame History

目录

为什么选择 EverOS
快速开始
使用场景
文档
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，中文默认推荐先在阿里云百炼控制台创建一个 DashScope API Key：

能力	默认 Provider	用途	填入这些 `.env` 字段
Chat / extraction	阿里云百炼 / DashScope	`LLM`	`EVEROS_LLM__API_KEY`
Embedding	阿里云百炼 / DashScope	`EMBEDDING`	`EVEROS_EMBEDDING__API_KEY`
Re-rank	阿里云百炼 / DashScope	`RERANK`	`EVEROS_RERANK__API_KEY`

同一个 DashScope API Key 可以填到这三个 slot。多模态文件摄取仍通过 EVEROS_MULTIMODAL__* 单独配置；如果只跑下面的文本记忆闭环，不需要先配置它。

1. 安装

uv pip install everos
# or: pip install everos

2. 体验 Demo

在配置 API keys 或启动 server 之前，先运行：

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。

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 可以这样运行：

everos demo --cinematic

如果 shell 不是 interactive，或者你只想看一个可复制的静态预览：

everos demo --plain

3. 配置

生成一个 starter .env 文件，然后根据生成的注释填入对应的 API key 字段。中文 quick start 默认推荐使用阿里云百炼控制台的 DashScope API Key 配置 LLM / EMBEDDING / RERANK 三个核心能力。

everos init
# or, from a source checkout:
cp .env.example .env

everos init 默认写入 ./.env。也可以使用 everos init --xdg 写入 ${XDG_CONFIG_HOME:-~/.config}/everos/.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

4. 启动 EverOS

everos server start

保持服务运行，然后打开第二个 terminal 检查：

curl http://127.0.0.1:8000/health

预期响应：

{"status":"ok"}

everos server start 会按以下顺序查找 .env：--env-file <path> → ./.env（当前目录）→ ${XDG_CONFIG_HOME:-~/.config}/everos/.env → ~/.everos/.env。端点栈兼容 OpenAI protocol（OpenAI / OpenRouter / vLLM / Ollama / DeepInfra）。你可以覆盖生成的 .env 中的 *__BASE_URL 来指向任意这些模型服务。

现在可以把 demo 跑成真实 server flow。在第二个 terminal 里运行：

everos demo --live

Live demo mode 会连接正在运行的 server，并在打开同一个 memory sphere UI 之前真实执行 /health -> /api/v2/memory/add -> /api/v2/memory/flush -> /api/v2/memory/search。如果 server 不在 http://127.0.0.1:8000，可以使用 --server-url <url>。

5. 试写第一条记忆

[!NOTE] 业务接口位于 /api/v2。旧的 /api/v1 前缀仍然指向同一批 handler，已有集成不会受影响；但它只是兼容用的 legacy alias，未来的大版本可能移除 —— 新代码请直接使用 /api/v2。

添加一个很小的 conversation：

TS=$(($(date +%s)*1000))

curl -X POST http://127.0.0.1:8000/api/v2/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：

curl -X POST http://127.0.0.1:8000/api/v2/memory/flush \
  -H 'Content-Type: application/json' \
  -d '{"session_id":"demo-001","app_id":"default","project_id":"default"}'

再把这条记忆搜索回来：

curl -X POST http://127.0.0.1:8000/api/v2/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。

可选：摄取多模态文件

如果要通过 /api/v2/memory/add 的 content items 摄取非文本内容（image / pdf / audio / office documents），安装可选 extra：

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 文档服务前，请先在宿主机安装：

brew install --cask libreoffice              # macOS
sudo apt-get install -y libreoffice          # Debian / Ubuntu

贡献者开发

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

使用场景

现在你已经完成了第一个成功的 EverOS moment，可以继续看看大家如何把持久记忆用在 agents、apps 和社区集成里。

这些使用场景展示了持久记忆可以在真实产品和工作流中带来什么能力。有些示例已经打包在本仓库中，另一些则指向外部 demo 或集成，你可以研究并复用。

Reunite - 用 EverOS 找回连接

父母描述他们记得的线索，孩子描述他们残留的回忆。Reunite 使用语义记忆来浮现这些连接。

了解更多

Hive Orchestrator

面向 CLI coding agents 的 browser-native hive-mind。Claude Code、Codex、Gemini 和 OpenCode 作为真实 PTY 进程，通过团队协议协作。

代码

接入 EverOS 的 AI 编程助手

由 EverOS 驱动的通用长期记忆层，面向 AI coding assistants。

代码

AI Data Technician

一个 agentic AI 系统，可以从科学家的交互中学习，用于检查、分析和分类高维时间序列数据，并通过跨 session 改进的持久记忆持续变强。

代码

接入 EverOS 的 Rokid AI 助手

在 Rokid Glasses 中连接 EverOS，为你的智能活动启用长期记忆。

即将推出

带长期记忆的创意助手

拥有长期记忆的创意助手，让你的创作上下文可以跨 session 持续可用。

即将推出

Earth Online 记忆游戏

Earth Online 是一款 memory-aware productivity game，把日常计划变成一个持续生长的 quest log。

代码

多 Agent 编排平台

Golutra 为工程团队提供 multi-agent workforce，把 IDE 从单一 assistant 扩展为协同 agents。

代码

你的个人品鉴宇宙

通过沉浸式 3D 星图记录、可视化并探索你的 tasting journey。

代码

EverOS Open Her

构建有感受的 AI。开源 persona engine，让 personality 从 neural drives 中涌现，而不是来自 prompts。灵感来自 Her。

代码

面向个人记忆的浏览器 Agent

Ruminer 为 browser agent 带来持久记忆，让它能在不同网页任务之间携带个人上下文。

插件

EverMem 与 EverOS 同步

一条命令，把任意 AI coding CLI 连接到 EverMemOS 长期记忆。

代码

MCO - 编排 AI Coding Agents

MCO 为你的主 Agent 配备一个 agent team，让它们可以一起处理复杂任务。

代码

带自进化记忆的 Study Buddy

使用拥有 self-evolving memory 的 Agent，主动辅助学习。

代码

阿尔茨海默症记忆助手

通过高级记忆支持和日常辅助，帮助有需要的人更好地生活。

代码

记忆驱动的 Multi-Agent NPC 体验

一款 iOS 科幻悬疑游戏，玩家可以探索世界并揭开真相。

代码

Mobi Companion

一款 iOS app，用户可以创建、养成并与名为 Mobi 的个性化 AI companion 一起生活。

代码

带记忆的 AI 可穿戴设备

一个 context-native AI wearable，聆听日常生活，并把对话转换为记忆。

代码

Legacy OpenClaw Agent 记忆

已归档的 pre-1.0.0 plugin reference。新的集成应使用当前 EverOS API。

了解更多

带记忆的 Live2D 角色

为实时 Live2D character 添加长期记忆，由 TEN Framework 驱动。

代码

带记忆的 Computer-Use

运行基于截图的分析任务，并把结果存入记忆。

在线演示

Game Of Thrones Memories

通过与 A Game of Thrones 互动问答体验，展示 AI 记忆基础设施。

代码

Claude Code Plugin

Claude Code 的持久记忆插件。自动保存并回忆过去 coding sessions 的上下文。

代码

记忆图谱可视化

在图界面中探索已存储的 entities 和 relationships。前端 demo 已可用；后端集成仍在进行中。