EverCore 记忆系统原理 外带测试Demo和记忆可视化管理

EverCore 记忆系统原理文档

你的操作 系统内部 存储变化
─────────────────────────────────────────────────────────────
点击「发送」 → 原样存入 MongoDB raw_messages +1
"我喜欢路小雨" status: accumulated

点击「Flush」 → 加载所有累积消息 memcells +1
→ LLM 边界检测（切分话题）
→ LLM 提取情景记忆 episodic_memories +N
→ LLM 提取原子事实 atomic_facts +N
→ 向量化 → 存入 Milvus milvus +N
→ jieba 分词 → 存入 ES elasticsearch +N
→ 清空已消费的原始消息 raw_messages -N

搜索"我喜欢谁" → jieba 分词 → ES BM25 返回情景记忆
→ 或向量 → Milvus 相似度 + 用户画像
→ Rerank 精排

测试

一、项目概述

EverOS 是一个面向自进化智能体（Self-Evolving Agents）的长期记忆操作系统。其核心组件EverCore能够从对话中提取、结构化和检索持久化知识，使智能体能够跨会话记忆并随时间自适应进化。

与传统 RAG（检索增强生成）仅做"文档切片 → 向量检索"不同，EverCore 实现了一套认知级记忆系统，模拟人类记忆的编码、存储、巩固和检索过程。

1.1 与传统 RAG 的核心区别

二、系统架构

EverCore 采用六层分层架构，围绕两条核心认知轨道运行：

• 记忆构建轨道（Memory Construction）：消息 → 边界检测 → 记忆提取 → 存储索引

• 记忆感知轨道（Memory Perception）：查询 → 多策略检索 → Rerank → 上下文注入

┌───────────────────────────────────────────────────────────┐ │ API Layer (FastAPI) │ │ /api/v1/memories | /search | /flush | /get │ └─────────────────────────────┬─────────────────────────────┘ │ ┌─────────────────────────────▼─────────────────────────────┐ │ Agentic Layer（智能体层） │ │ MemoryManager: memorize() / retrieve_mem() / get_mem() │ │ ├── VectorizeService（向量化：Hybrid主备 + 自动故障转移） │ │ ├── RerankService（重排序：Hybrid主备 + 自动故障转移） │ │ └── AgenticUtils（充分性检查 + 多查询生成） │ └─────────────────────────────┬─────────────────────────────┘ │ ┌─────────────────────────────▼─────────────────────────────┐ │ Memory Layer（记忆层） │ │ ConvMemCellExtractor（边界检测） │ │ ├── EpisodeMemoryExtractor（情景记忆提取） │ │ ├── ForesightExtractor（前瞻性记忆提取） │ │ ├── AtomicFactExtractor（原子事实提取） │ │ ├── AgentCaseExtractor（智能体经验提取） │ │ └── ProfileExtractor（用户画像提取） │ └─────────────────────────────┬─────────────────────────────┘ │ ┌─────────────────────────────▼─────────────────────────────┐ │ Business Layer（业务层） │ │ memorize() → 预处理 → 边界检测 → 记忆提取 → 三路存储 │ │ ├── ClusterManager（聚类管理） │ │ ├── MemorySyncService（ES + Milvus 同步） │ │ └── ConversationStatus（会话状态管理） │ └─────────────────────────────┬─────────────────────────────┘ │ ┌─────────────────────────────▼─────────────────────────────┐ │ Infrastructure Layer（基础设施层） │ │ ├── MongoDB 7.0+（主存储：结构化记忆数据） │ │ ├── Elasticsearch 8.x（BM25 关键词索引） │ │ ├── Milvus 2.4+（向量索引：语义检索） │ │ └── Redis 7.x（缓存 + 分布式锁） │ └─────────────────────────────┬─────────────────────────────┘ │ ┌─────────────────────────────▼─────────────────────────────┐ │ Core Framework（核心框架） │ │ ├── DI Container（依赖注入） │ │ ├── Tenant System（多租户隔离） │ │ ├── Observability（Metrics + Tracing + Logging） │ │ └── Distributed Lock（Redis 分布式锁） │ └───────────────────────────────────────────────────────────┘

三、记忆类型体系

EverCore 定义了丰富的记忆类型，模拟人类多层次的记忆结构：

3.1 数据模型继承关系

