agentmemory + Claude Code：一段可直接粘贴的完整插件安装教程

【免费下载链接】agentmemory #1 Persistent memory for AI coding agents based on real-world benchmarks 项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory

agentmemory 是一款为 AI 编码智能体打造的持久记忆层，本教程带你用一条命令 + 两条斜杠命令，把它完整装进 Claude Code：自动捕获每次工具调用、压缩成可搜索的记忆，并在下个会话开始时自动注入上下文。全程无需配置 MCP，无需手写任何 JSON，装完即用。

为什么你的 Claude Code 需要 agentmemory

用 Claude Code 的人大概都有这个体验：每次开新会话都要重新解释项目架构、重新说一遍技术选型、重新描述刚踩过的坑。内置的 CLAUDE.md 只能当"便利贴"用——容量有限，而且很快过时。

agentmemory 解决的就是这个问题：

痛点	agentmemory 的做法
每次会话重复解释上下文	会话开始时自动注入最相关的记忆
踩过的坑反复踩	工具调用、报错、修复方案自动入库
上下文越贴越长，Token 爆炸	压缩后约 1900 tokens/会话，比全文粘贴省 92%
记忆散落在多个智能体中	一个记忆服务器，Claude Code、Cursor、Codex 共享

官方基准测试中，agentmemory 的混合检索在 LongMemEval-S 数据集上达到 95.2% 的 R@5 命中率，详见 benchmark/LONGMEMEVAL.md。

第一步：一条命令启动记忆服务器

在终端中运行（需要 Node.js 20+）：

npx @agentmemory/agentmemory

首次运行会进入交互式引导：选择要接入的智能体（勾选 Claude Code）、选择 LLM 提供商（也可以完全不用 API key，本地嵌入模型免费可用）。完成后它会自动：

• ✅ 在 ~/.claude.json 中写好 MCP 配置（写之前自动备份原文件）
• ✅ 在 3111 端口启动记忆服务器
• ✅ 询问是否全局安装，让 agentmemory 命令随处可用

💡 修改 ~/.claude.json 的逻辑在 src/cli/connect/claude-code.ts，它对已有配置是合并写入而非覆盖，你原有的 MCP 服务器不会被清掉。

第二步：在 Claude Code 里粘贴两条命令

打开 Claude Code，直接粘贴以下两行（这就是标题说的"一段可直接粘贴"）：

/plugin marketplace add rohitg00/agentmemory
/plugin install agentmemory

安装完成后，插件会自动注册三样东西（定义见 plugin/plugin.json）：

注册内容	数量	作用
生命周期 Hooks	12 个	在会话开始、工具调用前后、会话结束等节点自动捕获记忆
MCP 工具	54 个	如 memory_smart_search、memory_save、memory_sessions 等
原生 Skills	17 个	/remember、/recall、/recap 等斜杠命令

12 个钩子的完整清单在 plugin/hooks/hooks.json，覆盖了 SessionStart、PreToolUse、PostToolUse、Stop、SessionEnd 等全部关键时机——你不需要理解它们，装完就自动生效。

第三步：三个动作验证安装成功

1. 健康检查 —— 在终端运行：

curl http://localhost:3111/agentmemory/health

2. 确认 MCP 服务器 —— 在 Claude Code 会话中运行 /mcp，应能看到 agentmemory 处于连接状态。

3. 打开实时查看器 —— 浏览器访问 http://localhost:3113，可以看到记忆实时构建的过程：

查看器里还有一个 Replay 标签页，可以像放视频一样回放任意历史会话的完整时间线（提示词、工具调用、结果），支持 0.5x–4x 变速和键盘快捷键。

装好后怎么用：日常斜杠命令

装完不需要改变任何工作习惯——钩子会静默捕获。主动使用的场景，记住这几个就够了：

命令	用途
/remember <内容>	手动存入一条记忆
/recall <关键词>	语义检索记忆，比如"上次那个 N+1 查询怎么修的"
/recap	生成当前会话摘要
/handoff	生成交接文档，方便换智能体或换人接手
/forget <关键词>	删除相关记忆
/commit-context	结合 Git 提交生成上下文说明

这些技能定义在 plugin/skills/ 目录下，每个技能都有 SKILL.md 说明。

常见问题排查

Q：安装后 Claude Code 没反应？ 重启 Claude Code，或直接在会话里运行 /mcp 手动加载。

Q：npx 装的不是最新版？ npx 会按版本缓存，用 npx -y @agentmemory/agentmemory@latest 强制最新版。

Q：npm 全局安装报 EACCES？ 在 macOS/Linux 系统自带的 Node 上需要加 sudo。

Q：想把旧的 Claude Code 会话历史也导入？

npx @agentmemory/agentmemory import-jsonl

⚠️ 注意：Claude Code 默认 cleanupPeriodDays 为 30，超过 30 天的 JSONL 转录已被自动清理，无法回溯导入。建议尽早安装，让钩子在会话进行时实时捕获。

Q：怎么卸载？

agentmemory remove

一条命令清掉它创建的所有配置。

幕后：记忆是怎么工作的

装好之后发生的事，可以简单理解为一条流水线：

工具调用 → 去重 + 隐私过滤（自动剥离 API key）→ 存原始观察
→ LLM 压缩成结构化事实 → 向量化 + BM25 双路索引

会话结束 → 生成会话摘要 → 抽取知识图谱

新会话开始 → 混合检索（BM25 + 向量 + 图谱）→ 按 2000 token 预算注入上下文

这套设计模仿了人类大脑的记忆分层：工作记忆、情景记忆、语义记忆、程序记忆四层，配合遗忘曲线做自动衰减。所有记忆本地存储，零外部数据库依赖。

写在最后

回顾一下完整流程，一共只有三步：

1. 终端：npx @agentmemory/agentmemory
2. Claude Code：/plugin marketplace add rohitg00/agentmemory + /plugin install agentmemory
3. 验证：curl http://localhost:3111/agentmemory/health

之后，你的 Claude Code 就真的"记得住"了。更多细节可以看项目主文档 README.md，或跑一下 agentmemory doctor 进行交互式体检。

【免费下载链接】agentmemory #1 Persistent memory for AI coding agents based on real-world benchmarks 项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory