fix(anolisa): release displaced plugin tool names on adapter enable

docs/user-guide/en/token-saving/agent-memory.md

@@ -115,6 +115,23 @@ anolisa adapter status agent-memory
 
 **Prerequisite**: `openclaw` CLI on `$PATH`. The script logs clearly and exits 0 if missing — rerun after installing OpenClaw. `yum remove agent-memory` triggers `%preun` to call the uninstall script, leaving no orphaned config.
 
+**Tool-name hand-off**: OpenClaw's bundled `memory-core` plugin owns the `memory_get` and `memory_search` tool names, and OpenClaw's plugin tool registry is first-wins. While `memory-core` stays loaded it keeps those names, so this plugin's own same-named tools are dropped and `memory_get` answers from `memory-core` instead of from agent-memory.
+
+Only the `anolisa adapter` entry point performs the hand-off:
+
+- `anolisa adapter enable agent-memory openclaw` disables `memory-core` and records the transition in the adapter receipt, driven by the `[[adapters.openclaw.displaces]]` declaration in the component contract; `anolisa adapter disable agent-memory` restores it from that receipt. `adapter enable --dry-run` lists the hand-off as a planned action, and `adapter disable --dry-run` lists the restore.
+- `anolisa adapter status agent-memory` reports degraded when `memory-core` is enabled again afterwards — by an operator command or a framework update — because the collision is back even though this plugin itself still registers and loads. It also reports **unknown** rather than healthy for a displacement it has recorded: `plugins disable` only writes config, and ANOLISA has no channel to the running gateway, so it can confirm the hand-off was *recorded* but not that the gateway has *applied* it. Whether you need to do anything further depends on OpenClaw's plugin reload mode: a mode that hot-reloads `plugins.entries.*` applies the change by itself, and one that does not needs `openclaw gateway restart`. Note that restarting does **not** turn this `unknown` into `healthy`, because ANOLISA still cannot observe the gateway afterwards. Read `unknown` here as "not observable", not as a fault. To confirm the hand-off yourself, call `memory_get` and check which plugin answers — a real tool call goes through the running gateway. Do **not** use `openclaw plugins list` or `plugins inspect` for this: both read the persisted registry and config, so before a restart they show `memory-core` as disabled while the old gateway may still be serving its tools. That reads as confirmation and is not.
+
+The `install.sh` entry point above does **not** touch `memory-core`. After installing that way, run `openclaw plugins disable memory-core` yourself (and `openclaw plugins enable memory-core` to undo it), or use `anolisa adapter enable agent-memory openclaw` instead.
+
+The adapter path never re-enables a `memory-core` you had disabled yourself before enabling, and never takes the memory slot back from a choice you made afterwards: if `plugins.slots.memory` points at another plugin by removal time, or you closed the slot explicitly with `plugins.slots.memory = "none"`, `memory-core` is left disabled and the reason is reported. If your OpenClaw is configured not to hot-reload plugin config, run `openclaw gateway restart` after enabling or disabling; a hot-reloading host applies both by itself.
+
+**What disabling `memory-core` costs**: the hand-off disables the whole bundled plugin, not just the two colliding tool names. Everything OpenClaw's `memory-core` provides beyond them is unavailable for as long as agent-memory is enabled — its own `memory_*` tools, the `openclaw memory` command surface, and the background dreaming / consolidation lifecycle that plugin runs. This is not an edge case: it happens on every `adapter enable`.
+
+agent-memory covers the retrieval path in the meantime (see *MCP tool set* and *Auto consolidation* below), but it reads and writes `~/.anolisa/memory`, not `memory-core`'s own store — so anything `memory-core` had already accumulated stays untouched and out of reach until the plugin is re-enabled, and the two stores are not merged for you.
+
+`memory-core` comes back when `anolisa adapter disable agent-memory` restores it, subject to the guard above: if `plugins.slots.memory` has since been given to another backend or closed explicitly, it stays disabled and you re-enable it yourself with `openclaw plugins enable memory-core`. As above, a host that does not hot-reload plugin config needs `openclaw gateway restart` for either change.
+
 Running `anolisa adapter enable agent-memory openclaw` or the agent-memory OpenClaw `install.sh` accepts the plugin's declared capabilities. Both entry points pass `--accept-capabilities` only when `plugins install --help` advertises that exact option, so older hosts keep working. Set `AGENT_MEMORY_ACCEPT_CAPABILITIES=0` when running `install.sh` to withhold consent — gating hosts then reject the install until you grant it yourself, e.g. via an interactive `openclaw plugins install`.
 
 Install-time environment variables (runtime `MEMORY_*` variables are listed separately under Environment variables):

