一、TL;DR（先看结论）

你的诉求	推荐方案	备选
给 Claude Code + Codex 装一套"自动捕获 + 跨会话记忆"，零运维	agentmemory	mem0（更通用）
想搭一个"个人 / 团队大脑"，沉淀想法、人脉、会议、决策	GBrain	Cognee
业务侧要给应用做"个性化用户画像 + 长期记忆 API"	mem0	Letta
需要"时间维度"的事实演化追踪（who said what, when）	Graphiti	GBrain
想要"自管理记忆 + 自我进化"的有状态 Agent 平台	Letta	Cognee
想统一摄入企业数据、做知识图谱沉淀	Cognee	Graphiti

对你这个具体场景（Claude Code + Codex）我的最终建议是：

1. 主线选 agentmemory：唯一一个原生同时支持 Claude Code（12 hooks + 53 MCP tools）和 Codex CLI（6 hooks + plugin）的方案，自动捕获 + 本地零依赖（SQLite + iii-engine），开箱即用。
2. 如果你想顺便建"个人/团队知识大脑"，叠加 GBrain 作为 MCP server：两者职责互补，agentmemory 管"会话过程记忆"，GBrain 管"沉淀后的可检索知识库"。
3. 避免一开始就上 Letta：它是"Agent 运行时"而非"记忆插件"，绑定深，不适合作为已有 Claude Code/Codex 的辅助记忆。

---

二、agentmemory 深度解读与最佳实践

1. 项目概述

“Your coding agent remembers everything. No more re-explaining.”
GitHub: https://github.com/rohitg00/agentmemory
协议：Apache-2.0 | 基于 iii-engine 构建

AgentMemory 是一个面向编码 Agent场景的持久记忆服务，核心定位是 Memory engine + MCP server（不是 Agent 运行时）。它解决的问题非常直接：每次编码 Agent 会话结束后，Agent 就忘了你之前做的所有事情——你设置的 JWT 认证、你修复的 N+1 查询 bug、你对 jose 而非 jsonwebtoken 的选择偏好。AgentMemory 在后台静默捕获 Agent 的所有操作，将其压缩为可检索的记忆，并在下次会话开始时自动注入正确的上下文。

该项目明确针对 Claude Code、Codex CLI、Cursor、Gemini CLI、OpenCode、OpenClaw、Hermes、pi 等主流编码 Agent，并且在 Trendshift 上已成为 code agent memory 赛道的头部项目。截至 2026 年 5 月，项目已通过 950+ 测试，维护活跃（v0.9.22 版本于 2026-05-22 发布），社区贡献者持续增长。

2. 核心特性总览

维度	实现
自动捕获	12 个 Claude Code hooks（SessionStart / UserPromptSubmit / PreToolUse / PostToolUse / PreCompact / Stop / SubagentStart/Stop / SessionEnd / PostToolUseFailure 等）；Codex 6 个 hooks；OpenCode 22 个 hooks
检索算法	BM25 + Vector + Graph 三流融合（RRF, k=60），LongMemEval R@5 95.2%，比 BM25 单流高 9pp
4 层记忆架构	Working → Episodic → Semantic → Procedural（类海马回-皮层巩固机制）
遗忘机制	Ebbinghaus 衰减曲线 + TTL + 矛盾检测 + 自动逐出
存储	SQLite + iii-engine（零外部依赖）
MCP 工具数	53 个（memory_recall / smart_search / save / patterns / consolidate / governance_delete / sentinel / lease / signal …）
REST 端点数	124 个
可视化	自带 Real-time Viewer（localhost:3113）+ iii Console（3114）查 OTEL trace
隐私	默认本地存储；写入前自动剥离 API key / secrets / PEM 私钥 / JWT token / <private> 标签
多 Agent	AGENT_ID + AGENTMEMORY_AGENT_SCOPE=isolated 隔离不同角色的记忆
本地 LLM	支持 Ollama / LM Studio / vLLM / llama.cpp，零成本运行 compress / summarize
协议许可	Apache-2.0

3. 安装与快速开始

3.1 基础安装（推荐方式）

# 全局安装（推荐，安装后 agentmemory 命令全局可用）
npm install -g @agentmemory/agentmemory

# 启动记忆服务
agentmemory                    # 启动服务，监听 :3111

# 或者不安装直接用 npx（适合试用）
npx @agentmemory/agentmemory

首次启动时会进入交互式引导向导，包含 Agent 选择、LLM Provider 选择等步骤。

3.2 iii-engine 安装

AgentMemory 依赖 iii-engine 作为底层运行时。当前版本 pin 在 v0.11.2。

macOS arm64（推荐）：

mkdir -p ~/.local/bin
curl -fsSL https://github.com/iii-hq/iii/releases/download/iii/v0.11.2/iii-aarch64-apple-darwin.tar.gz \
  | tar -xz -C ~/.local/bin
