YourMemory: 基于艾宾浩斯遗忘曲线的 Agentic AI 记忆系统深度解析

项目概览

YourMemory 是一个为 AI Agent 提供持久记忆能力的开源项目，核心特性是将人类记忆的遗忘机制——艾宾浩斯遗忘曲线（Ebbinghaus Forgetting Curve）——工程化为可配置的衰减算法。与传统记忆系统不同，YourMemory 让重要的记忆缓慢衰减、无关的记忆自动淡出，模拟人类认知的实际工作方式。

在 LoCoMo-10 基准测试中，YourMemory 以 59% 的 Recall@5 得分大幅领先同类产品，相比 Zep Cloud 提升超过 31 个百分点，且在全部 10 个多会话对话样本中均保持领先。

核心问题：AI Agent 的记忆困境

每一次新的对话，AI 助手都从零开始：重复询问相同的问题、遗忘用户的偏好设置、重新学习技术栈。现有解决方案要么依赖外部云服务（增加成本与隐私风险），要么采用简单的向量检索（无法捕捉记忆间的语义关联，更无法区分重要与不重要信息）。

YourMemory 的解决思路是：让记忆系统像人类一样工作——重要的事情记得更久，不重要的自然淡忘。通过将记忆按类别（strategy/fact/assumption/failure）分配不同的衰减速率，系统实现了"生物启发式"的记忆管理。

遗忘曲线机制：艾宾浩斯方程的工程实现

YourMemory 的核心创新在于将记忆衰减建模为可配置的数学方程。核心公式位于 src/services/decay.py：

effective_λ = base_λ × (1 - importance × 0.8)
strength    = importance × e^(−effective_λ × days) × (1 + recall_count × 0.2)

其中：

• base_λ 是类别基础衰减率，由 DECAY_RATES 字典定义
• importance 是记忆重要性（0-1），越高衰减越慢
• recall_count 是被召回次数，每次召回都强化记忆（+20%）

四种类别对应不同的衰减速度：

Failure 类别衰减最快——三个月前的限速错误现在很可能已经失效，不应继续占用记忆空间。Strategy 衰减最慢——经过验证的成功模式值得长期保留。

低于强度阈值 0.05 的记忆会在每日自动 job 中被裁剪（由 APScheduler 驱动）。

混合检索：两轮召回pipeline

单纯依赖向量相似度的检索容易遗漏"词汇不同但语义相关"的记忆。YourMemory 采用两轮混合检索：

第一轮：向量搜索 使用 sentence-transformers（all-mpnet-base-v2，768 维）将记忆内容编码为向量，通过余弦相似度在 DuckDB 向量存储中检索 top-k 结果。

第二轮：图扩展 以第一轮结果为种子，通过 BFS 图遍历（NetworkX）寻找语义相关但词汇不同的记忆——连接阈值设为余弦相似度 ≥ 0.4。这解决了"问 Python 后端但返回 Docker/Kubernetes 相关信息"的问题。

最终得分：score = cosine_similarity × strength，即相似度与记忆强度的乘积。频繁被召回的记忆在强度层面获得加持，排名自然靠前。

# recall_memory("Python backend")
#   Round 1 → [1] Python/MongoDB    (sim=0.61)
#              [2] DuckDB/spaCy     (sim=0.19)
#   Round 2 → [5] Docker/Kubernetes (sim=0.29 — below cut-off, surfaced via graph)

存储架构：默认本地，按需扩展

YourMemory 默认使用本地存储，零配置即可运行：

可选扩展至生产级基础设施：

# PostgreSQL + pgvector（团队场景）
pip install 'yourmemory[postgres]'
# DATABASE_URL=postgresql://user@localhost:5432/yourmemory

# Neo4j（图数据库）
pip install 'yourmemory[neo4j]'

快速开始：5 步接入任意 MCP 客户端

Step 1 — 安装

pip install yourmemory

Step 2 — 初始化（一次性）

yourmemory-setup

下载 spaCy 模型并创建本地数据库。

