告别 Claude 会话失忆：26.9K+ Star 开源工具，让 Token 开销直降 92%

01 AI 辅助开发中的常见问题

AI 编程助手已经能够参与代码编写、问题排查和项目维护，但在长期协作中，仍然存在明显的“失忆”现象。

每次创建新会话，开发者往往都要重新介绍项目架构、技术栈、目录约定以及过去遇到的问题。大量时间被消耗在重复说明上，而不是实际开发工作中。

常见问题主要包括：

• 新会话无法继承项目背景，需要反复讲解代码结构和开发规范
• CLAUDE.md、.cursorrules 等文本记忆容量有限，容易过期或堆积无效内容
• Cursor、Claude Code、Gemini CLI 等工具各自维护记忆，项目知识无法互通
• 为了让 AI 理解上下文，开发者需要不断复制粘贴代码，造成 Token 浪费
• 传统记忆系统通常依赖向量数据库，部署和维护成本较高
• 部分方案需要手动调用 API 保存记忆，使用流程不够自然
• 缺少可视化管理界面，难以检查、修正和批量维护 AI 保存的内容

这些问题会降低 AI 编程助手的连续协作能力，也会增加模型调用成本，使其难以成为稳定的长期开发伙伴。

02 项目定位

agentmemory 是一个面向 AI 编程 Agent 的开源持久化记忆项目，基于 iii engine v0.11.2 构建，目标是提供轻量、高效、跨平台的外置长期记忆能力。

它可以理解为 AI 编程助手的“项目记忆层”：经过一次配置后，系统会在后台自动记录项目结构、代码逻辑、操作习惯以及问题解决方案，并在后续会话中检索相关信息，帮助 AI 延续此前的工作上下文。

主要特性

1. 采用 Apache-2.0 开源协议，可用于商业项目
2. 支持 Windows、macOS 和 Linux
3. 兼容 32 种以上主流 AI 编程客户端，包括 Claude Code、Cursor、Gemini CLI、Codex、Hermes、OpenClaw、Cline、Goose、Claude Desktop、Windsurf 和 Aider 等
4. 基于 Karpathy LLM Wiki 思路扩展，加入置信度评估、记忆生命周期管理、知识图谱，以及 BM25、向量和图谱混合检索能力
5. 通过本地服务统一管理多个 AI 客户端的项目记忆

03 agentmemory 重点解决的七类问题

1. 会话结束后上下文丢失

会话关闭或客户端重启后，项目架构、代码关系以及历史修复方案仍然保存在记忆系统中，不需要从头开始说明。

2. 重复提供项目背景

系统会根据当前问题自动搜索相关记忆，并将匹配结果注入上下文，减少手动粘贴项目文档和历史代码的工作量。

3. 多工具之间无法共享信息

多个 AI 编程客户端可以连接到同一个 agentmemory 服务，从而使用统一的项目记忆，避免每个工具单独学习相同的背景。

4. 上下文过长导致 Token 成本上升

系统通过 Top-K 检索筛选最相关的信息，不再将整段历史上下文全部发送给模型。按照项目提供的测试数据，常规模式相比全文粘贴可以减少约 92% 的 Token 使用量。

5. 部署过程复杂

项目内置 SQLite，不要求额外安装 PostgreSQL、Qdrant 或 Redis 等服务，通常执行一条命令即可启动。

6. 记忆内容缺少管理入口

内置本地 Web 面板，可用于查看会话时间线、浏览知识图谱、编辑记忆、审计操作记录以及备份和恢复快照。

7. 敏感信息可能被保存

系统提供隐私过滤机制，可以识别并剥离 API Key、访问 Token、密钥等敏感内容，尽量只保留业务逻辑和代码相关信息。

04 六项核心技术能力

（1）自动捕获记忆

系统通过 12 个生命周期钩子自动收集开发过程中的重要信息，不需要用户频繁执行 remember 或 add 命令。

覆盖的事件包括：

• 会话开始与结束
• 用户提交问题
• 工具调用前后的状态
• 工具执行异常
• 子 Agent 的完整运行过程

这样可以将记忆收集融入正常开发流程，降低额外操作成本。

（2）四层记忆模型

agentmemory 将不同类型的信息分层保存，并根据使用情况自动衰减、强化、合并或修正冲突。

1. 工作记忆：保存工具调用和环境观察等短期信息
2. 情景记忆：记录单次会话发生了哪些操作
3. 语义记忆：沉淀项目事实、业务规则和结构化知识
4. 过程记忆：保存编码规范、开发流程和故障排查方法

这种分层方式可以减少重复信息，避免旧记忆长期占据检索结果。

（3）混合检索机制

系统同时使用三种检索方式：

• BM25 关键词检索
• 向量语义检索
• 知识图谱关联检索

最终通过 RRF（Reciprocal Rank Fusion）对结果进行融合排序。一方面可以精准匹配具体函数名、错误信息和配置项，另一方面也能处理表达方式不同但语义相近的问题。

（4）兼容标准 MCP

agentmemory 对外提供标准 MCP（Model Context Protocol）服务，能够被支持 MCP 的客户端接入。

