agentmemory:给 AI 编程助手装上一块长期记忆

内容摘要

agentmemory 是面向 AI 编程助手的长期记忆系统：自动记录会话、检索历史、压缩上下文，并通过 MCP/REST 跨工具共享。

一、为什么这个项目值得看

AI 编程助手越来越能写代码，但还有一个反复出现的问题：每开一个新会话，就像换了一个新人。你要重新解释项目结构、偏好、技术选型、踩过的坑；助手也会重新摸索同一个 bug、重复读同一批文件。

agentmemory 想解决的正是这件事：让编码助手把每次会话里发生过的事情沉淀为可检索、可压缩、可注入上下文的长期记忆。它不是另一个聊天机器人，而是一个给各种 agent 共用的记忆层。

从仓库信息看，这个项目目前非常活跃：GitHub 仓库为 rohitg00/agentmemory，主语言 TypeScript，Apache-2.0 许可证；截至我查看时约 15.4k stars、1.2k forks，npm 最新版本为 0.9.21。

二、它到底是什么

用一句话概括：agentmemory 是一个“AI 编程助手长期记忆服务器”。

它可以通过 hooks、MCP 或 REST 接入多种工具，包括 Claude Code、Cursor、Gemini CLI、Codex CLI、Hermes、OpenCode、OpenClaw 等。多个 agent 可以连接到同一个本地服务器，使用同一份项目记忆。

官方给出的核心命令很简单：

BASH

npx @agentmemory/agentmemory
agentmemory connect claude-code
agentmemory connect codex

启动后，它默认提供：

REST API：用于服务端能力访问；
MCP surface：用于 Cursor、Gemini CLI、Claude Desktop 等 MCP 客户端；
Viewer：一个本地可视化界面，用来查看记忆、会话回放和状态；
Hooks / Plugins：在 agent 生命周期里自动捕捉上下文。

三、核心流程：从“会话碎片”到“可用记忆”

agentmemory 的 README 把流程写得很直观，大致可以理解为三段。

1. 采集

当 agent 使用工具、读取文件、运行命令、遇到错误时，hooks 会自动把这些事件记录下来。项目里强调“zero manual effort”，也就是尽量不要求用户手动调用 memory_save。

2. 压缩与索引

原始记录会经过隐私过滤、去重、LLM 压缩，再提炼出结构化事实、概念和叙述；随后进入 BM25、向量索引，以及可选的知识图谱。

3. 注入

下一次新会话开始时，系统会根据项目、问题和 token 预算，检索相关记忆，把真正有用的上下文注入给 agent，而不是粗暴地把全部历史塞进去。

这个设计的关键不只是“存下来”，而是“在合适的时候取出合适的部分”。这也是长期记忆系统和普通日志系统的分界线。

四、设计亮点：它不是单纯的向量库

1. 4 层记忆模型

项目把记忆分成 working、episodic、semantic、procedural 四层：

Working：工具调用产生的原始观察；
Episodic：会话总结，回答“发生过什么”；
Semantic：抽取出的事实和模式，回答“我知道什么”；
Procedural：流程和决策模式，回答“以后该怎么做”。

这个分层让它更像“会成长的项目记忆”，而不是只会做相似度搜索的笔记本。

2. 混合检索

检索不是单一路线，而是 BM25 + Vector + Graph 的三路组合，并通过 RRF 做融合排序。这样既能处理文件名、函数名这类强关键词，也能处理“数据库性能优化”这类语义查询。

3. 多 agent 共享

这是 agentmemory 很有意思的一点：它并不绑定某个单一 agent。Claude Code 记录下来的项目决策，可以被 Codex CLI 或 Cursor 在后续会话里检索到。对同时使用多个工具的开发者来说，这比“每个工具各自记忆一份”更自然。

4. 隐私和治理

项目里有隐私过滤、audit trail、governance delete、auto-forget、retention 等能力。换句话说，它不是只管“记住”，也考虑“该忘的忘掉”“敏感内容不要存”“删除要有记录”。

五、源码里能看到什么

我粗略看了一下代码结构，这不是一个只有 README 的概念项目。仓库里有 280+ 个 TypeScript 文件、100+ 个测试文件，源码主要集中在 src/，并配套了 plugin/、integrations/、packages/mcp/、website/、benchmark/、eval/ 等目录。

几个关键模块很清晰：

src/index.ts：注册 worker、加载配置、初始化 provider、注册大量 memory functions、REST triggers、MCP endpoints 和 viewer；
src/functions/：记忆观察、压缩、检索、上下文注入、总结、图谱、治理、快照、行动队列等核心能力；
src/state/：KV、搜索索引、向量索引、混合搜索等状态层；
src/mcp/：MCP 工具注册和服务端；
src/hooks/ 与 plugin/：不同 agent 的自动采集入口。

它的实现建立在 iii-engine / iii-sdk 的 Worker、Function、Trigger 三个原语上，状态层默认走文件型 SQLite，不要求你额外部署 Qdrant、Postgres 或 pgvector。

六、和常见记忆方案的差异

如果和 mem0、Letta/MemGPT、Khoj、claude-mem 这类项目放在一起看，agentmemory 的定位比较明确：它不是完整 agent runtime，也不是面向个人知识库的第二大脑，而是偏“AI coding agent infrastructure”的记忆层。

它更适合这些场景：

你每天用 AI agent 改代码，不想反复解释项目背景；
你同时使用 Claude Code、Cursor、Codex、Gemini CLI 等多个工具；
你想本地自托管，不想为了记忆系统额外部署向量数据库；
你需要会话回放、来源追踪、审计、团队共享等工程化能力；
你愿意把“记忆”看成可治理的系统，而不是一个简单的聊天记录集合。

七、需要注意的地方

这个项目很强，但也不是所有人都应该立刻上生产。

首先，它的功能面很大：MCP 工具、REST endpoints、hooks、viewer、embedding、graph、retention、governance、team memory……这意味着上手虽然可以很快，但深入配置和长期维护需要理解它的运行模型。

其次，它强依赖 agent hooks 的质量。不同客户端对 hooks、MCP、插件机制的支持并不完全一致，仓库 changelog 里也能看到很多修复都和不同宿主的边界行为有关。

再次，README 里的 benchmark 很吸引人，但任何记忆系统都应该用自己的真实工作流验证。你的代码库、语言、会话长度、隐私要求、embedding provider，都会影响最终效果。

八、我的判断

agentmemory 抓住了 AI 编程助手下一个阶段的关键问题：不是“模型会不会写代码”，而是“助手能不能连续地理解一个项目”。

如果说第一代 coding agent 解决的是“把一次任务做完”，那么类似 agentmemory 的项目想解决的是“把一个长期项目做下去”。这件事一旦做好，AI 助手就不再只是一次性问答窗口，而更像一个会积累上下文、会记住偏好、会复用经验的协作成员。

对开发者来说，最值得尝试的入口其实很简单：找一个真实项目，运行几天，让它记录你的会话；然后在新会话里问它一个过去解释过的问题。只要那一刻它能少问你一句“这个项目是怎么组织的？”，长期记忆的价值就已经开始显现了。

项目地址：https://github.com/rohitg00/agentmemory 官网：https://agent-memory.dev