前言：你有没有被AI Agent的"金鱼记忆"气到过？

说个扎心的场景：你花了一个小时教 Claude Code 你的项目架构、技术栈偏好、代码规范，它表现得像个项目老手。结果第二天开新会话，它又变成了一张白纸，问你"这个项目用的什么框架？"

每次重新解释，每次重新踩坑。你心里想的是：这玩意儿怎么就不长记性呢？

其实这不是模型的问题，而是会话隔离的天然限制——每个新会话都从零开始，上一轮的上下文全部清空。CLAUDE.md、.cursorrules 这些本地规则文件能缓解一部分，但200行的容量上限、维护成本高、跨工具不互通，始终是硬伤。

今天介绍一个GitHub本周爆火的项目：agentmemory，15000+ Star，专门解决这个问题。它给AI编程Agent装上了"永久记忆"，让Agent跨会话记住你的项目上下文、技术偏好、踩过的坑。

agentmemory 是什么？一句话说清楚

agentmemory 是一个持久化记忆服务器，通过 MCP 协议或 REST API 给各种 AI 编程 Agent 提供跨会话的记忆能力。

它的工作原理很简单：

1. Agent 在会话中产生的关键信息（架构决策、代码规范、bug记录等）会被自动捕获
2. 经过压缩和索引后存入本地数据库
3. 下次新会话启动时，agentmemory 自动注入相关上下文

打个比方：以前的AI Agent像每天失忆的实习生，你得反复教。装上agentmemory之后，它变成了有工作笔记的老员工——上次聊过什么、做过什么决定、踩过什么坑，它都记得。

环境准备

系统要求

项目	要求
Node.js	>= 18.0（推荐 20 LTS）
npm	>= 9.0
操作系统	Windows / macOS / Linux 均可
磁盘空间	约 200MB（含依赖）

检查环境

打开终端，确认 Node.js 版本：

node --version
# 输出类似 v20.11.0 即可

npm --version
# 输出类似 10.2.0 即可

如果还没装 Node.js，去 https://nodejs.org 下载 LTS 版本安装就行，一路 Next 不用改配置。

安装与启动（3步搞定）

第一步：全局安装

npm install -g @agentmemory/agentmemory

macOS/Linux 如果遇到 EACCES 权限报错，加 sudo 重试：

sudo npm install -g @agentmemory/agentmemory

第二步：启动记忆服务器

agentmemory

默认监听 3111 端口，看到类似这样的输出就说明启动成功了：

🧠 agentmemory server running on http://localhost:3111
📊 Dashboard: http://localhost:3111/viewer

第三步：跑一下 demo 验证安装

新开一个终端窗口：

agentmemory demo

这个命令会往记忆库里灌一些示例数据，然后演示召回效果。如果你看到类似 “Recalled 5/5 memories” 的输出，说明一切正常。

实战：接入你的 AI 编程工具

agentmemory 支持几乎所有主流 AI 编程工具。下面挑几个最常用的讲讲怎么接。

接入 Claude Code

这是最简单的，一行命令搞定：

agentmemory connect claude-code

它会自动修改 Claude Code 的 MCP 配置，把 agentmemory 作为 MCP Server 注册进去。重启 Claude Code 后生效。

验证方式：在 Claude Code 里问它"你还记得我们上次讨论的项目架构吗？"——如果它能回忆起来，就说明接入成功了。

接入 Cursor

Cursor 走的是标准 MCP 协议。手动配置方法：

1. 打开 Cursor Settings → MCP Servers
2. 添加一个新的 MCP Server，配置如下：

{
  "mcpServers": {
    "agentmemory": {
      "url": "http://localhost:3111/mcp"
    }
  }
}

3. 保存后重启 Cursor

接入 Gemini CLI

# 编辑 Gemini CLI 配置文件
# 通常在 ~/.gemini/settings.json

在配置中添加 MCP server 地址 http://localhost:3111/mcp 即可。

通过 REST API 接入（通用方案）

如果你用的工具不支持 MCP，还可以直接调 REST API：

# 存储一条记忆
curl -X POST http://localhost:3111/api/memories \
  -H "Content-Type: application/json" \
  -d '{
    "content": "项目使用 Next.js 14 + TypeScript + Tailwind CSS",
    "type": "architecture",
    "importance": 0.9
  }'

# 搜索记忆
curl "http://localhost:3111/api/memories/search?q=技术栈&limit=5"