BaseMemory（基础字段：user_id, timestamp, group_id, vector, score...） ├── MemCell（记忆单元 - 边界检测的产物，所有下游记忆的源头） ├── EpisodeMemory（情景记忆 - 叙事性摘要） ├── AtomicFact（原子事实 - 最小粒度的事实陈述） ├── Foresight（前瞻性记忆 - 对未来决策的预测） ├── AgentCase（智能体经验 - 任务执行记录） ├── AgentSkill（智能体技能 - 从经验聚类中提炼的可复用技能） └── ProfileMemory（用户画像 - 显式信息 + 隐式特征）

3.2 各类型详细说明

3.3 场景差异

四、记忆构建流程（Memorize Pipeline）

这是 EverCore 最核心的流程，将原始对话流转化为结构化记忆。

4.1 完整流程图

原始消息流 │ ▼ ┌───────────────────────┐ │ 1. 消息累积与预处理 │ │ (Accumulate & Preprocess) │ │ 消息暂存到缓冲区 │ │ status: "accumulated" │ └───────────┬───────────┘ │ 触发 Flush ▼ ┌───────────────────────┐ │ 2. 边界检测 │ │ (Boundary Detection) │ │ ┌─ Phase 1: 强制分割 │ ← 超过 token/消息数硬限制 │ ├─ Phase 2: LLM检测 │ ← LLM 识别话题边界 │ └─ Phase 3: Flush尾部 │ ← 剩余消息打包 └───────────┬───────────┘ │ 输出 MemCell 列表 ▼ ┌───────────────────────┐ │ 3. 记忆提取 │ │ (Memory Extraction) │ │ ├─ Episode 提取 │ ← LLM 生成叙事摘要 │ ├─ AgentCase 提取 │ ← 智能体经验记录 │ ├─ Foresight 提取 │ ← 预测性记忆 (Solo) │ └─ AtomicFact 提取 │ ← 原子事实 (Solo) └───────────┬───────────┘ │ ▼ ┌───────────────────────┐ │ 4. 三路存储与索引 │ │ (Storage & Indexing) │ │ ├─ MongoDB (主存储) │ │ ├─ Elasticsearch (BM25) │ │ └─ Milvus (向量索引) │ └───────────┬───────────┘ │ ▼ ┌───────────────────────┐ │ 5. 后台演化任务 │ │ (Background Evolution)│ │ ├─ 聚类 (Clustering) │ │ ├─ Profile 提取 │ │ └─ Skill 提炼 │ └───────────────────────┘

4.2 阶段一：消息累积与预处理

当用户发送消息时，系统不会立即处理，而是先累积到缓冲区：

• 消息暂存到conversation_data_repo

• 系统记录last_memcell_time（上次记忆提取时间）标记当前窗口起点

• 新消息追加到当前窗口，等待 Flush 触发

• 返回"status": "accumulated"表示消息已接收

4.3 阶段二：边界检测（Boundary Detection）

这是 EverCore 区别于传统 RAG 的关键创新——不是简单按固定长度切分，而是用 LLM 智能识别对话中的话题边界。

三阶段算法：

Phase 1 - 强制分割循环：当消息超过硬限制时（默认 65536 tokens 或 500 条消息），自动将前段切分为 MemCell，无需 LLM 判断。使用二分查找找到合适的分割点。

Phase 2 - LLM 批量边界检测：

• 将消息格式化为[N] [2024-01-15 14:30:00+08:00] 张三: 消息内容

• 调用 LLM 一次性检测多个分割点

• LLM 返回 JSON：{"boundaries": [3, 7, 12], "should_wait": false}

• 解析失败时最多重试 5 次

Phase 3 - Flush 尾部处理：flush=True时，将剩余消息打包为最终 MemCell。

为什么边界检测很重要？

• 传统 RAG 按固定 token 数切分，会把一个完整话题切成碎片

• EverCore 用 LLM 理解语义边界，确保每个 MemCell 包含一个完整的话题/事件

• 这使得后续的记忆提取质量大幅提升

4.4 阶段三：记忆提取（Memory Extraction）

边界检测产出 MemCell 后，系统并行启动多维度记忆提取：

MemCell ├── EpisodeMemoryExtractor │ ├── Group Episode（群体视角摘要） │ └── Personal Episodes（个人视角，Team场景每个参与者一个） │ ├── AgentCaseExtractor（智能体对话场景） │ └── 任务意图 + 方法步骤 + 质量评分 │ ├── [后台] ForesightExtractor（Solo场景） │ └── 预测性记忆（未来影响、证据、持续时间） │ └── [后台] AtomicFactExtractor（Solo场景） └── 5-15条原子事实，每条独立向量化

