SOTA Sync
← 返回 FEED
PAPER2026-05-13

agentmemory：给 Claude/Cursor/Codex 装上无限记忆

agentmemory 开源项目近日爆发：3 天获得 4,000+ stars，v0.9.9 版本于 2026-05-11 发布，Apache-2.0 协议，一条 npx 命令安装。

它不是又一个静态文件记忆 hack，而是一个真正的本地记忆服务——替代 CLAUDE.md、.cursorrules 和所有其他「便利贴式」记忆方案。

核心问题：静态记忆的瓶颈

每个 AI coding agent 都带内置记忆：Claude Code 有 MEMORY.md，Cursor 有 notepads，Cline 有 memory bank。但这些就像便利贴——上限约 200 行，会过时，每次 session 打开时全部加载进上下文。

agentmemory 是便利贴背后的可搜索数据库。

三层架构：Capture → Pipeline → Retrieval

Capture（捕获）

12 个 Claude Code lifecycle hook 自动触发：SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、PostToolUseFailure、PreCompact、SubagentStart、SubagentStop、Notification、TaskCompleted、Stop、SessionEnd。

每个 hook 是独立 Node 脚本，从 stdin 读取 JSON，POST 到本地 REST API，然后退出。非 Claude agent 通过 /agentmemory/observe 或 MCP memory_save 工具同样捕获。零手动 add() 调用——agent 工作，hook 触发，观测落地。

Pipeline（处理）

每个观测在服务端经过四阶段：

  1. SHA-256 去重：5 分钟内重复内容被捕获
  2. 隐私过滤：自动剥离 <private> 块，redact API key、bearer token、GitHub token、AWS key、JWT 等
  3. 原始观测存入 iii-engine 文件 backed KV
  4. 合成压缩：BM25 索引（不调用 LLM）。若设置 AGENTMEMORY_AUTO_COMPRESS=true，配置的 Anthropic/MiniMax/Gemini/OpenRouter provider 将观测压缩为结构化事实

Retrieval（检索）

三条流并行运行：

  • BM25：Porter 词干提取 + 同义词扩展，始终运行
  • 向量：配置 embedding provider 时计算 cosine similarity（all-MiniLM-L6-v2 384 维，或 Gemini/OpenAI/Voyage/Cohere/OpenRouter）
  • 图谱：查询中检测到实体时遍历实体关系

结果通过 Reciprocal Rank Fusion（RRF_K=60）融合，然后按 session 多样化（每 session 最多 3 个结果），避免单个 session 的噪音主导 top-K。

四层记忆巩固模型

记忆通过四个层级递进，类比睡眠巩固：

层级内容
Working原始观测
Episodic压缩后的 session 摘要
Semantic提取的事实和模式
Procedural工作流和决策模式

记忆按艾宾浩斯曲线衰减。频繁访问的记忆强化。陈旧记忆自动驱逐。写入时检测并解决矛盾。

上下文组装

新 session 启动时，mem::context 组装 pinned slots、项目 profile、近期 session 摘要和高重要性观测，注入 <agentmemory-context> 块，默认 2,000 token 预算。

⚠️ 重要 caveat：SessionStart context injection 默认关闭（AGENTMEMORY_INJECT_CONTEXT=false）。README 里「agent 已经知道你的技术栈」的 demo 明确要求开启这个 env var。新手最常见的期望落差就是这里。

技术栈

agentmemory 基于 iii-engine（15K+ stars，TypeScript + Rust 服务组合框架）。函数、KV 状态、流、OTEL traces 都是 iii 原语。该引擎替代 Express.js、Postgres + pgvector、SSE/Socket.io、pm2 和 Prometheus。无外部数据库，无需 Docker。

安装与接入

# 启动服务
npx @agentmemory/agentmemory

# REST: 127.0.0.1:3111
# Streams: :3112
# Viewer: :3113

# 验证 demo
npx @agentmemory/agentmemory demo

# 打开 viewer
open http://localhost:3113

接入 agent（MCP 配置）：

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

支持 Cursor、Claude Desktop、Cline、Roo Code、Windsurf、Gemini CLI、Codex CLI、OpenCode。

Claude Code 用户：直接装 plugin：

/plugin marketplace add rohitg00/agentmemory
/plugin install agentmemory

自动注册 12 个 hook、4 个 skill，通过 .mcp.json 自动接入 MCP server。

Token 效率

方案每 session每年
agentmemory~1,900 tokens170K tokens (10/年，本地嵌入10/年，本地嵌入 0)
「贴进 CLAUDE.md」~22K tokens (240 条观测)-

92% token 减少（在重度用户第二个月常见的工作点上）。

LongMemEval-S（ICLR 2025，500 题，~48 sessions/题，~115K tokens/题）检索召回：

  • BM25 only：86.2% R@5
  • BM25 + 本地向量：95.2% R@5

已知问题

  1. 明文 HTTP 传输（issue #275 开放）：plugin 通过明文 HTTP 发送 AGENTMEMORY_SECRET bearer。默认 localhost 绑定限制了暴露范围，但任何超出单机的部署都需要反向代理 + TLS + auth review。

  2. Context injection 默认关闭： headline demo 需要手动开启 AGENTMEMORY_INJECT_CONTEXT=true。

  3. 引擎写入项目根目录（issue #303 开放）：iii-engine 在 Claude Code 从项目目录自动启动 agentmemory 时，会在用户 git working tree 内创建 data/state_store.db/。

  4. 文档漂移：AGENTS.md 说 v0.8.9 有 44 个工具、104 个 endpoint、699 个测试；源码有 51 个工具、127 个 endpoint 声明、888 个静态测试用例；README badge 说 104 endpoint/827 测试；README 正文说 107 endpoint。

  5. 非英语会话：BM25 检索今天会剥离非 ASCII token（issue #295）。

适用人群

✅ Claude Code、Cursor、Codex CLI、Gemini CLI、OpenCode 的 solo 或小团队用户 ✅ 在同一代码库上进行多 day agent session 的工程师 ✅ 想要实时查看 agent 学习内容的 viewer 的用户 ✅ 碰到 200 行 CLAUDE.md 天花板开始复制粘贴的人

❌ 未配置反向代理 + TLS 就把 REST surface 暴露到 localhost 之外的团队 ❌ 需要外部安全审计的生产部署（计划 Q4 2026） ❌ 依赖准确 BM25 检索的非英语 coding session ❌ 没有 Docker 或 iii-engine binary 的 Windows 用户

路线图

  • Q3 2026：增加维护者 onboarding（当前 91% 单维护者集中度）
  • Q4 2026：外部安全审计、SSO、RBAC、审计日志导出
  • Q1 2027：冻结 REST 和 MCP surface 为 v1.0

届时生产部署建议从「等」变成「部署」。

相关