【GitHub】AgentMemory 深度解析：让 AI 编程代理拥有持久化记忆的 16K+ Star 开源方案

项目地址： github.com/rohitg00/ag… | Stars： 16.2K+ | 许可证： Apache-2.0 版本： v0.9.21（2026-05-19） | 语言： TypeScript (81.4%) | NPM： @agentmemory/agentmemory

一、为什么 AI 编程代理需要"记忆"？
二、AgentMemory 是什么？
三、核心架构：三大原语
四、记忆处理流水线详解
五、四层记忆整合模型
六、三流混合检索机制
七、支持的 Agent 与接入方式
八、MCP 工具与 REST API 全景
九、基准测试与性能数据
十、与竞品的深度对比
十一、配置系统与环境变量
十二、部署方案
十三、安全与隐私设计
十四、iii 引擎扩展生态
十五、路线图与未来规划
十六、总结与思考

一、为什么 AI 编程代理需要"记忆"?

1.1 当前 AI 编程代理的根本缺陷

当前主流的 AI 编程代理（Claude Code、Cursor Agent、Codex CLI 等）都面临一个共同的根本性痛点：

每次会话结束后，代理会遗忘一切。

这意味着：

痛点	具体表现
重复解释成本高	每次开启新会话都要重新描述项目架构、约定和上下文
历史经验丢失	上次会话中踩过的坑、找到的解决方案无法被记住
上下文窗口浪费	为了维持连续性，用户不得不在 CLAUDE.md / MEMORY.md 中手动维护大量静态文本
跨会话学习为零	代理不会因为使用了某个 API 十次就变得更擅长使用它

1.2 现有方案的不足

在 AgentMemory 出现之前，开发者尝试过以下方式来解决记忆问题：

方案	问题
CLAUDE.md / MEMORY.md 静态文件	手动维护，容易过时，全量加载浪费 Token
Mem0（53K Star）	需要外部数据库 Qdrant + Neo4j，无自动捕获能力
Letta/MemGPT（22K Star）	完整 Agent 运行时，框架锁定严重，必须用 Letta
粘贴完整项目上下文	年消耗 19.5M+ Token，远超窗口限制

1.3 AgentMemory 的定位

AgentMemory 的核心主张是：

从第一天起，你的编程代理就应该拥有的记忆系统——零外部依赖、全自动捕获、高精度召回。

二、AgentMemory 是什么？

2.1 一句话定义

AgentMemory 是一个基于 iii Engine 构建的 AI 编程代理持久化记忆层，通过 12 个自动 Hooks 无缝捕获代理行为、利用 LLM 压缩为结构化事实、以 BM25 + 向量 + 知识图谱的三流混合检索实现 95.2% 的 R@5 召回精度，并将 Token 成本降低 92%。

2.2 核心指标一览

指标	数据	说明
GitHub Stars	16,200+	增长极快，周增 540+（GitHub 周榜第 9 名）
检索召回率 R@5	95.2%	LongMemEval-S 基准测试（ICLR 2025, 500 题）
Token 节省率	~92%	相比粘贴完整上下文方案
MCP 工具数量	53 个	核心模式 8 个 / 完整模式 51 个
自动 Hooks 数量	12 个	覆盖完整的代理生命周期
外部数据库依赖	0 个	SQLite + 内存向量索引
测试用例	950+ 通过	覆盖率高
REST API 端点	124 个	完整的可编程接口
支持的 Agent	16+	6 个原生插件 + 10+ MCP 兼容
许可证	Apache-2.0	商业友好

2.3 技术栈概览

运行时:   Node.js >= 20 (单进程)
引擎:     iii Engine (HTTP Triggers + KV State + Streams)
存储:     SQLite (磁盘 JSON) + 内存向量索引
嵌入:     本地 all-MiniLM-L6-v2 / Gemini / OpenAI / Voyage / Cohere
LLM:      Claude / Gemini / OpenRouter / MiniMax / OpenAI (可选)
协议:     REST (端口 3111) + MCP + WebSocket (iii)
UI:       Viewer (3113) + iii Console (3114)

三、核心架构：三大原语

3.1 Hooks（钩子）— 自动捕获原语

这是 AgentMemory 最关键的创新之一。通过 12 个自动钩子，系统能够无缝接入每个编程代理的生命周期事件，无需编写任何胶水代码。

Hook 名称	触发时机	捕获内容
`SessionStart`	会话启动时	项目路径、会话 ID、工作目录信息
`UserPromptSubmit`	用户提交 Prompt 时	用户意图（经隐私过滤）
`PreToolUse`	工具调用前	文件访问模式、即将执行的操作
`PostToolUse`	工具调用完成后	工具名称、输入参数、输出结果
`PostToolUseFailure`	工具调用失败时	错误类型、错误上下文
`PreCompact`	上下文压缩前	重新注入已有记忆到对话
`SubagentStart`	子代理启动时	子代理生命周期追踪
`SubagentStop`	子代理停止时	子代理结果收集
`Stop`	会话停止时	会话摘要触发
`SessionEnd`	会话结束时	最终标记与清理