docs/user-guide/zh/token-saving/agent-memory.md

@@ -114,6 +114,23 @@ anolisa adapter status agent-memory
 
 **前置条件**：`openclaw` CLI 在 `$PATH` 上。脚本缺失时输出明确日志并以 0 退出，安装 OpenClaw 后重跑即可。`yum remove agent-memory` 时 spec 的 `%preun` 自动调用 uninstall 脚本，配置不残留孤立项。
 
+**工具名交接**：OpenClaw 自带的 `memory-core` 插件占用 `memory_get` 与 `memory_search` 这两个工具名，而 OpenClaw 的插件工具注册表是「先到先得」。只要 `memory-core` 仍处于加载状态，它就继续持有这两个名字，本插件的同名工具会被丢弃，`memory_get` 也会由 `memory-core` 而非 agent-memory 应答。
+
+只有 `anolisa adapter` 入口执行这次交接：
+
+- `anolisa adapter enable agent-memory openclaw` 禁用 `memory-core`，并把这次状态变更记录在适配器 receipt 中，由组件契约里的 `[[adapters.openclaw.displaces]]` 声明驱动；`anolisa adapter disable agent-memory` 依据该 receipt 恢复。`adapter enable --dry-run` 会把这次交接列为计划动作，`adapter disable --dry-run` 会列出恢复动作。
+- 之后若 `memory-core` 被重新启用（人工命令或框架升级都可能），冲突即已回归，尽管本插件自身仍注册且加载正常——`anolisa adapter status agent-memory` 会因此报告 degraded。对已记录的 displacement，它报告的同样是 **unknown** 而不是 healthy：`plugins disable` 只写配置，而 ANOLISA 没有通往正在运行的网关的通道，因此只能确认交接已被**记录**，无法确认网关是否已**生效**。是否还需要额外动作取决于 OpenClaw 的插件 reload 模式：会热重载 `plugins.entries.*` 的模式自行生效，不会的则需要 `openclaw gateway restart`。注意重启**不会**把这个 `unknown` 变成 `healthy`，因为重启之后 ANOLISA 依然观测不到网关。此处的 `unknown` 应理解为「无法观测」，而不是故障。要自行确认交接是否生效，请调用一次 `memory_get` 看是哪个插件应答——真实的工具调用会穿过正在运行的网关。**不要**用 `openclaw plugins list` 或 `plugins inspect` 来确认：两者读取的都是持久化的 registry 与配置，因此在重启之前它们会显示 `memory-core` 已禁用，而旧网关可能仍在提供它的工具——那看起来像确认，其实不是。
+
+上面的 `install.sh` 入口**不会**处理 `memory-core`。以该方式安装后，请自行执行 `openclaw plugins disable memory-core`（撤销用 `openclaw plugins enable memory-core`），或改用 `anolisa adapter enable agent-memory openclaw`。
+
+adapter 路径不会重新启用你在 enable 之前自己禁用的 `memory-core`，也不会从你之后做出的选择手里抢回 memory slot：如果移除时 `plugins.slots.memory` 已指向其他插件，或你用 `plugins.slots.memory = "none"` 显式关闭了该 slot，`memory-core` 会保持禁用并说明原因。若你的 OpenClaw 配置为不热重载插件配置，则启用或禁用后执行 `openclaw gateway restart`；会热重载的宿主两者都自行生效。
+
+**禁用 `memory-core` 的代价**：这次交接禁用的是整个自带插件，而不只是冲突的那两个工具名。因此只要 agent-memory 处于启用状态，`memory-core` 在这两个名字之外提供的一切都不可用 —— 它自己的 `memory_*` 工具、`openclaw memory` 命令入口，以及该插件在后台运行的 dreaming / consolidation 生命周期。这不是边缘情况：每次 `adapter enable` 都会如此。
+
+这期间检索路径由 agent-memory 承担（见下文「MCP 工具集」与「自动 Consolidation」），但它读写的是 `~/.anolisa/memory`，不是 `memory-core` 自己的存储 —— 所以 `memory-core` 此前积累的内容原封不动，同时也不可访问，要等该插件重新启用后才恢复，且两边的存储不会自动合并。
+
+`anolisa adapter disable agent-memory` 恢复 `memory-core`，前提是满足上面那条让位规则：如果 `plugins.slots.memory` 此后已交给别的后端或被显式关闭，它会保持禁用，需要你自行执行 `openclaw plugins enable memory-core`。与上文同理，不热重载插件配置的宿主需要为任一变更执行 `openclaw gateway restart`。
+
 执行 `anolisa adapter enable agent-memory openclaw` 或 agent-memory 的 OpenClaw `install.sh` 即同意插件声明的能力。两个入口仅在 `plugins install --help` 列出完整的 `--accept-capabilities` 参数时传递它，以兼容旧版宿主。运行 `install.sh` 时设置 `AGENT_MEMORY_ACCEPT_CAPABILITIES=0` 可拒绝授予同意——带门禁的宿主将拒绝安装，直至自行授予（例如交互式执行 `openclaw plugins install`）。
 
 安装期环境变量（运行期 `MEMORY_*` 变量见「环境变量」一节）：

