AgentMemory — 持久记忆系统：安装、架构与深度使用指南

G_whang2026-06-14 11:57

1. 概述：为什么需要 AgentMemory

AI 编程助手（Claude Code、Cursor、Codex、Gemini CLI 等）的天然短板是跨会话遗忘 ------每次新对话都从零开始，项目架构、历史决策、踩过的坑全部丢失。AgentMemory 是一个本地优先的持久记忆中间件，基于 MCP（Model Context Protocol）为 AI Agent 提供跨会话、跨工具的共享记忆能力。

核心数据：

指标 数值
检索召回率（LongMemEval-S，R@5） 95.2%（业界最佳）
P50 检索延迟 < 20ms
Token 节省 相比全量上下文减少约 92%
年度 Token 开销 ~170K（约 $10/年）
GitHub Stars 21,000+

2. 架构总览

复制代码 
┌──────────────┐     MCP / REST / HTTP     ┌──────────────────────┐
│  AI Agent    │ ◄───────────────────────► │  AgentMemory Server  │
│  (Claude,    │                           │  (localhost:3111)    │
│   Cursor,    │                           │                      │
│   Codex,     │     实时查看器             │  ┌────────────────┐  │
│   OpenClaw,  │ ◄───────────────────────► │  │   SQLite +     │  │
│   Gemini,    │    (localhost:3113)        │  │   iii-engine   │  │
│   etc.)      │                           │  └────────────────┘  │
└──────────────┘                           │  ┌────────────────┐  │
                                            │  │  all-MiniLM    │  │
                                            │  │  -L6-v2 (本地) │  │
                                            │  └────────────────┘  │
                                            └──────────────────────┘

2.1 核心组件

组件 说明
Memory Server（:3111） 核心 REST API + 存储引擎
iii-engine Rust 编写的底层引擎，内核 SQLite + 本地向量嵌入，零外部依赖
MCP Server 暴露 53 个 MCP 工具给 AI Agent
Real-time Viewer（:3113） Web 仪表盘，实时展示 Agent 学到的内容
嵌入模型 all-MiniLM-L6-v2，本地运行，免费，无需 API Key

2.2 关键设计决策

  • 零外部依赖：仅 SQLite + iii-engine，无需 PostgreSQL、Qdrant、pgvector 或 Redis。
  • 本地优先：所有数据存于本地，不离开机器，写入前自动剥离 API Key/Secrets/JWT。
  • 确定性 + LLM 增强：存储层为确定性 SQLite；摘要和结构化提取由 LLM 完成。
  • 单服务多 Agent：所有 MCP 兼容工具共享同一记忆服务器与同一份记忆。

3. 安装

3.1 环境要求

依赖 最低版本
Node.js ≥ 18
npm ≥ 9

3.2 步骤 1：安装 AgentMemory

bash 复制代码 
# 卸载旧版本（如已安装）
npm uninstall -g @agentmemory/agentmemory

# 全局安装（国内网络建议使用 npmmirror 镜像）
npm install -g @agentmemory/agentmemory --registry=https://registry.npmmirror.com

3.3 步骤 2：验证安装

bash 复制代码 
agentmemory --version

3.4 步骤 3：下载 iii 引擎

iii-engine 是 AgentMemory 的底层运行时，需单独下载放置。

bash 复制代码 
# 下载链接（Windows x64）
https://github.com/iii-hq/iii/releases/download/iii%2Fv0.11.2/iii-x86_64-pc-windows-msvc.zip

# 其他平台/版本参见 Releases 页
https://github.com/iii-hq/iii/releases

3.5 步骤 4：解压并配置 PATH

bash 复制代码 
# 推荐目录
mkdir -p %USERPROFILE%\.local\bin

# 解压 zip，将 iii.exe 放到该目录
C:\.local\bin\iii.exe

配置 PATH（Windows）：

  1. 右键「此电脑」→ 属性 → 高级系统设置 → 环境变量
  2. 在用户变量 中选中 Path，点击编辑
  3. 新建 → 粘贴 %USERPROFILE%\.local\bin
  4. 确定保存

3.6 步骤 5：验证 iii 引擎

bash 复制代码 
iii --version

4. 启动与测试

4.1 启动记忆服务器

bash 复制代码 
agentmemory

服务器启动后将监听 http://localhost:3111，实时查看器位于 http://localhost:3113。此窗口保持打开，不要关闭。

4.2 灌入测试数据

在新终端中执行：

bash 复制代码 
agentmemory demo

4.3 验证

打开浏览器访问 http://localhost:3113，确认 Web 仪表盘正常展示。

4.4 启动 MCP 服务（独立窗口）

bash 复制代码 
npx -y @agentmemory/mcp