chmod +x ~/.local/bin/iii

macOS x64： 将 aarch64-apple-darwin 替换为 x86_64-apple-darwin

Linux x64： 替换为 x86_64-unknown-linux-gnu

Linux arm64： 替换为 aarch64-unknown-linux-gnu

Windows： 从 iii-hq/iii releases v0.11.2 下载 iii-x86_64-pc-windows-msvc.zip，解压 iii.exe 并添加到 PATH。

也可以使用 Docker（自带的 docker-compose.yml 会拉取 iiidev/iii:0.11.2）。

3.3 接入 Claude Code

# 方式一：Plugin 方式（推荐）
# 在 Claude Code 里执行：
/plugin marketplace add rohitg00/agentmemory
/plugin install agentmemory
# 自动注册 12 hooks + 8 skills + 53 MCP tools，无需额外配置

# 方式二：CLI 方式
agentmemory connect claude-code

# 验证安装
curl http://localhost:3111/agentmemory/health
open http://localhost:3113                  # 打开实时记忆可视化界面

注意事项： 如果你直接通过 ~/.claude.json 手动配置 MCP server 而非使用 /plugin install，Claude Code 无法解析 ${CLAUDE_PLUGIN_ROOT}，你需要使用绝对路径指向 hook 脚本。这些路径通常包含版本号，升级后会静默失效。推荐解法：

agentmemory connect claude-code --with-hooks

此命令将 hook 命令以绝对路径写入 ~/.claude/settings.json，升级后重新运行即可刷新路径。

3.4 接入 Codex CLI

# 启动记忆服务（在另一个终端）
npx @agentmemory/agentmemory

# 注册 marketplace 并安装插件
codex plugin marketplace add rohitg00/agentmemory
codex plugin add agentmemory@agentmemory

Codex 插件注册内容包括：MCP server（53 工具）、6 个生命周期 hooks（SessionStart / UserPromptSubmit / PreToolUse / PostToolUse / PreCompact / Stop）、8 个 skills（/recall、/remember、/session-history、/forget、/recap、/handoff、/commit-context、/commit-history）。

重要： Codex Desktop 当前构建版本不会分发插件本地 hooks.json（openai/codex#16430），MCP 工具正常工作但生命周期 hook 不会触发。在上游修复前，需要手动将 hook 命令写入全局配置：

agentmemory connect codex --with-hooks

3.5 接入其他 Agent（通用 MCP 方式）

对于 Cursor、Claude Desktop、Cline、Roo Code、Windsurf、Gemini CLI 等支持 MCP 的 Agent，将以下配置合并到各自的 mcpServers 配置中：

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/mcp"],
      "env": {
        "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
        "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
      }
    }
  }
}

各 Agent 的具体配置文件位置：

Agent	配置文件
Cursor	~/.cursor/mcp.json
Claude Desktop	claude_desktop_config.json（Application Support 目录）
Cline / Roo Code	Cline MCP settings UI
Windsurf	~/.codeium/windsurf/mcp_config.json
Gemini CLI	~/.gemini/settings.json（或 gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user）
OpenCode	opencode.json（注意格式不同，使用 mcp 顶层 key）

3.6 快速体验 Demo

# 终端 1：启动服务
npx @agentmemory/agentmemory

# 终端 2：运行 demo（种子 3 个真实会话并测试检索）
npx @agentmemory/agentmemory demo

# 打开可视化界面观察
open http://localhost:3113

Demo 会种入 3 个真实场景的会话（JWT 认证、N+1 查询修复、限流），并运行语义搜索进行验证。当你搜索 “database performance optimization” 时，它能找到 “N+1 query fix”——关键词匹配做不到这一点。

4. 工作原理与架构

4.1 数据流管线

PostToolUse hook 触发
  → SHA-256 去重（5分钟窗口）
  → 隐私过滤器（剥离 secrets、API keys、PEM 私钥、JWT token）
  → 存储原始观察
  → LLM 压缩 → 结构化 facts + concepts + narrative（或合成压缩）
  → 向量嵌入（6 种 provider + 本地嵌入）
  → 索引到 BM25 + 向量库

Stop / SessionEnd hook 触发
  → 汇总会话
  → 知识图谱抽取（GRAPH_EXTRACTION_ENABLED=true 时）
  → Slot 反射（AGENTMEMORY_REFLECT=true 时）

SessionStart hook 触发
  → 加载项目 profile（核心概念、文件、模式）
  → 混合检索（BM25 + Vector + Graph）
  → Token 预算（默认 2000 tokens）
  → 注入到对话上下文

4.2 四层记忆架构

AgentMemory 的四层记忆体系灵感来源于人脑的记忆巩固机制（类似睡眠巩固）：

