给你的AI Agent装上"行为记忆"：agentmemory安装到整合全指南

你正在用的AI编程助手确实很聪明，但有个致命弱点——它是个“一次性天才”。

你跟它交代清楚：“这个项目用PostgreSQL，不是MySQL。”它点头说明白了。第二天开了个新会话，换一个问题，这家伙又一脸认真地建议你装MySQL。什么感觉？血压上来了对吧。

这真不是模型的问题。换成GPT-5、Claude Sonar 4，情况都一样。根子在AI Agent的原生架构上——它是“无状态”的，每次对话一结束，记忆就清零了。它没有真正的“情节记忆”（episodic memory），它根本不记得你们俩之间发生过什么故事。

今天要聊的agentmemory，就是专门来解决这个痛点的——给AI Agent装上“行为记忆”。它像一个安静的书记员，默默记录下Agent读过的文件、执行过的命令、做过的决策、踩进去的坑。下次你再开一个新会话，它自己就把相关的历史记录注入到上下文里了。不需要你从头到尾再讲一遍，它是真的“记得”了。

效果如何？在LongMemEval-S这个包含500道记忆题的基准测试里，agentmemory的检索召回率R@5达到了95.2%。而且它极省资源——相比全上下文方案，能节省大约92%的token。关键是，它完全开源（Apache 2.0协议），可以本地部署，零外部依赖。这一点对于很多有数据安全要求的团队来说，至关重要。

接下来的内容，我们就一步步把它跑起来。

第一步：安装agentmemory

安装非常简单，一行命令搞定。前提是你的环境里已经装了Node.js（v18以上版本）。

# --registry参数主要是为了方便国内网络拉取
npm install -g @agentmemory/agentmemory --registry=https://registry.npmmirror.com

安装完之后，直接启动：

# 首次是在前台启动的
agentmemory

第一次启动的时候，agentmemory会自动下载一个叫iii-engine的核心引擎。之后的运行就会在后台持续进行。

启动之后，终端里会有提示让你去设置LLM、Embedding、组件这些东西。这块后面会讲，你也可以直接去修改 ~/.agentmemory/.env 这个配置文件。

怎么验证它是不是正常工作？跑个健康检查：

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

如果返回{"status":"healthy"}，那就一切正常。

agentmemory启动后，会占用四个端口：3111（REST API）、3112（stream）、3113（实时监控面板）、49134（engine）。打开你的浏览器，访问http://localhost:3113，你能看到实时记忆捕获面板——Agent每新记下一段记忆，面板上都会实时弹出来。

如果你想让agentmemory开机自启，macOS用户可以通过配置launchd来实现。agentmemory会在第一次启动时尝试自动配置launchd，如果没配好，可以让Hermes等Agent帮你搞定。手动检查的方法：

launchctl list | grep agentmemory

第二步：配置LLM和Embedding（以阿里云DashScope为例）

agentmemory其实挺灵活的，它即使不配任何API Key也能跑。它有一个“NOOP模式”，纯靠BM25（一种关键词匹配算法）来做检索，日常基本够用。但如果你想解锁那些高级能力，比如LLM压缩总结、智能反思、向量语义搜索，那就必须要配置LLM和Embedding了。

配置文件在~/.agentmemory/.env。我们以阿里云的灵积（DashScope）为例：

# ===== LLM 配置 =====
# agentmemory用LLM来压缩观察记录、生成摘要、提取概念
OPENAI_API_KEY=sk-你的DashScope_API_Key
OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
OPENAI_MODEL=qwen3.5-flash # 性价比比较高，你也可以根据需求调整

# ===== Embedding 配置 =====
# agentmemory用Embedding来做向量语义搜索
EMBEDDING_PROVIDER=openai
OPENAI_EMBEDDING_MODEL=text-embedding-v4 
OPENAI_EMBEDDING_DIMENSIONS=1024 # 推荐这个维度，你可以根据情况调整。维度越高，理论上召回效果越好，但占用存储也越多。

