agent-memory

Agent Memory

为 AI Agent 提供具备智能决策能力的持久化语义记忆。

🚀 创建者： TheProdSDE

---

问题

大多数 AI 记忆系统会检索过去的上下文，并将其注入每个提示词中。 这会浪费令牌、导致回答不一致，还会让 Agent 盲目重放过时或错误的答案。

Agent Memory 增加了一个决策层：

flowchart TD
    A[User Query] --> B[Resolve Memory]
    B --> C[Decision Engine]
    C -->|High confidence match| D[🔄 Replay — return stored answer]
    C -->|Moderate match| E[📋 Restore — inject as context]
    C -->|Needs validation| F[✅ Verify — validate before reuse]
    C -->|No match| G[❌ None — answer from scratch]

    style D fill:#0d47a1,color:#fff
    style E fill:#e65100,color:#fff
    style F fill:#1b5e20,color:#fff
    style G fill:#b71c1c,color:#fff

每次 resolve() 都会返回一个明确的操作，并附带经过评分、可解释的依据—— 而不仅仅是一个检索到的片段。 对抗性评估：陷阱查询得分为 34/36（94%）——未通过的 2 次会返回 VERIFY（谨慎处理），而非错误的 REPLAY——参见基准测试。

---

上下文腐化——它能解决的问题（以及无法解决的问题）

上下文腐化是指随着上下文窗口逐渐填满，大模型准确率出现的可测量下降—— 这种情况远在达到令牌上限之前就会发生。过时的片段、无关的检索结果和无限增长的对话 历史不只是浪费令牌，还会主动降低回答质量（“中间迷失”、指令漂移、干扰项敏感）。

上下文腐化有两个成因。Agent Memory 能解决第一个；模型本身以外的任何手段 都无法解决第二个。

1. 哪些内容进入上下文——可控，也是此 SDK 的职责：

腐化来源	Agent Memory 中的机制
每个提示词都注入无关记忆	决策层——当没有真正匹配的内容时，NONE 会拒绝注入（对抗性陷阱查询得分为 34/36；未通过的 2 次会安全地返回 VERIFY）
会话内历史无限增长	PagedMemory——固定大小的上下文缓冲区；较早的轮次会分页移入回忆存储，并按查询返回（MemGPT 式分层）
长时间编码会话中的指令漂移	RESTORE 会在查询需要时，将相关约定作为新内容重新注入上下文末尾附近
过时事实被悄然复用	VERIFY + 自定义验证器回调 + TTL 到期 + 半衰期时间衰减
永远不会自适应的提醒	mark_correct() / mark_wrong()——置信度学习会提升持续提供帮助的记忆，并降低已被纠正记忆的权重
会话结束后知识丢失	from_conversation() 会从对话轮次中提炼持久事实并存入存储

2. 模型如何关注上下文中已有的令牌——无法从外部控制。 长上下文中的注意力退化是模型本身的特性。任何记忆层都无法改变这一点。 Agent Memory 的作用是保持上下文精简且相关，让模型尽可能不进入退化状态。

诚实的说法： Agent Memory 可以避免上下文污染——这是 Agent 系统中 最主要且可控的上下文腐化成因。它不会改变模型的注意力行为；只有当你的 Agent 通过 resolve() / PagedMemory 路由上下文，而不是手动拼接历史记录时，它才能发挥作用。

---

对比

如今，你需要将三个工具连接在一起，才能通过一次调用实现 resolve() 的功能： 用于回放的语义缓存（GPTCache）、用于提供上下文的记忆层（Mem0 / Zep），以及 用于验证的自定义过时逻辑。现有工具都不会在读取时决定某条记忆是否以及如何使用。

关于其他项目的单元格是根据它们自己的源代码或文档进行的能力核查（mem0 核查于 2026-09-27），而非对实际行为的测量；❔ 表示我们尚未测试，并不代表该能力不存在。欢迎提出更正——请参阅 docs/comparison.md 了解信息来源，并参阅 benchmark RFC 了解评审流程。

