AgentMemory 适配器

使用此技能将 AgentMemory 构建为一个可靠的共享内存层，而不仅仅是一段复制粘贴的 MCP 片段。

适用场景

当用户希望执行以下任一操作时，请使用该技能：安装 AgentMemory；将 AgentMemory MCP 集成至 Codex 或 OpenClaw；审计现有内存配置；将 AgentMemory 使用指南发布至 ClawHub；或调试涉及 npx、本地回环（localhost）路由、Bearer Token 安全性、过期 Hook、重复插件路径、或降级 MCP 回退模式的内存故障。

操作顺序

1. 确认目标作用面：Codex、OpenClaw、ClawHub 技能打包，或特定项目工作区（workspace）。
2. 查阅附带的参考文档，了解当前架构与平台专用的最佳实践（recipes）。
3. 优先采用固定版本的本地 AgentMemory 二进制文件，而非长期运行的 npx 命令。
4. 仅应用满足目标作用面所需的最小范围配置变更，并完整保留用户已有配置。
5. 在变更前后均运行诊断脚本，并将任何警告解释为实际运行风险，而非隐藏或忽略。
6. 对于面向公开发布的技能工作，需依次执行 Codex 快速验证、ClawHub 技能医生（skill doctor）、泄露/提示泄露（leak/prompt-bleed）扫描、ClawPatch 审查，以及类 gstack 的发布门控（ship gate）检查，全部通过后方可发布。

首轮操作

1. 编辑配置前，先检查目标智能体（agent）与项目作用域。若用户需求为“适用于所有当前项目”，优先采用用户级（user-level）集成；仅当用户明确要求项目级行为时，才采用仓库本地（repo-local）集成。
2. 阅读 references/agentmemory-deep-analysis.md 了解当前 AgentMemory 架构；阅读 references/platform-recipes.md 获取 Codex、OpenClaw 与 ClawHub 就绪的具体集成模式。
3. 在变更前后均运行 scripts/check_agentmemory.py。若服务端部署于远程主机或使用非默认端口，请通过 --url 指定地址。
4. 保留用户现有配置及备份。agentmemory connect 会将备份写入 ~/.agentmemory/backups；手动编辑 JSON/TOML 配置文件时，也应遵循同等作用域原则。

安装策略

在长期运行的 MCP 配置中，优先使用稳定本地命令，避免无限制调用 npx：

npm install --prefix ~/.agentmemory/npm @agentmemory/agentmemory@0.9.22 --omit=optional
mkdir -p ~/.local/bin
ln -sfn ~/.agentmemory/npm/node_modules/.bin/agentmemory ~/.local/bin/agentmemory

仅当用户明确需要本地向量/图像嵌入能力，并自愿承担原生依赖安装开销时，才启用全部可选依赖（optional dependencies）。若 npx @agentmemory/agentmemory@latest 出现卡顿，应按上述方式本地安装核心包，并将 MCP 条目指向 ~/.local/bin/agentmemory mcp。

Codex 工作流

1. 使用本地命令接入 MCP：

codex mcp remove agentmemory 2>/dev/null || true
codex mcp add agentmemory 
  --env AGENTMEMORY_URL=http://localhost:3111 
  --env AGENTMEMORY_TOOLS=all 
  -- ~/.local/bin/agentmemory mcp

2. 当 Codex Desktop 或插件级 Hook 不可靠时，安装上游 Codex Hook 回退机制：

agentmemory connect codex --with-hooks --force

若 connect 命令将服务端重写为 npx 调用，请重新执行上方 MCP 添加命令。

3. 如需支持斜杠命令（slash skills），请安装上游 Codex 插件，或从本地市场副本安装；若需规避 npx，请将插件中的 .mcp.json 文件内命令路径更新为本地可执行路径。

4. 验证配置：

codex mcp list
python3 ~/.codex/skills/agentmemory-adapter/scripts/check_agentmemory.py

OpenClaw 工作流

1. 添加 MCP 服务端配置：

openclaw mcp set agentmemory '{"command":"'"$HOME"'/.local/bin/agentmemory","args":["mcp"],"env":{"AGENTMEMORY_URL":"http://localhost:3111","AGENTMEMORY_TOOLS":"all"}}'

2. 从持久化目录（而非临时源码检出目录）安装或链接 OpenClaw 内存插件。
3. 确保 plugins.slots.memory 设为 agentmemory，plugins.entries.agentmemory.enabled 为 true，且插件配置中包含 base_url、token_budget、min_confidence、fallback_on_error 和 timeout_ms 字段。
4. 验证配置：

openclaw mcp show agentmemory
openclaw plugins inspect agentmemory
openclaw plugins doctor

边缘情况规则

• 将 MCP 回退模式视为降级状态：当 REST 服务不可达时，该模式仅暴露极小的本地工具集。请启动 AgentMemory 服务端以获得完整工具面（tool surface）。
• 对于沙箱化（sandboxed）智能体，localhost 可能指向沙箱内部。仅当路由路径正确时，才使用可达的主机路由并设置 AGENTMEMORY_FORCE_PROXY=1。
• 切勿通过非回环（non-loopback）的 http:// 协议传输 AGENTMEMORY_SECRET。优先使用 HTTPS 或 SSH 隧道；如需强制校验，可设置 AGENTMEMORY_REQUIRE_HTTPS=1 使连接失败时立即报错。
• 升级 AgentMemory 后，需重新运行 agentmemory connect codex --with-hooks，因为用户级 Hook 中包含绝对路径脚本引用。
• 移除重复的 OpenClaw 插件路径；陈旧的临时路径可能遮蔽持久化安装。
• 仅当角色间需严格隔离时，才使用 AGENT_ID 与 AGENTMEMORY_AGENT_SCOPE=isolated。对单个用户的编码智能体而言，缺省的共享内存通常更优。
• 除非用户明确接受额外 token 开销，否则保持 AGENTMEMORY_INJECT_CONTEXT=false 与 AGENTMEMORY_AUTO_COMPRESS=false。
• 未经显式确认，禁止使用 memory_governance_delete 功能或 /forget 工作流。

ClawHub 就绪型技能开发

若技能计划发布至 ClawHub，请确保：SKILL.md 简洁明了；在 metadata.openclaw 中声明 OpenClaw 运行时依赖；避免出现付费技能或授权相关表述；发布时添加 --clawscan-note 标记（因本工作流会主动配置本地二进制、MCP 及网络访问权限）；发布或审查技能包前，务必参考 references/platform-recipes.md。