层级	内容	类比
Working（工作记忆）	来自工具使用的原始观察	短期记忆
Episodic（情景记忆）	压缩后的会话摘要	“发生了什么”
Semantic（语义记忆）	提取出的事实和模式	“我知道什么”
Procedural（程序记忆）	工作流和决策模式	“怎么做”

记忆随时间按 Ebbinghaus 曲线衰减。经常被访问的记忆会增强。陈旧的记忆自动逐出。矛盾的记忆被检测并解决。

4.3 三流融合检索

AgentMemory 使用三路检索信号的融合机制：

流	作用	触发条件
BM25	词干关键词匹配 + 同义词扩展	始终开启
Vector	密集嵌入的余弦相似度	配置了嵌入提供者时
Graph	通过实体匹配的知识图谱遍历	查询中检测到实体时

三路结果通过 Reciprocal Rank Fusion（RRF, k=60）融合，并进行会话多样化（每个会话最多 3 条结果）。图检索在 v0.9.19 从 BFS 升级为 Dijkstra 算法（基于加权边），显著提升了检索质量。

BM25 原生支持希腊语、西里尔文、希伯来语、阿拉伯语和重音拉丁字母。对于中文/日文/韩文，需安装可选的分词器：

npm install @node-rs/jieba tiny-segmenter

4.4 嵌入模型选择

Provider	模型	费用	说明
Local（推荐）	all-MiniLM-L6-v2	免费	离线运行，比纯 BM25 召回率高 8pp
Gemini	gemini-embedding-001	免费额度	100+ 语言，768/1536/3072 维度
OpenAI	text-embedding-3-small	$0.02/1M	最高质量
Voyage AI	voyage-code-3	付费	代码优化
Cohere	embed-english-v3.0	免费试用	通用
OpenRouter	任意模型	不等	多模型代理

安装本地嵌入（推荐，免费）：

npm install @xenova/transformers

5. 配置详解与最佳实践

5.1 配置文件位置

所有运行时配置放在 ~/.agentmemory/.env 中，格式为 KEY=value（不需要 export 前缀）。进程环境变量仍然生效且优先级高于文件值。

# 初始化配置文件
agentmemory init
# 将 .env.example 模板复制到 ~/.agentmemory/.env

5.2 LLM Provider 配置

AgentMemory 默认不进行 LLM 调用（noop 模式），除非你显式配置一个 provider 或开启 Claude 订阅回退。

推荐的低成本方案（~$0.40-0.55/35h 活跃使用）：

# ~/.agentmemory/.env

# 推荐：DeepSeek V4 Pro 或 Qwen3 Coder（通过 OpenRouter）
OPENROUTER_API_KEY=sk-or-...
# OPENROUTER_MODEL=deepseek/deepseek-v4-pro  # ~$0.46/35h
# OPENROUTER_MODEL=qwen/qwen3-coder          # ~$0.55/35h

# 或直接使用 OpenAI 兼容接口（支持 Ollama / vLLM / LM Studio）
# OPENAI_API_KEY=sk-...
# OPENAI_BASE_URL=http://localhost:11434/v1   # Ollama 示例
# OPENAI_MODEL=qwen3:8b

成本对比（基于 635 请求 / 888K tokens / 35h 活跃使用的实测数据）：

级别	模型	35h 成本	建议
推荐	deepseek/deepseek-v4-pro	~$0.46	压缩/摘要质量好，成本约为 Sonnet 的 1/10
推荐	qwen/qwen3-coder	~$0.55	代码场景推理能力强
高端	anthropic/claude-sonnet-4.6	~$5.02	质量高但对后台压缩任务来说偏贵
避免	anthropic/claude-opus-4.6	~$25+	推理级模型，压缩任务严重浪费

关键经验： 压缩是一种宽松质量要求的摘要任务（Agent 重读摘要，用户不直接看），DeepSeek-V4-Pro 和 Qwen3-Coder 在此任务上与 Sonnet 的差距在误差范围内，但成本低 10 倍。把高端模型的预算留给你直接阅读的查询结果。

5.3 核心功能开关

# ~/.agentmemory/.env

# === 压缩（默认关闭，推荐开启） ===
AGENTMEMORY_AUTO_COMPRESS=true
# 开启后每个 PostToolUse hook 会调用 LLM 压缩观察
# 关闭时使用零 token 的合成压缩（从工具名/输入/输出直接提取结构化信息）

# === 上下文注入（默认关闭） ===
AGENTMEMORY_INJECT_CONTEXT=false
# 开启后 SessionStart 会注入 ~1-2K chars 的项目上下文到首轮对话
# PreToolUse 会在每次文件操作时调用 /agentmemory/enrich

# === 知识图谱（默认关闭） ===
GRAPH_EXTRACTION_ENABLED=false
# 开启后 Stop/SessionEnd 时自动提取实体和关系

