一天一个开源项目（第36篇）：EverMemOS - 跨 LLM 与平台的长时记忆 OS，让 Agent 会记忆更会推理

引言

"More than memory — it's foresight.（不止于记忆，更是预见。）"

这是「一天一个开源项目」系列的第 36 篇文章。今天介绍的项目是 EverMemOS（GitHub）。

对话式 Agent 若只有「当前轮」的上下文，换会话就忘、跨平台不互通，很难做真正的长期陪伴与个性化。EverMemOS 是 EverMind-AI 开源的长时记忆操作系统：从对话中结构化抽取记忆（Encoding）、按情节与画像组织与巩固（Consolidation）、在需要时智能检索注入上下文（Retrieval），并支持情节记忆、事实、偏好、关系等多模态记忆类型。在 LoCoMo 长上下文记忆基准上达到 93% 推理准确率，且用 Milvus、Elasticsearch、MongoDB、Redis 等生产级组件，通过 REST API 与任意 LLM 集成，适合做跨 LLM、跨平台的 Agent 记忆底座。

为什么值得看？

• 🎯 93% LoCoMo 准确率：在长上下文记忆与推理基准上表现领先
• 🏗️ 生产级栈：Milvus 向量库、Elasticsearch、MongoDB、Redis，企业可用
• 🔌 易集成：REST API，与模型无关，任意 LLM 都可接入
• 📊 多模态记忆：Episodes（情节）、Facts（事实）、Preferences（偏好）、Relations（关系）
• 🔍 多种检索：BM25、向量、混合、Agentic 检索可配置
• 📄 论文与文档：有架构说明、API 文档、Demo、评估指南

你将学到什么

• EverMemOS 的定位与三阶段流程（Encoding → Consolidation → Retrieval）
• 多模态记忆类型与检索策略（轻量 vs Agentic）
• 快速开始：Docker + uv、环境变量、启动服务与健康检查
• API 基本用法：写入记忆、按 query 检索
• Demo 与评估：simple_demo、extract_memory、chat_with_memory，LoCoMo/LongMemEval/PersonaMem
• 项目结构、配置要点与扩展方向（Memory Genesis Competition 2026）

前置知识

• 对 LLM、Agent、RAG 有基本概念
• 了解向量检索、BM25 更佳
• 本地需 Python 3.10+、Docker 20.10+、uv、约 4GB RAM

---

项目背景

项目简介

EverMemOS 的 Slogan 是 「Long-term memory OS for your agents across LLMs and platforms」。它要解决的是：Agent 缺乏跨会话、跨平台、可推理的长时记忆 的问题。

通过三条流水线：

1. Encoding（编码）：从对话中抽取结构化记忆（事件、事实、偏好、关系等）
2. Consolidation（巩固）：将记忆组织成 Episodes（情节） 与 Profiles（画像），便于长期维护与更新
3. Retrieval（检索）：在需要时按 query 智能检索相关记忆并注入上下文，支持 BM25、向量、混合、Agentic 等策略

从而实现「不仅记住发生了什么，还理解记忆的含义，并用记忆指导决策」。在 LoCoMo（Long-Context Memory）基准上达到 93% 推理准确率，优于同类记忆系统。

面向的用户：

• 需要为对话 Agent 增加长时记忆的开发者
• 希望记忆与 LLM、平台解耦，可复用的架构师
• 需要多模态记忆（情节、事实、偏好、关系）与多种检索方式的产品与研究员
• 追求生产级部署（向量库、搜索引擎、持久化）的团队

作者/团队介绍

• 团队：EverMind-AI（evermind.ai）
• 仓库：EverMind-AI/EverMemOS
• 社区：Discord、WeChat、X、LinkedIn、Hugging Face、Reddit（见 README）
• 近期：举办 Memory Genesis Competition 2026（Agent+Memory、Platform Plugins、OS Infrastructure 等赛道）

项目数据

• ⭐ GitHub Stars: 约 2.3k
• 🍴 Forks: 约 246
• 📦 版本: v1.2.0（API 增强与 DB 效率优化，见 Changelog）
• 📄 License: Apache-2.0
• 🌐 官网: evermind.ai
• 📚 文档: Quick Start、Configuration、API Usage、Development、Memory API、Demo、Evaluation

技术栈：Python（约 99.9%）、Docker、FastAPI、MongoDB、Elasticsearch、Milvus、Redis。

---

主要功能

核心作用

EverMemOS 的核心作用是：为 Agent 提供跨 LLM、跨平台的长时记忆能力，包括：

