如何使用AgentMemory

使用范围

本工具适用于以下 Agent 框架与 MCP 客户端：

安装方式

支持 RPM 包安装（推荐用于 Alinux 4）与源码一键安装两种方式。

RPM 包安装（推荐）：

# 使用 dnf 安装（自动解决依赖）
sudo dnf install agent-memory

RPM 安装到系统级 FHS 路径：

• 服务二进制：/usr/bin/agent-memory

• 默认配置：/usr/share/anolisa/agent-memory/default.toml

• MCP 服务描述符：/usr/share/anolisa/mcp-servers/agent-memory.json

• systemd user 模板：/usr/lib/systemd/user/anolisa-memory@.service

• OpenClaw 适配器 bundle：/usr/share/anolisa/adapters/agent-memory/

源码一键安装：

git clone https://github.com/alibaba/anolisa.git
cd src/agent-memory
make build # cargo build --release --locked
sudo make install
# 安装到 /usr/local 下
# 构建依赖：Rust ≥ 1.85、cmake（libgit2 vendored 构建）、systemd-devel（journald 审计 fan-out）。 
# 运行时仅支持 Linux（依赖 user_namespace、mount(2)、cgroup v2、inotify、journald）。

配置与集成

RPM 安装后，OpenClaw 适配器资源位于 /usr/share/anolisa/adapters/agent-memory/，包含 scripts/install.sh 用于完成插件注册。其余 MCP 客户端通过 MCP 配置文件直接接入。

OpenClaw 集成

sudo bash /usr/share/anolisa/adapters/agent-memory/openclaw/scripts/install.sh
# 安装后重启 OpenClaw gateway： 
openclaw gateway restart 
# 使用 openclaw 命令查看 agent-memory 插件安装状态：
openclaw plugins list |grep memory

Claude Code 等 Agent 集成

在 Claude Code 的 MCP 配置文件中添加 agent-memory：

{
   "mcpServers":
   {
      "agent-memory":
      {
         "command": "/usr/bin/agent-memory",
         "args": [],
         "env": 
         {
            "USER_ID": "alice",
            "MEMORY_PROFILE": "advanced"
         }
      }
   }
}

systemd 服务管理

RPM 安装后可通过 systemd user 模板管理 agent-memory 服务：

# 启动服务（以 alice 用户为例）
systemctl --user start anolisa-memory@alice
# 查看状态
systemctl --user status anolisa-memory@alice
# 开机自启
systemctl --user enable anolisa-memory@alice
# 查看日志
journalctl --user -u anolisa-memory@alice -f

MCP 工具集

agent-memory 通过 MCP 协议提供 37 个标准工具，按功能分为三个层级：

mem_read # 读取文件内容
mem_write # 写入文件
mem_append # 追加内容
mem_edit # 编辑文件（old_str 唯一命中替换）
mem_list # 列出目录内容
mem_grep # 正则搜索文件内容
mem_diff # 文件差异对比
mem_mkdir # 创建目录
mem_remove # 删除文件/目录
mem_promote # 会话草稿原子移入持久化仓
mem_session_log # 查看当前会话 JSONL 日志

memory_search # BM25/向量/混合语义搜索
memory_observe # 自动捕获观察并去重
memory_get_context # 获取最近修改文件的上下文预览
memory_sessions # 历史会话列表
memory_timeline # 指定会话的工具调用时间线
mem_index_refresh # 强制重建 FTS5 索引

mem_snapshot # 创建 tar.gz 快照
mem_snapshot_list # 列出快照
mem_snapshot_restore # 恢复快照
mem_log # Git 变更历史
mem_revert # 文件级 Git 回滚
mem_consolidate # 自动提取原子事实并持久化
mem_compact # 冷数据归档

memory_about # 按 topic 检索记忆
memory_auto_created # 自动提取事实列表
memory_consent # 同意/撤回记忆操作
memory_forget # 删除指定 topic 的记忆
mem_export # 导出记忆仓为 AMA JSON
mem_import # 从 AMA JSON 导入记忆
memory_task_save # 保存/更新任务
memory_task_list # 任务摘要列表
memory_task_resume # 恢复任务上下文
memory_task_close # 关闭任务
memory_summary # 记忆仓统计概览
memory_session_context # 会话启动上下文注入
mem_dream # 用户画像合成

配置说明

[global]
user_id = "alice"

[memory]
profile = "advanced" # basic | advanced | expert
max_read_bytes = 1048576 # 1 MiB
max_write_bytes = 16777216 # 16 MiB

[memory.paths]
base_dir = "~/.anolisa/memory"

[memory.mount]
strategy = "auto" # auto | userland | userns

[memory.index]
enabled = true

[memory.consolidation]
enabled = true

Profile 含义

Profile 控制工具可见性，在 tools/list 和 tools/call 两层校验：

• basic：37 个工具全部展示，弱模型也能用 Tier B 的结构化 API

• advanced（默认）：37 个工具全部展示，强模型应优先使用 Tier A 文件操作

• expert：隐藏 Tier B 工具（memory_search、memory_observe、memory_get_context 等），tools/call 调用会以 METHOD_NOT_FOUND 拒绝

关键环境变量

每个配置项都有对应 MEMORY_* 环境变量，优先级：env > config.toml > default。