# === 记忆巩固（默认开启） ===
CONSOLIDATION_ENABLED=true

# === Lesson 衰减（默认开启） ===
LESSON_DECAY_ENABLED=true

# === 记忆 Slots（默认关闭） ===
AGENTMEMORY_SLOTS=false
# 开启后提供可编辑的钉选记忆槽位：persona / user_preferences /
# tool_guidelines / project_context / guidance / pending_items /
# session_patterns / self_notes

# === Slot 反射（默认关闭，需 SLOTS=true） ===
AGENTMEMORY_REFLECT=false
# 开启后 Stop hook 触发 mem::slot-reflect：扫描近期观察，
# 自动追加 TODO 到 pending_items，计数 session_patterns 中的模式

# === Obsidian 导出（默认关闭） ===
OBSIDIAN_AUTO_EXPORT=false
AGENTMEMORY_EXPORT_ROOT=~/.agentmemory

# === Claude Memory Bridge（默认关闭） ===
CLAUDE_MEMORY_BRIDGE=false
# 开启后与 MEMORY.md 双向同步

5.4 检索调优

# BM25 和向量检索的权重配比
BM25_WEIGHT=0.4
VECTOR_WEIGHT=0.6

# 上下文 token 预算（SessionStart 注入的最大 token 数）
TOKEN_BUDGET=2000

5.5 安全配置

# 设置后所有 REST 端点需要 Bearer token 认证
AGENTMEMORY_SECRET=your-secret-here

# 远程部署时启动 Claude Code
# AGENTMEMORY_URL=https://your-remote-host:3111
# AGENTMEMORY_SECRET=your-secret-here

5.6 端口配置

端口	进程	用途	环境变量覆盖
3111	agentmemory	REST API + MCP HTTP + 健康检查	III_REST_PORT
3112	iii-engine	内部流处理	III_STREAMS_PORT
3113	agentmemory	实时可视化界面	AGENTMEMORY_VIEWER_PORT
49134	iii-engine	WebSocket（worker 注册 + OTEL 遥测）	III_ENGINE_URL

6. 实际应用场景与代码示例

6.1 场景一：跨会话代码记忆

这是 AgentMemory 最核心的使用场景。安装后无需手动操作，Agent 自动记住一切：

Session 1: "给 API 添加认证"
  Agent 编写代码、运行测试、修复 bug
  agentmemory 静默捕获每一次工具调用
  会话结束 → 观察被压缩为结构化记忆

Session 2: "现在添加限流"
  Agent 已经知道：
    - 认证使用 src/middleware/auth.ts 中的 JWT 中间件
    - test/auth.test.ts 中的测试覆盖了 token 验证
    - 你选择了 jose 而不是 jsonwebtoken（因为 Edge 兼容性）
  零重复解释。直接开始工作。

6.2 场景二：使用 Slash Commands

AgentMemory 注册了 8 个 skill 命令，与 Claude Code/Codex 的 slash command 体系无缝集成：

• /recall — 搜索记忆
• /remember — 保存到长期记忆
• /session-history — 查看近期会话摘要
• /forget — 删除观察/会话
• /recap — 获取当前项目的回顾
• /handoff — Agent 之间的上下文交接
• /commit-context — 保存 commit 相关的上下文
• /commit-history — 查看 commit 关联的历史记忆

6.3 场景三：通过 REST API 集成

# 健康检查
curl http://localhost:3111/agentmemory/health

# 智能搜索（BM25 + Vector + Graph 融合）
curl -X POST http://localhost:3111/agentmemory/smart-search \
  -H "Content-Type: application/json" \
  -d '{"query": "how do tokens refresh"}'

# 保存记忆
curl -X POST http://localhost:3111/agentmemory/remember \
  -H "Content-Type: application/json" \
  -d '{
    "content": "我们选择 jose 而不是 jsonwebtoken 是因为 Edge 兼容性",
    "concepts": ["auth", "jwt", "edge"],
    "files": ["src/middleware/auth.ts"]
  }'

# 获取项目 profile
curl http://localhost:3111/agentmemory/profile

# 导出所有记忆数据
curl http://localhost:3111/agentmemory/export

# 查看 token 节约统计
npx @agentmemory/agentmemory status

6.4 场景四：通过 iii-sdk 多语言集成

AgentMemory 的核心操作注册为 iii 函数，任何语言的 iii SDK 都可以直接通过 WebSocket 调用，无需独立的 REST 客户端。

Python 示例：

pip install iii-sdk

from iii import register_worker

iii = register_worker("ws://localhost:49134")
iii.connect()

# 智能搜索
result = iii.trigger({
    "function_id": "mem::smart-search",
    "payload": {"project": "my-project", "query": "how do tokens refresh"},
})

# 保存记忆
iii.trigger({
    "function_id": "mem::remember",
    "payload": {
        "content": "N+1 查询修复方案：使用 DataLoader 批量加载",
        "concepts": ["performance", "database", "dataloader"]
    },
})