1. 记忆写入：将单条或批量对话/消息写入系统，触发抽取与入库
2. 结构化抽取：用 LLM 从自然语言中抽取 Episodes、Facts、Preferences、Relations 等
3. 组织与巩固：按情节与用户/实体画像组织记忆，支持增量更新
4. 智能检索：按自然语言 query 检索相关记忆，支持 BM25、向量、混合、Agentic
5. REST API：标准 HTTP 接口，与前端、任意 LLM 或平台对接

从而让 Agent 在多轮、多会话、多端场景下保持「记得住、查得到、用得上」的记忆。

使用场景

1. 对话式助手

   • 用户偏好、历史话题、重要事实跨会话保留，回答更一致、更个性化

2. 客服与支持

   • 记录用户问题、处理结果、设备/账号信息，下次接入时自动带上相关记忆

3. 个人/团队知识 Agent

   • 将文档、会议、对话沉淀为情节与事实，按需检索增强生成

4. 多 Agent 协作

   • 共享或按角色隔离的记忆层，不同 Agent 复用同一套记忆 OS

5. 研究与评估

   • 在 LoCoMo、LongMemEval、PersonaMem 等基准上复现与对比记忆/推理效果

快速开始

环境：Python 3.10+、Docker 20.10+、uv、4GB RAM。

# 1. 克隆并进入目录
git clone https://github.com/EverMind-AI/EverMemOS.git
cd EverMemOS

# 2. 启动 Docker 依赖（MongoDB、Elasticsearch、Milvus、Redis 等）
docker compose up -d

# 3. 安装 uv 与项目依赖
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync

# 4. 配置 API Key
cp env.template .env
# 编辑 .env：LLM_API_KEY（记忆抽取）、VECTORIZE_API_KEY（向量化/重排）等

# 5. 启动服务
uv run python src/run.py

# 6. 健康检查
curl http://localhost:1995/health
# 预期：{"status": "healthy", ...}

服务默认运行在 **http://localhost:1995**。完整步骤见 Getting Started。

基本 API 用法

写入一条对话记忆：

import requests

API_BASE = "http://localhost:1995/api/v1"

# 写入单条消息（系统会做抽取与入库）
requests.post(f"{API_BASE}/memories", json={
    "message_id": "msg_001",
    "create_time": "2025-02-01T10:00:00+00:00",
    "sender": "user_001",
    "content": "I love playing soccer on weekends"
})

按 query 检索记忆：

# 检索与「用户喜欢什么运动」相关的记忆
response = requests.get(f"{API_BASE}/memories/search", json={
    "query": "What sports does the user like?",
    "user_id": "user_001",
    "memory_types": ["episodic_memory"],
    "retrieve_method": "hybrid"  # 可选：bm25, embedding, hybrid, agentic 等
})

result = response.json().get("result", {})
for memory_group in result.get("memories", []):
    print(memory_group)

更多示例与完整 API 见 API Usage Guide、Memory API。

核心特性

1. 93% LoCoMo 准确率

   • 在长上下文记忆与单跳/多跳推理基准上优于现有记忆系统

2. 生产级基础设施

   • Milvus：向量存储与检索
   • Elasticsearch：全文/关键词检索（如 BM25）
   • MongoDB：结构化记忆与元数据
   • Redis：缓存与会话等

3. 与 LLM 解耦

   • 通过 REST API 接入，任意 LLM 或平台均可作为「前端」，记忆层统一由 EverMemOS 提供

4. 多模态记忆

   • Episodes：情节式记忆（何时何地发生了什么）
   • Facts：事实型记忆
   • Preferences：用户偏好
   • Relations：实体间关系

5. 多种检索策略

   • BM25、向量检索、混合（hybrid）、Agentic（由 Agent 决定检索与重排），可按场景选轻量或强推理

6. 群聊与元数据

   • 支持多说话人对话、会话元数据控制，便于群组、频道、线程等场景

7. 批量与评估

   • 批量写入与评估脚本，支持 LoCoMo、LongMemEval、PersonaMem 等基准

8. Docker + uv

   • 一键启动依赖服务，Python 环境用 uv 管理，便于本地与 CI 复现

项目优势

对比项	EverMemOS	仅对话历史 / 简单 KV	自建向量+RAG
记忆结构	多模态（情节/事实/偏好/关系）	多为原始文本	视实现而定
推理能力	LoCoMo 93%，专门优化记忆推理	无基准	需自测
检索方式	BM25 + 向量 + 混合 + Agentic	多为关键词或简单向量	需自研
生产组件	Milvus + ES + MongoDB + Redis	常为单机/单库	需自行选型
集成方式	REST API，与 LLM 无关	常与某 LLM 绑定	视架构而定
文档与评估	文档齐全 + 多基准复现	少	视项目而定

为什么选 EverMemOS？

