不知道你有没有这种感觉——你用的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出场做三件事：

1. 压缩总结：把几千token的工具输出压成几十token的结构化事实。比如"用户把src/db/config.ts中的数据库连接从MySQL改为PostgreSQL"
2. 概念提取：从描述中抽取关键概念（PostgreSQL、config.ts、数据库迁移），用于构建知识图谱
3. 反思整合：定期扫描多条记忆，提炼出更高层次的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方式（先完成步骤一）。

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方式的关键区别是它多了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里的内容不会丢。

---

避坑提示

三个容易卡住的地方：

1. 端口冲突：agentmemory默认占3111（REST）、3112（stream）、3113（viewer）、49134（engine）。如果被其他服务占了，用--port整体位移，比如agentmemory --port 3211。然后记得同步更新AGENTMEMORY_URL环境变量。
2. 没有LLM时的能力边界：不配LLM/Embedding也能跑，搜索也基本能用（BM25+本地小模型）。但没有压缩总结、智能反思、知识图谱抽取。想先试试可以跳过第二步，正式用还是建议配。
3. 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本地大模型所用。