这里有个细节：虽然配置项叫OPENAI_API_KEY，但agentmemory并不局限于OpenAI。它用的是OpenAI兼容协议，任何兼容这个协议的服务都可以接入。DashScope的API完全兼容OpenAI协议，所以我们只需要把OPENAI_BASE_URL指向它的兼容端点就行。同样的逻辑，可以套用到DeepSeek、硅基流动、你自己本地的Ollama等等。agentmemory也支持Claude等主流模型。

Embedding模型我们这里选的是text-embedding-v4，这是阿里云最新的版本，输出1024维向量，中文语义理解表现相当不错。如果你用的是其他厂商的服务，记得改成对应的模型名。比如如果用的是OpenAI的text-embedding-3-small，那就得改成1536维。

配置完成后，重启agentmemory：

agentmemory stop
agentmemory

然后用agentmemory status确认一下状态。你会看到Provider和Embedding都已经打上勾了。

LLM和Embedding各做什么？

它们俩的分工完全不同。

每当Agent完成一组操作，比如改了几个文件、跑了个测试，agentmemory的post_tool_use钩子会立刻捕获这些信息。这时候，LLM就出场了，它主要做三件事：

1. 压缩总结
   ：把可能几千个token的工具输出，压成几十个token的结构化事实。比如“用户把src/db/config.ts中的数据库连接从MySQL改成了PostgreSQL”。

2. 概念提取
   ：从描述中抽取关键概念，比如PostgreSQL、config.ts、数据库迁移，这些是构建知识图谱的基础。

3. 反思整合
   ：它会定期扫描多条记忆，从中提炼出更高层次的洞察和可复用的经验教训。

LLM处理完的文字保存下来了，但问题来了：怎么在几十上百条记忆里，快速找到“跟数据库连接相关”的那几条？这里就是Embedding的主场。它把每段文字转成向量（一串数字），语义相近的文字，在向量空间里的距离就更近。你搜索“数据库连接”，即使记忆里写的是“PostgreSQL connection”，向量距离也能把它们匹配上。

上面这张图直观地展示了agentmemory中LLM和Embedding是如何协同工作的。

如果你没配Embedding，agentmemory会自动切换到BM25-only模式（纯关键词匹配），日常用也够，但在中文语义检索上精度会打折扣。有条件的话，还是建议配上商用Embedding模型。

agentmemory的四个Flags：按需开启的能力开关

agentmemory有几个功能开关（Flags），默认有些开有些关。搞明白每个Flag是干什么的、什么时候该开、什么时候该关，能让你的记忆引擎更精准地适配自己的使用场景。

这些配置都在~/.agentmemory/.env里：

# 四个功能开关：
GRAPH_EXTRACTION_ENABLED=false
CONSOLIDATION_ENABLED=true
AGENTMEMORY_AUTO_COMPRESS=true
AGENTMEMORY_INJECT_CONTEXT=true

我们来逐个拆解：

agentmemory不仅能存文字记忆，还能从这些记忆中自动抽取实体和关系，构建成一张知识图谱。比如从“用户把MySQL换成了PostgreSQL，修改了src/db/config.ts”这条记忆里，抽取出的图谱节点会包括“MySQL”、“PostgreSQL”、“src/db/config.ts”，而边则是“替换关系”、“文件路径”。

开启这个功能后，memory_graph_query工具就可以直接在知识图谱里遍历了——“找出所有跟PostgreSQL相关的实体，以及它们之间的关联”。

默认关闭的原因很简单：这个功能比较消耗LLM。每条记忆都要做一次实体和关系的抽取。如果你的记忆库不大，就几百条，或者你想省点API费用，保持关闭即可。当记忆量上千条以后，开着它就能大幅提升跨主题的关联检索能力。

这是agentmemory的4层记忆整理管道（consolidation pipeline）：

• 工作记忆：Agent刚干的事（“刚才改了config.ts第15行”）。
• 情景记忆：这次会话发生了什么（“今天把数据库从MySQL迁到了PostgreSQL”）。
• 语义记忆：跨会话提炼出的稳定知识（“这个项目用PostgreSQL，配置文件在src/config”）。
• 程序性记忆：可复用的操作流程（“数据库迁移的标准步骤是：备份→改配置→跑migration→验证”）。

这个功能默认是开启的。如果你的使用场景是短期、高频、不需要跨会话积累知识的（比如只是做一次性的代码审查），可以关掉它来省token。

