agentmemory：让你的AI编程助手永久记住你的代码库

项目介绍

你是否经历过这样的场景？今天你花了一小时向 AI 编程助手解释整个项目的架构、模块职责和最新修改进度。到了第二天，一切归零——助手像是失忆了一般，要求你重新讲述一切。你无奈地再次从头到尾重复昨天的工作，浪费了大量时间和 API 调用费用。

如果你对此深有体会，那么agentmemory 就是为你量身定制的解决方案。

agentmemory 是由开发者 rohitg00 发起的开源项目，近期在 GitHub Trending 上以每日超过 533颗星的速度飙升，累计星标已突破 3700颗。该项目采用 Apache 2.0 许可证，基于 TypeScript 构建，最新版本为 v0.9.5（于 2026 年 5 月 9 日发布）。它的核心定位非常明确：为所有主流 AI 编程助手提供持久的、跨会话的记忆能力。

与传统方案不同，agentmemory 并非一个简单的提示词模板，而是一个完整、自托管的记忆引擎。它通过模拟人脑的四层记忆巩固机制，结合三重流检索技术，真正解决了 AI 编程助手在长期协作中的"遗忘症"问题。

核心功能详解

一、解决的根本痛点

AI 编程助手的每一次对话本质上都是一个独立的会话窗口。当会话关闭后，所有的上下文信息都会消失。这意味着每天每次新会话开始时，开发者都必须花费数十分钟重新说明以下内容：

项目的整体架构和技术栈
最近完成的工作和下一步计划
代码中的关键设计决策及其原因
特定模块的职责边界和接口约定

据实际测试统计，一个活跃开发者每年用于重复解释上下文的 token 消耗量高达 1950万，折合成本约 500美元——这在许多情况下是完全无法承受的。而引入 agentmemory 后，token 用量可直接缩减至约 17万次，降幅达 92%，月度成本降至 10美元左右。如果配合本地嵌入模型（如 all-MiniLM-L6-v2），则可以实现近乎零成本的离线运行。

二、四层记忆巩固机制

agentmemory 的核心创新之一，是借鉴人类大脑的记忆形成过程，设计了四个层级的记忆存储与检索体系：

工作记忆（Working Memory）：当前活跃会话中产生的临时信息，如正在进行的功能开发任务、待解决的 bug 等。这些数据保留在内存中，供即时查询。
情景记忆（Episodic Memory）：记录具有时间戳的交互事件，包括你让助手做了什么、何时做的、产生了什么结果。这种记忆方式让助手能够回答"上周我在做什么？“这类时序性问题。
语义记忆（Semantic Memory）：从大量交互中提取出的结构化知识，如模块之间的关系、函数的用途、项目的业务逻辑等。这部分内容经过聚合处理后，形成对项目整体的深层理解。
程序性记忆（Procedural Memory）：固化下来的模式和习惯。例如，如果你在多个项目中都习惯用同样的方式组织 API 路由文件，agentmemory 会学习并记住这一偏好，在新项目中自动应用。

这四个层级之间会自动进行信息流动与整合，确保重要的记忆不会丢失，次要的记忆会被合理抽象。

三、三重流检索融合

在记忆检索方面，agentmemory 采用了一种创新的三路并行策略：

BM25 全文检索：针对精确的关键词匹配，如函数名、变量名或具体错误信息
向量相似度检索：利用嵌入模型捕捉语义层面的关联，适合模糊描述的查询
知识图谱检索：基于项目中提取的结构化关系（模块依赖、文件引用等）进行图遍历

这三种检索结果通过**倒数排名融合（Reciprocal Rank Fusion, RRF）**算法进行合并排序。根据 LongMemEval-S 基准测试数据，该策略的 R@5 召回率达到了 95.2%，远超纯 BM25 方案的 86.2%。

四、广泛的生态兼容性

agentmemory 通过标准的 **MCP（Model Context Protocol）**协议与各大编程助手无缝集成，目前已全面支持以下主流工具：

Claude Code
Cursor
Gemini CLI
Codex CLI
OpenCode
Cline
Goose
Kilo Code
Roo Code
Aider
Windsurf
Claude Desktop