能力	Mem0	Zep / Graphiti	Letta (MemGPT)	GPTCache	Agent Memory
读取时决策（回放 / 注入 / 验证 / 跳过）	❌ 始终注入	❌ 始终注入	⚠️ 由 LLM 自行管理	⚠️ 仅回放	✅ REPLAY / RESTORE / VERIFY / NONE
可解释的逐项决策评分	❌	❌	❌	❌	✅ decision.explain()
语义答案缓存（跳过 LLM 调用）	❌	❌	❌	✅	✅
读取时过时保护	⚠️ 写入侧更新 + expiration_date	✅ 时间图谱	❌	⚠️ 仅淘汰	✅ VERIFY + TTL + 置信度衰减
已发布对抗性陷阱查询评测	❔ 未找到	❔ 未找到	❔ 未找到	❔ 未找到	✅ 34/36（94%）
每次记忆操作的 LLM / API 调用次数	1+	1+	1+	0	0
安装/缓存模型资产后可本地运行，无需 API 密钥	⚠️ 可自托管；提取需要 LLM	⚠️ 需要服务端 + LLM	⚠️ 每次操作都需要 LLM	✅	✅ SQLite + 本地 ONNX
分页式上下文层级（MemGPT 风格）	❌	❌	✅	❌	✅ memory.paged()

托管配置或基于模型的配置可能会为每次记忆操作增加一次 LLM 或嵌入 API 往返调用，因此其延迟包含服务提供商、模型和网络开销。具体延迟取决于各项目的配置；本仓库并未发布统一的 100ms–2s 下限。Agent Memory 在纯 SQLite 模式下于进程内完成解析；实测延迟取决于语料形态和缓存状态（参见性能和压力测试详情）。

关于检索，我们在下文公布了清理版发行版本的检索代理指标。 关于端到端准确率（LLM 作答 + 评审，Mem0 和 Zep 已公布相关数据），我们不会引用尚未测量的数据——此阶段已列入路线图中的下一步。 → 完整功能矩阵与权衡（包括其他方案更出色之处）：docs/comparison.md

在 LongMemEval（ICLR 2025）上的基准测试

LongMemEval 是一项用于对话历史检索的基准测试。这些结果衡量的是 Agent Memory 的 RESTORE/检索层，而非 REPLAY、VERIFY、TTL 或端到端答案正确性。每个问题都会针对一个单独的 SQLite 存储运行，其中包含该问题的候选内容；汇总的摄取总量并非单个被查询存储的大小。所有摄取均使用 零次 LLM 调用，API 费用为 $0：

• LongMemEval_S（500 个独立的约 48 会话候选集；所有运行共包含 124K 个轮次对条目）：使用本地 ONNX 嵌入时，会话 Recall@5 为 98.1%；仅使用词法检索时为 96.0%；词法检索 p50 为 10.04ms，语义检索 p50 为 19.56ms。报告还包含 p90/p95/p99 和运行资源测量数据。

• LongMemEval_M（500 个独立的约 500 会话候选集；每个被查询存储约有 2,500 个轮次对条目）：使用词法检索时，会话 Recall@5 为 87.0%，p50 为 12.05ms。此结果使用官方清理后的重新发布版本和轮次对索引；不能直接与论文中基于原始发布版本的会话索引基线进行比较。

完整的方法说明、各类型表格、范围说明（此基准测试涵盖和不涵盖的内容）以及负面结果，请参阅**基准测试报告**。使用 uv run python benchmarks/longmemeval/run_retrieval.py --semantic 可复现语义 _S 结果。

真正的软件，而非原型

以下每项声明均可通过此仓库复现：

• 对抗性决策质量评估得分为 34/36（94%），且 2 次失误均安全失败（VERIFY，从不错误地执行 REPLAY）——agent-memory eval（方法说明）
• LongMemEval 检索代理指标：Recall@5 为 98.1%（_S，语义）· 87.0%（_M，词法）——500 个独立候选集；并非端到端测试，也不是与论文基线的直接对比，完整报告
• 可复现的压力测试工具，用于测试最多含 1,000,000 个条目的合成种子工作负载；发布性能声明前，请归档 JSON 输出（方法说明）
• **压力测试基准图表：**针对 10K、100K 和 1M 个条目的词法 FTS5 运行，展示延迟百分位数、种子吞吐量、资源使用、操作占比以及缓存/决策率；工作负载和归档结果 JSON 见 压力测试
• 共收集 412 项测试，分布在 25 个测试模块中，涵盖决策质量、并发、全部 4 种后端、MCP 服务和适配器——每次推送都会在 CI 中运行
• 已发布到 PyPI 和官方 MCP Registry
• 附带 REST API、Streamlit 仪表板、CLI、LangChain/LlamaIndex 适配器，以及用于记忆读写和决策操作的异步对应版本

---

适用场景——真实用例

