agentmemory

agentmemory 是一个专为 AI 编码智能体设计的持久化记忆引擎，旨在解决智能体每次新会话从零开始、用户需反复解释项目上下文的核心痛点。

在记忆获取层面，通过 12 个 Auto-Hooks（覆盖 SessionStart 至 SessionEnd 全生命周期事件）实现零配置自动捕获，无需手动标记或干预。在检索层面，采用 BM25 关键词匹配 + 向量语义检索 + 知识图谱遍历的三流混合架构，通过 Reciprocal Rank Fusion（k=60）融合排序，P50 检索延迟低于 20ms。在记忆整合层面，实现受人类睡眠巩固启发的四层模型——Working（原始观察）经 LLM 压缩为 Episodic（会话摘要），再提取为 Semantic（事实与模式），最终固化为 Procedural（工作流与决策模式），并集成 Ebbinghaus 遗忘曲线衰减与矛盾检测。

底层由 Rust 原生二进制 iii-engine 驱动，存储采用磁盘 JSON + SQLite，零外部数据库依赖。提供 51 个 MCP 工具和 121 个 REST 端点，可被 Claude Code、Cursor、Gemini CLI、Aider 等任意支持 MCP 的智能体接入。支持团队命名空间隔离、Mesh 联邦同步、Git 版本化快照、会话回放（0.5×–4×）、Obsidian 导出、OpenTelemetry 可观测性集成。在 LongMemEval-S（ICLR 2025）基准上达到 R@5 95.2%、MRR 88.2%，Token 效率约为全量上下文粘贴的 8%。

记忆生命周期管理#

• 12 个 Auto-Hooks：自动捕获 SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、PostToolUseFailure、PreCompact、SubagentStart/Stop、Stop、SessionEnd
• 4 层记忆整合：Working（原始观察）→ Episodic（会话摘要）→ Semantic（事实与模式）→ Procedural（工作流与决策模式）
• 遗忘机制：Ebbinghaus 遗忘曲线衰减 + 自动遗忘 + 矛盾检测与解决
• Git 快照：版本化、回滚、diff 记忆状态

检索与召回#

• 三流混合检索：BM25（词干+同义扩展）+ 向量语义（cosine similarity）+ 知识图谱（实体 BFS 遍历）
• RRF 融合：Reciprocal Rank Fusion（k=60），会话多样性控制（每会话最多 3 条结果）
• 去重：SHA-256 哈希去重（5 分钟窗口内）

知识图谱#

• 实体与关系抽取，需 GRAPH_EXTRACTION_ENABLED=true
• 支持带时间维度的图遍历
• Viewer（:3113）中力导向图可视化

隐私与安全#

• 隐私过滤默认开启，API Key、Secret、<private> 标签存储前自动剥离
• 任何记忆均可追溯到原始观察源

协作与联邦#

• 团队记忆：命名空间隔离的共享/私有记忆
• Mesh 联邦：注册其他节点，Bearer Token 认证的 HTTPS push/pull

可观测与容错#

• 自愈机制：Circuit breaker、Provider 降级链
• 健康监控：OpenTelemetry 集成（默认 memory exporter 本地，OTLP 支持 Jaeger/Honeycomb/Tempo）

导出与回放#

• 会话回放：play/pause、0.5×–4× 速度、键盘快捷键；支持导入 Claude Code JSONL 转录文件
• Obsidian 导出：frontmatter-tagged Markdown，兼容 Obsidian 图谱视图

基准性能#

快速开始#

npx @agentmemory/agentmemory
npx @agentmemory/agentmemory demo
open http://localhost:3113

Claude Code 一键安装：

/plugin marketplace add rohitg00/agentmemory
/plugin install agentmemory

通用 MCP 配置：

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/mcp"],
      "env": { "AGENTMEMORY_URL": "http://localhost:3111" }
    }
  }
}