🧠 AgentMemory：AI Agent记忆管理框架 语义搜索 知识图谱 MCP工具

AgentMemory 是一个开源的 AI Agent 记忆管理框架，支持语义搜索、知识图谱、MCP 工具集成。自动捕获工具调用记录，无外部依赖，提供 BM25+向量+图谱混合检索，95.2% R@5 准确率。适合多 Agent 协作和长期记忆场景，文末附详细使用教程

🎤 引言

你有没有这种感觉：AI 编程助手用久了，它好像什么都记不住。每次新对话都要重新解释项目背景、代码规范、之前的决策原因。问了"之前为什么用这个方案"，AI 一脸茫然。

这是因为大多数 AI Agent 都是"无状态"的——它们没有持久记忆能力。每次对话都是从零开始。

今天要安利的 AgentMemory 专门解决这个痛点。它是一个开源的记忆管理框架，给 AI Agent 装上"持久内存"，让 AI 记住项目上下文、工具调用历史、决策逻辑，而且还能跨对话搜索。

⭐ 核心功能

自动捕获（Auto Capture）

AgentMemory 通过 12 个钩子（Hook） 自动记录 AI 的所有行为，零手动操作：

这意味着：只要 AI 调用过什么工具、操作过什么文件、产生过什么输出，全部自动记录，事后可查。

混合检索（Hybrid Search）

检索能力是 AgentMemory 的强项。它把三种检索方式融合在一起：

• BM25：传统关键词检索，精确匹配
• 向量检索：语义相似度匹配
• 知识图谱：实体关系 + BFS 遍历

三种结果用 RRF（Reciprocal Rank Fusion） 算法融合，取长补短。官方基准测试显示 R@5 达到 95.2%，而且节省 92% token 用量。

记忆进化（Memory Evolution）

AgentMemory 不是简单的时间序列存储，它有版本控制 + supersession 机制：

• 记忆可以版本化，任意回滚
• 当新记忆覆盖旧记忆时，关系图自动维护
• 矛盾检测：自动发现相互冲突的记忆

自动遗忘（Auto-Forgetting）

长期记忆会越来越多，AgentMemory 有三层遗忘机制：

1. TTL 过期：设置记忆存活时间
2. 重要性驱逐：低价值记忆优先清除
3. 矛盾检测：冲突记忆自动标记

隐私优先（Privacy First）

很多记忆框架会把 API Key、密钥、敏感信息一并存入记忆，非常危险。AgentMemory 在存储前会自动：

• 过滤 API Key 和 Secrets
• 识别 <private> 标签的内容不存储
• 脱敏处理后才写入

MCP 工具支持

支持 51 个 MCP（Model Context Protocol）工具，开箱即用。包括：memory_search、memory_next、memory_lease、memory_mesh_sync 等，覆盖搜索、多 Agent 协作、事件监听等场景。

📥 安装使用

环境要求

• Node.js 18+
• 支持 npm / yarn / pnpm

安装方式

# npm
npm install @agentmemory/agentmemory

# yarn
yarn add @agentmemory/agentmemory

# pnpm
pnpm add @agentmemory/agentmemory

# 或者直接用 npx（免安装）
npx @agentmemory/agentmemory

快速上手

import { createAgentMemory } from '@agentmemory/agentmemory';

const memory = createAgentMemory({
  projectPath: '/path/to/your/project',
  // 可选：向量数据库配置
  vectorDb: 'memory', // 使用内置存储
});

// 开始会话
await memory.sessionStart();

// AI 调用工具时自动记录
await memory.preToolUse({ tool: 'read', params: { path: 'src/index.ts' } });
await memory.postToolUse({ tool: 'read', output: 'file content...' });

// 搜索记忆
const results = await memory.search('上次为什么用这个方案？');

// 结束会话
await memory.sessionEnd();

Claude 集成

AgentMemory 支持和 Claude 的 MEMORY.md 双向同步：

// 同步到 MEMORY.md
await memory.syncToClaude('./MEMORY.md');

// 从 MEMORY.md 读取
const memories = await memory.syncFromClaude('./MEMORY.md');

🎯 适用场景

多会话开发（Multi-Session Development）

比如你同时维护三个项目，每次切换项目都要重新配置上下文。有了 AgentMemory，AI 自动记住每个项目的技术栈、代码规范、上次做到哪里了。

多 Agent 协作（Multi-Agent Systems）

当多个 AI Agent 协同工作时，它们需要共享状态和记忆。memory_mesh_sync 支持 P2P 同步，memory_lease 防止多个 Agent 同时操作同一资源。

长期项目维护（Long-Term Projects）

维护一个 2-3 年的老项目，最难的是"当时为什么这么设计"。AgentMemory 记录了所有决策上下文，新接手的人可以直接问 AI："这个模块当初为什么这样实现？"

审查和复盘（Audit & Review）

所有工具调用都有记录，可以追溯任何操作的来源。适合需要审计日志的合规场景。

🔍 对比同类工具

AgentMemory 的最大优势：零外部依赖，一个 npm 包解决所有问题。不需要额外部署向量数据库，不需要云账号，本地就能跑。

⚠️ 注意事项

1. 记忆不是越多越好。虽然有自动遗忘机制，但建议定期清理低价值记忆，避免检索结果被噪声淹没。
2. 隐私过滤不完美。自动过滤机制基于正则匹配，极端情况下可能漏过敏感信息。涉及真正敏感的数据，建议手动加 <private> 标签。
3. 向量检索需要模型。虽然默认使用 BM25，但完整功能需要配置 embedding 模型。官方推荐用 OpenAI 的 text-embedding-3-small，成本低效果好。
4. 多 Agent 场景需要 lease 机制。如果不加锁，多个 Agent 同时修改同一份记忆可能导致数据不一致。memory_lease 提供了排他操作的支持。

✅ 总结

AgentMemory 解决了一个很实在的问题：AI Agent 的"金鱼记忆"。

用它之后，AI 编程助手不再是每次从零开始的"新人"，而是能记住项目历史、决策原因、代码规范的"老员工"。

优点：

• 零外部依赖，npm 包直接用
• 95.2% R@5，检索质量靠谱
• 12 个自动钩子，零手动记录
• MCP 工具丰富，可扩展性强
• 隐私处理到位，敏感信息不泄露

缺点：

• 目前主要面向 Node.js 生态，Python 支持在路线图上
• 知识图谱功能需要一定配置成本
• 团队协作场景需要额外的 mesh 配置

推荐指数：⭐⭐⭐⭐（扣一星因为 Python 生态暂时较弱）

相关资源

• GitHub 官方仓库
• npm 包地址
• MIT 许可证