用例	不使用记忆	使用 Agent Memory	节省
支持机器人每天处理 10k 个相同的常见问题查询	每次查询都需要调用 1 次大模型	如果约 75% 的请求与可复用记忆匹配，这些匹配项无需调用大模型即可 REPLAY	大模型成本可能更低；请测量自己的工作负载
编码 Agent每次会话都要重新推导项目规范	每次会话浪费 2–5 次大模型调用来“记住”规范	规范只需存储一次，之后每次会话的首次查询都会 REPLAY/RESTORE	无需重复推导
研究 Agent在多次会话中积累知识	每次会话都从头开始；重复阅读相同来源	将事实和摘要作为上下文 RESTORE	跨会话持久化知识
客户入门引导机器人反复回答相同步骤	始终生成回复	高置信度的工作流会原样 REPLAY	答案一致且完全相同
工具输出缓存，适用于开销高昂的 API 调用	每次都调用外部 API	结果带 TTL 存储；在 TTL 内 REPLAY，过期后重新调用	降低外部 API 成本
策略合规 Agent，必须在重放前验证事实	过时数据可能导致无提示的幻觉风险	requires_verification=True 会将相关匹配项路由至 VERIFY；低分匹配项则返回 NONE	可审计性 + 安全性

Agent Memory 如何切实省钱

一次 GPT-4o 调用成本约为 ~$0.005。一个支持 Agent 每天处理 50,000 次查询，重复率为 70%：

• 不使用记忆：50,000 × $0.005 = $250/天
• 使用 Agent Memory：15,000 次大模型调用 + 缓存未命中 = $75/天
• 节省：约 $175/天（约 $64k/年）
• 节省金额取决于重复率，以及传入查询与之前存储的查询有多相似——请在自己的流水线中测量。

策略允许时，REPLAY 无需调用大模型。延迟和成本差异取决于本地工作负载、提供商、模型和网络；请在自己的流水线中测量两种路径。

这适合你的用例吗？

适合：

• Agent 会在多个会话中回答相同或相似的问题
• 你有可能过时的事实敏感型答案（价格、限制、策略）
• 多个 Agent 或服务共用一个知识库
• 你需要审计轨迹——了解是哪条记忆回答了问题，以及原因

不适合：

• 对文件语料库进行文档 RAG → 使用向量数据库
• 替代应用程序的真实数据源数据库
• 从不重复遇到相似查询的 Agent

---

功能一览

功能	说明
决策引擎	每次 resolve() 都会返回 REPLAY / RESTORE / VERIFY / NONE——绝不会静默注入
可解释性	decision.explain() 会显示各组件的评分：语义、时效性、置信度、使用情况
混合检索	BM25 FTS5 + 可选向量 KNN + RRF 融合——快速且准确
4 种后端	SQLite（默认，无需设置） · ChromaDB · Redis · PostgreSQL
框架适配器	为 LangChain 和 LlamaIndex 提供即插即用的 BaseMemory
MCP 服务	通过 Model Context Protocol 支持 Cursor、Claude Code、VS Code
REST API	FastAPI 服务，提供 9 个端点 + Swagger UI
仪表板	Streamlit UI——统计数据、记忆浏览器、实时 resolve 沙盒
多 Agent	多个 Agent 间的 SHARED / NAMESPACED / ISOLATED 记忆
置信度学习	事件驱动的置信度更新 + 半衰期时间衰减
记忆图谱	关系边、路径查找、聚类、PageRank 重要性
分页上下文	MemGPT 风格的层级：上下文内缓冲区 → 回忆 → 归档；每次查询的工作集有界
对话提炼	from_conversation() 可从对话轮次中自动提取事实、偏好和实体
异步 API	aremember、aresolve、alist，……——记忆读写和决策操作均有对应的异步版本
TTL 和状态	自动过期、归档、近似重复项合并

→ 完整功能参考：docs/features.md

---

性能

延迟、CPU 和内存使用量取决于语料库、查询分布、缓存状态、嵌入模式、机器和操作系统。附带的测试工具使用可重复的合成工作负载；它不构成生产环境 SLA。

当前词法 FTS5 基准测试结果及图表与源 JSON 一同归档在压力测试方法中。有关命令、工作负载范围以及结果解读指南，请参阅该文档。

---

适用场景

适合使用 Agent Memory 的场景：

• 你希望 Agent 记住过往交互，但不想将所有交互都注入每个提示词
• 你需要明确控制何时使用记忆（重放确切答案、将其作为上下文注入，还是先进行验证）
• 你有不同信任级别的记忆（用户偏好、可能已过时的事实、工具输出）
• 多个进程、服务或 Agent 共享同一个记忆存储
• 你需要审计跟踪——每次重放都可追溯到特定的存储条目，并附有评分明细