关键设计决策：

零侵入性：安装插件即完成全部配置，不需要修改任何业务代码
隐私优先：API Key、Secret、<private> 标签内容在捕获阶段就被自动剥离
去重机制：SHA-256 哈希去重，5 分钟滑动窗口防止同一操作被重复记录
渐进式丰富：从原始观察 → 结构化事实 → 语义概念，信息密度逐级提升

3.2 Recall（召回）— 三流检索原语

详见第六章：三流混合检索机制，这里先给出高层视角：

BM25 流：词法级别的关键词匹配，始终可用，零延迟
Vector 流：语义级别的密集嵌入相似度匹配
Graph 流：知识图谱实体关系遍历

三者通过 RRF（Reciprocal Rank Fusion） 算法融合，最终输出 Top-K 相关记忆。

3.3 Consolidate（整合）— 压缩存储原语

仿照人脑睡眠巩固机制，AgentMemory 将原始观察记录逐步压缩提炼为长期记忆：

原始观察 (Working)
    ↓ LLM 提取结构化事实
    ↓ 合并重复项 + 消除矛盾
    ↓ 重要性评分 + 时间衰减
长期记忆 (Semantic / Procedural)

四、记忆处理流水线详解

当 PostToolUse hook 触发后，一条观察记录会经历以下完整处理流水线：

4.1 处理流程

┌──────────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Hook 触发    │ ──▶ │ SHA-256 去重 │ ──▶ │  隐私过滤    │ ──▶ │  存储原始   │ ──▶ │  LLM 压缩   │
│ (PostToolUse)│     │ (5分钟窗口)  │     │ (剥离密钥)   │     │   观察       │     │ (结构化提取) │
└──────────────┘     └──────────────┘     └──────────────┘     └──────────────┘     └──────────────┘
                                                                              │
┌──────────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────────◀──┘
│  双索引写入  │ ◀── │  向量嵌入    │ ◀── │  BM25 分词   │ ◀── │  事实/概念/  │
│              │     │ (6个提供商)  │     │ (同义词扩展) │     │   叙述三元组  │
└──────────────┘     └──────────────┘     └──────────────┘     └──────────────┘

4.2 各阶段详细说明

第一阶段：去重与过滤

# 伪代码示意
def process_observation(raw_obs: Observation):
    # Step 1: SHA-256 哈希去重（5分钟滑动窗口）
    obs_hash = sha256(normalize(raw_obs))
    if cache.exists(obs_hash) and cache.age(obs_hash) < 300s:
        return DUPLICATE
    
    # Step 2: 隐私过滤
    filtered = strip_secrets(raw_obs)  # 剥离 API Key / Secret / private tags
    
    # Step 3: 存储 Working Memory（原始观察）
    store_working(filtered)

隐私过滤规则：

自动识别并剥离：sk-ant-...、sk-...、api_key、password、token 等敏感字段
<private> XML 标签内的内容直接移除
用户自定义的正则过滤规则

第二阶段：LLM 压缩（可选但推荐）

当配置了 LLM 提供商时，原始观察会被压缩为三种结构化单元：

单元类型	内容示例	用途
Fact（事实）	"项目使用 FastAPI + PostgreSQL 技术栈"	可验证的具体信息
Concept（概念）	"认证中间件位于 auth/middleware.py"	抽象化的领域知识
Narrative（叙述）	"用户反馈 API 响应慢，改用了 Redis 缓存"	有因果关系的经验记录

注意： 即使不配置 LLM（默认状态），BM25 词法搜索仍然可以正常工作。LLM 压缩是增强项而非必需项。

第三阶段：双索引写入

每条压缩后的记录同时写入两个索引：

BM25 倒排索引：对文本进行词干提取、同义词扩展后建立倒排排序列表
向量索引：将文本通过嵌入模型转换为稠密向量，支持语义相似度搜索

五、四层记忆整合模型

5.1 各层级详细说明

层级	类比	存储内容	生命周期	更新频率
Working 记忆	人脑的短期记忆 / 感觉登记器	工具调用的原始观察（未压缩）	数小时 ~ 数天	每次 hook 触发
Episodic 记忆	"我昨天做了什么" — 自传体记忆	压缩后的会话摘要、时间线	数天 ~ 数周	Stop / SessionEnd 时
Semantic 记忆	"我知道什么" — 事实性知识	提取的事实、概念、模式	数周 ~ 数月	Consolidation 定期扫描
Procedural 记忆	"怎么做" — 技能性记忆	工作流模板、决策模式、最佳实践	长期（半永久）	反思与归纳后形成