• 专注「长时记忆 OS」，从抽取、组织到检索形成闭环，并有论文与基准背书
• 生产级组件与 API 设计，适合直接做产品记忆层或二次开发
• 跨 LLM、跨平台，一次建设多端复用
• 开源社区活跃，有竞赛与多语言社区（Discord、WeChat 等）

---

项目详细剖析

架构概览（三阶段）

README 与文档中的核心流程可概括为：

1. Encoding（编码）

   • 输入：对话消息（单条或批量）
   • 过程：调用 LLM 做结构化抽取，得到 Episodes、Facts、Preferences、Relations 等
   • 输出：结构化记忆写入存储（MongoDB 等），向量写入 Milvus，全文入 Elasticsearch（视配置）

2. Consolidation（巩固）

   • 将记忆按**情节（Episodes）与画像（Profiles）**组织
   • 支持增量更新、去重与合并，形成长期可用的记忆图

3. Retrieval（检索）

   • 输入：自然语言 query、user_id、记忆类型、检索方式等
   • 过程：BM25（ES）+ 向量（Milvus）+ 可选重排与 Agentic 决策
   • 输出：相关记忆列表，供调用方注入 LLM 上下文

整体上，EverMemOS 作为「记忆中间层」夹在对话/前端与 LLM 之间：前端或 Agent 将消息写入 EverMemOS，在需要时再向 EverMemOS 做检索，把结果拼进 prompt 再调 LLM。

项目结构（概要）

• src/：核心服务入口（如 run.py）、API、编码/巩固/检索逻辑
• data/、data_format/：示例数据与数据格式说明
• demo/：simple_demo、extract_memory、chat_with_memory 等脚本
• docs/：开发文档、配置、API、架构说明
• evaluation/：LoCoMo、LongMemEval、PersonaMem 等评估脚本与说明
• config.json、env.template：服务与依赖配置
• docker-compose.yaml：MongoDB、Elasticsearch、Milvus、Redis 等

检索策略简述

• BM25：基于 Elasticsearch 的关键词/全文检索，适合精确词、专有名词
• Embedding：向量检索，适合语义相似、同义表达
• Hybrid：结合 BM25 与向量，常用作默认平衡方案
• Agentic：由 LLM/Agent 参与检索或重排，适合复杂 query、多步推理，代价相对更高

通过 API 的 retrieve_method 等参数选择，详见 API 文档。

Demo 与评估

运行简单 Demo：

# 终端 1：启动 API
uv run python src/run.py

# 终端 2：运行简单 demo
uv run python src/bootstrap.py demo/simple_demo.py

完整体验：先 extract_memory.py 从示例数据抽取记忆，再 chat_with_memory.py 做带记忆的交互式对话。详见 Demo Guide。

评估（以 LoCoMo 为例）：

uv sync --group evaluation
uv run python -m evaluation.cli --dataset locomo --system evermemos --smoke  # 快速烟雾测试
uv run python -m evaluation.cli --dataset locomo --system evermemos          # 完整评估
cat evaluation/results/locomo-evermemos/report.txt

详见 Evaluation Guide。

配置要点

• .env：由 env.template 复制而来，需配置 LLM_API_KEY（抽取用）、VECTORIZE_API_KEY（向量化/重排）等；其他服务地址可由 Docker Compose 默认提供。
• config.json：服务端口、各存储连接、检索默认参数等，见 Configuration Guide。

Memory Genesis Competition 2026

EverMind-AI 举办的开源竞赛，赛道包括：Agent + Memory（带长时记忆的智能体）、Platform Plugins（VSCode、Chrome、Slack、Notion、LangChain 等集成）、OS Infrastructure（核心功能与性能优化）。可通过 Discord 组队与获取 Starter Kit，详见 README。

---

项目地址与资源

官方资源

• 🌟 GitHub: github.com/EverMind-AI…
• 🌐 官网: evermind.ai
• 📚 文档: Quick Start、Configuration、API Usage、Memory API、Demo、Evaluation
• 💬 社区: Discord、WeChat、X、LinkedIn、Hugging Face、Reddit
• 🐛 Issues: GitHub Issues

相关资源

• 论文与愿景：README 中链接的 Paper、Vision & Overview、Architecture
• DeepWiki：Ask DeepWiki 可对仓库做 AI 问答
• GitHub Codespaces：支持在 4-core+ 机器上打开即用，见 README

适用人群

• Agent 与对话系统开发者：需要长时记忆、多模态记忆与可复现基准
• 架构师：在为多 LLM、多平台设计统一记忆层
• 研究员：在做记忆、推理、RAG 相关实验与对比
• 竞赛与插件开发者：参与 Memory Genesis 2026 或做 VSCode/Chrome/LangChain 等集成

---

欢迎来我中的个人主页找到更多有用的知识和有趣的产品