Rust / Node 也可用：

cargo add iii-sdk           # Rust
npm install iii-sdk          # Node

6.5 场景五：多 Agent 记忆隔离

在多 Agent 共享一个 AgentMemory 服务的场景下（如架构师 / 开发者 / 评审员），AGENT_ID 标记每次写入的角色，AGENTMEMORY_AGENT_SCOPE 控制检索是否过滤。

# Agent A 的环境变量
TEAM_ID=company
USER_ID=engineering-team
AGENT_ID=architect
AGENTMEMORY_AGENT_SCOPE=isolated  # 严格隔离：架构师看不到开发者的记忆

两种模式：

模式	标记写入	过滤检索	适用场景
shared（默认）	是	否	跨 Agent 上下文共享 + 审计追踪
isolated	是	是	严格隔离，各角色记忆完全独立

6.6 场景六：导入历史 Claude Code 会话

如果你已有之前的 Claude Code JSONL 会话记录：

# 导入 ~/.claude/projects 下的所有会话
npx @agentmemory/agentmemory import-jsonl

# 或导入单个文件
npx @agentmemory/agentmemory import-jsonl ~/.claude/projects/-my-project/abc123.jsonl

导入的会话会自动出现在 Replay 选择器中，并自动生成 lessons 和 crystals。

6.7 场景七：Session-to-Commit 关联

v0.9.19 新增功能：将会话与 Git 提交关联，回答"这段代码是哪个会话写的"和"这个会话提交了哪些 commit"。

# REST API
curl -X POST http://localhost:3111/agentmemory/session/commit \
  -H "Content-Type: application/json" \
  -d '{"sha": "abc123", "sessionId": "session-1"}'

# 反向查找：从 commit 找会话
curl http://localhost:3111/agentmemory/commits/abc123

# MCP 工具
# memory_commit_lookup / memory_commits

7. 可视化与调试工具

7.1 Real-time Viewer（端口 3113）

打开 http://localhost:3113 即可看到：

• Dashboard — 会话计数、记忆计数、健康状态
• Sessions — 会话列表，每个会话显示首条 prompt 预览（140 字符）
• Memories — 记忆浏览器，显示记忆强度仪表
• Knowledge Graph — 知识图谱可视化（支持 1000+ 节点）
• Actions — 工作项管理
• Lessons — 学习到的经验法则
• Crystals — 晶化的行动链
• Replay — 会话回放，支持播放/暂停、速度控制（0.5×–4×）、键盘快捷键

Viewer 首次启动时如果没有数据，会显示引导卡片提示运行 agentmemory demo。功能标志状态会以紧凑的横幅形式显示在每个标签页顶部。

7.2 iii Console（端口 3114）

iii console --port 3114

iii Console 展示 Agent 做了什么（与 Viewer 展示 Agent 记住了什么 互补）：

页面	用途
Workers	查看所有连接的 worker（包括 agentmemory 实例本身）
Functions	直接调用 agentmemory 的任何函数（如 memory.recall / memory.consolidate）
Triggers	重放 HTTP / cron / event / state 触发器
States	KV 浏览器——会话、记忆槽位、生命周期定时器、嵌入索引，可原地编辑
Streams	实时 WebSocket 监控：记忆写入、hook 事件、观察更新
Queues	持久队列管理，可重放或丢弃失败的嵌入/压缩任务
Traces	OpenTelemetry 瀑布/火焰/服务分解视图，追踪每一次 memory.search 的完整流程
Logs	结构化 OTEL 日志，关联到 trace/span ID

7.3 诊断命令

# 综合诊断
agentmemory doctor
# 检查：.env 配置、LLM key、引擎版本、Viewer 端口、PID 文件、API key 有效性等
# 支持 --all 自动修复

# 查看状态（含 token 节约统计）
agentmemory status

# 导出/导入
agentmemory export
agentmemory import

8. 部署方案

8.1 本地开发（推荐起步方式）

npm install -g @agentmemory/agentmemory
agentmemory

零外部依赖，SQLite 本地存储，默认绑定 127.0.0.1。

8.2 远程/团队部署

提供一键部署模板（deploy/ 目录下），每个模板自包含 Dockerfile：

平台	特点
fly.io	单机 + auto_stop_machines = "stop"，最低闲置成本
Railway	Hobby plan 固定费用，Dashboard 管理存储卷
Render	Blueprint 流程，付费计划自动磁盘快照
Coolify	自托管在自己的 VPS 上，完全控制数据

所有模板只暴露端口 3111（REST API）。Viewer 保持绑定在容器内的 loopback——通过 SSH 隧道访问：

ssh -L 3113:localhost:3113 your-server
open http://localhost:3113

8.3 Docker 部署注意事项