src/agent-memory/.anolisa/component.toml.in

@@ -21,3 +21,20 @@ dest = "{datadir}/adapters/{component}/openclaw/"
 # relying on the driver's "openclaw.plugin.json" default, so the contract is
 # self-describing and survives driver default changes.
 entry = "openclaw.plugin.json"
+# OpenClaw ships a bundled `memory-core` plugin that owns the `memory_get` /
+# `memory_search` tool names, and it stays loaded even after this plugin takes
+# the memory slot — the loader exempts it from slot exclusivity. The
+# framework's tool registry is first-wins, so it drops this adapter's own
+# same-named tools and `memory_get` keeps binding to `memory-core` (#3218).
+# Declaring the displacement makes `anolisa adapter enable agent-memory
+# openclaw` release those names and `adapter disable` hand them back. This is
+# the driver's contract only: the bundle's own install.sh / uninstall.sh script
+# entry point does not read this key and does not perform the hand-off, so a
+# script install still needs `openclaw plugins disable memory-core` by hand.
+# `slot` names the exclusive slot the bundled plugin re-takes when it is
+# re-enabled, so disable steps aside for an operator who moved
+# `plugins.slots.memory` to another backend — or closed the slot outright with
+# `plugins.slots.memory = "none"` — afterwards.
+[[adapters.openclaw.displaces]]
+id = "memory-core"
+slot = "memory"

src/agent-memory/README.md

@@ -28,20 +28,46 @@ sudo yum install agent-memory
 
 ### OpenClaw adapter
 
