攀岩者

从0到1：agentmemory部署实战

作者：

climbing

在

系列教程第二篇 | 作者：攀岩者 | 公众号：AI学习日记

引言：理论很美好，落地才真实

上一篇我们对比了四大 AI 记忆方案，最终选择了 agentmemory——检索最强、Token 最省、零依赖。

今天，我将带你从 0 到 1 部署 agentmemory，并且把我踩过的每一个坑都告诉你，让你少走弯路。

一、环境准备

1.1 系统要求

项目 最低要求 推荐配置

|——|———|———|

操作系统 Linux / macOS / Windows Arch Linux / Ubuntu
Node.js 18+ 22+
内存 2GB 4GB+
磁盘 500MB 1GB+

1.2 安装 Node.js

`bash

# Arch Linux

sudo pacman -S nodejs npm

# Ubuntu / Debian

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash –

sudo apt-get install -y nodejs

# macOS

brew install node

`

验证安装：

`bash

node –version # 应该 >= 18

npm –version

`

二、安装 agentmemory

2.1 一行命令安装

`bash

npm install -g @agentmemory/agentmemory

`

验证安装：

`bash

agentmemory –version

# 输出: agentmemory v0.9.21

`

2.2 安装 iii-engine（核心引擎）

⚠️ 踩坑警告： 直接从 GitHub 下载在国内非常慢（~10KB/s），需要使用代理。

方法 1：使用 ghfast.top 代理（推荐）

`bash

# 下载 iii-engine（约 11MB）

curl -L –connect-timeout 30 –max-time 600

“https://ghfast.top/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

# 解压到 ~/.local/bin

tar -xzf /tmp/iii.tar.gz -C ~/.local/bin

chmod +x ~/.local/bin/iii

# 验证

~/.local/bin/iii –version

# 输出: 0.11.2

`

方法 2：使用 Docker（需要安装 Docker）

`bash

docker pull iiidev/iii:0.11.2

export AGENTMEMORY_USE_DOCKER=1

`

方法 3：直接使用 npm 内置的 iii-engine

`bash

# agentmemory 会自动下载，但可能很慢

agentmemory

`

2.3 初始化配置

`bash

agentmemory init

`

这会在 ~/.agentmemory/.env 创建配置文件。

三、配置 API

3.1 编辑配置文件

`bash

nano ~/.agentmemory/.env

`

3.2 配置 LLM Provider

方案 A：使用小米 MiMo（推荐，国内访问快）

`bash

# 在文件末尾添加

OPENAI_API_KEY=你的小米API密钥

OPENAI_BASE_URL=https://token-plan-cn.xiaomimimo.com/v1

`

方案 B：使用 OpenAI

`bash

OPENAI_API_KEY=sk-你的OpenAI密钥

`

方案 C：使用 FreeLLMAPI（免费，本地部署）

`bash

OPENAI_API_KEY=你的FreeLLMAPI密钥

OPENAI_BASE_URL=http://localhost:3001/v1

`

3.3 配置 Embedding（可选）

如果不配置，会使用本地模型（效果稍差）：

`bash

# 使用 OpenAI Embedding

EMBEDDING_PROVIDER=openai

OPENAI_EMBEDDING_MODEL=text-embedding-3-small

# 或使用本地模型（默认）

EMBEDDING_PROVIDER=local

`

四、启动服务

4.1 启动 agentmemory

`bash

agentmemory

`

⚠️ 踩坑警告： 首次启动可能需要等待 iii-engine 初始化，约 10-30 秒。

4.2 验证服务状态

`bash

agentmemory status

`

正常输出：

`

┌ agentmemory status

│

◆ Connected — v0.9.21 at http://localhost:3111

│

◇ agentmemory ──────────────────────────────────────╮

│ │

│ Health: ✓ healthy │

│ Sessions: 0 │

│ Observations: 0 │

│ Memories: 0 │

│ Graph: 0 nodes, 0 edges │

│ Circuit: closed │

│ Heap: 31 MB │

│ Uptime: 0s │

│ Viewer: http://localhost:3113 │

│ │

│ Provider: ✓ llm │

│ Embeddings: ✓ embeddings │

│ │

├────────────────────────────────────────────────────╯

`

关键指标：

  • Health: ✓ healthy（健康）
  • Provider: ✓ llm（LLM 连接正常）
  • Embeddings: ✓ embeddings（Embedding 正常）
  • Viewer: http://localhost:3113（可视化界面）

4.3 访问可视化界面

打开浏览器访问：http://localhost:3113

你可以在这里看到：

  • 所有会话记录
  • 记忆图谱
  • 搜索测试

五、连接 Agent

5.1 连接 Hermes

⚠️ 踩坑警告： Hermes 使用 YAML 配置，不能用自动连接命令，需要手动配置。

编辑 ~/.hermes/config.yaml，添加：

`yaml

mcp_servers:

agentmemory:

command: npx

args: ‘[“-y”, “@agentmemory/mcp”]’

memory:

provider: agentmemory

`

或者使用命令行：

`bash

hermes config set mcp_servers.agentmemory.command npx

hermes config set ‘mcp_servers.agentmemory.args’ ‘[“-y”, “@agentmemory/mcp”]’

hermes config set memory.provider agentmemory

`

5.2 连接 OpenClaw

⚠️ 踩坑警告： 不能直接编辑 openclaw.json 添加 mcpServers，需要用专用命令。