此命令以 MCP stdio 模式运行，供 AI 工具通过 MCP 协议调用 53 个记忆工具。此窗口同样保持打开。

5. Claude Code 集成（插件方式，推荐）

5.1 安装插件

在 Claude Code 会话中依次执行：

bash 复制代码 
# 进入 Claude Code
claude

# 添加插件市场
/plugin marketplace add rohitg00/agentmemory

# 安装插件
/plugin install agentmemory

安装完成后会自动生成 .mcp.json 配置文件，并注册：

  • 12 个 Hooks（自动捕获）
  • 15 个 Skills（8 个操作类 + 7 个参考类）
  • 53 个 MCP 工具

5.2 配置自动记忆

bash 复制代码 
# 开启自动存储（每次对话自动存入记忆）
$env:AGENTMEMORY_AUTO_STORE="true"

# 开启上下文注入（会话启动时自动注入相关记忆）
$env:AGENTMEMORY_INJECT_CONTEXT="true"

注意： 上述为 PowerShell 语法。在 bash 中使用 export AGENTMEMORY_AUTO_STORE=true。

设置环境变量后重启 Claude Code，正常聊天即可自动记忆。所有对话会自动存入 http://localhost:3113 可查。

5.3 验证

bash 复制代码 
curl http://localhost:3111/agentmemory/health

5.4 远程/受保护环境

bash 复制代码 
AGENTMEMORY_URL=<远程地址> AGENTMEMORY_SECRET=<密钥> claude

6. OpenClaw 集成

6.1 配置 MCP

编辑 openclaw.json，在 mcp.servers 中增加：

json 复制代码 
{
  "mcp": {
    "servers": {
      "agentmemory": {
        "command": "cmd.exe",
        "args": ["/c", "npx", "-y", "@agentmemory/mcp"],
        "env": {
          "AGENTMEMORY_URL": "http://localhost:3111",
          "AGENTMEMORY_AUTO_STORE": "true",
          "AGENTMEMORY_INJECT_CONTEXT": "true"
        }
      }
    }
  }
}

说明： AGENTMEMORY_URL 指向记忆服务器地址，AGENTMEMORY_AUTO_STORE 控制是否自动存储对话，AGENTMEMORY_INJECT_CONTEXT 控制是否在会话启动时注入上下文。

6.2 重启 OpenClaw

bash 复制代码 
openclaw gateway restart

6.3 启用记忆

bash 复制代码 
# 启动交互式聊天
openclaw chat

# 查看已识别的 MCP 服务
/mcp list

# 启用 agentmemory
/mcp use agentmemory

6.4 验证

bash 复制代码 
/remember 测试：MCP shim 正常

提醒： OpenClaw 自身已具备记忆存储能力，如仅个人使用，不建议重复叠加 AgentMemory。

7. 通用 MCP 配置方式

对于任何 MCP 兼容客户端（Cursor、Gemini CLI、Codex CLI 等），在配置文件中的 mcpServers 部分添加：

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

8. MCP 工具详解

AgentMemory 通过 MCP 协议暴露 53 个工具，以下是核心工具分类：

8.1 记忆检索

工具 用途
memory_smart_search 主检索入口------BM25 + Vector + Graph 三流融合搜索
memory_recall 按关键词查询历史记忆，支持紧凑/叙事/完整三种输出格式
memory_sessions 列出和回放历史会话
memory_timeline 以某时间点/事件为锚点，展示前后记忆上下文
memory_context 获取当前会话的 top-N 相关记忆用于上下文注入

8.2 记忆管理

工具 用途
memory_save 显式保存一条记忆（通常不需要，hooks 自动完成）
memory_governance_delete 带审计日志的安全删除
memory_export 导出全部记忆为 JSON（备份/迁移）
memory_consolidate 手动触发 4 层记忆固化管道
memory_compress_file 压缩 Markdown 文件以减少 token 占用
memory_crystallize 将已完成的任务链压缩为晶体摘要

8.3 知识图谱

工具 用途
memory_graph_query BFS 遍历知识图谱，探索实体和关系
memory_relations 查询指定记忆的关系图
memory_patterns 检测跨会话的行为模式
memory_reflect 遍历知识图谱，聚类相关记忆并合成高阶洞见

8.4 多 Agent 协调

工具 用途
memory_lease 分布式租约/锁，防止多 Agent 冲突操作
memory_signal_send 向其他 Agent 发送带类型的消息（info/request/response/alert/handoff）
memory_signal_read 读取发给当前 Agent 的消息
memory_mesh_sync 多实例间同步记忆和任务
memory_team_share 向团队成员共享记忆
memory_team_feed 查看团队共享内容流

8.5 诊断与配置