5.2 记忆演化机制

记忆并非静态存储，而是随时间动态演化：

                    时间轴 →

Working ──(压缩)──▶ Episodic ──(提炼)──▶ Semantic ──(抽象)──▶ Procedural
  │                    │                   │                    │
  ▼                    ▼                   ▼                    ▼
 TTL 过期            会话摘要             概念合并            工作流固化
 快速淘汰            保留关键节点         矛盾解决            最佳实践沉淀

核心演化规则：

规则	描述	配置项
艾宾浩斯衰减	不被访问的记忆随时间逐渐降低重要性分数	`LESSON_DECAY_ENABLED=true`
频率强化	被频繁检索到的记忆会加强其保留评分	自动
矛盾检测	新事实与旧事实冲突时标记并尝试解决	自动
TTL 过期	低重要性且长时间未访问的记忆最终被清理	可配置
审计追踪	所有删除操作都有完整日志记录	`GOVERNANCE.md` 定义策略

六、三流混合检索机制

6.1 BM25 词法搜索流

// BM25 搜索的核心逻辑（简化）
function bm25Search(query, corpus) {
    const terms = tokenize(stem(query));           // 词干提取
    const expanded = synonymExpand(terms);          // 同义词扩展
    return rankedByTFIDF(expanded, corpus);        // TF-IDF 加权排序
}

特点：

始终开启，无额外依赖
对精确关键词匹配极其有效（如函数名、文件名、变量名）
延迟趋近于 0ms
权重默认 0.4（可通过 BM25_WEIGHT 调整）

6.2 Vector 向量搜索流

# 向量搜索伪代码
def vector_search(query_embedding: np.ndarray, top_k: int = 20):
    # 余弦相似度计算
    similarities = cosine_similarity(
        query_embedding,          # 查询向量 (1 x dim)
        memory_embeddings         # 记忆库矩阵 (N x dim)
    )
    # 返回 Top-K 结果及相似度分数
    return topk(similarities, k=top_k)

支持的嵌入提供商：

提供商	推荐度	模型	成本	维度	特点
本地（推荐）	⭐⭐⭐⭐⭐	`all-MiniLM-L6-v2`	免费	384	离线可用，比纯 BM25 高 8pp 召回
Gemini	⭐⭐⭐⭐	`gemini-embedding-001`	免费层	768/1536/3072	100+ 语言支持
OpenAI	⭐⭐⭐	`text-embedding-3-small`	$0.02/1M	1536	最高质量
Voyage AI	⭐⭐	`voyage-code-3`	付费	1024	专为代码优化
Cohere	⭐⭐	`embed-english-v3.0`	免费试用	1024	通用场景

6.3 Graph 知识图谱流

当查询中检测到已知实体（如项目中的类名、模块名、API 端点名）时触发：

查询: "UserService 的认证逻辑在哪里?"
     │
     ▼ (NER 实体识别)
检测到实体: UserService
     │
     ▼ (BFS 图遍历)
UserService ──uses──▶ AuthService ──implements──▶ JwtStrategy
     │                  │
     ├──located_in──▶ auth/service.ts
     └──called_by──▶ UserController

图谱特性：

在 Consolidation 阶段自动提取实体和关系边
支持时序边查询（知道某关系在何时建立）
力导向可视化展示（Viewer 端口 3113）

6.4 RRF 融合算法

三条流的搜索结果通过 Reciprocal Rank Fusion 进行融合：

$score(d) = \sum_{i=1}^{n} \frac{1}{k + rank_i(d)}$

其中：

$d$ = 候选文档
$rank_i(d)$ = 第 $i$ 条流中文档 $d$ 的排名
$k$ = 平滑常数，默认 60
$n$ = 活跃流的数量（通常为 2 或 3）

额外优化：会话多样化

融合后的结果还会进行一次后处理——每个来源会话最多返回 3 条记录，避免单一会话的结果垄断输出，确保记忆覆盖面的多样性。

6.5 性能表现

场景	p50 延迟	p95 延迟	备注
BM25-only	< 1ms	< 5ms	纯内存倒排索引
BM25 + Vector (本地)	~14ms	~40ms	LongMemEval-S 基准
BM25 + Vector + Graph	~20ms	~60ms	含图遍历开销
完整上下文注入	< 100ms	< 200ms	含 LLM 格式化

七、支持的 Agent 与接入方式

AgentMemory 支持 16+ 种 AI 编程代理和 IDE，分为两类：

7.1 第一方原生插件（深度集成）

这些 Agent 拥有官方维护的原生插件，支持最完整的 Hook 覆盖和功能：

