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 的核心区别维度传统 RAGEverCore记忆粒度原文切片chunk结构化记忆单元MemCell → Episode/Foresight/AtomicFact处理方式文档入库时一次性切分实时对话流 → 边界检测 → LLM 深度理解 → 多维度提取存储结构单一向量库MongoDB结构化 ES关键词 Milvus向量三路存储检索策略单一向量相似度关键词 / 向量 / 混合RRF / Agentic多轮召回 Rerank 重排序记忆演化无聚类 → 用户画像提取 → 成熟度评分 → 技能提炼多租户通常无支持逻辑隔离shared和物理隔离exclusive二、系统架构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聚类管理 │ │ ├── MemorySyncServiceES Milvus 同步 │ │ └── ConversationStatus会话状态管理 │ └─────────────────────────────┬─────────────────────────────┘ │ ┌─────────────────────────────▼─────────────────────────────┐ │ Infrastructure Layer基础设施层 │ │ ├── MongoDB 7.0主存储结构化记忆数据 │ │ ├── Elasticsearch 8.xBM25 关键词索引 │ │ ├── Milvus 2.4向量索引语义检索 │ │ └── Redis 7.x缓存 分布式锁 │ └─────────────────────────────┬─────────────────────────────┘ │ ┌─────────────────────────────▼─────────────────────────────┐ │ Core Framework核心框架 │ │ ├── DI Container依赖注入 │ │ ├── Tenant System多租户隔离 │ │ ├── ObservabilityMetrics Tracing Logging │ │ └── Distributed LockRedis 分布式锁 │ └───────────────────────────────────────────────────────────┘三、记忆类型体系EverCore 定义了丰富的记忆类型模拟人类多层次的记忆结构3.1 数据模型继承关系BaseMemory基础字段user_id, timestamp, group_id, vector, score... ├── MemCell记忆单元 - 边界检测的产物所有下游记忆的源头 ├── EpisodeMemory情景记忆 - 叙事性摘要 ├── AtomicFact原子事实 - 最小粒度的事实陈述 ├── Foresight前瞻性记忆 - 对未来决策的预测 ├── AgentCase智能体经验 - 任务执行记录 ├── AgentSkill智能体技能 - 从经验聚类中提炼的可复用技能 └── ProfileMemory用户画像 - 显式信息 隐式特征3.2 各类型详细说明记忆类型存储位置说明典型数量MemCellMongoDBmemcells边界检测产出的最小容器包含原始消息列表每次边界检测产生 1-N 个EpisodeMemoryMongoDB ES Milvus从 MemCell 提取的叙事摘要分 Group群体和 Personal个人视角每个 MemCell 1-N 个AtomicFactMongoDB ES Milvus从 MemCell 直接提取的原子事实每条独立向量化存储仅 Solo 场景每个 MemCell 5-15 条ForesightMongoDB ES Milvus预测性记忆描述对话对未来决策的潜在影响仅 Solo 场景每个 MemCell ~10 条AgentCaseMongoDB ES Milvus从智能体对话提取的经验记录含质量评分每个 MemCell 1-N 个AgentSkillMongoDB ES Milvus从 AgentCase 聚类中派生的可复用技能有成熟度评分聚类后增量产生ProfileMemoryMongoDB ES Milvus用户画像包含显式信息兴趣/事实和隐式特征性格/偏好每用户 1 个持续更新3.3 场景差异场景EpisodeForesightAtomicFactProfileSolo1用户N智能体1个 Group Episode~10条5-15条通过聚类提取Team多用户智能体1个Group N个Personal不提取不提取通过聚类提取Agent 对话Episode AgentCase不提取可选跳过通过聚类提取四、记忆构建流程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:0008:00] 张三: 消息内容调用 LLM 一次性检测多个分割点LLM 返回 JSON{boundaries: [3, 7, 12], should_wait: false}解析失败时最多重试 5 次Phase 3 - Flush 尾部处理flushTrue时将剩余消息打包为最终 MemCell。为什么边界检测很重要传统 RAG 按固定 token 数切分会把一个完整话题切成碎片EverCore 用 LLM 理解语义边界确保每个 MemCell 包含一个完整的话题/事件这使得后续的记忆提取质量大幅提升4.4 阶段三记忆提取Memory Extraction边界检测产出 MemCell 后系统并行启动多维度记忆提取MemCell ├── EpisodeMemoryExtractor │ ├── Group Episode群体视角摘要 │ └── Personal Episodes个人视角Team场景每个参与者一个 │ ├── AgentCaseExtractor智能体对话场景 │ └── 任务意图 方法步骤 质量评分 │ ├── [后台] ForesightExtractorSolo场景 │ └── 预测性记忆未来影响、证据、持续时间 │ └── [后台] AtomicFactExtractorSolo场景 └── 5-15条原子事实每条独立向量化每种提取都通过 LLM 完成使用精心设计的 Prompt支持中英文存储在src/memory_layer/prompts/目录中。4.5 阶段四三路存储与索引每条记忆同时写入三个存储系统各自承担不同职责存储系统写入内容检索能力MongoDB完整记忆文档所有字段结构化查询、分页、排序Elasticsearch经过 Converter 转换的 ES 文档BM25 关键词搜索、全文检索Milvus向量化实体Embedding语义相似度搜索余弦距离4.6 阶段五后台演化任务记忆提取完成后后台异步触发演化任务聚类Clustering使用ClusterManager基于相似度阈值和时间间隔进行聚类通过 Redis 分布式锁防止并发冲突聚类状态持久化支持增量更新用户画像提取Profile Extraction基于聚类结果定期触发 Profile 提取两层过滤策略组级过滤 → 用户级过滤冷启动保护新群组使用当前 MemCell 时间戳失败容错提取失败时仍然推进时间戳避免卡在循环重试技能提炼AgentSkill Extraction从聚类的 AgentCase 中提炼可复用技能包含成熟度评分maturity_score随使用反馈更新五、RAG 检索流程Retrieve PipelineEverCore 提供四种检索策略从简单到复杂精度逐步提升。5.1 四种检索方法对比策略延迟PrecisionRecallF1适用场景Keyword关键词50-100ms0.720.680.70精确术语匹配、无需 Embedding 服务Vector向量200-500ms0.780.750.77语义理解、模糊查询Hybrid / RRF混合200-600ms0.850.820.84推荐默认策略综合最优Agentic智能体2-5s0.910.890.90复杂查询、需要多轮推理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 混合检索 / RRFHybrid Search这是 EverCore推荐的默认策略综合关键词和向量的优势用户查询 ──┬── 关键词搜索ES BM25──┐ │ ├── 按 ID 去重合并 → Rerank 重排序 → Top-K 结果 └── 向量搜索Milvus─────┘流程并行执行关键词搜索和向量搜索asyncio.gather按 ID 去重合并两个结果集Rerank 重排序使用 Reranker 模型默认Qwen/Qwen3-Reranker-4B对合并结果进行精细化重排截取 Top-K结果返回5.5 Agentic 检索最复杂、最智能这是最复杂的检索模式模拟人类的多步推理过程Round 1: Hybrid 检索top_n20 │ ▼ Rerank 重排序top_n10 │ ▼ LLM 充分性检查 ── 充足 ──→ 返回结果 │ 不充足 ▼ LLM 生成 2-3 个补充查询 │ ▼ Round 2: 并行 Hybrid 检索每个查询 top_n50 │ ▼ 合并 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 Service6.1 混合策略 自动故障转移EverCore 的向量化和重排序服务都采用Hybrid 混合策略主服务Primary ├── 成功 → 返回结果重置失败计数 └── 失败 → 失败计数 1 ├── fallback 未启用 → 抛出异常 └── fallback 已启用 → 尝试备用服务 ├── 成功 → 返回结果 └── 失败 → 两者都失败抛出异常6.2 配置项# 主向量化服务 VECTORIZE_PROVIDERvllm # vllm自部署或 deepinfra云服务 VECTORIZE_BASE_URLhttp://localhost:8000/v1 VECTORIZE_MODELQwen/Qwen3-Embedding-4B ​ # 备用向量化服务 VECTORIZE_FALLBACK_PROVIDERdeepinfra VECTORIZE_FALLBACK_BASE_URLhttps://api.deepinfra.com/v1/openai VECTORIZE_FALLBACK_API_KEYyour-key ​ # 主重排序服务 RERANK_PROVIDERvllm RERANK_BASE_URLhttp://localhost:12000/v1/rerank RERANK_MODELQwen/Qwen3-Reranker-4B七、多租户机制EverCore 原生支持多租户隔离隔离模式说明适用场景shared默认所有租户共享表/索引通过tenant_id逻辑隔离SaaS 多用户共享部署exclusive每个租户使用独立的数据库/集合/索引物理隔离企业级私有部署每个租户可独立配置 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 }) });九、技术栈总览组件技术选型用途Web 框架FastAPI Python 3.10REST API 服务主数据库MongoDB 7.0 (Beanie ODM)结构化记忆存储关键词索引Elasticsearch 8.xBM25 全文检索向量数据库Milvus 2.4语义相似度搜索缓存/锁Redis 7.x缓存 分布式锁LLMOpenAI 兼容 APIDeepSeek/OpenAI 等记忆提取 推理EmbeddingQwen3-Embedding-4B文本向量化RerankerQwen3-Reranker-4B检索结果重排序中文分词jieba关键词搜索分词Token 计数tiktoken (o200k_base)边界检测中的 token 限制十、核心设计理念10.1 认知级记忆 vs 文档级 RAGEverCore 的核心理念是将记忆从文档切片提升到认知理解传统 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 源码分析生成