这个Flag控制agentmemory在捕获Agent的操作后，是否调用LLM来做压缩。开启时，原始的工具输出（可能有几千个token）会被LLM压缩成几十个token的结构化事实。关闭时则跳过LLM调用，直接保存原始摘要。

默认是开启的。当然，如果你没配LLM API Key（也就是处于NOOP模式），这个Flag会自动失效，agentmemory只用BM25做基础检索。

这可以说是agentmemory的核心黑魔法。开启后，Hermes的prefetch()钩子会在每轮LLM调用之前，自动从agentmemory里检索与当前对话相关的历史记忆，然后直接注入到系统提示词里。整个过程，对用户来说是完全无感的——你不需要手动让Agent去“查一下之前的事”，记忆已经在上下文里了。

如果你关掉这个Flag，agentmemory仍然会在后台默默保存记忆，但不会主动注入。Agent只能通过手动调用MCP工具（比如memory_smart_search）来查询历史。

绝大多数场景，保持默认开启就可以了。唯一可能需要关闭的情况，是你发现注入的上下文反而干扰了Agent的当前推理（这种情况很少见，通常是记忆库里积攒了大量无关内容）。

四个Flag的组合建议，可以参考这张表格：

场景	GRAPH	CONSOLIDATION	AUTO_COMPRESS	INJECT_CONTEXT
初次试用、节省费用	关	开	开	开
日常开发（推荐）	开	开	开	开
一次性任务（代码审查等）	关	关	开	关
记忆库上千条后	开	开	开	开

核心用法：memory、lesson和action

agentmemory提供了43个MCP工具（最新的版本已经扩展到53个了），但日常最核心的，其实就三类：

这是最常用的。每发现一个值得记住的事情，就存一条：

# 记录项目约定
内容："项目使用pytest -n 4做并行测试，配置文件在tests/conftest.py"
类型：fact

# 记录踩过的坑
内容："macOS上brew安装的postgresql@16默认端口5432，但brew services start后需等5秒才能连接"
类型：pattern

每一条记忆在存储时，会自动标记时间戳、关联文件路径，并提取关键概念，方便后续检索。

这里的“lesson”不限于真正的“教训”，它更像是一套带置信度评分的经验体系。同样的lesson如果被多次“reinforce”，它的置信度就会提升，而长期不用则会衰减——这意味着它会自动帮你淘汰过时的知识，非常智能。

# 存一条环境经验
内容："DashScope的text-embedding-v4模型输出1024维，base_url必须加/compatible-mode/v1后缀"
置信度：0.7

根据仙踪问道团队的实际体验，把工作流程类的知识用lesson存下来，效果比用普通memory好很多。原因就是lesson天然有“不用就衰减”的淘汰机制，能让记忆库不会越积越臃肿。

这个不止是简单的待办列表。action系统支持依赖关系、租约锁、检查点——这些特性是为多Agent协作设计的。

# 创建一个有依赖的任务
memory_action_create:
  title: "给hermes配置agentmemory MCP连接"
  requires: "先完成agentmemory启动验证"  # 前置依赖
  priority: 8

配合memory_lease（用来锁住任务，防止多个Agent抢同一个任务）和memory_checkpoint（作为外部审批关卡），就可以做复杂的多Agent协同工作流了。

在检索方面，memory_smart_search是日常的主要入口——它混合了BM25关键词、向量语义和图遍历三种检索方式，最后把结果加权融合后排序，保证了召回的精准度。

与Hermes等Agent的结合：两层接入方式

好了，现在我们来把agentmemory接到Hermes上。这里有两个步骤，你可以按需选择。其他类型的Agent如何接入，可以参考agentmemory官网的指引。

这是最简单的方法。在Hermes的~/.hermes/config.yaml中加上下面这段配置：

mcp_servers:
  agentmemory:
    command: npx
    args: ["-y", "@agentmemory/mcp"]

memory:
  provider: agentmemory

你也可以用Hermes的原生命令来添加：

hermes mcp add agentmemory --command "npx -y @agentmemory/mcp"
hermes config set memory.provider agentmemory