工具 用途
memory_diagnose 全子系统健康检查（actions、leases、sentinels、sessions 等）
memory_heal 自动修复诊断发现的可修复问题
memory_audit 查看所有记忆操作的审计轨迹
memory_verify 追溯记忆的来源链和置信度
memory_profile 用户/项目画像（高频概念、文件模式）
memory_status 索引状态和健康概览
memory_claude_bridge_sync 与 Claude Code 原生 MEMORY.md 双向同步

8.6 任务与工作流

工具 用途
memory_action_create 创建带依赖类型的可执行工作项
memory_action_update 更新任务状态/优先级/结果
memory_frontier 获取无阻塞、按优先级排序的可执行任务边界
memory_next 返回最重要的下一项待办任务
memory_checkpoint 创建/解析外部检查点（CI 结果、审批、部署状态）
memory_sentinel_create 创建事件驱动哨兵，自动解除阻塞任务

9. 记忆生命周期------4 层固化管道

复制代码 
原始捕获（Raw Observations）
    │  12 个 Hooks 自动采集：工具调用、文件编辑、错误、决策
    ▼
Working Memory（工作记忆缓冲区）
    │  当前会话活跃状态的临时缓存
    ▼  ─── 每小时自动扫描
Episodic Memory（情景记忆）
    │  具体事件 + 涉及文件 + 时间线
    ▼  ─── LLM 压缩合并
Semantic Memory（语义记忆）
    │  概括性事实，如"项目使用 jose 做 JWT 鉴权"
    ▼  ─── 模式提取
Procedural Memory（程序性记忆）
    │  可复用的工作流与约定，如"发布前必须运行 npm run build"
    ▼
自动遗忘机制
    · Ebbinghaus 衰减曲线（基于使用频率）
    · TTL 过期（基于时间）
    · 矛盾检测（新旧知识冲突时自动标记）
    · 重要性驱逐（低置信度记忆自动逐出）

10. 自动捕获 Hooks

AgentMemory 通过在 AI 工具中注册 生命周期 Hooks 实现零手动记忆。Claude Code 插件自动注册 12 个 Hooks：

Hook 触发时机 捕获内容
SessionStart 会话启动 项目路径、会话 ID
UserPromptSubmit 用户提交提示 提示内容（隐私过滤后）
PreToolUse 工具调用前 文件访问模式、上下文
PostToolUse 工具调用后 工具名、输入、输出结果
PostToolUseFailure 工具调用失败 错误上下文
PreCompact 上下文压缩前 压缩前状态保存
Stop 用户停止 会话中断时的状态
SessionEnd 会话结束 生成会话摘要
Notification 通知事件 通知内容
TaskCompleted 任务完成 任务结果
Subagent 子 Agent 事件 子 Agent 行为
Filesystem-watcher 文件系统变更（v0.9.x 新增） 文件变化跟踪

其他工具支持：Codex CLI 提供 6 个 Hooks；OpenCode 提供 22 个 Hooks。

11. Skills------15 个原生技能

安装插件后可用以下指令：

11.1 操作类（8 个）

Skill 用途
/remember 显式保存当前上下文到记忆
/recall 按主题搜索历史记忆
/recap 回顾最近会话的摘要
/handoff 生成任务移交文档
/forget 安全删除指定记忆
/commit-context 查看某次 git commit 产生的 Agent 会话
/commit-history 查看 Agent 会话关联的提交历史
/session-history 浏览历史会话列表

11.2 参考类（7 个）

Skill 用途
agentmemory-mcp-tools MCP 工具参考
agentmemory-rest-api REST API 文档
agentmemory-config 配置指南
agentmemory-agents 多 Agent 协调指南
agentmemory-hooks Hooks 配置说明
agentmemory-architecture 架构文档
write-agentmemory-skill 自定义 Skill 编写指南

12. 三流检索架构

AgentMemory 的核心检索采用 BM25 + Vector + Graph 三流融合 + RRF（Reciprocal Rank Fusion） 重排序：

12.1 检索三流

流 技术 延迟 优势
关键词 BM25（FTS5） 0ms 精确术语匹配，强基线
语义 Vector Embedding（all-MiniLM-L6-v2） < 20ms 语义相似性
图谱 Knowledge Graph BFS 遍历 < 5ms 实体关系推理

12.2 知识图谱特性

  • 实体抽取：自动识别文件、函数、概念、决策等实体
  • 类型化评分连接：关系携带类型和相关性评分
  • 级联失效：某记忆被覆盖时，相关图谱节点/边自动标记为过时
  • 动态重连（Zettelkasten 风格）：新记忆触发相似度检查，自动链接现有记忆
  • PageRank 文件排序：基于调用关系计算文件重要性

12.3 检索基准