Agent	维护方	集成方式	Hook 数	特殊功能
Claude Code	Anthropic	`/plugin install agentmemory`	12	斜杠命令 `/recall` `/remember`
Codex CLI	OpenAI	`codex plugin install`	6	原生插件 + MCP
OpenClaw	openclaw 社区	Gateway 插件	-	MCP + 插件
Hermes	Nous Research	Python yaml 配置	-	Python 插件
pi	pi 团队	原生插件	-	MCP
OpenHuman	tinyhumansai	Rust 后端	-	Memory trait

7.2 MCP 协议兼容（通用集成）

任何支持 MCP 协议的 Agent 都可以通过标准配置接入：

Agent	配置文件位置	说明
Cursor	`~/.cursor/mcp.json`	一键 Deeplink 安装
Claude Desktop	Application Support 目录	标准 MCP Server
Windsurf	`~/.codeium/windsurf/mcp_config.json`	标准 MCP
Gemini CLI	`~/.gemini/settings.json`	标准 MCP
Cline	VSCode 扩展设置	标准 MCP
Roo Code	VSCode 扩展设置	标准 MCP
Goose	Block 配置	标准 MCP
Kilo Code	IDE 设置	标准 MCP
Aider	REST API	通过 HTTP 直接调用
OpenCode	`opencode.json`	22 hooks + MCP（最强兼容）

7.3 通用 MCP 配置模板

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

7.4 Claude Code 一键安装体验

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

# 终端 2：Claude Code 中执行（一键完成）
/plugin marketplace add rohitg00/agentmemory
/plugin install agentmemory

# 验证
/recall "项目的认证机制"

八、MCP 工具与 REST API 全景

8.1 MCP 工具列表（53 个）

核心工具（始终可用，8 个）

工具名称	功能描述	使用频率
`memory_recall`	搜索过去的观察记录	★★★★★
`memory_save`	保存洞察、决策或模式到长期记忆	★★★★☆
`memory_smart_search`	混合语义 + 关键词智能搜索	★★★★★
`memory_sessions`	列出最近的会话及其摘要	★★★☆☆
`memory_profile`	获取项目概要（概念、文件、模式）	★★★★★
`memory_export`	导出所有记忆数据为 JSON	★★☆☆☆
`memory_file_history`	查询特定文件的修改历史观察	★★★☆☆
`memory_timeline`	按时间顺序排列的所有观察	★★☆☆☆

扩展工具（需 `AGENTMEMORY_TOOLS=all`，共 51 个）

分类	工具举例	功能
知识图谱	`memory_graph_query`	BFS 遍历知识图谱
整合管理	`memory_consolidate`	手动触发四层整合
桥接同步	`memory_claude_bridge_sync`	与 MEMORY.md 双向同步
团队协作	`memory_team_share`	跨团队成员命名空间共享
治理审计	`memory_audit` / `memory_governance_delete`	操作审计追踪 + 安全删除
版本控制	`memory_snapshot_create`	Git 版本级快照
工作流	`memory_action_create`	创建带依赖的工作项
多 Agent	`memory_lease` / `memory_signal_send`	独占锁 + 消息传递
运维	`memory_diagnose` / `memory_heal`	健康检查 + 自动修复
标签	`memory_facet_tag`	多维度标签（维度:值）
溯源	`memory_verify`	追溯任意记忆到源观察
压缩	`memory_compress_file`	压缩 Markdown 文件为摘要

MCP 资源与提示（Resources & Prompts）

除了工具外，MCP Server 还暴露了资源端点和预定义提示：

类型	名称	功能
Resource	`agentmemory://status`	服务健康状态、会话数、记忆数统计
Resource	`agentmemory://project/{name}/profile`	每个项目智能概要
Resource	`agentmemory://memories/latest`	最近 10 条活跃记忆
Resource	`agentmemory://graph/stats`	知识图谱统计（实体数、边数）
Prompt	`recall_context`	搜索并返回格式化的上下文消息
Prompt	`session_handoff`	Agent 间交接数据打包
Prompt	`detect_patterns`	分析重复模式的提示模板
Skill	`/recall`	快捷搜索斜杠命令
Skill	`/remember`	快捷保存斜杠命令
Skill	`/session-history`	查看最近会话摘要
Skill	`/forget`	删除指定观察或会话

8.2 REST API（124 个端点）

REST API 运行在 端口 3111，提供完整的可编程接口：

方法	路径	功能
`GET`	`/agentmemory/health`	健康检查（公开端点）
`POST`	`/agentmemory/session/start`	启动新会话 + 获取注入上下文
`POST`	`/agentmemory/session/end`	结束当前会话
`POST`	`/agentmemory/observe`	手动提交一条观察记录
`POST`	`/agentmemory/smart-search`	混合搜索（等价于 `memory_smart_search`）
`POST`	`/agentmemory/context`	生成用于注入的上下文片段
`POST`	`/agentmemory/remember`	保存到长期记忆
`POST`	`/agentmemory/forget`	删除观察/会话/记忆
`POST`	`/agentmemory/enrich`	文件上下文 + 相关记忆 + Bug 关联
`GET`	`/agentmemory/profile`	获取项目概要
`GET`	`/agentmemory/export`	导出全部数据（JSON）
`POST`	`/agentmemory/import`	从 JSON 导入数据
`POST`	`/agentmemory/graph/query`	知识图谱查询
`POST`	`/agentmemory/team/share`	团队共享记忆
`GET`	`/agentmemory/audit`	操作审计日志