重启Hermes之后，所有43个MCP工具（比如memory_sa ve、memory_lesson_sa ve、memory_smart_search等）会自动注册到Hermes的工具列表里。在对话中，你直接对Hermes说“查一下PostgreSQL迁移那次是怎么搞的”，它就会调用agentmemory进行检索并返回精准答案。

如果你想让agentmemory深度嵌入到Hermes的Agent循环里——不是被动等待工具调用，而是在每个关键节点自动介入——那就用Plugin方式。当然，前提是先完成步骤一的配置。

1. 先把插件文件从agentmemory仓库拷贝过来：

# 把agentmemory源码中的integrations/hermes目录拷贝到Hermes的plugins下
# 具体文件路径可以看：https://github.com/rohitg00/agentmemory/blob/main/integrations/hermes/README.md
cp -r agentmemory/integrations/hermes ~/.hermes/plugins/agentmemory

2. 确保agentmemory server正在运行。
3. 重启Hermes。

Plugin方式和MCP方式的关键区别在于，它多了

（lifecycle hooks）。这些钩子嵌入了Hermes Agent循环的各个阶段：

这六个钩子各有各的职责：

钩子	触发时机	作用
prefetch()	每轮LLM调用前	从记忆库预加载与当前上下文相关的历史记忆，注入到系统提示词中
sync_turn()	每轮工具调用后	捕获本轮Agent的操作（比如读了哪些文件、执行了哪些命令），自动写入观察记录
on_session_end()	会话结束时	对整个会话做最终化处理——包括压缩、总结、提取关键决策
on_pre_compress()	上下文压缩前	在Hermes触发上下文压缩之前，先把重要的记忆持久化，避免压缩过程中丢失信息
on_memory_write()	任何写入记忆的操作后	将新记忆镜像写入MEMORY.md文件，保持Hermes原生记忆和agentmemory的同步
system_prompt_block()	构建系统提示词时	向Hermes的系统提示词中注入“你有持久化记忆，可通过MCP工具查询”的指令块

简单总结一下：

。两者的关系，就像是“被动查询”和“主动推送”。

例如prefetch()这个钩子，它在Hermes调用LLM之前，会先根据当前的对话内容去agentmemory里检索相关的历史记忆，然后把类似“你之前在这个项目里用的是PostgreSQL，配置文件在src/config”这样的上下文片段注入到系统提示词里。整个过程对用户是透明的——你不需要手动让Hermes去查记忆，它已经在上下文里了。

on_memory_write()这个钩子也很实用。它把agentmemory的结构化记忆同步写入Hermes原生的MEMORY.md文件，确保两边保持一致。这样一来，即使你哪天不用agentmemory了，MEMORY.md里的内容也不会丢失。

---

避坑提示

最后，分享三个比较容易卡住的地方：

1. 端口冲突
   ：agentmemory默认会占用3111（REST）、3112（stream）、3113（viewer）、49134（engine）这四个端口。如果被其他服务占用了，可以用--port参数整体偏移，比如agentmemory --port 3211。然后记得同步更新AGENTMEMORY_URL这个环境变量。

2. 没有LLM时的能力边界
   ：即使不配LLM和Embedding，agentmemory也能跑起来，搜索也基本能用（靠BM25加上本地小模型）。但代价是没有了压缩总结、智能反思、知识图谱抽取这些高级功能。如果想先试试看，可以跳过配置步骤直接体验；但在正式使用中，还是建议配上的。

3. memory.provider设定后，Hermes可能仍用原生memory
   ：如果不放心，可以检查一下hermes memory status，确认provider确实已经切换到了agentmemory。如果显示的还是其他provider，很可能是~/.hermes/config.yaml中存在冲突设置，或者plugin文件的拷贝路径不对。

AI Agent正在从“一次性工具”演进为“长期协作伙伴”。记忆是这个进化过程中最关键的一块拼图——没有记忆的AI，就是一个永远第一天上班的新人；有记忆的AI，才像一个真正了解你、懂得项目历史的老搭档。

agentmemory给Agent装上了真正的“情节记忆”，而且是本地化、零成本、开箱即用的方案。花15分钟把它装好，你的AI助手，就从一个金鱼，变成了一头大象。