# 首次部署后运行（修复卷权限问题）
docker compose down && docker compose up -d

iii-engine 使用 distroless 镜像（UID 65532），Docker 初始化 named volumes 时默认 root:root mode 755，会导致写入失败。compose 文件已内置 init 服务自动修复权限。日志大小限制为 30MB（防止崩溃重启循环填满磁盘）。

9. 与 iii 生态的集成扩展

AgentMemory 本身就是一个运行中的 iii 实例，所有功能都是 iii 原语。通过 iii worker add 可以立即扩展能力：

iii worker add iii-pubsub          # 多实例记忆同步：每次 remember 广播，每次 search 读取联合集
iii worker add iii-cron            # 定时任务：夜间巩固、每周快照、定时衰减
iii worker add iii-queue           # 持久重试：嵌入/压缩任务在重启后恢复
iii worker add iii-observability   # OTEL 追踪（默认已开启）
iii worker add iii-sandbox         # 在隔离 microVM 中运行从 memory_recall 获取的代码
iii worker add iii-database        # SQL 后端状态适配器（超出内存 KV 时）

每个 iii worker add 将新函数和触发器注册到 AgentMemory 已在运行的同一个引擎中。Viewer 和 Console 立即识别它们——无需重载、无需新集成、无需新容器。

10. 与配套工具的组合使用

AgentMemory 设计上不与其他工具重叠，推荐以下组合方式：

项目	负责的层面	与 AgentMemory 的配合
codegraph	代码结构（符号、调用边、路由）	AgentMemory 记住"过程"，codegraph 提供"结构"
Understand Anything	代码架构 + 业务领域 + 架构图	图谱教你认识代码库，AgentMemory 记住你和 Agent 在其中的操作
Graphify	代码 + 文档 + PDF + 图片 + 视频的知识图谱	最广泛的制品扫描，AgentMemory 捕获探索过程

问题路由示例：

问题类型	最佳工具
“这个仓库的架构是什么？”	Understand-Anything 或 Graphify
“符号 X 在哪里定义？谁调用它？”	codegraph
“三个会话前我们为什么选了 X 而不是 Y？”	agentmemory（memory_smart_search）
“我们 4 月 8 日发布了什么？”	agentmemory（memory_timeline）

11. 最佳实践总结

11.1 初始配置建议

极简起步（推荐）： 先不配置 LLM provider，使用合成压缩（零 token 成本）+ 本地嵌入（免费）。这已经能显著改善跨会话体验。

# ~/.agentmemory/.env（极简配置）
# 无需 LLM key，合成压缩 + 本地嵌入即可工作

进阶配置（使用几天后）： 开启 LLM 压缩以获得更高质量的记忆摘要，选择低成本模型。

# ~/.agentmemory/.env（进阶配置）
OPENROUTER_API_KEY=sk-or-...
OPENROUTER_MODEL=deepseek/deepseek-v4-pro
AGENTMEMORY_AUTO_COMPRESS=true
GRAPH_EXTRACTION_ENABLED=true
CONSOLIDATION_ENABLED=true

11.2 性能与成本优化

AgentMemory 内置 token 节约计算器，运行 agentmemory status 可以查看实际节约量。年度成本对比：

方案	Token/年	费用/年
粘贴完整历史到上下文	19.5M+	不可能（超出上下文窗口）
LLM 摘要记忆（提取式）	~650K	~$500
agentmemory（API 嵌入）	~170K	~$10
agentmemory（本地嵌入）	~170K	$0

关键 tips：

• 默认关闭 AGENTMEMORY_AUTO_COMPRESS（合成压缩零成本）
• 使用本地嵌入 all-MiniLM-L6-v2（免费，比纯 BM25 高 8pp 召回率）
• 如果开启 LLM 压缩，选择 DeepSeek 或 Qwen3（成本约 Sonnet 的 1/10）
• TOKEN_BUDGET=2000 已经是很好的默认值

11.3 安全最佳实践

• 始终设置 AGENTMEMORY_SECRET（生产环境）：所有 REST 端点将需要 Bearer token
• Viewer 和 Console 只绑定 127.0.0.1：永远不要暴露到公网
• 远程部署用 SSH 隧道访问 Viewer
• 隐私过滤器默认开启：API key、secrets、PEM 私钥、JWT token 在存储前自动剥离
• 通过 AGENTMEMORY_REQUIRE_HTTPS=1 禁止明文 HTTP 传输 bearer token

11.4 升级与维护

# 升级到最新版
npx @agentmemory/agentmemory upgrade

# 停止服务
agentmemory stop

# 完全卸载
agentmemory remove

# 端口冲突排查
lsof -i :3111,3112,3113,49134
agentmemory stop  # 优雅关闭

升级后重新运行 connect 命令以刷新 hook 脚本路径：