Step 3 — 获取配置路径

yourmemory-path

返回完整可执行文件路径，用于配置 MCP 客户端。

Step 4 — 配置 MCP 客户端

Claude Code：~/.claude/settings.json 添加：

{
  "mcpServers": {
    "yourmemory": {
      "command": "yourmemory"
    }
  }
}

Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json 添加相同配置。

其他客户端（Cline、Cursor、OpenCode、Windsurf 等）配置方式类似，详见 README。

Step 5 — 加载记忆工作流

cp sample_CLAUDE.md CLAUDE.md

编辑 CLAUDE.md，替换 YOUR_NAME 和 YOUR_USER_ID。之后 Claude 会自动遵循 recall → store → update 的记忆工作流。

MCP 工具：三个核心 API

YourMemory 作为标准 stdio MCP 服务器，向 AI 客户端暴露三个工具：

示例：

# 存储偏好
store_memory("Sachit 在 Python 中偏好 Tab 而非空格", importance=0.9, category="fact")

# 下次会话自动召回——无需重复告知
recall_memory("Python 格式化")
# → {"content": "Sachit 在 Python 中偏好 Tab 而非空格", "strength": 0.87}

多 Agent 共享记忆

多个 Agent 可以共享同一个 YourMemory 实例，通过 register_agent 实现权限隔离：

from src.services.api_keys import register_agent

result = register_agent(
    agent_id="coding-agent",
    user_id="sachit",
    can_read=["shared", "private"],
    can_write=["shared", "private"],
)
# 返回 {"api_key": "ym_xxxx"}，仅显示一次

传递 api_key 参数后，Agent 访问记忆时会返回 shared 记忆加自身 private 记忆；其他 Agent 只能看到 shared 记忆。

性能基准：59% Recall@5 的含义

YourMemory 在 LoCoMo-10（Snap Research 发布的 10 个多会话对话数据集，共 1,534 个 QA 对）上的表现：

YourMemory 在全部 10 个样本中均领先 Zep Cloud，相对提升达 111%。除了解析准确性的因素外，核心原因是 YourMemory 的混合 BM25 + 向量 + 图检索 pipeline 保留了完整的会话摘要，而 Zep Cloud 等基于 LLM 摘要的系统在压缩过程中丢失了具体的日期、姓名和事件细节——恰恰是 LoCoMo QA 对测试的目标。

Token 效率方面，3 个会话累计节省 19.7% tokens；30 个会话后成本降幅达 84.1%——因为记忆块大小稳定在 76-91 tokens，而无记忆方案的历史上下文线性增长。

适用场景与边界

适合的场景：

• 需要跨会话记忆的 AI 编程助手（Claude Code、Cline、Cursor 等）
• 长期运行的 Agent 项目，需要区分重要与过时信息
• 多 Agent 协作，需要 shared + private 记忆隔离
• 对数据隐私有要求，不想使用第三方云服务

不适合的场景：

• 需要毫秒级响应的实时系统（本地向量检索有延迟）
• 需要处理超大规模记忆（>10 万条）的场景（建议扩展至 PostgreSQL + pgvector）
• 商业产品（CC BY-NC 许可证禁止未经授权的商业使用）

总结

YourMemory 将认知科学中经典的艾宾浩斯遗忘曲线转化为可工程的记忆衰减算法，配合混合 BM25 + 向量 + 图检索两轮 pipeline，在 LoCoMo-10 基准上以 59% Recall@5 大幅领先同类产品。默认本地存储、零配置启动、5 步接入任意 MCP 客户端的设计，大幅降低了 AI Agent 记忆系统的使用门槛。

对于需要在多会话中保持上下文一致性的 AI 开发工作流，YourMemory 提供了一套有科学依据、可配置、按重要性分层的记忆管理方案。

• 仓库地址：github.com/sachitrafa/YourMemory
• 在线演示：yourmemoryai.vercel.app
• 技术解读：I built memory decay for AI agents using the Ebbinghaus forgetting curve