完整端点列表定义在源码 src/triggers/api.ts 中，共计 124 个端点。

8.3 编程接口 SDK

除了 MCP 和 REST，AgentMemory 还通过 iii Engine 提供 WebSocket 编程接口：

pip install iii-sdk    # Python
cargo add iii-sdk      # Rust  
npm install iii-sdk    # Node.js

Python 使用示例：

from iii import register_worker

# 连接到本地 iii Engine
iii = register_worker("ws://localhost:49134")
iii.connect()

# 执行混合搜索
result = iii.trigger({
    "function_id": "mem::smart-search",
    "payload": {
        "project": "my-awesome-project",
        "query": "how do JWT tokens refresh in this codebase?"
    }
})

print(result)  # 返回相关记忆列表

核心 iii 函数速查：

函数 ID	功能	参数
`mem::remember`	保存记忆	`{text, project, tags?}`
`mem::observe`	捕获观察	`{raw, source?, session_id?}`
`mem::context`	获取上下文	`{project, budget?=2000}`
`mem::smart-search`	混合搜索	`{query, project, top_k?=10}`
`mem::forget`	删除记忆	`{id_or_filter}`

九、基准测试与性能数据

9.1 LongMemEval-S 基准（ICLR 2025）

LongMemEval-S 是 ICLR 2025 提出的长期记忆评估基准，包含 500 道测试题，模拟真实编码场景中的记忆检索需求：

系统	R@5	R@10	MRR	备注
AgentMemory	95.2%	98.6%	88.2%	混合检索（BM25 + 向量 + 图谱）
BM25-only fallback	86.2%	94.6%	71.5%	仅 BM25（无 LLM 压缩时）
Mem0	81.4%	—	—	向量为主
Letta/MemGPT	73.8%	—	—	向量归档
Cognee	78.1%	—	—	向量 + Neo4j

解读： AgentMemory 在该基准上领先第二名近 14 个百分点（R@5），主要归功于 BM25 + 向量的混合检索策略以及本地嵌入的高质量分词。

9.2 内部编码语料库测试

适配器	P@5	R@5	Top-5 命中率	p50 延迟
AgentMemory hybrid	0.578	0.967	15/15	14ms
grep baseline	0.267	0.967	15/15	0ms

注意：虽然 grep baseline 的 R@5 也是 0.967（因为它做的是全文扫描），但其 P@5（精确率@5）仅为 0.267，意味着大量不相关的结果排在前面。AgentMemory 的 P@5 达到 0.578，是基线的 2.16 倍。

9.3 Token 成本对比

这是 AgentMemory 最吸引人的价值主张之一——大幅降低 Token 消耗：

方案	年 Token 消耗量	年成本估算	局限性
粘贴完整项目上下文	19.5M+	远超预算	超出上下文窗口限制
LLM 摘要方案	~650K	~$500/年	需要额外的 LLM 调用链
AgentMemory	~170K/年	~$10/年	高效精准
AgentMemory + 本地嵌入	~170K/年	$0	完全免费

Token 节省 = 92%（相对于粘贴完整上下文方案）

十、与竞品的深度对比

10.1 全面特性对比表

特性维度	AgentMemory	Mem0 (53K⭐)	Letta/MemGPT (22K⭐)	内置 MEMORY.md
类型	记忆引擎 + MCP	记忆层 API	完整 Agent 运行时	静态 Markdown 文件
R@5 精度	95.2%	81.4%	73.8%	N/A
自动捕获	12 hooks（零手动）	手动 `add()` 调用	Agent 自编辑	手动编辑
搜索方式	BM25 + 向量 + 图谱 (RRF)	向量 + 图谱	向量（归档式）	全量加载
外部 DB 依赖	0（SQLite + 内存）	Qdrant + Neo4j	PostgreSQL + 向量DB	无
MCP 工具数	53	11	12	0
REST 端点	124	有限	有限	0
框架锁定	无	无	强（必须用 Letta）	每 Agent 独有格式
多 Agent 协作	MCP + REST + 租约 + 信号	API（无协调）	仅 Letta 内部	完全隔离
Token 效率	~1900 tokens/会话	不确定	核心记忆常驻上下文	240条观察 ≈ 22K tokens
实时查看器	有 (3113)	云端 Dashboard	云端 Dashboard	无
许可证	Apache-2.0	Apache-2.0	Apache-2.0	N/A
Star 增速	+540/周	稳定	稳定	N/A