基准 指标 分数
LongMemEval-S（ICLR 2025，500 题） R@5 95.2%
R@10 98.6%
MRR 88.2%
coding-agent-life-v1（项目自建） R@5 1.000（完美召回）
P50 延迟 14ms

13. 竞品对比

维度 AgentMemory mem0 Letta/MemGPT CLAUDE.md
类型 记忆引擎 + MCP 服务器 记忆层 API 完整 Agent 运行时 静态文件
检索 R@5 95.2% 68.5% 83.2% N/A（grep）
自动捕获 12 个 Hooks，零手动 手动 add() Agent 自编辑 手动编辑
检索方式 BM25 + Vector + Graph（RRF） Vector + Graph Vector（归档） 全文加载
多 Agent 协调 MCP + REST + 租约 + 信号 无协调 API 仅 Letta 运行时 各自文件
外部依赖 零（SQLite + iii） Qdrant / pgvector Postgres + 向量库 无
Token 效率 ~1,900/会话 视集成而定 核心在上下文 22K+
记忆生命周期 4 层 + 衰减 + 自动遗忘 被动提取 Agent 管理 手动修剪
隐私过滤 自动剥离 Secrets 无 无 无
离线 ✅ ❌ ❌ ✅

14. Token 经济分析

方案 年度 Token 年度成本
全量上下文灌入 19.5M+ 不可用（超窗口限制）
LLM 摘要 ~650K ~$500
AgentMemory ~170K ~$10
AgentMemory + 本地嵌入 ~170K $0

节省约 92% 的 Token 开销。

15. 日常运维命令

命令 功能
agentmemory 启动记忆服务器（前台运行，:3111）
agentmemory demo 灌入测试数据
agentmemory stop 关闭服务
agentmemory doctor 交互式诊断与修复
agentmemory remove 完全卸载
agentmemory connect <agent> 一键接入指定 Agent
npx skills add rohitg00/agentmemory -y 安装 15 个原生 Skills

16. 故障排查

问题 解决方案
agentmemory 命令找不到 检查 npm 全局安装路径是否在 PATH 中；或使用 npx @agentmemory/agentmemory
iii --version 无响应 确认 %USERPROFILE%\.local\bin\iii.exe 存在且 PATH 已配置
Agent 未识别 MCP 工具 确认 npx -y @agentmemory/mcp 正在运行；检查 Agent 的 mcpServers 配置
记忆未自动存储 确认 AGENTMEMORY_AUTO_STORE=true 环境变量已设置并重启 Agent
上下文未注入 确认 AGENTMEMORY_INJECT_CONTEXT=true 环境变量已设置
Web 仪表盘无法访问 确认 agentmemory 服务器进程在运行；访问 http://localhost:3113
端口冲突 默认端口 :3111（API）和 :3113（Web）；检查是否被其他进程占用
国内 npm 安装慢 使用 --registry=https://registry.npmmirror.com 镜像

参考资源

相关推荐
meilindehuzi_a2 小时前
构建基于 RESTful 架构的 TodoList 全栈应用：从前后端理论到 TypeScript/Bun 实战
架构·typescript·restful
happyprince2 小时前
02_verl-代码目录结构详解
人工智能·架构·强化学习
沪漂阿龙2 小时前
LangChain 的整体架构：模型、工具、RAG、Agent、记忆、观测
架构·langchain
happyprince2 小时前
10_verl-Rollout模块详解
人工智能·架构·强化学习
G_whang2 小时前
Claude-Mem — 持久记忆压缩系统：安装、架构与深度使用指南
架构
黄焖鸡能干四碗2 小时前
软件系统概要设计说明书模版（Word）
大数据·运维·数据库·架构·需求分析
土星云SaturnCloud2 小时前
从云端到边缘：电子装配线AI视频分析在土星云SE110S-WA32上的落地实践
服务器·人工智能·ai·边缘计算
互联网推荐官3 小时前
上海AI Agent智能体开发公司技术选型实录：六条路径、三类架构与真实落地约束
java·人工智能·ai·架构·开发经验·上海
小丶舟3 小时前
Firma.Dev 企业级应用开发核心场景指南
人工智能·ai
热门推荐
01HTTP 与 HTTPS 的区别：从原理到实战详解022026 AI 编程工具终极实战指南：Cursor vs Claude Code vs Copilot，开发者该怎么选？03【AI】2026 年具身智能模型和世界模型总结042026年6月AI行业全景：从百模大战到Agent元年，这30天发生了什么？05AI科技热点日报 | 2026年6月1日06《置身钉内》原文-可播放阅读07GitHub 镜像站点08Claude Code、Codex、Cursor三分天下：2026年AI编程Agent生态全景剖析092026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf10AI一周事件 · 2026-06-03 至 2026-06-09