核心功能深度体验

1. 自动记忆捕获

接入之后你不需要手动做任何事。Agent 在会话中的关键操作（比如选择了某个库、做了架构决策、修了一个诡异的bug）会被自动捕获并存入记忆库。

# 查看当前记忆库中的所有记忆
agentmemory list

# 按类型过滤
agentmemory list --type architecture
agentmemory list --type bug_fix

2. 混合搜索（Hybrid Search）

agentmemory 的搜索不是简单的关键词匹配，而是语义搜索 + 关键词搜索的混合方案。官方 benchmark 显示，precision@5 达到 0.578，比纯 grep 方案好 2.2 倍。

# 搜索与"认证"相关的记忆
agentmemory search "JWT认证中间件"

# 限制返回数量
agentmemory search "数据库设计" --limit 3

3. 记忆置信度评分

每条记忆都有一个 confidence 分数，基于出现频率和时间衰减计算。经常被引用的记忆分数高，很久没用到的会自动降权。

4. 实时查看器

浏览器打开 http://localhost:3111/viewer，可以看到一个可视化的记忆管理面板：

• 查看所有记忆条目
• 按类型、时间、置信度筛选
• 手动编辑或删除记忆
• 查看知识图谱关系

5. 跨工具共享

这是最爽的一点——你在 Claude Code 里积累的记忆，Cursor 和 Gemini CLI 也能用。因为它们连的是同一个记忆服务器。

Claude Code ──┐
              ├──→ agentmemory server (localhost:3111)
Cursor ───────┤
              ├──→ 同一份记忆库
Gemini CLI ───┘

常见问题 Q&A

Q1: agentmemory 会上传我的代码到云端吗？

不会。 所有数据都存在本地，agentmemory 服务器跑在你自己的机器上，不联网、不上传。对代码安全有要求的团队可以放心用。

Q2: 记忆数据存在哪里？占用多大空间？

默认存在 ~/.agentmemory/ 目录下，使用 SQLite 存储。一般项目跑几个月下来，数据量在几十MB左右，不会占用太多磁盘。

Q3: 我不想让某些对话被记住怎么办？

可以在配置中设置排除规则，或者在特定会话中临时禁用记忆捕获：

# 临时禁用
agentmemory pause

# 恢复
agentmemory resume

Q4: 和 CLAUDE.md / .cursorrules 有什么区别？

对比项	CLAUDE.md	agentmemory
容量	~200行上限	无限制
更新方式	手动维护	自动捕获
跨工具	不互通	全部共享
搜索能力	无	语义+关键词混合搜索
知识图谱	无	自动构建

简单说，CLAUDE.md 是"静态规则"，agentmemory 是"动态记忆"。两者可以共存，不冲突。

Q5: 支持团队协作吗？

目前版本（v0.9.x）主要面向个人开发者。团队共享记忆功能在 roadmap 中，预计后续版本支持。

进阶配置

修改端口

默认端口 3111 如果被占用，可以指定其他端口：

agentmemory --port 3200

记得同步修改 MCP 配置中的 URL。

配置自动清理策略

记忆太多也不好，会稀释搜索精度。可以配置自动清理：

{
  "retention": {
    "maxMemories": 10000,
    "pruneBelowConfidence": 0.1,
    "pruneOlderThanDays": 90
  }
}

接入文件系统监控

v0.9.0 新增了 filesystem connector，可以监控代码文件变更并自动生成记忆：

npm install -g @agentmemory/fs-watcher
agentmemory watch ./src

总结

agentmemory 解决的是AI编程工具的一个底层痛点——会话间记忆断裂。装上之后最直观的感受就是：开新会话不用再重复解释项目背景了，Agent 自己就知道。

几个关键信息回顾：

• 安装：npm install 一行搞定
• 接入：agentmemory connect 一行配置
• 数据安全：全部本地存储，不上传云端
• 跨工具：Claude Code / Cursor / Gemini CLI 共享同一份记忆

下一步建议：

1. 先跑通 demo，体验一下记忆召回的效果
2. 接入你最常用的编程工具，用一周看看差异
3. 关注项目 GitHub 的 changelog，v1.0 正式版值得期待

项目地址：https://github.com/rohitg00/agentmemory

如果这篇文章对你有帮助，点个赞收藏一下，后续会出更多 AI 编程工具的实战教程。