这意味着无论你日常使用哪个助手，都可以立即接入这套记忆系统，无需更换工具链。

五、隐私与安全性

作为本地优先的设计，agentmemory 在数据隐私方面表现出色：

完全自托管：仅需 SQLite 数据库和 iii-engine 两个组件，无任何外部云服务依赖
敏感信息过滤：在将数据存储到内存之前，系统会自动检测并过滤 API 密钥、密码等敏感内容
本地嵌入支持：内置 all-MiniLM-L6-v2 模型，完全离线运行，不向任何第三方发送数据
实时可视化界面：通过 localhost:3113 即可访问记忆浏览器，直观查看当前的记忆内容和结构
会话回放功能：可以回放任意历史会话的操作轨迹，方便回顾和调试

使用教程

安装与启动

首先，从 GitHub 克隆项目并进入目录：

git clone https://github.com/rohitg00/agentmemory.git
cd agentmemory

然后通过 npm 安装依赖并启动服务：

npm install
npm start

启动后，MCP 服务器会在本地运行，同时可通过 http://localhost:3113 访问可视化记忆浏览器。

配置编程助手

Cursor 用户

在 Cursor 的设置中找到 MCP 服务器配置区域，添加如下配置：

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/mcp"]
    }
  }
}

重启 Cursor 后即可生效。

Claude Code 用户

在项目根目录下创建 .claude/settings.json 文件（如果不存在），然后添加 MCP 配置：

{
  "env": {
    "additionalModelRulesText": "",
    "allowedTools": [],
    "tools": []
  },
  "permissions": {
    "allow": [],
    "deny": []
  }
}

然后在 .mdrc 规则文件中启用 agentmemory 相关的记忆工具。

核心 MCP 工具一览

agentmemory 提供了完整的 51个 MCP 工具来操作记忆系统，常用的包括但不限于：

add_memory — 向记忆系统手动添加一条记录
query_memory — 查询记忆系统中的相关内容
forget_memory — 移除不需要的记忆条目
consolidate_memory — 触发记忆整合流程，将短期记忆转化为长期记忆
list_memories — 列出指定类别下的所有记忆条目
search_graph — 通过知识图谱进行结构化检索
export_session — 导出某次会话的完整记录

你可以在记忆浏览器的工具面板中直接预览和测试每个工具的参数与返回结果。

记忆自动捕获

除了手动操作外，agentmemory 还具备全自动的记忆捕获能力。当你使用编程助手完成任务时，系统会自动记录：

你提出的需求和修改指令
助手的响应和行动步骤
生成的代码变更
产生错误的调试过程

这些信息会被自动分类并注入到相应的记忆层级中，整个过程对开发者透明无感。你只需要正常编码，记忆系统会自动在后台建立你的项目知识档案。

实际应用场景

场景一：大型团队协作

想象你加入了一个已有数百个文件的庞大项目，团队中有十多名开发者轮流维护同一个模块。在没有记忆系统的情况下，每位新开发者都需要数天的阅读和沟通才能上手。而借助 agentmemory，你可以直接询问：

“这个认证模块的设计意图是什么？谁最后改过它？为什么选择了 JWT 而不是 OAuth 回调？”

记忆系统会从情景记忆和语义记忆中提取出相关的所有讨论记录和决策依据，让你瞬间获得项目背景知识。

场景二：长期维护的个人项目

很多开发者都有"三个月不看，连自己在写什么都忘了"的经历。agentmemory 的情景记忆会像日记一样，按时间线记录你的每一个操作。几个月后回来接手，你只需说"回忆一下我上次在这个项目上做了什么”，助手就能准确列出最近的修改清单和未完成的任务。

场景三：多助手协同工作

你可能在某些时候使用 Claude Code，某些时候切换到 Cursor 或 Gemini CLI。传统的方案下，切换助手意味着切换上下文。但有了 agentmemory，所有助手共享同一套记忆库。无论你在哪个助手中开始工作，都能立刻继承之前的全部进展，真正实现多助手自由切换而不丢失上下文。