agentmemory connect claude-code --with-hooks
agentmemory connect codex --with-hooks

11.5 常见问题排查

症状	排查方法
memory_smart_search 返回空	检查是否安装了嵌入模型；运行 agentmemory doctor
Viewer 显示空白	先运行 agentmemory demo 种入示例数据
Hook 不触发（Codex Desktop）	运行 agentmemory connect codex --with-hooks
引擎版本不匹配	确保 iii-engine 是 v0.11.2（iii --version）
端口被占用	agentmemory stop 或 lsof -i :3111 排查
Windows 启动失败	添加 --verbose 查看引擎 stderr
大语料库启动慢	rebuildIndex 现在后台运行（v0.9.21+），不阻塞启动
CJK 搜索不准	安装 @node-rs/jieba tiny-segmenter

12. 与竞品的对比优势

12.1 核心对比

	agentmemory	mem0 (53K ⭐)	Letta/MemGPT (22K ⭐)	内置 (CLAUDE.md)
类型	Memory engine + MCP	Memory layer API	完整 Agent 运行时	静态文件
检索 R@5	95.2%	68.5% (LoCoMo)	83.2% (LoCoMo)	N/A (grep)
自动捕获	12 hooks（零手动操作）	手动 add() 调用	Agent 自编辑	手动编辑
搜索	BM25 + Vector + Graph (RRF)	Vector + Graph	Vector (archival)	全量加载到上下文
多 Agent	MCP + REST + 租约 + 信号	API（无协调）	仅 Letta 运行时内	按 Agent 独立文件
框架绑定	无（任何 MCP 客户端）	无	高（必须用 Letta）	按 Agent 格式
外部依赖	无（SQLite + iii-engine）	Qdrant / pgvector	Postgres + vector DB	无
记忆生命周期	4 层巩固 + 衰减 + 自动遗忘	被动提取	Agent 管理	手动修剪
Token 效率	~1,900 tokens/会话（$10/年）	因集成而异	核心记忆在上下文中	22K+ tokens（240条观察时）
实时可视化	有（端口 3113）	云端 Dashboard	云端 Dashboard	无
隐私过滤	自动剥离 secrets/keys/PEM/JWT	无	无	无
审计追踪	所有变更已记录	无	有限	无

12.2 AgentMemory 的独特优势

AgentMemory 在编码 Agent 记忆赛道的决定性优势可以归纳为五点：

第一，原生全栈集成。它是唯一一个对 Claude Code 和 Codex CLI 同时提供"原生 plugin + 钩子 + skills + MCP"全套支持的项目。mem0 需要手动 add()，Letta 要替代你的 Agent，Cognee 虽有 hooks 但生态偏 Python。AgentMemory 是唯一一个装上就"零心智负担"的方案。

第二，零外部依赖。SQLite + iii-engine，不需要 Postgres、不需要 Qdrant、不需要 Redis。npm 一行装完。对比 mem0 需要向量数据库，Letta 需要 Postgres + vector DB，Graphiti 需要 Neo4j/FalkorDB。

第三，隐私优先设计。写入前自动剥离 API key、secrets、PEM 私钥、JWT token，默认本地存储。集成层面也有防护：向非 loopback 明文 HTTP 发送 bearer token 时自动警告，可通过 AGENTMEMORY_REQUIRE_HTTPS=1 升级为硬拒绝。这在所有竞品中是唯一的。

第四，经济性。本地嵌入 + 合成压缩 = $0/年。即使开启 LLM 压缩，使用 DeepSeek 也仅 ~$10/年。对比 mem0 的提取式方案约 ~$500/年。

第五，可观测性。Real-time Viewer + iii Console + OTEL 追踪，从"记住了什么"到"做了什么"全链路可视。这在同类项目中独一无二。

---

三、其他项目简要对比

GBrain（garrytan/gbrain）

“Search gives you raw pages. GBrain gives you the answer.”
作者：Garry Tan（YC President & CEO）

定位为个人/团队"大脑"——知识图谱 + 合成回答引擎。核心理念是搜索给你"相关页面"，GBrain 给你"带引用的合成答案 + 你不知道什么（gap analysis）"。使用 PGLite（PostgreSQL WASM）或 Postgres + pgvector，零配置。与 agentmemory 完美互补：agentmemory 捕获过程态、短期记忆；GBrain 沉淀长期态、可对外引用的知识。MIT 许可。

mem0（mem0ai/mem0）

“The Memory Layer for Personalized AI” — 53k stars，YC S24。

通用 Memory Layer API，不绑定 Agent 框架。适合给自家产品加"长期记忆"。Library + Self-hosted Server + Cloud Platform 三件套。核心劣势：没有 hook 自动捕获，需要手动 add()。Apache-2.0 许可。

Letta / MemGPT（letta-ai/letta）

MemGPT 原作团队的完整 Agent 运行时。

