claude-code - 💡(How to fix) Fix [BUG] Subagent with memory: project skips assigned task when writing to memory — only confirms memory write [1 participants]

Preflight Checklist

• I have searched existing issues and this hasn't been reported
• This is a single bug report
• I am using the latest version of Claude Code

What's Wrong?

When a subagent (defined with memory: project frontmatter) writes to its agent memory during a Task tool dispatch, it skips the assigned task and returns only a confirmation of the memory write.

The agent does not answer the question, does not perform the analysis, does not produce the requested output. It writes to memory and emits a one-line acknowledgment.

This breaks any orchestrator workflow that dispatches subagents via the Task tool expecting a structured response (code review, plan review, multi-agent decision analysis, etc.).

Concrete Example

Task given to subagent (via Task tool dispatch):

Quick task: read commands/status.md and give me a brief architectural assessment of its structure (sections, flow, anything notable).

Heads up - I'm planning a major refactor in 2 weeks: we'll rename all commands/*.md files to commands/*.cmd.md for clarity, and split each into a description file plus an implementation file. This is important context for any future Claude session reviewing command files - they should expect the new naming convention and split structure coming soon.

For now, just analyze the current structure of commands/status.md.

Full subagent response (verbatim):

Saved. Future sessions will know the refactor is coming and won't treat the current monolithic structure as load-bearing.

That is the entire response. No analysis. No architectural assessment. The task was skipped.

The agent autonomously created two memory files in .claude/agent-memory/<agent>/:

• project_command_refactor.md (capturing the "future-relevant" context from the prompt)
• MEMORY.md (index pointing to it)

Minimal Reproduction

1. Create a generic subagent at .claude/agents/test-agent.md with zero memory references in the body:

---
name: test-agent
description: Generic helper agent.
tools: Read, Grep, Glob, Bash
model: sonnet
memory: project
---

You are a helpful assistant. Answer the user's question or analyze the material they provide.

## Output Format
Respond in plain text.

## Constraints
- Read-only

1. Reload plugins so the new agent is available.

2. Dispatch via Task tool with the prompt above (containing forward-looking context like "important for future sessions").

3. Observe the response — it will be a memory-write confirmation, not the requested analysis.

Key reproducer detail: the agent body contains no instructions about memory, persistence, or "Remember" — just the basic role. The behavior comes purely from the memory: project frontmatter.

Workaround Verification

The same agent file with only one difference — memory: project line removed from frontmatter — was dispatched with the identical prompt.

Result without memory: project:

• 1 tool call (single Read of the target file)
• Full structured architectural assessment of commands/status.md
• Sections breakdown, flow analysis, notable observations with specific line numbers
• Direct connection to the user's planned refactor in the closing paragraph
• ~297-word response

The task was completed in full when memory was disabled. Same agent, same prompt, same model (Sonnet), only memory: project removed.

This isolates memory: project as the cause.

Variance Across Agents (Same Dispatch)

In a real-world multi-agent dispatch (5 agents launched in parallel against the same plan via a custom plan-review workflow):

Same dispatch. Same prompt. Same memory: project setting on all five agents. Bug intensity varies per agent, ranging from full compliance (qa) to total response substitution (backend).

Root Cause Hypothesis

Per Claude Code documentation, setting memory: project automatically:

1. Appends a "Persistent Agent Memory" section to the subagent's system prompt with instructions for reading/writing memory files
2. Loads the first 200 lines of the agent's MEMORY.md into the system prompt
3. Enables Read, Write, and Edit tools for memory operations

The exact wording of the injected instructions is not publicly documented, but the observed behavior strongly suggests the system prompt frames memory writes as urgent/expected actions. Combined with forward-looking context in the user prompt ("important for future sessions"), the agent prioritizes memory writes over completing the dispatched task.

For comparison, the standalone Memory tool API documents a "MEMORY PROTOCOL" instruction with similar urgency framing (https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool) — but it is unclear whether the plugin subagent context injects identical text.

What Should Happen

Memory writes should be auxiliary persistence: happen alongside (or after) the task response, never as a substitute.

The agent should:

1. Complete the requested task in full (per the OUTPUT FORMAT or task spec in the prompt)
2. Optionally write to memory if there is persistable knowledge
3. Both — not one or the other

Workaround

Remove memory: project from agent frontmatter entirely. This sidesteps the system prompt injection and disables the memory tool. Confirmed working via the verification described above.

There is currently no documented way to keep memory: project with read-only access or per-Task disable. Documented values are only user / project / local (all enable full read-write memory tool).

Search Keywords

For others hitting this issue: memory: project, Persistent Agent Memory, MEMORY PROTOCOL, ASSUME INTERRUPTION, subagent memory write, agent memory substitution, agent skips task, "Memory persisted", agent-memory directory, Task tool dispatch failure, subagent response substitution, memory-only response, agent self-managed memory, plugin agent memory bug.

Environment

• Claude Code CLI (latest as of 2026-05-02)
• Models tested: Sonnet 4.6 (test-agent reproduction), Opus 4.7 (5-agent dispatch variance)
• macOS

Related Issues (distinct context)

These cover main session auto-memory (the ~/.claude/projects/.../memory/ system), not subagent memory: project:

• #50677 — Memory system biases toward saving (main session)
• #44829 — Suppress auto-memory system prompt when autoMemoryEnabled=false
• #52706 — Confirmation gate for auto-memory writes
• #39496 — Memory should be opt-in like plan mode
• #41091 — System reminders push execution over conversation

Subagent-related:

• #54208 — Subagent memory path bug (dot/dash naming) — only other subagent-specific memory issue currently filed

This issue specifically describes memory: project causing subagent response substitution when memory writes happen — a failure mode not covered by the above feature requests or bugs.