目前提供 54 个 MCP 工具接口，覆盖：

• 记忆搜索
• 记忆新增、修改与删除
• 会话归档
• 项目档案管理
• 知识图谱查询
• 审计日志
• 团队共享
• 快照备份
• 多实例同步

（5）本地 Web 管理面板

服务默认使用 3113 端口提供可视化查看器，主要功能包括：

• 实时查看记忆数据流
• 按时间回放会话过程
• 支持 0.5 倍至 4 倍播放速度及步进控制
• 展示知识图谱中的实体关系
• 查看服务健康状态和资源占用情况

（6）本地运行与离线使用

项目使用 SQLite 保存数据，并内置 all-MiniLM-L6-v2 本地向量模型。启用本地嵌入后，不需要额外配置 API Key，也不会产生远程嵌入调用费用，适合内网或对数据隔离要求较高的开发环境。

05 项目基准测试

项目提供了公开测试数据集，用户可以在本地复现相关结果。文档列出的指标包括：

• LongMemEval-S 编程测试集的 R@5 召回率为 95.2%
• 内部编码数据集 Top5 命中率达到 100%
• 检索精度约为传统 grep 全文匹配的 2.2 倍
• 检索 p50 平均延迟约为 14ms
• 全文注入模式年消耗约 1950 万 Token
• agentmemory 常规检索模式年均消耗约 17 万 Token
• 本地嵌入模式不产生嵌入 API Token 费用
• 与全文粘贴上下文相比，Token 开销减少约 92%
• 项目声明已有 950 余项单元测试通过，可用于持续运行场景

这些结果属于项目提供的基准数据，实际表现仍会受到硬件、模型、项目规模和配置方式影响。

06 与其他记忆方案的对比

对比项	agentmemory	mem0	Letta / MemGPT	Khoj	编辑器原生记忆
R@5 检索表现	95.2%，支持本地复现	68.5%，第三方数据集	83.2%，第三方数据集	缺少结构化检索数据	主要依赖全文搜索
记忆写入方式	通过 12 个钩子自动采集	通常需要调用 add() API	由 Agent 自主编辑	主要依赖人工录入	手动维护文本文件
检索方式	BM25、向量、知识图谱融合	向量加基础图谱	向量归档检索	基础语义检索	全文加载
外部依赖	内置 SQLite	通常需要 Qdrant 或 pgvector	需要 Postgres 和向量数据库	依赖多个组件	无额外依赖
多工具共享	单服务统一共享	API 级互通	主要面向 Letta 运行时	不支持多工具共享	工具之间相互隔离
生命周期管理	自动合并、衰减、过期和冲突修正	主要依赖被动提取	需要 Agent 主动维护	手工管理	手工编辑
可视化能力	本地 Web 面板	云端面板	云端面板	提供基础 Web UI	通常没有
部署方式	本地优先，也支持云端	云服务或自建	云服务或自建	以本地自建为主	本地静态文件

07 30 秒快速启动

环境要求

• Node.js 20 或更高版本
• Windows 用户可以使用 Docker Desktop，以减少原生兼容问题

方式一：全局安装

npm install -g @agentmemory/agentmemory

如果 macOS 或 Linux 出现权限错误，可以使用：

sudo npm install -g @agentmemory/agentmemory

方式二：使用 npx 临时运行

npx @agentmemory/agentmemory

如果需要强制获取最新版本：

npx -y @agentmemory/agentmemory@latest

启动服务

安装完成后执行：

agentmemory

默认服务地址：

• REST API：http://localhost:3111
• Web 查看器：http://localhost:3113

运行服务的终端需要保持开启，关闭终端后记忆服务也会停止。

运行示例 Demo

新开一个终端，执行：

agentmemory demo

该命令会导入 JWT 鉴权、数据库优化和接口限流等开发场景，用于验证记忆保存及混合检索效果。

也可以使用一体化命令：

agentmemory demo --serve

该模式会自动启动服务、运行演示并在结束后清理运行环境。

常用维护命令

agentmemory stop       # 停止服务
agentmemory remove     # 删除全部本地记忆数据
agentmemory doctor     # 检查并修复环境问题
agentmemory upgrade    # 更新到最新稳定版本

08 MCP 客户端接入方式

Cursor

打开 ~/.cursor/mcp.json，在 mcpServers 中加入：

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

保存后重启 Cursor。

Claude Code

推荐使用带钩子的连接命令：

agentmemory connect claude-code --with-hooks

该命令会注册插件、配置 MCP 服务，并绑定 12 个生命周期钩子。

优先使用：

/plugin install agentmemory

如果仅使用基础 MCP 配置，升级客户端后可能出现钩子路径失效，需要重新执行连接命令。

Gemini CLI

gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user

Codex CLI

完整插件模式：

codex plugin marketplace add rohitg00/agentmemory
codex plugin add agentmemory@agentmemory

仅使用 MCP 的基础模式：

codex mcp add agentmemory -- npx -y @agentmemory/mcp

Codex Desktop 目前可能存在上游钩子触发问题。如需写入全局钩子配置，可以额外执行：

agentmemory connect codex --with-hooks

通用 MCP 配置