10.2 AgentMemory 的独特优势总结

零外部依赖：单个 Node 进程即可运行，不需要 Redis/Kafka/Postgres/Qdrant/Neo4j
真正的自动化：12 个 Hook 让记忆捕获完全透明，不需要在任何代码里写 memory.add()
混合检索精度最高：BM25 + Vector + Graph 的 RRF 融合达到 95.2% R@5
极致 Token 效率：~170K tokens/年 vs 粘贴方案的 19.5M+
最大生态系统兼容性：6 个原生插件 + 10+ MCP 兼容，覆盖几乎所有主流编码 Agent

十一、配置系统与环境变量

11.1 配置文件位置

操作系统	路径
macOS / Linux	`~/.agentmemory/.env`
Windows	`%USERPROFILE%\.agentmemory\.env`

11.2 完整环境变量参考

LLM 提供商配置（用于记忆压缩，选配）

# 方案 A: Anthropic Claude（推荐）
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxx

# 方案 B: Google Gemini（同时启用嵌入）
GEMINI_API_KEY=your-gemini-key

# 方案 C: OpenRouter（支持任意模型）
OPENROUTER_API_KEY=your-openrouter-key

# 方案 D: OpenAI（支持 Azure/vLLM/LM Studio 自定义端点）
OPENAI_API_KEY=sk-...
OPENAI_BASE_URL=https://api.openai.com
OPENAI_MODEL=gpt-4o-mini
OPENAI_TIMEOUT_MS=60000
OPENAI_REASONING_EFFORT=none    # low | medium | high | none

# 方案 E: MiniMax（Anthropic 兼容 API）
MINIMAX_API_KEY=your-minimax-key

# 特殊: 使用 Claude 订阅（无需 API Key，零配置）
AGENTMEMORY_ALLOW_AGENT_SDK=true  # 仅选择性启用

嵌入提供商配置

EMBEDDING_PROVIDER=local               # 推荐！完全免费
VOYAGE_API_KEY=...
OPENAI_EMBEDDING_MODEL=text-embedding-3-small

功能开关

# === 核心功能开关 ===
AGENTMEMORY_AUTO_COMPRESS=false        # 自动压缩（默认关，建议按需开）
AGENTMEMORY_SLOTS=false                # 可编辑固定记忆槽（实验性）
AGENTMEMORY_REFLECT=false              # Stop hook 自动反思（默认关）
AGENTMEMORY_INJECT_CONTEXT=false       # SessionStart 自动注入上下文（默认关）
GRAPH_EXTRACTION_ENABLED=false         # 知识图谱提取（需 LLM）
CONSOLIDATION_ENABLED=true             # 四层整合（默认开）
LESSON_DECAY_ENABLED=true              # 记忆衰减（艾宾浩斯曲线）
CLAUDE_MEMORY_BRIDGE=false             # MEMORY.md 双向同步
SNAPSHOT_ENABLED=false                 # Git 版本快照

# === 工具可见性 ===
AGENTMEMORY_TOOLS=core                 # core(8个) 或 all(51个)

搜索与性能调优

# 检索权重
BM25_WEIGHT=0.4                        # BM25 流权重（0~1）
VECTOR_WEIGHT=0.6                      # 向量流权重（0~1）
TOKEN_BUDGET=2000                      # 每次注入的 Token 预算上限

# 超时
AGENTMEMORY_LLM_TIMEOUT_MS=60000       # LLM 调用超时

安全与网络

AGENTMEMORY_SECRET=your-secret-key     # Bearer Token 认证密钥
III_REST_PORT=3111                     # API 端口（默认 3111）

团队协作

TEAM_ID=my-team-id
USER_ID=user-123
TEAM_MODE=private                      # private | shared

11.3 LLM 提供商选择指南

你的情况	推荐方案	原因
零配置快速体验	不设任何 LLM Key	BM25-only 模式即可工作
已有 Claude API 额度	`ANTHROPIC_API_KEY`	压缩质量最佳
追求最低成本	Gemini 免费层	同时获得嵌入 + LLM
需要私有部署	`OPENAI_BASE_URL` 指向 vLLM	完全离线
Claude Pro 订阅者	`AGENTMEMORY_ALLOW_AGENT_SDK`	零额外费用

十二、部署方案

12.1 本地开发部署（最常用）

# 步骤 1: 安装（全局）
npm install -g @agentmemory/agentmemory

# 步骤 2: 启动服务
agentmemory                          # API :3111, Viewer :3113

# 步骤 3: 验证
agentmemory demo                     # 种子示例数据 + 验证召回效果

# 步骤 4: 连接你的 Agent
agentmemory connect claude-code      # 或 cursor / codex / gemini-cli ...

零安装替代方案（适合临时体验）：