每种提取都通过 LLM 完成，使用精心设计的 Prompt（支持中英文），存储在src/memory_layer/prompts/目录中。

4.5 阶段四：三路存储与索引

每条记忆同时写入三个存储系统，各自承担不同职责：

4.6 阶段五：后台演化任务

记忆提取完成后，后台异步触发演化任务：

聚类（Clustering）：

• 使用ClusterManager基于相似度阈值和时间间隔进行聚类

• 通过 Redis 分布式锁防止并发冲突

• 聚类状态持久化，支持增量更新

用户画像提取（Profile Extraction）：

• 基于聚类结果，定期触发 Profile 提取

• 两层过滤策略：组级过滤 → 用户级过滤

• 冷启动保护：新群组使用当前 MemCell 时间戳

• 失败容错：提取失败时仍然推进时间戳，避免卡在循环重试

技能提炼（AgentSkill Extraction）：

• 从聚类的 AgentCase 中提炼可复用技能

• 包含成熟度评分（maturity_score），随使用反馈更新

五、RAG 检索流程（Retrieve Pipeline）

EverCore 提供四种检索策略，从简单到复杂，精度逐步提升。

5.1 四种检索方法对比

5.2 关键词检索（Keyword Search）

用户查询 → jieba 分词 → 去除停用词 → ES BM25 搜索 → 返回结果

• 使用jieba中文分词器（jieba.cut_for_search）

• 通过停用词过滤器过滤短词（最短 2 字符）

• 基于 Elasticsearch 的 BM25 算法进行相关性评分

• 不需要 Embedding 服务，延迟最低

5.3 向量检索（Vector Search）

用户查询 → Embedding 模型 → 查询向量 → Milvus 余弦相似度搜索 → 阈值过滤 → 返回结果

• 使用 Embedding 模型（默认Qwen/Qwen3-Embedding-4B，维度 1024）将查询文本转为向量

• 在 Milvus 中执行余弦相似度搜索

• 支持相似度阈值过滤（默认 0.6）

• 支持无限模式（top_k=-1）返回所有超过阈值的结果

5.4 混合检索 / RRF（Hybrid Search）

这是 EverCore推荐的默认策略，综合关键词和向量的优势：

用户查询 ──┬── 关键词搜索（ES BM25）──┐ │ ├── 按 ID 去重合并 → Rerank 重排序 → Top-K 结果 └── 向量搜索（Milvus）─────┘

流程：

1. 并行执行关键词搜索和向量搜索（asyncio.gather）

2. 按 ID 去重合并两个结果集

3. Rerank 重排序：使用 Reranker 模型（默认Qwen/Qwen3-Reranker-4B）对合并结果进行精细化重排

4. 截取 Top-K结果返回

5.5 Agentic 检索（最复杂、最智能）

这是最复杂的检索模式，模拟人类的多步推理过程：

Round 1: Hybrid 检索（top_n=20） │ ▼ Rerank 重排序（top_n=10） │ ▼ LLM 充分性检查 ── 充足 ──→ 返回结果 │ 不充足 ▼ LLM 生成 2-3 个补充查询 │ ▼ Round 2: 并行 Hybrid 检索（每个查询 top_n=50） │ ▼ 合并 Round 1 + Round 2 结果（最多 40 条） │ ▼ 最终 Rerank → 返回结果

关键创新：

• 充分性检查（Sufficiency Check）：让 LLM 判断已检索的记忆是否足够回答查询，返回{is_sufficient, reasoning, missing_information}

• 多查询生成（Multi-Query Generation）：基于原始查询、已检索结果和缺失信息，LLM 生成 2-3 个互补查询，扩大召回范围

• 两轮检索：第一轮快速召回 → 判断是否充分 → 不充分则第二轮深度召回

5.6 Rerank 重排序

Rerank 是所有检索策略的最后一步，用于精细化排序：

• 使用专用 Reranker 模型（Qwen/Qwen3-Reranker-4B）

• 采用HybridRerankService混合策略 + 自动故障转移

• 支持批量并发处理 + 指数退避重试

• 支持阈值过滤（默认 0.6），低于阈值的结果被剔除

六、向量化服务（Embedding Service）

