agentmemory

agentmemory 是什么？

agentmemory 是为 AI 编码代理设计的本地“记忆层”，用于捕获代理的会话活动，并提供快速召回以支持后续步骤。它在本地以单一 Node 进程运行，将状态以 JSON 格式存储在磁盘上，无需外部数据库。

系统通过自动捕获钩子记录工具调用和提示，将原始观察结果整合为语义记忆，并通过混合流水线（BM25 + 向量 + 知识图谱）提供检索，同时支持设备端重排序。

主要特性

• 本地运行时与 JSON 磁盘存储（零外部数据库）： 以单一 Node 进程运行，将数据持久化为 JSON 存储在磁盘上；无需 Redis、Kafka、Postgres、Qdrant 或 Neo4j。
• 代理活动的自动捕获钩子： PreToolUse、PostToolUse、SessionStart、Stop 等事件在安装后无需额外胶水代码即可自动进入记忆流水线。
• 混合检索与设备端重排序： 三路召回结合 BM25、向量和知识图谱信号，并在设备端对结果进行重排序（页面描述为“笔记本电脑上 P50 低于 20ms”）。
• 自动整合与保留行为： 每小时扫描将原始观察结果整合为语义记忆，合并重复项，使用保留评分使陈旧行衰减，并在项目删除时输出批量审计行。
• MCP 服务器与定义的工具接口： 暴露 MCP 工具如 memory_save、memory_recall、memory_smart_search、memory_sessions、governance、audit 和 export，同时为每个 MCP 工具提供 REST 副本，路径为 /agentmemory/*。
• 通过 JSONL 导入重放会话： 从 Claude Code JSONL 转录本中重新激活会话，包括观察、工具使用和时间线，导入到存储中。
• 知识图谱压缩与查询： 在压缩过程中提取实体和关系；支持通过 /agentmemory/graph 进行图查询和查看器可视化。
• 节点间联邦同步（认证 HTTPS）： 使用持有者令牌认证在 agentmemory 节点之间推送/拉取记忆；页面明确注明“无静默同步”。
• 本地查看器与可观测性输出： 提供实时观察流查看器（端口 3113），并通过“OTEL 可观测性工作进程”输出日志/跟踪（页面提到支持 OTLP 导出到 Jaeger、Honeycomb、Tempo 等追踪后端）。

如何使用 agentmemory

1. 一次安装： 运行 npm install -g @agentmemory/agentmemory 将 agentmemory 加入 PATH。
2. 启动服务器： 运行 agentmemory（服务器运行于 :3111，查看器运行于 :3113）。
3. 本地验证： 打开 http://localhost:3113 查看实时观察流和仪表板。
4. 通过 MCP 连接代理： 配置代理使用 agentmemory MCP JSON 配置（站点说明“一个 MCP JSON 适用于几乎所有情况”）。
5. 可选导入过去会话： 使用提供的 JSONL 会话导入功能将之前的代理运行重放到存储中。

使用场景

• 跨多个编码会话保持连续性： 捕获每个会话的提示和工具使用，使后续代理动作能快速检索相关过去观察。
• 支持“代理为何这样做？”审计： 使用删除时描述的审计输出和可观测性/跟踪输出来检查记忆操作和会话处理期间发生的事情。
• 提升混合查询的检索质量： 当查询包含词汇、语义或依赖提取的关系时，使用混合搜索（BM25 + 向量 + 知识图谱）与设备端重排序。
• 将转录本转为可 Wied 记忆： 导入 Claude Code JSONL 转录本重新激活完整会话时间线——适用于需要稍后查询过去运行的情况。
• 协调多个代理机器： 使用认证 HTTPS 在 agentmemory 节点之间设置点对点同步以进行记忆交换。

常见问题

• agentmemory 是否需要外部数据库（如 Postgres 或 Qdrant）？ 不需要。页面明确标注“ZERO EXTERNAL DATABASES”，并描述系统为单一进程，状态以 JSON 形式存储在磁盘上。

• 如何访问保存和召回记忆的工具？ agentmemory 提供 MCP 服务器，包含 memory_save 和 memory_recall 等工具。页面还提到每个工具都提供 REST 端点，路径为 /agentmemory/*。

• 在哪里可以查看服务器正在捕获的内容？ 页面会在端口 3113 自动启动查看器，展示实时观察流、会话浏览器、记忆浏览器、知识图谱可视化以及健康仪表盘。

• 是否可以导入现有的编码转录？ 可以。页面描述了 JSONL 会话导入流程，可将 Claude Code JSONL 转录内容导入，并重新生成观察、工具使用和时间线。

• agentmemory 是否支持在不同机器间迁移记忆数据？ 页面描述了通过认证 HTTPS 进行点对点同步，并要求使用 bearer token（不进行静默同步）。

替代方案

• 通用向量数据库 + 自定义代理记忆层： 可以存储嵌入向量并实现检索，但需要自行负责编排、整合、钩子以及会话/时间线处理——这与 agentmemory 描述的自动捕获 + MCP/REST 接口不同。
• 用于代码历史记录的本地知识库工具（笔记/图谱风格系统）： 此类工具可以索引文档并提供搜索/图谱视图，有助于召回，但可能无法直接通过此处描述的钩子管道捕获代理工具调用和会话事件。
• 不具备代理特定自动捕获功能的 RAG 框架： 许多 RAG 堆栈提供检索和生成时上下文组装，但可能需要更多定制集成来将 SessionStart/Stop 和工具使用事件捕获到可检索的记忆模型。
• 仅代理遥测/可观测性设置： 追踪工具可以帮助检查行为，但通常无法提供 agentmemory 描述的记忆整合、检索端点和重放导入流程。