从0到1：agentmemory部署实战

系列教程第二篇 | 作者：攀岩者 | 公众号：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

这会：

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

七、踩坑大全

坑 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 实战教程。

从0到1：agentmemory部署实战

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

一、环境准备

1.1 系统要求

1.2 安装 Node.js

二、安装 agentmemory

2.1 一行命令安装

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

2.3 初始化配置

三、配置 API

3.1 编辑配置文件

3.2 配置 LLM Provider

3.3 配置 Embedding（可选）

四、启动服务

4.1 启动 agentmemory

4.2 验证服务状态

4.3 访问可视化界面

五、连接 Agent

5.1 连接 Hermes

5.2 连接 OpenClaw

5.3 连接其他 Agent

六、测试验证

6.1 添加测试记忆

6.2 搜索测试记忆

6.3 使用内置 Demo

七、踩坑大全

坑 1：iii-engine 下载慢

坑 2：iii-engine 崩溃（SIGSEGV）

坑 3：OpenClaw 启动失败

坑 4：Hermes 连接失败

坑 5：搜索无结果

八、生产环境建议

8.1 设置 systemd 自启动

8.2 配置防火墙

8.3 定期备份

九、总结

十、下一篇预告

评论

发表回复 取消回复

更多文章

攀岩运动简介

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

从零部署agentmemory：含5个踩坑经验

AI记忆革命：七大记忆方案终极对决——谁是Agent最佳外脑？

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

发表回复取消回复