6.1 混合策略 + 自动故障转移

EverCore 的向量化和重排序服务都采用Hybrid 混合策略：

主服务（Primary） ├── 成功 → 返回结果，重置失败计数 └── 失败 → 失败计数 +1 ├── fallback 未启用 → 抛出异常 └── fallback 已启用 → 尝试备用服务 ├── 成功 → 返回结果 └── 失败 → 两者都失败，抛出异常

6.2 配置项

# 主向量化服务 VECTORIZE_PROVIDER=vllm # vllm（自部署）或 deepinfra（云服务） VECTORIZE_BASE_URL=http://localhost:8000/v1 VECTORIZE_MODEL=Qwen/Qwen3-Embedding-4B ​ # 备用向量化服务 VECTORIZE_FALLBACK_PROVIDER=deepinfra VECTORIZE_FALLBACK_BASE_URL=https://api.deepinfra.com/v1/openai VECTORIZE_FALLBACK_API_KEY=your-key ​ # 主重排序服务 RERANK_PROVIDER=vllm RERANK_BASE_URL=http://localhost:12000/v1/rerank RERANK_MODEL=Qwen/Qwen3-Reranker-4B

七、多租户机制

EverCore 原生支持多租户隔离：

每个租户可独立配置 MongoDB、Redis、Elasticsearch、Milvus 连接。

八、典型使用流程

8.1 对话记忆流程

用户: "我今天去了上海博物馆，看到了青铜器展览" │ ▼ POST /api/v1/memories │ status: "accumulated" ← 消息暂存 │ ▼ 触发 Flush │ 边界检测 → 识别为一个完整话题 │ 提取 Episode: "用户于今日参观了上海博物馆，观看了青铜器展览" │ 提取 AtomicFact: ["用户今天去了上海", "用户参观了博物馆", "用户看了青铜器展览"...] │ 提取 Foresight: "用户对历史文化感兴趣，未来可推荐类似展览" │ 存储到 MongoDB + ES + Milvus │ ▼ 用户后续查询 │ "推荐一些文化活动" → Agentic 检索 → 找到青铜器展览记忆 → 推荐相关活动

8.2 API 调用示例

// 1. 发送消息（累积模式） await fetch("http://localhost:1995/api/v1/memories", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ user_id: "user-001", session_id: "session-001", messages: [{ role: "user", content: "我今天去了上海博物馆", timestamp: Date.now() }] }) }); // 响应: { status: "accumulated", message_count: 1 } ​ // 2. Flush 处理 await fetch("http://localhost:1995/api/v1/memories/flush", { method: "POST", body: JSON.stringify({ user_id: "user-001", session_id: "session-001" }) }); ​ // 3. 搜索记忆 await fetch("http://localhost:1995/api/v1/memories/search", { method: "POST", body: JSON.stringify({ query: "博物馆", method: "hybrid", // keyword | vector | hybrid | agentic memory_types: ["episodic_memory", "profile"], filters: { user_id: "user-001" }, top_k: 5 }) });

九、技术栈总览

十、核心设计理念

10.1 认知级记忆 vs 文档级 RAG

EverCore 的核心理念是将记忆从"文档切片"提升到"认知理解"：

• 传统 RAG：文档 → 切片 → 向量化 → 检索（机械切分，丢失上下文）

• EverCore：对话流 → 话题边界 → LLM 深度理解 → 多维度结构化提取 → 演化（模拟人类认知）

10.2 记忆的生命周期

编码（Encode） → 消息流经边界检测和 LLM 提取，转化为结构化记忆 存储（Store） → 三路持久化（MongoDB + ES + Milvus） 巩固（Consolidate）→ 聚类 + Profile 提取 + Skill 炼化 检索（Retrieve） → 多策略检索 + Rerank 精排 遗忘（Fade） → 成熟度评分驱动的记忆衰减（规划中）

10.3 两条认知轨道的协同

对话流 │ ┌───────────┴───────────┐ ▼ ▼ 记忆构建轨道 记忆感知轨道 (Memory Construction) (Memory Perception) │ │ │ 边界检测 │ 多策略检索 │ 记忆提取 │ Rerank 重排 │ 三路存储 │ 充分性检查 │ 聚类/演化 │ 上下文注入 │ │ └───────────┬───────────┘ │ ▼ 智能体响应 (更准确、更个性化的回答)

文档生成日期：2026-05-31基于 EverCore 源码分析生成