agentmemory 安装与使用手册

概述

agentmemory (v0.9.11) 是一个持久化记忆系统，专为 AI 编程代理（Claude Code、Cursor、Gemini CLI、OpenCode 等）设计。它自动捕获代理的操作记录，压缩为结构化记忆，并通过混合搜索在下一次会话中注入相关上下文------无需重复解释项目架构、代码决策和偏好设置。

核心机制：PostToolUse 钩子捕获 → SHA-256 去重 → 隐私过滤 → 压缩存储 → BM25+向量混合索引 → SessionStart 注入

核心数据

指标	数值
检索准确率 (R@5)	95.2%
Token 节省	92%
注册函数	254
REST 端点	107
MCP 工具	51
外部依赖	无（SQLite + iii-engine）

架构

bash 复制代码

┌─────────────────────────────────────────────────────────┐
│                    iii-engine (v0.11.2)                  │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐  │
│  │ HTTP     │ │ WebSocket│ │ State    │ │ CRON/Queue │  │
│  │ :3111    │ │ :3112    │ │ (SQLite) │ │            │  │
│  └──────────┘ └──────────┘ └──────────┘ └────────────┘  │
│                     │  WebSocket (49134)                 │
│  ┌──────────────────────────────────────────────────┐    │
│  │           iii-exec Worker                         │    │
│  │  └── node dist/index.mjs (agentmemory) ──────────────────┐
│  └──────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────┘
         │                        │
         ▼                        ▼
   REST API (:3111)          Viewer (:3113)
   /agentmemory/*            实时观测面板

iii-engine: Rust 编写的运行时，提供 HTTP 服务、状态存储（SQLite 文件）、WebSocket 流、队列、定时任务
agentmemory (Node.js) : 通过 WebSocket 连接 iii-engine，注册 254 个函数，提供 107 REST 端点 + 51 MCP 工具
Viewer: 端口 3113，实时观测记忆流、会话回放、知识图谱可视化

记忆流水线

vbnet 复制代码

工具调用 → PostToolUse 钩子触发
  → SHA-256 去重（5 分钟窗口）
  → 隐私过滤（脱敏 API Key、密钥）
  → 存储原始观测
  → LLM 压缩 → 结构化事实 + 概念 + 叙述
  → 向量嵌入（6 种嵌入提供商 + 本地）
  → BM25 + 向量索引

会话停止/结束 → 总结会话
  → 知识图谱提取（可选）
  → 槽位反射（可选）

会话开始 → 加载项目画像
  → 混合搜索（BM25 + 向量 + 图谱）
  → Token 预算（默认 2000）
  → 注入对话上下文

4 层记忆整合

层级	内容	类比
Working	工具调用的原始观测	短期记忆
Episodic	压缩后的会话摘要	"发生了什么"
Semantic	提取的事实与模式	"我知道什么"
Procedural	工作流与决策模式	"如何做"

记忆会随时间衰减（艾宾浩斯曲线），频繁访问的记忆会增强，过时记忆自动清除，矛盾会被检测和解决。

安装指南

环境要求

组件	要求
操作系统	Linux x86_64 / arm64、macOS、Windows
Node.js	>= 20.0.0
内存	最低 512MB，推荐 1GB+
磁盘	至少 1GB 可用空间

方式一：从源码安装

这是推荐的部署方式，适合生产环境。

第 1 步：安装 Node.js >= 20

csharp 复制代码

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
apt-get install -y nodejs

# 验证
node --version   # 应输出 v22.x.x
npm --version    # 应输出 10.x.x

第 2 步：部署 agentmemory

bash 复制代码

# 克隆仓库
git clone https://github.com/rohitg00/agentmemory.git /opt/agentmemory
cd /opt/agentmemory

# 安装依赖
npm install

# 构建
npm run build

构建成功后 dist/ 目录包含编译产物。

第 3 步：安装 iii-engine 运行时

agentmemory 依赖 iii-engine v0.11.2 运行时（Rust 二进制）。

bash 复制代码

# Linux x86_64
curl -fsSL "https://github.com/iii-hq/iii/releases/download/iii/v0.11.2/iii-x86_64-unknown-linux-gnu.tar.gz" \
  -o /tmp/iii.tar.gz
mkdir -p /usr/local/bin
tar -xzf /tmp/iii.tar.gz -C /usr/local/bin/
chmod +x /usr/local/bin/iii

# 验证
iii --version   # 应输出 0.11.2

其他架构下载链接：

架构	下载链接
macOS arm64	`https://github.com/iii-hq/iii/releases/download/iii/v0.11.2/iii-aarch64-apple-darwin.tar.gz`
macOS x64	`https://github.com/iii-hq/iii/releases/download/iii/v0.11.2/iii-x86_64-apple-darwin.tar.gz`
Linux arm64	`https://github.com/iii-hq/iii/releases/download/iii/v0.11.2/iii-aarch64-unknown-linux-gnu.tar.gz`
Linux armv7	`https://github.com/iii-hq/iii/releases/download/iii/v0.11.2/iii-armv7-unknown-linux-gnueabihf.tar.gz`
Windows x64	从 GitHub Releases 下载 `iii-x86_64-pc-windows-msvc.zip`

重要：agentmemory 当前固定在 iii-engine v0.11.2。v0.11.6+ 引入了新的沙箱模型，agentmemory 尚未完成重构适配。如果已手动迁移到沙箱模式，可通过 AGENTMEMORY_III_VERSION=<version> 覆盖。

第 4 步：创建生产配置文件

创建专门的 production 配置（关闭开发文件监听）：

yaml 复制代码

cat > /opt/agentmemory/iii-config.production.yaml << 'EOF'
workers:
  - name: iii-http
    config:
      port: 3111
      host: 127.0.0.1
      default_timeout: 180000
      cors:
        allowed_origins: ["http://localhost:3111", "http://localhost:3113", "http://127.0.0.1:3111", "http://127.0.0.1:3113"]
        allowed_methods: [GET, POST, PUT, DELETE, OPTIONS]
  - name: iii-state
    config:
      adapter:
        name: kv
        config:
          store_method: file_based
          file_path: ./data/state_store.db
  - name: iii-queue
    config:
      adapter:
        name: builtin
  - name: iii-pubsub
    config:
      adapter:
        name: local
  - name: iii-cron
    config:
      adapter:
        name: kv
  - name: iii-stream
    config:
      port: 3112
      host: 127.0.0.1
      adapter:
        name: kv
        config:
          store_method: file_based
          file_path: ./data/stream_store
  - name: iii-observability
    config:
      enabled: true
      service_name: agentmemory
      exporter: memory
      sampling_ratio: 1.0
      metrics_enabled: true
      logs_enabled: true
      logs_console_output: true
  - name: iii-exec
    config:
      exec:
        - node dist/cli.mjs
        - --no-engine
EOF

第 5 步：创建 systemd 服务

ini 复制代码

cat > /etc/systemd/system/agentmemory.service << 'EOF'
[Unit]
Description=agentmemory - Persistent memory for AI coding agents
Documentation=https://github.com/rohitg00/agentmemory
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/agentmemory
ExecStart=/usr/bin/node /opt/agentmemory/dist/cli.mjs
Restart=on-failure
RestartSec=10
TimeoutStopSec=30
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target
EOF

# 重新加载并启用服务
systemctl daemon-reload
systemctl enable agentmemory
systemctl start agentmemory

# 检查状态
systemctl status agentmemory

注意：ExecStart 中的 /usr/bin/node 路径需根据实际 which node 输出调整，不同发行版可能为 /usr/local/bin/node。

第 6 步：验证安装

bash 复制代码

# 等待服务启动（约 15-20 秒）
sleep 20

# 检查服务状态
systemctl status agentmemory

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

# 更详细的诊断
node /opt/agentmemory/dist/cli.mjs doctor

健康检查返回示例：

json 复制代码

{
  "status": "healthy",
  "version": "0.9.11",
  "circuitBreaker": { "state": "closed" },
  "service": "agentmemory"
}

方式二：Docker 部署

bash 复制代码

# 使用 Docker Compose（包含 iii-engine 和 agentmemory）
git clone https://github.com/rohitg00/agentmemory.git /opt/agentmemory
cd /opt/agentmemory
docker compose up -d

方式三：一键 npx 快速体验

bash 复制代码

# 自动检测环境，自动下载 iii-engine 或使用 Docker
npx @agentmemory/agentmemory

服务管理

systemd 操作

bash 复制代码

# 状态查看
systemctl status agentmemory

# 启动/停止/重启
systemctl start agentmemory
systemctl stop agentmemory
systemctl restart agentmemory

# 开机自启
systemctl enable agentmemory
systemctl disable agentmemory

# 实时日志
journalctl -u agentmemory -f

# 最近 100 条日志
journalctl -u agentmemory -n 100 --no-pager

端口说明

端口	服务	绑定地址	说明
3111	REST API	127.0.0.1	`/agentmemory/*` 端点
3112	WebSocket	127.0.0.1	实时流
3113	Viewer	127.0.0.1	实时观测面板
49134	WebSocket	127.0.0.1	iii-engine ↔ agentmemory SDK 通信

数据目录

bash 复制代码

/opt/agentmemory/data/
├── state_store.db     # 主状态数据库（SQLite）
└── stream_store/      # 流存储

备份：定期备份 data/state_store.db 文件即可完整保存记忆数据。

配置说明

环境变量

创建配置文件 ~/.agentmemory/.env：

shell 复制代码

# LLM 提供商（任选其一；不配置则使用 noop 模式，不调用 LLM）
# ANTHROPIC_API_KEY=sk-ant-...
# ANTHROPIC_BASE_URL=...              # Anthropic 兼容代理 / Azure
# GEMINI_API_KEY=...
# OPENROUTER_API_KEY=...
# MINIMAX_API_KEY=...

# 嵌入提供商（自动检测，可覆盖）
# EMBEDDING_PROVIDER=local
# OPENAI_API_KEY=sk-...
# OPENAI_EMBEDDING_MODEL=text-embedding-3-small

# 搜索调优
# BM25_WEIGHT=0.4
# VECTOR_WEIGHT=0.6
# TOKEN_BUDGET=2000

# 认证
# AGENTMEMORY_SECRET=your-secret

# 功能开关
# AGENTMEMORY_AUTO_COMPRESS=false    # LLM 压缩观测（默认关闭，会消耗 API Token）
# AGENTMEMORY_SLOTS=false            # 可编辑的固定记忆槽位
# AGENTMEMORY_REFLECT=false          # 停止时自动反射（需 SLOTS=on）
# AGENTMEMORY_INJECT_CONTEXT=false   # 注入上下文到对话
# GRAPH_EXTRACTION_ENABLED=false     # 知识图谱提取
# CONSOLIDATION_ENABLED=true         # 记忆整合
# LESSON_DECAY_ENABLED=true          # 经验衰减
# SNAPSHOT_ENABLED=false             # Git 快照

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

修改后需重启服务生效：

复制代码

systemctl restart agentmemory

嵌入提供商对比

提供商	模型	费用	说明
Local（推荐）	all-MiniLM-L6-v2	免费	离线，比 BM25-only 提升 +8pp 召回率
Gemini	text-embedding-004	免费额度	1500 RPM
OpenAI	text-embedding-3-small	$0.02/1M tokens	最高质量
Voyage AI	voyage-code-3	付费	针对代码优化
Cohere	embed-english-v3.0	免费试用	通用

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

bash 复制代码

npm install @xenova/transformers

功能特性

自动捕获

agentmemory 通过钩子（hooks）自动记录 AI 代理的每个操作：

钩子	捕获内容
SessionStart	项目路径、会话 ID
UserPromptSubmit	用户提示（已过隐私过滤）
PreToolUse	文件访问模式 + 上下文增强
PostToolUse	工具名称、输入、输出
PostToolUseFailure	错误上下文
PreCompact	压缩前重新注入记忆
SubagentStart/Stop	子代理生命周期
Stop	会话结束摘要
SessionEnd	会话完成标记

搜索能力

三重流检索，融合三种信号：

流	方式	适用场景
BM25	词干关键字 + 同义词扩展	始终开启
向量	密集嵌入余弦相似度	配置嵌入后启用
图谱	知识图谱 BFS 遍历	检测到查询实体时启用

使用倒数排名融合（RRF, k=60）和会话多样性（每会话最多 3 条结果）。

数据安全

隐私过滤：API 密钥、密码、<private> 标签内容在存储前脱敏
断路器：自动熔断异常提供商
审计日志：所有状态变更操作记录审计跟踪
绑定 127.0.0.1：默认不暴露到外网

与 AI 代理集成

通用 MCP 配置

大多数 AI 代理通过 MCP（Model Context Protocol）与 agentmemory 集成：

perl 复制代码

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

OpenCode

在 opencode.json 中添加：

json 复制代码

{
  "mcp": {
    "agentmemory": {
      "type": "local",
      "command": ["npx", "-y", "@agentmemory/mcp"],
      "enabled": true
    }
  }
}

Claude Code

bash 复制代码

# 安装插件（自动注册 12 个钩子 + 4 个技能 + MCP）
/plugin marketplace add rohitg00/agentmemory
/plugin install agentmemory

Cursor

在 ~/.cursor/mcp.json 的 mcpServers 中添加 agentmemory 条目。

无 MCP 客户端（REST API 直接调用）

ruby 复制代码

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

# 语义搜索
curl -X POST http://localhost:3111/agentmemory/smart-search \
  -H "Content-Type: application/json" \
  -d '{"query": "auth middleware", "limit": 5}'

# 保存记忆
curl -X POST http://localhost:3111/agentmemory/remember \
  -H "Content-Type: application/json" \
  -d '{"title": "决策记录", "content": "选择 jose 而非 jsonwebtoken", "tags": ["auth"]}'

实时查看器

启动后浏览器打开：

arduino 复制代码

http://localhost:3113

功能：实时观测流、会话浏览器、记忆浏览器、知识图谱可视化、健康面板。

常见操作

查看状态

bash 复制代码

# 服务端
systemctl status agentmemory

# agentmemory 诊断
node /opt/agentmemory/dist/cli.mjs status
node /opt/agentmemory/dist/cli.mjs doctor

运行演示（验证功能）

bash 复制代码

node /opt/agentmemory/dist/cli.mjs demo

该命令会注入 3 个示例会话（JWT 认证、N+1 查询修复、限流中间件），并执行语义搜索验证。

导入历史会话

bash 复制代码

# 导入 Claude Code JSONL 日志
node /opt/agentmemory/dist/cli.mjs import-jsonl

# 导入指定文件
node /opt/agentmemory/dist/cli.mjs import-jsonl /path/to/session.jsonl

升级

bash 复制代码

node /opt/agentmemory/dist/cli.mjs upgrade

该命令会更新 npm 依赖、尝试更新 iii-engine 运行时、拉取最新 Docker 镜像。

监控与运维

健康端点

bash 复制代码

curl http://localhost:3111/agentmemory/health

返回：服务状态、内存用量、CPU、事件循环延迟、KV 连接状态、连接的工作节点列表。

日志查看

perl 复制代码

# 实时跟踪
journalctl -u agentmemory -f

# 过滤关键字
journalctl -u agentmemory | grep -i error

# 指定时间范围
journalctl -u agentmemory --since "1 hour ago"

备份与恢复

bash 复制代码

# 停止服务
systemctl stop agentmemory

# 备份数据库
cp /opt/agentmemory/data/state_store.db /backup/agentmemory-$(date +%Y%m%d).db

# 恢复
cp /backup/agentmemory-20260513.db /opt/agentmemory/data/state_store.db
systemctl start agentmemory

端口冲突排查

perl 复制代码

# 检查端口占用
lsof -i :3111
ss -tlnp | grep 3111

# 使用自定义端口
systemctl edit agentmemory
# 添加 Environment="III_REST_PORT=3114"
# 然后 systemctl restart agentmemory

故障排查

服务启动失败

bash 复制代码

# 查看启动日志
journalctl -u agentmemory -n 50 --no-pager

# 手动运行查看详细输出
node /opt/agentmemory/dist/cli.mjs --verbose

iii-engine 未就绪

perl 复制代码

# 检查 iii-engine 是否可运行
/usr/local/bin/iii --version

# 检查端口
ss -tlnp | grep -E "3111|49134"

记忆不生效

bash 复制代码

# 运行诊断
node /opt/agentmemory/dist/cli.mjs doctor

# 检查是否配置了 API Key（无 LLM 时使用 BM25-only 模式）
# 检查嵌入提供商状态

常见问题速查

症状	原因	解决
`status=203/EXEC`	Node.js 路径错误	检查 `which node`，修正 `ExecStart` 路径
`iii-engine 未就绪`	引擎未下载或版本不匹配	重新安装 iii-engine v0.11.2
`端口被占用`	其他进程占用 3111/3112/3113	使用 `--port <N>` 指定其他端口
`服务频繁重启`	引擎进程崩溃	运行 `--verbose` 查看引擎 stderr
`搜索返回空`	BM25 索引为空	运行一次 `demo` 验证功能
`MCP 连接拒绝`	agentmemory 未运行	`systemctl status agentmemory` 检查状态

性能调优

Token 预算

ini 复制代码

TOKEN_BUDGET=2000    # 每次 SessionStart 注入的最大 token 数

搜索权重

ini 复制代码

BM25_WEIGHT=0.4      # BM25 权重（默认 0.4）
VECTOR_WEIGHT=0.6    # 向量权重（默认 0.6）

定时任务间隔

ini 复制代码

AUTO_FORGET_INTERVAL_MS=3600000        # 自动遗忘间隔（默认 1 小时）
CONSOLIDATION_INTERVAL_MS=7200000      # 记忆整合间隔（默认 2 小时）

工具可见性

ini 复制代码

AGENTMEMORY_TOOLS=core    # core=8 个核心工具，all=51 个全部工具

参考链接

本文档对应 agentmemory v0.9.11 / iii-engine v0.11.2，部署于 Linux x86_64 环境。