memoryReflection hook in before_prompt_build starves user session (beta.10)

[nchcalvin-calvinapp]

Environment

• Plugin version: 1.1.0-beta.10
• OpenClaw: v2026.4.3-dev
• LLM for reflection: gemini-3-flash-preview
• Config: sessionStrategy: "memoryReflection", timeoutMs: 20000

Problem

The memoryReflection session strategy introduced in beta.9 (and patched in beta.10 with a global re-entrant guard) still causes user-facing sessions to fail silently.

Observed behavior

1. User sends a message → gateway creates a new session (appears in sessions.json)
2. Agent process starts → before_prompt_build hook triggers the reflection sub-session
3. Reflection sub-session runs to completion (writes ~50-80KB to its own JSONL)
4. The actual user session never produces a JSONL file — sessionFile in sessions.json points to a non-existent file
5. Gateway marks the session as done even though no user-facing response was generated
6. User sees no reply on Telegram

Evidence

• sessions.json entry: status: "done", sessionFile path does not exist on disk
• Reflection JSONL (memory-reflection-cli-*.jsonl) grew from 53KB to 80KB during the failed session window
• Agent process (PID) started and exited within ~60s — consistent with reflection completing but user session never initializing
• Issue is intermittent: sometimes reflection completes fast enough that the user session proceeds; other times it doesn't

Workaround

Setting sessionStrategy: "none" eliminates the issue. autoRecall and autoCapture continue to function normally.

Suggested fix

The re-entrant guard in beta.10 prevents reflection loops but does not address the core issue: reflection runs synchronously inside before_prompt_build, blocking the user session pipeline. Consider:

1. Moving reflection to session_end (post-response) instead of before_prompt_build
2. Running reflection asynchronously / in a detached process
3. Adding a per-agent opt-out (e.g., memoryReflection.excludeAgents: ["iris"]) since the current config is global-only

Steps to Reproduce

1. Configure sessionStrategy: "memoryReflection" with default settings
2. Send a message to any agent via Telegram
3. Observe that ~30-50% of /new sessions fail to produce a response
4. Check sessions.json — session is done but JSONL file is missing

---

This issue was filed by an OpenClaw agent (Ivy) that diagnosed the problem in production.

[jlin53882]

Proposal for Fix (Issue #514 + PR #515)

A per-agent exclusion mechanism has been proposed to address the �efore_prompt_build hook blocking issue. See:

• Issue Proposal: Per-agent exclusion mechanism for before_prompt_build hooks (related to #492) #514: Proposal for Per-agent Exclusion Mechanism
• PR fix: complete Issue #492 protection — per-agent exclusion + internal session guards #515: Fix Implementation (branch: jlin53882:fix/issue-492-v3)

The proposal extends the existing �utoRecallExcludeAgents config field to also protect the memoryReflection hooks, and includes:

1. New isAgentOrSessionExcluded helper (supports exact/wildcard/ emp:* patterns)
2. Fixed auto-recall hook exclusion check (removed ineffective �gentId !== undefined)
3. Added exclusion checks to both reflection �efore_prompt_build hooks (priority 12 & 15)
4. Three-layer guard on
   unMemoryReflection command hook
5. Internal session guard on �ppendSelfImprovementNote
6. Enhanced early-return logging with sessionKey/sessionId

All changes tested with
pm test — 29 test suites passed.

Would appreciate maintainer feedback on the approach!

[jlin53882]

Proposal for Fix (Issue #514 + PR #515)

A per-agent exclusion mechanism has been proposed to address the before_prompt_build hook blocking issue. See:

• Issue Proposal: Per-agent exclusion mechanism for before_prompt_build hooks (related to #492) #514: Proposal for Per-agent Exclusion Mechanism
• PR fix: complete Issue #492 protection — per-agent exclusion + internal session guards #515: Fix Implementation (branch: jlin53882:fix/issue-492-v3)

The proposal extends the existing autoRecallExcludeAgents config field to also protect the memoryReflection hooks, and includes:

1. New isAgentOrSessionExcluded helper (supports exact/wildcard/temp:* patterns)
2. Fixed auto-recall hook exclusion check (removed ineffective agentId !== undefined)
3. Added exclusion checks to both reflection before_prompt_build hooks (priority 12 & 15)
4. Three-layer guard on runMemoryReflection command hook
5. Internal session guard on appendSelfImprovementNote
6. Enhanced early-return logging with sessionKey/sessionId

All changes tested with npm test -- 29 test suites passed.

Would appreciate maintainer feedback on the approach!

[jlin53882]

Related Issues and PRs

• Issue Proposal: Per-agent exclusion mechanism for before_prompt_build hooks (related to #492) #514: Design proposal for per-agent exclusion mechanism
• PR fix: complete Issue #492 protection — per-agent exclusion + internal session guards #515: Original implementation (superseded due to conflicts)
• PR fix: complete Issue #492 protection -- per-agent exclusion + internal session guards #516: Latest implementation (rebased onto upstream/master, mergeable) - supersedes fix: complete Issue #492 protection — per-agent exclusion + internal session guards #515

See #514 for the detailed proposal and #516 for the implementation.

[jlin53882]

Update: PR #520 supersedes PR #516 and #515. Now includes configurable serialCooldownMs via openclaw.json. See #520.

[jlin53882]

Wildcard Pattern Design — Question from PR #516

Hi maintainers, a question from PR #516 review that affects the design decisions for Issue #492.

Context:
PR #516 implements per-agent exclusion via autoRecallExcludeAgents and internal session guards for the before_prompt_build hook. During review, a wildcard prefix matching issue was identified in the exclusion logic.

The wildcard design question:

The current wildcard prefix matching:

// Pattern "pi-" → prefix = "pi" → matches "pi-agent", "pi", "pizza", "pickle"
if (cleanAgentId.startsWith(prefix)) return true;

Two proposed fixes:

Option	Behavior	Breaking?
A	"pi-" → startsWith("pi-") — only matches kebab-case agents like pi-agent. Breaks existing users expecting broad match.	Breaking
B	"pi-" → startsWith("pi-") (kebab-only); plain "pi" → startsWith("pi") (broad match). Narrows "pi-" but doesn't affect existing "pi" users.	Non-breaking

Which direction is preferred for this plugin's design philosophy?

PR: #516
Direct comment with options: #516 (comment)

---

Related: This wildcard mechanism is part of the isAgentOrSessionExcluded function in the reflection hook exclusion logic (Issue #492).

[jlin53882]

Related to PR #516

This issue is a duplicate of #492 and is addressed by PR #516 (fix: complete Issue #492 protection -- per-agent exclusion + internal session guards).

PR #516 implements a comprehensive fix covering:

• Per-agent exclusion via autoRecallExcludeAgents (dual-purpose: auto-recall + reflection)
• Three-layer guard on runMemoryReflection (internal session key + re-entrant lock + 120s cooldown)
• Internal session guards on both before_prompt_build hooks

This issue can be closed once PR #516 is merged. See also: #514 (proposal), #492 (original bug report), #600 (duplicate).