feat: add autoRecallExcludeAgents to suppress memory injection for background agents

[clawdbot520]

Problem

Background agents (e.g. a memory-distiller, cron workers) that receive structured task prompts have their output degraded when <relevant-memories> is injected by the before_agent_start hook.

Concrete failure mode: a memory-distiller agent whose job is to read raw session JSONL and extract new memories receives injected old-memory summaries alongside the fresh session content. The LLM then echoes or recomposes existing memories instead of distilling genuinely new insights. The distilled output is meaningless — it is a paraphrase of what was already known, not a synthesis of what happened in the session.

Why existing skip patterns don't cover this:
The shouldSkipRetrieval() function in adaptive-retrieval.ts handles prompt-level heuristics (HEARTBEAT, cron prefix [cron:…] run …, short greetings, etc.). However custom background-agent prompts that don't match these patterns — for example, a distiller cron whose prompt is Read HEARTBEAT.md if it exists. Follow it strictly… or any other structured instruction — fall through and get injected.

This is the root of the class of issues described in #137.

Solution

Add autoRecallExcludeAgents?: string[] to PluginConfig.

When an agent's ID appears in this list, before_agent_start returns immediately before any embedding call or injection occurs. A single info-level log line is emitted so the skip is observable in gateway logs.

{
  "autoRecall": true,
  "autoRecallExcludeAgents": ["memory-distiller", "my-cron-agent"]
}

What this is NOT

This is not a scope restriction (unlike agentAccess: { "memory-distiller": [] } which works but is undocumented and operates at the store-read level). autoRecallExcludeAgents is a clean, intentional, documented config opt-out at the injection layer.

Changes

File	Change
index.ts	Add autoRecallExcludeAgents?: string[] to PluginConfig interface; early-return guard in before_agent_start; parse in parsePluginConfig
README.md	Add Option B to "injected memories show up in replies" troubleshooting section explaining the use case

Test plan

• Set autoRecallExcludeAgents: ["test-agent"] and verify gateway logs show auto-recall skipped for excluded agent 'test-agent' on cron trigger
• Verify other agents (not in the list) still receive injection normally
• tsc --noEmit passes (confirmed locally)
• Empty string entries in the array are filtered out by parsePluginConfig

Related

• Heartbeat / NO_REPLY turns may still trigger autoRecall injection and cause compaction-related latency #137 — heartbeat/cron agent context bloat from autoRecall injection
• before_agent_start hook 将 XML 元数据块注入到用户消息体中，污染对话历史 #261 — <relevant-memories> appearing in conversation history

🤖 Generated with Claude Code

[AliceLJY]

autoRecallExcludeAgents 这个功能有实际需求，背景 agent 不该被注入记忆。

不过这个 PR 的实现是基于 beta.9 的，有几个问题：

1. hook 路径过时：beta.10 的 auto-recall 已经从 before_agent_start 迁移到 before_prompt_build（index.ts:2149-2167），当前实现接不上。
2. 缺 schema 支持：openclaw.plugin.json 里没有加这个配置项，用户在 UI 里看不到也配不了。
3. 缺测试：需要一个 hook 级回归测试，证明被排除的 agent 确实不会 retrieve 和 inject 记忆。

建议基于最新 master 重写，对齐 before_prompt_build 路径 + 补 schema + 补测试。工作量不大，主要是对齐新的 hook 入口。期待更新 🙏