-The bundled plugin (`memory-anolisa`) is deployed by
-`/usr/share/anolisa/adapters/agent-memory/openclaw/scripts/install.sh`, which
-grants the plugin's declared capabilities by default. Set
-`AGENT_MEMORY_ACCEPT_CAPABILITIES=0` to withhold consent — on hosts that gate
-consent the install then fails until consent is granted interactively. Set
-`AGENT_MEMORY_SAFE_INSTALL=1` to decline the unsafe-install bypass on hosts
-that would still receive one. Full reference:
-[user guide](../../docs/user-guide/en/token-saving/agent-memory.md).
+**Recommended** — the adapter entry point deploys the bundled plugin
+(`memory-anolisa`) *and* performs the tool-name hand-off:
+
+```bash
+anolisa adapter enable agent-memory openclaw
+anolisa adapter status agent-memory
+```
+
+OpenClaw's bundled `memory-core` plugin owns the `memory_get` and
+`memory_search` tool names, and OpenClaw's plugin tool registry is first-wins:
+while `memory-core` stays loaded it keeps those names, so this plugin's own
+same-named tools are dropped and `memory_get` answers from `memory-core` instead
+of from agent-memory. `adapter enable` disables it and records the transition in
+the adapter receipt; `anolisa adapter disable agent-memory` restores it from that
+receipt. Disabling `memory-core` costs more than the two colliding tool names —
+see *What disabling `memory-core` costs* in the user guide.
+
+Or deploy the plugin with the bundled script:
 
 ```bash
 bash /usr/share/anolisa/adapters/agent-memory/openclaw/scripts/install.sh
+openclaw plugins disable memory-core   # the script does NOT do this
 openclaw gateway restart
 ```
 
+`install.sh` deliberately does **not** touch `memory-core`, so after installing
+that way the collision is still there until you disable the plugin yourself
+(`openclaw plugins enable memory-core` undoes it). Only the adapter path records
+the hand-off in a receipt, previews it under `--dry-run`, and reports through
+`adapter status` when the collision later comes back. If your OpenClaw is
+configured not to hot-reload plugin config, run `openclaw gateway restart` after
+enabling or disabling; a hot-reloading host applies both by itself.
+
+The script grants the plugin's declared capabilities by default. Set
+`AGENT_MEMORY_ACCEPT_CAPABILITIES=0` to withhold consent — on hosts that gate
+consent the install then fails until consent is granted interactively. Set
+`AGENT_MEMORY_SAFE_INSTALL=1` to decline the unsafe-install bypass on hosts
+that would still receive one. Full reference:
+[user guide](../../docs/user-guide/en/token-saving/agent-memory.md).
+
 Both optional installer flags are negotiated from `openclaw plugins install
 --help`, but the two switches are not symmetric. `--accept-capabilities` is
 passed only when the host advertises that exact option — current hosts do, so

src/agent-memory/README_zh.md

@@ -28,16 +28,29 @@ sudo yum install agent-memory
 
 ### OpenClaw 适配器
 
-随包附带的插件（`memory-anolisa`）由
-`/usr/share/anolisa/adapters/agent-memory/openclaw/scripts/install.sh` 部署，默认授予插件声明的能力。设置
-`AGENT_MEMORY_ACCEPT_CAPABILITIES=0` 可拒绝授予同意——带门禁的宿主上安装将失败，直至交互式授予。设置
-`AGENT_MEMORY_SAFE_INSTALL=1` 可在仍会传递 unsafe-install 覆盖参数的宿主上拒绝它。完整说明见[用户指南](../../docs/user-guide/zh/token-saving/agent-memory.md)。
+**推荐** —— adapter 入口会部署随包插件（`memory-anolisa`），**并**执行工具名交接：
+
+```bash
+anolisa adapter enable agent-memory openclaw
+anolisa adapter status agent-memory
+```
+
+OpenClaw 自带的 `memory-core` 插件占用 `memory_get` 与 `memory_search` 这两个工具名，而 OpenClaw 的插件工具注册表是「先到先得」：只要 `memory-core` 仍处于加载状态，它就继续持有这两个名字，本插件的同名工具会被丢弃，`memory_get` 也会由 `memory-core` 而非 agent-memory 应答。`adapter enable` 会禁用它，并把这次状态变更记录在适配器 receipt 中；`anolisa adapter disable agent-memory` 依据该 receipt 恢复。禁用 `memory-core` 的代价不止冲突的那两个工具名——详见用户指南的「禁用 `memory-core` 的代价」。
+
+或使用随包脚本部署插件：
 
 ```bash
 bash /usr/share/anolisa/adapters/agent-memory/openclaw/scripts/install.sh
+openclaw plugins disable memory-core   # 脚本不会执行这一步
 openclaw gateway restart
 ```
 