不适合用于：

• 文档 RAG（在文件语料库中搜索）——请使用向量数据库；Agent Memory 存储的是查询→答案经验
• 替代你的数据库——它存储的是 Agent 的临时知识，而不是应用程序的事实来源数据

---

快速开始

pip install agent-memory-sdk

from agent_memory import Memory, MemoryAction

memory = Memory(persist_dir=".agent_memory")

# Store once after a good answer
memory.remember(
    "How do I reset my password?",
    "Go to Settings → Security → Reset Password.",
    type="conversation", tags=["auth"],
)

# Decide before every LLM call
decision = memory.resolve("How do I reset my password?")

if decision.action == MemoryAction.REPLAY:
    return decision.response          # exact match — no LLM call needed

if decision.action == MemoryAction.RESTORE:
    context = memory.format_restore_context(decision)
    return call_llm(query, system_extra=context)

# VERIFY or NONE — validate or answer fresh

→ 完整的集成模式和 API 参考：docs/usage.md

---

本地设置

选项 1 — SQLite（无需依赖，推荐入门使用）

pip install agent-memory-sdk

# Store something
agent-memory remember "How do I reset my password?" \
  "Go to Settings → Security → Reset Password." \
  --type conversation --tags auth,faq

# Ask the exact question back → REPLAY (no LLM call needed)
agent-memory resolve "How do I reset my password?"
# ✅ REPLAY   confidence: 0.88
# response: Go to Settings → Security → Reset Password.

# Ask a paraphrase → RESTORE (inject as context, don't answer verbatim)
agent-memory resolve "I forgot my password"
# 📋 RESTORE  confidence: 0.77
# [1] score=0.77  How do I reset my password? → Go to Settings → …

# See what's stored
agent-memory stats

选项 2 — Redis 或 Postgres 后端

# Spin up the services
docker compose -f docker-compose.dev.yml up -d

# Install the backend extra
pip install "agent-memory-sdk[redis]"      # or [postgres]

# Use it
agent-memory --backend redis remember "API limit" "1000 req/min" --type fact
agent-memory --backend redis resolve "What is the rate limit?"

选项 3 — Streamlit 仪表板（可视化探索）

pip install "agent-memory-sdk[dashboard]"

# Seed demo data (optional)
python scripts/seed_demo.py --data-dir .agent_memory

# Open the dashboard
AGENT_MEMORY_DIR=.agent_memory agent-memory-dashboard
# → http://localhost:8501

选项 4 — 开发／从源代码构建

git clone https://github.com/TheProdSDE/agent-memory-sdk.git
cd agent-memory-sdk
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
make test          # run all tests
make check         # lint + type check

---

仪表板

交互式 Streamlit 仪表板，可用于探索记忆、测试 resolve 沙盒并监控统计数据。

统计数据 — KPI + 图表	记忆 — 可搜索表格

Resolve → REPLAY	Resolve → VERIFY

pip install "agent-memory-sdk[dashboard]"
AGENT_MEMORY_DIR=.agent_memory agent-memory-dashboard   # → http://localhost:8501

# Seed demo data (optional — run only when you want it)
python scripts/seed_demo.py --data-dir .agent_memory

MCP 服务

Agent Memory 已发布到 MCP Registry，可在任何兼容 MCP 的客户端中安装，无需手动设置。

添加到你的 MCP 客户端

Cursor — 将配置添加到项目中的 .cursor/mcp.json，或全局添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "agent-memory": {
      "command": "uvx",
      "args": ["agent-memory-sdk"]
    }
  }
}

Claude Desktop — 将配置添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "agent-memory": {
      "command": "uvx",
      "args": ["agent-memory-sdk"]
    }
  }
}

Claude Code — 将配置添加到项目中的 .claude/settings.json：

{
  "mcpServers": {
    "agent-memory": {
      "command": "uvx",
      "args": ["agent-memory-sdk"]
    }
  }
}

uvx 会在首次运行时安装此软件包，无需执行 pip install。

自定义存储位置

{
  "mcpServers": {
    "agent-memory": {
      "command": "uvx",
      "args": ["agent-memory-sdk"],
      "env": {
        "AGENT_MEMORY_DIR": "/path/to/your/memory",
        "AGENT_MEMORY_COLLECTION": "my_project"
      }
    }
  }
}