npx @agentmemory/agentmemory         # 直接运行
npx -y @agentmemory/agentmemory@latest  # 强制最新版

12.2 Docker 部署

# 使用自带 docker-compose.yml
docker compose up -d

# 或手动构建
docker build -t agentmemory .
docker run -p 3111:3111 -p 3113:3113 agentmemory

12.3 云平台部署

平台	模板	特点	适用场景
fly.io	`deploy/fly.toml`	单机 + auto_stop_machines	个人使用，最低闲置成本
Railway	`deploy/railway.json`	Hobby 计划固定费用	小团队
Render	`deploy/render.yaml`	Blueprint 流程 + 磁盘快照	需要数据持久化
Coolify	`deploy/coolify/`	自托管 VPS	完全掌控数据

重要安全提醒： 只暴露端口 3111（API）。查看器端口 3113 应绑定容器内回环地址，通过 SSH 隧道访问。

12.4 Windows 特别说明

Windows 用户有三条路：

方案	难度	说明
A: 预编译二进制（推荐）	低	下载 iii-x86_64-pc-windows-msvc.zip 解压到 PATH
B: Docker Desktop	中	自动使用 docker-compose.yml
C: 仅 MCP Server	低	`npx -y @agentmemory/agentmemory mcp`，无需完整引擎

12.5 从源码构建

git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
npm install
npm run build        # TypeScript 编译
npm start             # 启动生产服务器

# 开发模式（热重载）
npm run dev

# 测试
npm test              # 950+ 测试用例
npm run test:integration  # API 集成测试（需运行中的服务）

十三、安全与隐私设计

13.1 隐私保护机制

AgentMemory 将隐私作为一等公民来设计：

保护层	机制	实现细节
捕获层	即时剥离	API Key / Secret / `<private>` 标签内容在存储前移除
传输层	Bearer Token	受保护端点需 `Authorization: Bearer <secret>`
存储层	明文 JSON	数据存储在本地磁盘，不上传至云端
查看器	回环绑定	默认绑定 `127.0.0.1:3113`，不可从外部访问
控制台	本地限制	iii Console 绑定 `127.0.0.1`，禁止公网暴露

13.2 认证体系

# 设置密钥后，所有非健康检查端点都需要认证
AGENTMEMORY_SECRET=my-super-secret-key

# 请求时携带
curl -H "Authorization: Bearer my-super-secret-key" \
  http://localhost:3111/agentmemory/profile

13.3 审计与治理

操作审计追踪：所有增删改操作均有日志记录
带审计的安全删除：memory_governance_delete 确保每次删除都可追溯
治理文档：GOVERNANCE.md 定义了删除策略、保留期限和数据分类标准

十四、iii 引擎扩展生态

AgentMemory 本身就是一个运行的 iii Engine 实例。iii 是一个轻量级的 Node.js 应用运行时，AgentMemory 可以通过 Worker 系统无缝扩展能力：

14.1 可用 Worker 扩展

iii worker add iii-pubsub          # 多实例记忆同步（Pub/Sub 消息队列）
iii worker add iii-cron            # 定时任务：整合调度、衰减扫描、快照轮换
iii worker add iii-queue           # 嵌入/压缩任务的持久化重试队列
iii worker add iii-observability   # OTEL 可观测性（每次操作的追踪，默认开启）
iii worker add iii-sandbox         # 隔离 microVM 中运行召回的代码
iii worker add iii-database        # SQL 后端状态适配器（替换 JSON 文件）
iii worker add mcp                 # 并行运行额外 MCP Server

14.2 iii 替代传统技术栈

传统技术栈	AgentMemory (iii) 替代	优势
Express.js / Fastify	iii HTTP Triggers	声明式路由，自动生成 OpenAPI
SQLite + pgvector	iii KV State + 内存向量	零配置向量索引
SSE / Socket.io	iii Streams (WebSocket)	内置连接管理
pm2 / systemd	iii Engine Worker Supervision	内置进程守护
Prometheus / Grafana	iii OTEL + Health Monitor	开箱即用的监控面板

十五、路线图与未来规划

AgentMemory 制定了清晰的 12 个月路线图（Q2 2026 - Q1 2027），按季度主题推进：

15.1 四季度规划全景

季度	主题	核心方向
Q2 2026	Depth（深度）	多模态记忆、更多连接器、清理遗留问题
Q3 2026	Breadth（广度）	更多 Agent 的 Hook 对等支持、社区扩展、OpenSSF
Q4 2026	Trust（信任）	企业级特性：SSO/RBAC/审计导出/长期部署
Q1 2027	v1.0 正式发布	接口冻结、LTS 分支、稳定版承诺

15.2 Q2 2026（当前季度）— Depth

