agentmemory

为 AI 编程 Agent 提供持久化记忆的引擎，解决”每次新会话都要重新解释一遍”的痛点。

🎯 为什么需要它

每个编程 Agent（Claude Code、Cursor、Copilot 等）在会话结束后都会遗忘一切。你每次新会话的前 5 分钟都在重新解释你的技术栈、偏好和上下文。

内置记忆方案（CLAUDE.md、.cursorrules）有 200 行上限且容易过时。agentmemory 在后台静默捕获 Agent 的每次工具调用，压缩成可搜索的记忆，并在下次会话开始时自动注入正确的上下文。

Session 1: "给 API 加认证"
  Agent 写代码、跑测试、修 bug
  agentmemory 静默记录每次工具调用
  会话结束 → 观察压缩成结构化记忆

Session 2: "现在加限流"
  Agent 已经知道：
    - 认证用的是 JWT 中间件，在 src/middleware/auth.ts
    - 测试在 test/auth.test.ts，覆盖了 token 验证
    - 你选了 jose 而不是 jsonwebtoken，因为 Edge 兼容性
  零重复解释，直接开始工作。

✅ 核心优势

• 零手动捕获：通过 12 个 hooks 自动记录每次工具调用，无需手动 add() 调用
• 三路融合搜索：BM25 + 向量 + 知识图谱，RRF 融合排序，R@5 达到 95.2%
• 4 层记忆整合：Working → Episodic → Semantic → Procedural，模拟人脑记忆处理
• 自动遗忘：TTL 过期、矛盾检测、重要性淘汰，记忆按 Ebbinghaus 曲线衰减
• 隐私优先：API keys、secrets、<private> 标签在存储前自动剥离
• 跨 Agent 共享：一个 MCP 服务器，Claude Code / Cursor / Codex / Copilot 共享记忆
• 极低 Token 开销：~170K tokens/年，成本约 $10（本地嵌入则 $0）

⚡ 性能表现

检索准确率（LongMemEval-S，ICLR 2025，500 题）

Token 效率

🚀 快速上手

方式一：Claude Code 插件（推荐）

# 1. 启动记忆服务器（单独终端）
npx @agentmemory/agentmemory

# 2. 安装 Claude Code 插件
/plugin marketplace add rohitg00/agentmemory
/plugin install agentmemory

# 3. 验证
curl http://localhost:3111/agentmemory/health

插件自动注册 12 个 hooks + 4 个 skills + 51 个 MCP 工具，零额外配置。

方式二：Python API

pip install agentmemory

from agentmemory import create_memory, search_memories
from agentmemory.clustering import cluster

# 创建记忆
create_memory(
    category='code_context',
    text='项目使用 FastAPI + PostgreSQL，认证用 JWT',
    metadata={'project': 'myapp'}
)

# 搜索记忆
results = search_memories('认证方案', category='code_context')

# 聚类分析
cluster(epsilon=0.1, min_samples=3, category='code_context')

方式三：MCP 配置（通用）

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/mcp"],
      "env": {
        "AGENTMEMORY_URL": "http://localhost:3111"
      }
    }
  }
}

配置要点

📦 适用场景

适合：

• 长期使用 AI 编程 Agent 的开发者（每天用 Claude Code / Cursor）
• 多 Agent 协作环境，需要共享项目上下文
• 需要跨会话保持项目知识的团队
• 对 Token 成本敏感的场景

不适合：

• 偶尔使用 Agent 的轻度用户（内置 CLAUDE.md 够用）
• 需要云端托管记忆的场景（默认本地部署）
• Python API 的 PyPI 版本严重过时（0.4.8 vs GitHub v0.9.11），需从 GitHub 安装

⚠️ 已知坑 & 注意事项

• 需要单独运行服务器：npx @agentmemory/agentmemory 必须在单独终端运行，不是 pip 包那种”装了就能用”
• 控制台无认证：实时查看器（端口 3113）和服务器（端口 3111）没有认证，默认绑定 127.0.0.1，不要暴露到公网
• PyPI 版本过时：PyPI 上是 0.4.8（2023 年 10 月），GitHub 已到 v0.9.11（2026 年 5 月），建议用 npx 方式
• Claude 订阅回退有递归风险：AGENTMEMORY_ALLOW_AGENT_SDK=true 会导致 Stop-hook 无限递归（#149），默认已关闭
• LLM 功能默认关闭：默认是 no-op 模式，纯 BM25 压缩。需要 LLM 摘要要配置 API key
• Breaking Changes：v0.9.0 有较大变更（文件系统连接器、MCP 代理重构），升级前看 CHANGELOG

🆚 竞品对比

选择建议：

• 如果你用 Claude Code / Cursor 且想要”无感记忆”→ 选 agentmemory，hooks 自动捕获是最大差异
• 如果你需要纯 API 集成、不想跑本地服务 → 选 mem0
• 如果你需要完整的 Agent 运行时（自主决策、多步推理） → 选 Letta
• 如果你只是偶尔用 Agent → 内置 CLAUDE.md 够了

🌍 生态 & 社区

• 维护状态：非常活跃，33 个 releases，292 commits，最新 v0.9.11（2026-05-12）
• 文档质量：README 很详细，有 Quick Start、Benchmark、竞品对比、配置说明
• 周边生态：
  • Claude Code 插件（.claude-plugin/）
  • Codex CLI 插件（.codex-plugin/）
  • MCP 服务器（packages/mcp/）
  • 文件系统连接器（@agentmemory/fs-watcher）
  • 实时查看器（端口 3113）
  • 着陆页 agent-memory.dev
• 社区活跃度：549 forks，Issues 响应快（PR #77 当天关闭）

💡 引入评估

结论：推荐使用 — 对于重度 Claude Code 用户，这是目前最好的”无感记忆”方案。零配置自动捕获 + 三路融合搜索的组合在竞品中独一无二。主要风险是 v0.x 阶段的稳定性，以及需要单独运行服务器的运维成本。

推荐引入版本：v0.9.11（通过 npx @agentmemory/agentmemory，不要用 PyPI 的 0.4.8）

🔗 相关链接

• Claude Code MCP AI Agent 向量搜索 知识图谱
• 官方仓库
• 着陆页
• PyPI（版本过时）
• CHANGELOG

📝 个人备注

（待补充实际使用心得）