EverOS/README.zh-CN.md at 5a821acf20b9892efb154ac912be0ff62dba7475

31 KiB

Raw Blame History

目录

EverOS 1.0.0
EverOS: One Memory For All
EverOS 的差异
快速开始
使用场景
架构概览
存储布局
功能
项目结构
文档
关注 EverOS
EverMind 生态
参与贡献

EverOS 1.0.0

[!IMPORTANT]

EverOS 1.0.0 是面向自进化记忆的一次重要发布。 它带来了 local-first 运行时、Markdown 作为 source of truth、混合检索、多模态摄取、用户记忆与 Agent 记忆作用域，以及由 EverAlgo 支撑的模块化算法。

即将推出： Knowledge Wiki 会把记忆整理成可编辑、可溯源的 Markdown 知识页。Reflection（也称 Dreaming）会在系统空闲或离线时连接信号、压缩历史，并持续改进 profile 和 skills。

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` 五维独立检索。

EverOS 的差异

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 知识页	❌ 通常是 retrieval、graph、dashboard 或 generated summaries，而不是可编辑、可溯源的知识页
Dreaming / Reflection	✅ 即将推出：在系统空闲或离线时运行，用来连接信号、压缩历史，并在 session 之间改进 profiles 和 skills	❌ 通常是在线读写 API、retrieval records 或 summaries，而不是空闲态记忆整理

快速开始

目标：启动 EverOS，写入一条记忆，然后把它搜索回来。

0. 前置条件

Python 3.12+
默认 provider 需要 API keys：OpenRouter 用于 chat / multimodal， DeepInfra 用于 embedding / rerank。也可以通过 .env 里的 *__BASE_URL 字段切换到其他 OpenAI-compatible providers。

1. 安装

uv pip install everos
# or: pip install everos

2. 配置

生成一个 starter .env 文件，然后根据生成的注释填入四个 API key slots。默认配置只需要两把不同的 key：OpenRouter 用于 LLM / MULTIMODAL， DeepInfra 用于 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。

3. 启动 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 来指向任意这些模型服务。

4. 试写第一条记忆

添加一个很小的 conversation：

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：

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"}'

再把这条记忆搜索回来：

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。

可选：摄取多模态文件

如果要通过 /api/v1/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 init                          # fill the four API key slots in .env (two distinct keys)

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 1.0.0 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 已可用；后端集成仍在进行中。

在线演示

架构概览

┌───────────────────────────────────────────────┐
│  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。

存储布局

~/.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/）默认保持隐藏，因此可见文件夹仍然是面向用户的记忆表面，而提取出的衍生信息则安静地放在旁边。

功能

混合检索: 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

项目结构

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)

文档

docs/overview.md - 项目概览与愿景
docs/architecture.md - DDD 分层架构与依赖规则
docs/engineering.md - 工程与开发效率基础设施（CI / tooling / Claude Code）
docs/use-cases.md - 完整使用场景 gallery 和集成示例
docs/migration-to-1.0.0.md - Legacy API 与基础设施迁移说明
CHANGELOG.md - 发布记录
CONTRIBUTING.md - 如何贡献
.claude/rules/ - 详细代码规范（Claude Code 会自动加载）

关注 EverOS

EverOS 1.0.0 是更大规模记忆系统路线图的第一个发布版本。Watch 这个仓库，即可持续关注更深入的空闲态和离线进化、benchmark releases，以及更多真实 Agent 集成。

Knowledge Wiki

把分散的 episodes、files、facts 和 Agent traces 整理成有来源的 Markdown 知识页，覆盖 people、projects、topics、decisions 和 workflows。记忆不再只是向量召回结果，而是用户可以阅读、修正、链接、版本化，并用现有 Markdown 工具打开的知识层。

Dreaming / Reflection

在系统空闲或离线时运行，重新审视已存储记忆，连接弱信号，把嘈杂历史压缩成稳定模式，并持续改进 profile 和 skills。目标是让 Agent 在活跃 session 之间也能变得更好，而不是只在你 prompt 它时才进步。

许多记忆系统停留在聊天历史、黑盒 profile 或向量召回。EverOS 的差异在于：记忆保持本地、Markdown-native、可审计、可自进化；原始记忆仍然可读，衍生知识沉淀为 wiki，Reflection 则把重复经验转化为更有用的长期行为。

如果 EverOS 对你的 Agent stack 有帮助，Star 这个仓库也会帮助更多 builders 发现它。

Star 趋势

EverMind 生态

EverMind 是一个面向长期记忆、自进化 Agent 和记忆评测的开源生态。

EverMind 开源生态
核心记忆架构	EverOS - 本地记忆操作系统，以及有研究支撑的 Agent 和用户记忆运行时。
算法引擎	EverAlgo - stateless extraction、ranking、parsing 和 memory operators，为 EverOS 提供算法能力。
替代架构	HyperMem - 面向长期对话的 hypergraph memory，拥有独立的 benchmark-backed topic -> episode -> fact 检索方法。
Benchmarks	EverMemBench · EvoAgentBench - conversational memory 和 Agent self-evolution 的评测套件。
Long-Context Research	MSA - Memory Sparse Attention，用于可扩展 latent memory 和 100M-token contexts。
个人记忆层	EverMe - CLI 和 Agent plugin suite，用于跨设备、跨 Agent 的个人记忆。
开发者集成	evermem-claude-code · everos-plugins - AI coding agents 的 plugins、skills 和 migration tooling。

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

参与贡献

欢迎为整个仓库贡献：架构方法、benchmark coverage、use-case examples、文档和 bug fixes。浏览 Issues 找到适合的切入点，准备好后即可提交 PR。

[!TIP]

欢迎各种形式的贡献 🎉

一起让 EverOS 变得更好。代码、文档、benchmark reports、use-case write-ups 和 integration examples 都很有价值。也欢迎在社交媒体上分享你的项目，启发更多人。

你可以在 𝕏 上联系 EverOS maintainer @elliotchen200，或在 GitHub 上联系 @cyfyifanchen，获取项目更新、讨论和协作机会。

31 KiB Raw Blame History Unescape Escape