以下配置可用于 Cursor、Claude Desktop、Cline、Roo Code、Windsurf 和 OpenClaw 等 MCP 客户端：

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

09 自定义配置与云端部署

本地环境变量

创建文件：

~/.agentmemory/.env

示例配置如下：

# 使用本地向量模型
EMBEDDING_PROVIDER=local

# 根据需要配置远程大模型
# ANTHROPIC_API_KEY=xxx
# GEMINI_API_KEY=xxx
# OPENAI_API_KEY=xxx

# 服务鉴权密钥
AGENTMEMORY_SECRET=your_custom_secret

# 每次会话最多注入的记忆 Token 数
TOKEN_BUDGET=2000

# 启用知识图谱实体提取
GRAPH_EXTRACTION_ENABLED=true

# 开启记忆合并、压缩和生命周期管理
CONSOLIDATION_ENABLED=true

# 可选高级能力
# AGENTMEMORY_SLOTS=true
# SNAPSHOT_ENABLED=true

云端部署

项目提供标准 Dockerfile，可部署到 fly.io、Railway、Render、Coolify 或自建 VPS。

部署时需要将容器内的 /data 目录挂载为持久化存储。对外通常只开放 3111 API 端口，3113 Web 面板默认仅允许本地访问。若需要远程访问，建议使用 SSH 隧道，而不是直接将管理面板暴露到公网。

使用 iii 引擎扩展能力

基于 iii 引擎，还可以通过以下命令增加企业级任务能力：

iii worker add iii-cron      # 定期整理记忆、清理过期内容、轮换快照
iii worker add iii-queue     # 异步任务失败后自动重试
iii worker add iii-pubsub    # 在多个服务实例之间同步记忆
iii worker add iii-sandbox   # 隔离执行检索出的代码片段

10 常见问题处理

端口被占用

Windows：

netstat -ano | findstr :3111

macOS 或 Linux：

lsof -i :3111

找到对应 PID 后结束占用进程，再重新启动服务。

无法访问 3113 管理面板

可以依次检查：

1. agentmemory 服务是否仍在运行
2. 本机防火墙是否拦截了 3113
3. 是否开启了会影响 localhost 访问的代理或 VPN

Demo 没有检索结果

建议：

1. 重新运行 agentmemory demo
2. 检查 Node.js 是否达到 20 及以上版本
3. 暂时关闭网络代理后再次测试

MCP 只显示少量基础工具

如果客户端只显示 7 个基础工具，通常说明主服务没有正常连接，MCP shim 进入了降级模式。

可按以下步骤处理：

1. 在独立终端启动 agentmemory
2. 检查 AGENTMEMORY_URL 是否为 http://localhost:3111
3. 完全退出并重启 AI 客户端，让 MCP 配置重新加载

Windows 启动异常

Windows 用户可以优先尝试 Docker Desktop。若继续使用原生模式，则需要下载与系统架构匹配的 iii-engine v0.11.2 二进制文件，并确保它位于系统 PATH 中。

11 使用建议

1. 第一次使用时，尽可能完整地说明项目架构、技术栈、目录规则、禁用写法以及历史 Bug，让系统先建立基础项目知识。
2. 优先选择本地嵌入模型，减少 API 依赖，并满足内网或敏感项目的离线使用需求。
3. 多个客户端共用一个 agentmemory 实例即可，避免重复启动服务和产生多套互相独立的记忆。
4. 定期通过 3113 面板检查自动生成的内容，删除错误、冲突或已经失效的记忆。
5. 对重要项目开启快照备份，以便进行版本对比和回滚。
6. 团队项目可以启用共享记忆图谱，统一团队成员对编码规范和排错方案的理解。
7. 不要直接修改底层 SQLite 文件。记忆的新增、编辑、删除和备份应通过 Web 面板或 MCP 工具完成，否则可能破坏数据结构。

12 总结

agentmemory 的核心价值在于为 AI 编程工具补充一层独立、持久且可共享的项目记忆。

它通过自动钩子捕获开发过程，将信息分为工作、情景、语义和过程四类记忆，再利用关键词、向量和知识图谱进行联合检索。这样既能减少重复说明，也能让 Cursor、Claude Code、Gemini CLI、Codex 等多个工具共享同一套项目知识。

项目的主要卖点包括：

• 一次配置，持续保留项目上下文
• 12 个生命周期钩子自动采集记忆
• 多编辑器和 CLI 工具共享记忆
• 通过精准检索降低 Token 消耗
• 内置 SQLite，无需额外数据库
• 支持本地离线运行
• 提供 Web 面板进行查看、编辑、审计和备份
• 兼容标准 MCP 协议

对于个人开发者，它可以减少重复沟通；对于团队项目，则可以帮助统一工程规范和问题处理经验。

项目地址：

https://github.com/rohitg00/agentmemory

改写策略： 保留原文的产品定位、功能结构、安装配置和故障排查信息；重新组织句式和段落逻辑，减少重复表达，并将部分宣传性表述改为更客观的功能说明。基准性能、兼容客户端数量及工具接口数量等内容仍属于原文提供的数据，使用前建议结合项目仓库和实际版本进一步核验。