+`install.sh` 刻意**不**处理 `memory-core`，因此以该方式安装后冲突仍然存在，直到你自行禁用该插件（撤销用 `openclaw plugins enable memory-core`）。只有 adapter 路径会把这次交接记录进 receipt、在 `--dry-run` 下预览它，并在冲突日后回归时通过 `adapter status` 报告。若你的 OpenClaw 配置为不热重载插件配置，则启用或禁用后执行 `openclaw gateway restart`；会热重载的宿主两者都自行生效。
+
+脚本默认授予插件声明的能力。设置
+`AGENT_MEMORY_ACCEPT_CAPABILITIES=0` 可拒绝授予同意——带门禁的宿主上安装将失败，直至交互式授予。设置
+`AGENT_MEMORY_SAFE_INSTALL=1` 可在仍会传递 unsafe-install 覆盖参数的宿主上拒绝它。完整说明见[用户指南](../../docs/user-guide/zh/token-saving/agent-memory.md)。
+
 两个可选安装参数都从 `openclaw plugins install --help` 协商，但两个开关并不对称。只有宿主列出完整的 `--accept-capabilities` 时才传递它——当前宿主会列出，因此 `AGENT_MEMORY_ACCEPT_CAPABILITIES` 在这些宿主上仍然会改变 argv：取 `1` 时在 `openclaw plugins install <插件目录> --force` 之后追加 `--accept-capabilities`，取 `0` 时省略它，带同意门禁的宿主随后会拒绝这次安装。只有宿主仍声明 `--dangerously-force-unsafe-install` 有效时才传递该覆盖参数（OpenClaw 2026.6.1 及更早版本）。当前宿主把它标注为 deprecated no-op，两种取值下都不会收到它，因此 `AGENT_MEMORY_SAFE_INSTALL` 在这些宿主上不产生任何差别，安装期安全由运维自有的 `security.installPolicy` 决定。安装日志会说明命中的是哪一种情况。
 
 ### 集成（MCP 客户端）

src/anolisa/crates/anolisa-cli/src/commands/adapter/application.rs

@@ -258,6 +258,8 @@ mod tests {
                 plugin_resource: "plugin".to_string(),
                 skill_resources: Vec::new(),
                 config_resources: Vec::new(),
+
+                displaced_plugins: Vec::new(),
             }),
         }
     }

src/anolisa/crates/anolisa-cli/src/commands/common.rs

@@ -1181,6 +1181,8 @@ mod tests {
                 plugin_resource: "plugin".to_string(),
                 skill_resources: Vec::new(),
                 config_resources: Vec::new(),
+
+                displaced_plugins: Vec::new(),
             }),
         }
     }

src/anolisa/crates/anolisa-cli/src/commands/tier1/forget.rs

@@ -280,6 +280,8 @@ mod tests {
                 plugin_resource: "plugin".to_string(),
                 skill_resources: Vec::new(),
                 config_resources: Vec::new(),
+
+                displaced_plugins: Vec::new(),
             }),
         }
     }

src/anolisa/crates/anolisa-cli/src/commands/tier1/uninstall.rs

@@ -1468,6 +1468,8 @@ mod tests {
                 plugin_resource: "plugin".to_string(),
                 skill_resources: Vec::new(),
                 config_resources: Vec::new(),
+
+                displaced_plugins: Vec::new(),
             }),
         }
     }

src/anolisa/crates/anolisa-cli/tests/forget_dry_run_adapter.rs

@@ -152,6 +152,8 @@ fn sample_claim(component: &str) -> AdapterClaim {
             plugin_resource: "plugin".to_string(),
             skill_resources: Vec::new(),
             config_resources: Vec::new(),
+
+            displaced_plugins: Vec::new(),
         }),
     }
 }

src/anolisa/crates/anolisa-cli/tests/scope_identity.rs

@@ -329,6 +329,8 @@ fn adapter_claim(component: &str) -> AdapterClaim {
             plugin_resource: "plugin".to_string(),
             skill_resources: Vec::new(),
             config_resources: Vec::new(),
+
+            displaced_plugins: Vec::new(),
         }),
     }
 }