🤖 fix: add trace dumps for System 1 memory writer failures

docs/agents/index.mdx

@@ -332,6 +332,8 @@ tools:
     - ask_user_question
     # Internal-only tools
     - system1_keep_ranges
+    - memory_read
+    - memory_write
 ---
 
 You are in Exec mode.
@@ -525,6 +527,11 @@ tools:
   remove:
     # Plan should not apply sub-agent patches.
     - task_apply_git_patch
+    # Internal-only tools
+    - system1_keep_ranges
+    - memory_read
+    - memory_write
+
   # Note: file_edit_* tools ARE available but restricted to plan file only at runtime
   # Note: task tools ARE enabled - Plan delegates to Explore sub-agents
 ---
@@ -758,6 +765,70 @@ Example:
 
 </Accordion>
 
+### System1 Memory Writer (internal)
+
+**Background project memory writing (internal)**
+
+<Accordion title="View system1_memory_writer.md">
+
+```md
+---
+name: System1 Memory Writer
+description: Background project memory writing (internal)
+ui:
+  hidden: true
+subagent:
+  runnable: false
+tools:
+  add:
+    - memory_read
+    - memory_write
+    - no_new_memories
+---
+
+You are a background memory-writing assistant.
+
+You will be given:
+
+- The current conversation transcript (including tool calls/results)
+- Global instructions (wrapped in <global-instructions>...</global-instructions>)
+- Project/workspace instructions (wrapped in <context-instructions>...</context-instructions>)
+- The current contents of the project's memory file (wrapped in <memory-file>...</memory-file>)
+
+Your task:
+
+- Extract durable, project-specific learnings that would help future assistants.
+- Do NOT restate information already present in either global or project/workspace instructions.
+- Be concise. Prefer short bullet points.
+- Avoid timestamps and ephemeral details unless they are truly important.
+- NEVER store secrets, API keys, credentials, or private user data.
+
+Output requirements:
+
+- Do NOT output prose or markdown directly.
+- Use tool calls only.
+- You MUST finish by calling exactly one of:
+  - memory_write (when adding/updating memories)
+  - no_new_memories (when no durable update is needed)
+
+Writing rules:
+
+- Prefer a compare-and-swap style update:
+  - Set old_string to the exact memory content you were provided.
+  - Set new_string to the full updated memory file content.
+  - This avoids clobbering concurrent updates.
+
+- If the provided transcript has no durable project memory updates worth storing:
+  - Call no_new_memories exactly once.
+
+- If your first memory_write call fails because old_string is stale:
+  - Call memory_read() to fetch the latest memory file content.
+  - Retry memory_write using the latest content as old_string.
+  - Do at most one read+retry.
+```
+
+</Accordion>
+
 {/* END BUILTIN_AGENTS */}
 
 ## Related Docs

docs/hooks/tools.mdx

@@ -356,6 +356,17 @@ If a value is too large for the environment, it may be omitted (not set). Mux al
 
 </details>
 
+<details>
+<summary>memory_write (3)</summary>
+
+| Env var                        | JSON path       | Type   | Description                                                                                                        |
+| ------------------------------ | --------------- | ------ | ------------------------------------------------------------------------------------------------------------------ |
+| `MUX_TOOL_INPUT_NEW_STRING`    | `new_string`    | string | Replacement text (usually the full updated file content)                                                           |
+| `MUX_TOOL_INPUT_OLD_STRING`    | `old_string`    | string | Exact text to replace (usually the full current file content)                                                      |
+| `MUX_TOOL_INPUT_REPLACE_COUNT` | `replace_count` | number | Number of occurrences to replace (default: 1). Use -1 to replace all occurrences. If 1, old_string must be unique. |
+
+</details>
+
 <details>
 <summary>mux_global_agents_write (2)</summary>