场景四：审计与追溯

对于需要严格代码审查的团队，agentmemory 的会话回放功能可以提供完整的决策追踪链。每当有人质疑某个代码变更的原因时，可以一键调出当时的对话记录和分析过程。

与竞品对比

在选择持久记忆方案时，开发者通常会考虑以下几个选项。以下是 agentmemory 与其他常见方案的对比分析：

与 mem0 对比

mem0 是目前较为知名的 AI 记忆方案，但它主要依赖云端基础设施，部署门槛较高，且数据需要经过外部服务处理。agentmemory 的最大优势在于完全本地化——所有数据存储在你自己的机器上，不涉及任何外部依赖。对于注重数据安全的团队而言，这一差异尤为关键。

与 Letta 对比

Letta 是一个面向聊天场景的记忆增强框架，更侧重于对话管理和角色扮演一致性。虽然它也提供了记忆管理能力，但在代码开发的垂直领域，其定制化程度不如 agentmemory。此外，Letta 的部署复杂度明显更高，需要额外的运行时环境。agentmemory 则专注于编程场景，开箱即用。

与内置 CLAUDE.md 对比

许多开发者选择用手动维护 CLAUDE.md 文件的方式来传递项目上下文。这种方式简单粗暴，但也存在明显的局限性：

容量有限：大文件超出上下文窗口会导致部分信息被截断
更新滞后：手动维护难以跟上快速迭代的代码变化
缺乏语义检索：只能做简单的关键词匹配，无法理解语义关联
不支持多助手共享：每个助手的上下文必须单独准备

agentmemory 从根本上解决了这些问题。它通过自动化的记忆捕获、语义级检索和多层压缩，不仅大幅减少了 token 消耗，还保持了极高的信息召回率。

综合对比总结

特性	agentmemory	mem0	Letta	CLAUDE.md
部署方式	完全本地	云依赖	复杂运行时	纯文本文件
Token 节省	92%	有限	中等	几乎为零
语义检索	✅ 三重流融合	✅ 向量	⚠️ 基础	❌ 仅关键词
多助手兼容	✅ 12+ 工具	⚠️ 有限	⚠️ 单助手	❌ 单助手
隐私安全	✅ 完全本地	⚠️ 数据外传	⚠️ 混合	✅ 完全本地
学习成本	低	中	高	极低
记忆层级	四层	单层	双层	无

获取方式

agentmemory 目前已在 GitHub 上开源，采用宽松的 Apache 2.0 许可证，任何人都可以自由使用、修改和分发。

GitHub 仓库：https://github.com/rohitg00/agentmemory
当前版本：v0.9.5（2026 年 5 月 9 日发布）
编程语言：TypeScript
最低依赖：SQLite + iii-engine

你可以直接在项目中引用 agentmemory 的 MCP 工具包，也可以将其作为独立服务部署在自己的开发环境中。项目文档完善，社区活跃，对于希望提升 AI 辅助开发效率的中文开发者来说，这是一个值得第一时间尝试的工具。

💡 小贴士：如果你的项目涉及商业机密或敏感代码，建议开启 agentmemory 的本地嵌入模式（使用 all-MiniLM-L6-v2 模型），这样所有的索引和检索过程都不会离开你的本机，真正做到数据安全不出域。

欢迎在下方评论区分享你使用 AI 编程助手的经验，以及你对持久记忆功能的期待！

项目介绍#

核心功能详解#

一、解决的根本痛点#

二、四层记忆巩固机制#

三、三重流检索融合#

四、广泛的生态兼容性#

五、隐私与安全性#

使用教程#

安装与启动#

配置编程助手#

Cursor 用户#

Claude Code 用户#

核心 MCP 工具一览#

记忆自动捕获#

实际应用场景#

场景一：大型团队协作#

场景二：长期维护的个人项目#

场景三：多助手协同工作#

场景四：审计与追溯#

与竞品对比#

与 mem0 对比#

与 Letta 对比#

与内置 CLAUDE.md 对比#

综合对比总结#

获取方式#