`bash

# 正确方式：使用 openclaw mcp set

openclaw mcp set agentmemory ‘{“command”:”npx”,”args”:[“-y”,”@agentmemory/mcp”]}’

# 验证

openclaw mcp list

# 输出: MCP servers: – agentmemory

`

错误方式（会导致启动失败）：

`bash

# ❌ 直接编辑 openclaw.json 添加 mcpServers

# ❌ 使用 agentmemory connect openclaw（格式不对）

`

5.3 连接其他 Agent

`bash

# Claude Code

agentmemory connect claude-code

# Codex CLI

agentmemory connect codex

# Cursor

agentmemory connect cursor

# 一键连接所有

agentmemory connect –all

`

六、测试验证

6.1 添加测试记忆

`bash

curl -s -X POST http://localhost:3111/agentmemory/remember

-H “Content-Type: application/json”

-d ‘{

“hookType”: “manual”,

“sessionId”: “test-001”,

“project”: “test”,

“cwd”: “/home/user”,

“timestamp”: “‘$(date -u +%Y-%m-%dT%H:%M:%S.000Z)’”,

“content”: “这是一条测试记忆，用于验证 agentmemory 是否正常工作。”,

“type”: “fact”

}’

`

正常输出：

`json

{

“memory”: {

“id”: “mem_xxx”,

“content”: “这是一条测试记忆…”,

“type”: “fact”

},

“success”: true

}

`

6.2 搜索测试记忆

`bash

curl -s -X POST http://localhost:3111/agentmemory/search

-H “Content-Type: application/json”

-d ‘{

“query”: “测试记忆”,

“limit”: 5

}’

`

正常输出：

`json

{

“results”: [

{

“observation”: {

“narrative”: “这是一条测试记忆，用于验证 agentmemory 是否正常工作。”

},

“score”: 5.123

}

],

“tokens_used”: 150

}

`

6.3 使用内置 Demo

`bash

agentmemory demo

`

这会：

  1. 创建 3 个示例会话
  2. 添加 6 条观察
  3. 运行 3 次搜索测试
  4. 展示语义搜索能力

七、踩坑大全

坑 1：iii-engine 下载慢

现象： agentmemory 启动时卡在 “Waiting for iii-engine to be ready”

原因： 国内访问 GitHub 慢

解决： 使用 ghfast.top 代理下载（见第二节）

坑 2：iii-engine 崩溃（SIGSEGV）

现象： process killed by signal SIGSEGV

原因： 下载的文件不完整

解决：

`bash

rm -f ~/.local/bin/iii

# 重新下载，确保文件完整

curl -L –max-time 600 “https://ghfast.top/…” -o /tmp/iii.tar.gz

tar -xzf /tmp/iii.tar.gz -C ~/.local/bin

`

坑 3：OpenClaw 启动失败

现象： Invalid config: Unrecognized key: "mcpServers"

原因： 直接编辑 openclaw.json 添加了不支持的字段

解决：

`bash

# 删除错误的配置

# 编辑 ~/.openclaw/openclaw.json，删除 “mcpServers” 部分

# 使用正确的命令

openclaw mcp set agentmemory ‘{“command”:”npx”,”args”:[“-y”,”@agentmemory/mcp”]}’

`

坑 4：Hermes 连接失败

现象： memory provider not found

原因： 配置格式错误

解决： 确保 YAML 格式正确，args 是字符串不是数组

坑 5：搜索无结果

现象： search returns empty results

原因： 使用了 project 过滤但记忆没有设置 project

解决： 搜索时不要带 project 参数，或者确保添加记忆时设置了 project

八、生产环境建议

8.1 设置 systemd 自启动

`bash

# 创建服务文件

cat > ~/.config/systemd/user/agentmemory.service << 'EOF'

[Unit]

Description=AgentMemory Server

After=network.target

[Service]

Type=simple

ExecStart=/usr/bin/env agentmemory

Restart=always

RestartSec=5

[Install]

WantedBy=default.target

EOF

# 启用并启动

systemctl –user enable agentmemory

systemctl –user start agentmemory

# 开机自启（需要 loginctl linger）

loginctl enable-linger $USER

`

8.2 配置防火墙

`bash

# 只允许本地访问

sudo ufw deny 3111

sudo ufw deny 3113

`

8.3 定期备份

`bash

# 备份记忆数据

cp -r ~/.agentmemory/memory.db ~/backup/memory-$(date +%Y%m%d).db

`

九、总结

步骤 命令 耗时

|——|——|——|

安装 agentmemory npm install -g @agentmemory/agentmemory 1 分钟
安装 iii-engine curl + tar 2 分钟
初始化配置 agentmemory init 1 分钟
编辑 API nano ~/.agentmemory/.env 2 分钟
启动服务 agentmemory 30 秒
连接 Agent hermes config set / openclaw mcp set 2 分钟
测试验证 agentmemory demo 1 分钟

总计：约 10 分钟完成部署。

十、下一篇预告

《打通 Hermes 和 OpenClaw：跨平台记忆共享实战》

下一篇将手把手教你：

  • 如何让 Hermes 和 OpenClaw 共享记忆
  • 如何验证记忆桥接是否成功
  • 实际使用中的最佳实践

敬请期待！

作者简介：攀岩者，东华软件技术总监，19 年 IT 经验，PMP+CKA。每天分享 AI 学习笔记，陪你从零基础到 AI 达人。

>

关注公众号：AI学习日记，获取更多 AI 实战教程。

评论

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注

更多文章