状态	功能	说明
✅ 已交付	iii console 文档	含本地化截图
✅ 已交付	健康严重性门控	基于 RSS 阈值的自动告警
✅ 已交付	独立 MCP 代理连接	支持第三方 MCP 连接运行中的服务器
✅ 已交付	审计覆盖	`mem::forget` 审计追踪
✅ 已交付	文件系统连接器	`@agentmemory/fs-watcher`
✅ 已交付	官网部署	Next.js + Vercel
🔄 进行中	多模态记忆	图片存储、视觉提示压缩、磁盘配额
🔄 进行中	治理基线	GOVERNANCE / CONTRIBUTING / SECURITY 等文档
📋 计划中	GitHub 连接器	Issues/PRs/Discussions 同步为观察记录
📋 计划中	会话回放 UI	时间线拖拽回放每个观察
📋 计划中	CI 基准测试	每次发版自动跑 LongMemEval-S

15.3 Q3 2026 - Breadth

Slack / Discord 消息连接器
OpenSSF Scorecard 银牌认证
知识图谱 DSL 查询语言
Hermes 集成加固
首次会议演讲（KubeCon / LlamaCon）
候选：跨 Agent 共享记忆命名空间

15.4 Q4 2026 - Trust

SSO OIDC 网关
审计日志导出到 S3/Loki/stdout
记忆范围 RBAC（project:read / write / govern）
长期运行部署指南（Docker/systemd/launchd）
性能 SLO 发布（p50/p95 召回延迟目标）
外部安全审计

15.5 Q1 2027 - v1.0

REST + MCP 接口 Semver 冻结
LTS 分支 v1.x（12 个月安全修复承诺）
正式 v1.0 发布 + 文档审查
候选：社区托管参考实例、第二语言参考实现（Rust/Go）

15.6 明确排除的范围

为了保持项目聚焦，以下内容刻意不在路线图中：

❌ 云托管 SaaS 版本
❌ 计费/订阅/Apache-2.0 以外的商业许可
❌ Agent 框架本身（AgentMemory 是依赖库，不是 Agent 运行时的替代品）

十六、总结与思考

16.1 核心创新总结

创新	为什么重要
12 个自动 Hooks	彻底消除了"手动记记忆"的负担，实现了真正的无感记忆
三流混合检索 (RRF)	95.2% R@5 精度，比纯向量方案高出 14pp
四层记忆整合	仿人脑巩固机制，记忆随时间自我进化
零外部依赖	单 Node 进程运行，SQLite + 内存向量，部署门槛极低

16.2 适用场景

场景	适配度	说明
个人开发者日常编码	★★★★★	解决跨会话上下文丢失的最直接方案
小团队协作开发	★★★★☆	团队共享记忆 + 命名空间隔离
大型企业内部工具	★★★☆☆	待 Q4 SSO/RBAC 就绪后更成熟
非 AI 编程场景	★★☆☆☆	设计目标明确面向编程代理
研究/学术用途	★★★★☆	1112 个测试 + 基准测试套件完善

16.3 局限性与注意事项

限制	影响	缓解措施
LLM 压缩需配置 API Key	默认只有 BM25	本地嵌入已足够大多数场景
知识图谱需 LLM 支持	GRAPH_EXTRACTION_ENABLED 默认关闭	配置 Gemini 免费层即可启用
单进程架构	高并发场景受限	iii Pub/Sub worker 支持多实例
主要面向编程代理	通用对话场景优化较少	观察 + 记忆模式可扩展
OKVQA 等通用 VQA 基准较弱	专注于编码领域	这是设计取舍而非缺陷

16.4 个人评价

AgentMemory 在一个极度拥挤的"AI 记忆赛道"中找到了自己的独特定位：

它不做 Agent 运行时（不像 Letta/MemGPT），避免了框架锁定
它不强求外部依赖（不像 Mem0 需要 Qdrant+Neo4j），降低了部署门槛
它真正做到了自动化（12 个 Hooks vs 竞品的手动 add()），解决了"谁去调用记忆 API"的根本问题

16K+ Star 和周增 500+ 的增速说明了社区对这个方向的认可。对于任何一个日常使用 AI 编程代理的开发者来说，AgentMemory 值得一试——毕竟，让你的代理拥有记忆，可能是提升它效率的最简单的方式。

参考链接

资源	链接
GitHub 仓库	github.com/rohitg00/ag…
官网	www.agent-memory.dev
NPM 包	www.npmjs.com/package/@ag…
底层引擎 iii	iii.dev/docs
项目演示页	ericbill21.github.io/fullflow/ （注：此为论文项目主页，非 AgentMemory 演示）
Star 历史	www.star-history.com/#rohitg00/a…
CHANGELOG	github.com/rohitg00/ag…
路线图	github.com/rohitg00/ag…

本文基于 AgentMemory v0.9.21（2026-05-19）版本撰写，项目持续迭代中，请以 GitHub 仓库最新版本为准。