不是插件，是替代品。适合从零构建有记忆的 Agent 产品。核心劣势：你已经在用 Claude Code/Codex，再换运行时是倒退。Apache-2.0 许可。

Graphiti（getzep/graphiti）

Zep 商业平台的开源核心；时间维度的 Context Graph 引擎。

核心创新是每个事实带"生效窗口"——旧事实不删除而是 invalidate。适合 CRM、医患记录、合规审计等场景。需要 Neo4j/FalkorDB 等图数据库。Apache-2.0 许可。

Cognee（topoteretes/cognee）

Memory control plane，强调 ingestion 任何格式。

数据摄入 + 图谱 + 检索全家桶。适合企业级统一摄入多源数据做"公司大脑"。有 Claude Code 插件（覆盖全 hook），但比 agentmemory 重很多。混合许可。

---

四、横向对比矩阵

4.1 总览

项目	定位	主语言	存储	Claude Code	Codex CLI	自动捕获	许可
agentmemory	Memory engine + MCP	TS/Node	SQLite + iii	⭐ Native plugin + 12 hooks + 53 MCP tools	⭐ Native plugin + 6 hooks	✅ Hook 自动	Apache-2.0
GBrain	知识合成大脑	TS (Bun)	PGLite / Postgres	MCP（30+ tools）	MCP	❌ 主动 capture	MIT
mem0	个性化 Memory API	Python/Node	Qdrant/pgvector	Skill 包	Skill 包	❌ 手动 add()	Apache-2.0
Letta	Agent 运行时	Python	Postgres + vector	替代品	替代品	Agent 自管	Apache-2.0
Graphiti	时间图谱引擎	Python	Neo4j/FalkorDB/Kuzu	MCP server	需自配	❌ 主动 add_episode	Apache-2.0 (core)
Cognee	记忆控制平面	Python	多种 graph + vector	⭐ Plugin + 全 hooks	需自配	✅ Hook 自动	见仓库

4.2 检索能力（公开 benchmark 数据）

项目	LongMemEval R@5	LoCoMo	备注
agentmemory	95.2%	–	BM25+Vector+Graph RRF，本地 MiniLM 嵌入
mem0 v3	–	68.5%	单 LLM call
GBrain	–	–	自有 BrainBench，P@5 49.1 / R@5 97.9
Letta	–	83.2	LoCoMo 数据
Graphiti	–	–	强调 sub-second 延迟

4.3 适用场景速查

┌─────────────────────────────────────────────────────────────┐
│           你想干什么？                          推荐         │
├─────────────────────────────────────────────────────────────┤
│ 让 Claude Code / Codex 记住代码会话           → agentmemory │
│ 沉淀我的笔记/想法/人脉做"大脑"                → GBrain      │
│ 给自家产品加用户画像 API                      → mem0        │
│ 从头建一个有记忆的自学习 Agent                → Letta       │
│ 处理"事实随时间变化"的场景                    → Graphiti    │
│ 企业级统一摄入+知识图谱                        → Cognee      │
└─────────────────────────────────────────────────────────────┘

---

五、给你的最终建议：Claude Code + Codex 技术选型

推荐方案 A：极简单机（90% 用户）

只装 agentmemory，结束。

落地动作：

npm install -g @agentmemory/agentmemory
agentmemory                                       # 启动
# Claude Code:
/plugin marketplace add rohitg00/agentmemory && /plugin install agentmemory
# Codex:
codex plugin marketplace add rohitg00/agentmemory && codex plugin add agentmemory@agentmemory
agentmemory connect codex --with-hooks            # 解决 Codex Desktop hook bug

推荐方案 B：会话记忆 + 知识大脑（中重度用户）

agentmemory（管会话） + GBrain（管沉淀）双引擎。

职责切分：

• agentmemory → 会话过程记忆：你刚才在改什么文件、调试到第几步、上次报错的原因、你对某个写法的偏好
• GBrain → 长期沉淀：技术方案文档、架构决策记录、调研笔记、人脉、会议纪要

两者都暴露成 MCP server，Claude Code 同时挂载即可。工具命名不冲突（memory_* vs gbrain_*）。

⚠️ 不建议的组合

• agentmemory + mem0：功能重叠且 mem0 不是 hook 模型，意义不大
• 直接上 Letta：你已经有 Claude Code/Codex，再换运行时是倒退
• 直接上 Graphiti：除非明确需要时间维度事实管理，否则图数据库运维成本不划算

---

附录：信息来源

项目	URL
agentmemory	https://github.com/rohitg00/agentmemory
GBrain	https://github.com/garrytan/gbrain
mem0	https://github.com/mem0ai/mem0
Letta / MemGPT	https://github.com/letta-ai/letta
Graphiti	https://github.com/getzep/graphiti
Cognee	https://github.com/topoteretes/cognee