变量	默认值	说明
AGENT_MEMORY_DIR	~/.agent_memory	持久化 SQLite 存储目录
AGENT_MEMORY_COLLECTION	agent_memories	集合名称（每个集合对应一个数据库）

提供的工具

工具	功能
resolve_memory	检索记忆并获取明确的决策：重放 / 恢复 / 验证 / 无，并提供置信度分数和推理过程
remember_memory	存储查询/响应对，可选添加标签、类型、范围、置信度和 TTL
list_memories	分页列出已存储的记忆，并支持按范围和归档状态筛选
get_memory_by_id	按 ID 获取单条记忆
forget_memory	永久删除一条记忆
archive_memory	归档一条记忆（不再参与检索，但不会删除）
consolidate_memories	将近似重复的记忆合并为摘要条目

→ 完整的 MCP 设置指南和 Docker 配置：docs/mcp.md

---

集成

agent-memory-sdk 是核心组件——所有集成都委托给 Memory。

集成	安装额外依赖	示例
核心 SDK（SQLite）	（无）	basic_usage.py
LangChain BaseMemory	[langchain]	langchain_integration.py
LlamaIndex BaseMemory	[llamaindex]	llamaindex_integration.py
Redis 后端	[redis]	redis_backend.py
PostgreSQL 后端	[postgres]	postgres_backend.py
多 Agent 隔离	（无）	multi_agent.py
FastAPI REST 服务	[api]	rest_api.py
置信度 + 图	（无）	confidence_and_graph.py
基准测试工具	（无）	benchmark_harness.py

→ 各项集成的设置说明和代码片段：examples/README.md

---

技术栈

组件	技术
语言	Python 3.10+
存储	SQLite · ChromaDB · Redis · PostgreSQL
检索	BM25 FTS5 + 向量 KNN + RRF 融合
接口	MCP · FastAPI · Streamlit · CLI
适配器	LangChain BaseMemory · LlamaIndex BaseMemory
搜索 DSA	布隆过滤器（NONE 快速路径）· 动态 IDF 停用词 · RRF 融合
测试	pytest（收集了 412 个测试）· ruff · mypy
CI/CD	GitHub Actions — 测试矩阵 3.10–3.13 → 发布门禁 → PyPI

无需 API 密钥——所有内容均在本地运行。

---

文档

文档	内容
docs/usage.md	集成模式、API 参考、MemoryEntry / MemoryDecision 字段
docs/features.md	决策操作、混合检索、类型、作用域、TTL、图、多 Agent
docs/mcp.md	Cursor、Claude Code、VS Code 的 MCP 服务设置；Docker 配置
docs/cli.md	CLI 命令、REST API 服务、启动仪表板、评测数据集格式
docs/roadmap.md	已发布的所有功能、后续计划、GitHub Project 看板
docs/release.md	CI 自动化发布流程、版本管理、回滚
docs/architecture.md	检索流程、评分策略、系统设计
docs/comparison.md	与 Redis、mem0、Zep、LangMem、LlamaIndex、MemGPT 的功能对比
docs/stress-testing.md	10K / 100K / 1M 延迟基准测试及方法
docs/benchmarks.md	评测结果和复现命令
docs/why-decision-layer.md	本项目旨在解决的故障模式
examples/README.md	所有可运行示例的索引
CONTRIBUTING.md	开发环境设置、测试命令、PR 检查清单

---

状态与路线图

截至 v0.5.0 的所有计划功能均已发布。 在 GitHub Project → 查看后续计划

→ docs/roadmap.md

发布

由标签触发，完全由 CI 把关：git tag v0.x.y && git push origin v0.x.y

→ docs/release.md

---

参与贡献

请参阅 CONTRIBUTING.md，了解开发环境设置、测试命令和 PR 检查清单。

---

引用

如果您在研究、文章或项目中使用 Agent Memory SDK 或其基准测试套件，请使用 GitHub 的 Cite this repository 按钮引用此代码库。

为确保基准测试对比结果可复现，请注明确切的 SDK 版本、基准测试数据集版本、配置和 Git 提交。

---

许可证

Apache-2.0 — 详见 LICENSE。

---

支持

• 问题：GitHub Issues
• 讨论：GitHub Discussions
• **电子邮件：**[email protected]

---

Agent Memory 帮助 Agent 做出决策：重放 → 恢复 → 验证 → 忽略

由 TheProdSDE 倾心打造 ❤️

mcp-name: io.github.theprodsde/agent-memory