不知道你有没有这种感觉——你用的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引擎，之后会在后台持续运行。
agentmemory启动之后根据提示进行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 #推荐1024，也可以试自身情况调整维度。维度越高理论上查找效果越好，但是占用存储也越多
注意，这里虽然写的是OPENAI_API_KEY，但它不限于OpenAI——agentmemory用的是OpenAI兼容协议，任何兼容的服务都可以。DashScope的API完全兼容OpenAI协议，所以把OPENAI_BASE_URL指向DashScope的兼容端点就行。同样的逻辑适用于DeepSeek、硅基流动、本地Ollama等。同样agentmemory也支持Claude等主流模型。
Embedding模型text-embedding-v4是阿里云最新的，输出1024维向量，中文语义理解表现很好。如果用的其他服务商，改成对应模型名（如OpenAI的text-embedding-3-small是1536维）。
配置完成后重启：
agentmemory stop agentmemory
然后用agentmemory status确认状态：Provider和Embedding都打上了的✓。
LLM和Embedding各做什么？
两个东西分工不同：
LLM负责"理解"
当Agent完成一组操作后（比如改了三个文件、跑了测试），agentmemory的post_tool_use钩子会自动捕获。LLM出场做三件事：
- 压缩总结：把几千token的工具输出压成几十token的结构化事实。比如"用户把src/db/config.ts中的数据库连接从MySQL改为PostgreSQL"
- 概念提取：从描述中抽取关键概念（PostgreSQL、config.ts、数据库迁移），用于构建知识图谱
- 反思整合：定期扫描多条记忆，提炼出更高层次的insight和可复用的lessons
Embedding负责"找"
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
逐个解释：
1. GRAPH_EXTRACTION_ENABLED — 知识图谱抽取
agentmemory不仅能存文字记忆，还能从记忆中自动抽取实体和关系，构建一张知识图谱。比如从"用户把MySQL换成了PostgreSQL，修改了src/db/config.ts"这条记忆中，抽取出的图谱节点包括"MySQL""PostgreSQL""src/db/config.ts"，边是"替换关系""文件路径"。
开启后，memory_graph_query工具可以直接在图中遍历——"找出所有跟PostgreSQL相关的实体，以及它们之间的关联"。
默认关闭的原因是这个功能比较消耗LLM调用量（每条记忆都要做一次实体+关系抽取）。如果你的记忆库不大（几百条以内），或者想省API费用，保持关闭即可。记忆量上千条以后，开着能大幅提升跨主题的关联检索能力。
2. CONSOLIDATION_ENABLED — 记忆整理(建议开启)
这是agentmemory的4层记忆整理管道（consolidation pipeline）：
- 工作记忆：Agent刚干的事（"刚才改了config.ts第15行"）
- 情景记忆：这次会话发生了什么（"今天把数据库从MySQL迁到了PostgreSQL"）
- 语义记忆：跨会话提炼出的稳定知识（"这个项目用PostgreSQL，配置文件在src/config"）
- 程序性记忆：可复用操作流程（"数据库迁移的标准步骤是：备份→改配置→跑migration→验证"）
默认开启。如果你的使用场景是短期、高频、不需要跨会话积累知识（比如一次性代码审查），可以关掉省token。
3. AGENTMEMORY_AUTO_COMPRESS — LLM压缩观察记录（建议开启）
这个Flag控制agentmemory在捕获Agent操作后是否调用LLM做压缩。开启时，原始工具输出（可能几千token）被LLM压缩成几十token的结构化事实。关闭时跳过LLM调用，直接存原始摘要。
默认开启。如果你没配LLM API Key（NOOP模式），这个Flag自动失效，agentmemory只用BM25做基础检索。
4. AGENTMEMORY_INJECT_CONTEXT — 上下文自动注入
这是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个），日常最核心的就三类：
1. memory_save — 记一条事实/经验
这是最常用的。每发现一个值得记住的事情就存一条：
# 记录项目约定 内容："项目使用pytest -n 4做并行测试，配置文件在tests/conftest.py" 类型：fact # 记录踩过的坑 内容："macOS上brew安装的postgresql@16默认端口5432， 但brew services start后需等5秒才能连接" 类型：pattern
每条记忆存储时自动标记时间戳、关联文件路径、提取关键概念，方便后续检索。
2. memory_lesson_save — 记一个可复用的教训
lesson不限于"教训"，它更像一套带置信度评分的经验体系。同样的lesson被多次reinforce时置信度提升，长期不用则衰减——这意味着它会自动帮你淘汰过时知识：
# 存一条环境经验 内容："DashScope的text-embedding-v4模型输出1024维， base_url必须加/compatible-mode/v1后缀" 置信度：0.7
仙踪问道团队的实际体验是：把工作流程类知识用lesson存下来比用普通memory效果好很多——因为lesson天然有"不用就衰减"的淘汰机制，记忆库不会越积越臃肿。
3. memory_action_create — 创建待办工作项
这不止是todo list。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的官网指引。
步骤一：MCP Server接入（30秒搞定）
这是最简单的。在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_save、memory_lesson_save、memory_smart_search等）自动注册到Hermes的工具列表中。在对话中直接对Hermes说"查一下PostgreSQL迁移那次是怎么搞的"，它会调agentmemory检索并返回精准答案。
步骤二：Plugin深度集成（推荐）
如果你想让agentmemory深度嵌入Hermes的Agent循环——不是被动等工具调用，而是在每个关键节点自动介入——用Plugin方式（先完成步骤一）。
- 从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
- 确保agentmemory server在运行。
- 重启Hermes。
Plugin方式的关键区别是它多了6个生命周期钩子（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工具查询"的指令块 |
简单说，MCP方式让Hermes"可以问"agentmemory；Plugin方式让agentmemory"主动告诉"Hermes。
比如prefetch()钩子，它在Hermes调用LLM之前，先根据当前对话内容去agentmemory里检索相关历史记忆，然后把"你之前在这个项目里用的是PostgreSQL，配置文件在src/config"这样的上下文片段注入到系统提示词里。整个过程对用户透明——你不需要手动让Hermes去查记忆，它已经在上下文里了。
on_memory_write()也很实用——它把agentmemory的结构化记忆同步写入Hermes原生的MEMORY.md文件，保持两边一致。这样即使你哪天不用agentmemory了，MEMORY.md里的内容不会丢。
避坑提示
三个容易卡住的地方：
- 端口冲突：agentmemory默认占3111（REST）、3112（stream）、3113（viewer）、49134（engine）。如果被其他服务占了，用
--port整体位移，比如agentmemory --port 3211。然后记得同步更新AGENTMEMORY_URL环境变量。 - 没有LLM时的能力边界：不配LLM/Embedding也能跑，搜索也基本能用（BM25+本地小模型）。但没有压缩总结、智能反思、知识图谱抽取。想先试试可以跳过第二步，正式用还是建议配。
- memory.provider设定后Hermes可能仍用原生memory：检查
hermes memory status确认provider确实切到了agentmemory。如果显示的是别的provider，可能是因为~/.hermes/config.yaml中有冲突设置，或者plugin文件拷贝路径不对。
AI Agent正在从"一次性工具"演进为"长期协作伙伴"。记忆是这个进化中最关键的一块拼图——没有记忆的AI是一个永远第一天上班的新人，有记忆的AI才像一个了解你、懂得项目历史的老搭档。
agentmemory给了Agent真正的"情节记忆"，而且是本地化、零成本、开箱即用的方案。花15分钟装上，你的AI助手就从金鱼变成了大象。
您也可以为agentmemory使用本地部署的LLM和Embedding模型，也足够使用，也没有再额外付费的烦恼。您也可以使用仙踪问道·智能助手在本地安装Hermes/Openclaw以及oMXL本地大模型所用。
