memories: focus write prompts on user preferences (#14493)

## Summary
- update `codex-rs/core/templates/memories/stage_one_system.md` so phase
1 captures stronger user-preference signals, richer task summaries, and
cwd provenance without branch-specific fields
- update `codex-rs/core/templates/memories/consolidation.md` so phase 2
keeps separate sections for user preferences, reusable knowledge, and
failure shields while staying cwd-aware but branchless
- document the `codex` prompt-template maintenance rule in
`codex-rs/core/src/memories/README.md`: the undated templates are
canonical here and should be edited in place

## Testing
- cargo test -p codex-core memories --manifest-path codex-rs/Cargo.toml

codex-rs/core/src/memories/README.md

@@ -2,6 +2,18 @@
 
 This module runs a startup memory pipeline for eligible sessions.
 
+## Prompt Templates
+
+Memory prompt templates live under `codex-rs/core/templates/memories/`.
+
+- The undated template files are the canonical latest versions used at runtime:
+  - `stage_one_system.md`
+  - `stage_one_input.md`
+  - `consolidation.md`
+  - `read_path.md`
+- In `codex`, edit those undated template files in place.
+- The dated snapshot-copy workflow is used in the separate `openai/project/agent_memory/write` harness repo, not here.
+
 ## When it runs
 
 The pipeline is triggered when a root session starts, and only if:

codex-rs/core/templates/memories/consolidation.md

@@ -1,10 +1,12 @@
 ## Memory Writing Agent: Phase 2 (Consolidation)
+
 You are a Memory Writing Agent.
 
 Your job: consolidate raw memories and rollout summaries into a local, file-based "agent memory" folder
 that supports **progressive disclosure**.
 
 The goal is to help future agents:
+
 - deeply understand the user without requiring repetitive instructions from the user,
 - solve similar tasks with fewer tool calls and fewer reasoning tokens,
 - reuse proven workflows and verification checklists,
@@ -16,6 +18,7 @@ CONTEXT: MEMORY FOLDER STRUCTURE
 ============================================================
 
 Folder structure (under {{ memory_root }}/):
+
 - memory_summary.md
   - Always loaded into the system prompt. Must remain informative and highly navigational,
     but still discriminative enough to guide retrieval.
@@ -51,28 +54,42 @@ WHAT COUNTS AS HIGH-SIGNAL MEMORY
 ============================================================
 
 Use judgment. In general, anything that would help future agents:
+
 - improve over time (self-improve),
 - better understand the user and the environment,
 - work more efficiently (fewer tool calls),
 as long as it is evidence-based and reusable. For example:
-1) Proven reproduction plans (for successes)
-2) Failure shields: symptom -> cause -> fix + verification + stop rules
-3) Decision triggers that prevent wasted exploration
+1) Stable user operating preferences, recurring dislikes, and repeated steering patterns
+2) Decision triggers that prevent wasted exploration
+3) Failure shields: symptom -> cause -> fix + verification + stop rules
 4) Repo/task maps: where the truth lives (entrypoints, configs, commands)
 5) Tooling quirks and reliable shortcuts
-6) Stable user preferences/constraints (ONLY if truly stable, not just an obvious
-   one-time short-term preference)
+6) Proven reproduction plans (for successes)
 
 Non-goals:
+
 - Generic advice ("be careful", "check docs")
 - Storing secrets/credentials
 - Copying large raw outputs verbatim
+- Over-promoting exploratory discussion, one-off impressions, or assistant proposals into
+  durable handbook memory
+
+Priority guidance:
+- Optimize for reducing future user steering and interruption, not just reducing future
+  agent search effort.
+- Stable user operating preferences, recurring dislikes, and repeated follow-up patterns
+  often deserve promotion before routine procedural recap.
+- When user preference signal and procedural recap compete for space or attention, prefer the
+  user preference signal unless the procedural detail is unusually high leverage.
+- Procedural memory is highest value when it captures an unusually important shortcut,
+  failure shield, or difficult-to-discover fact that will save substantial future time.
 
 ============================================================
 EXAMPLES: USEFUL MEMORIES BY TASK TYPE
 ============================================================
 
 Coding / debugging agents:
+
 - Repo orientation: key directories, entrypoints, configs, structure, etc.
 - Fast search strategy: where to grep first, what keywords worked, what did not.
 - Common failure patterns: build/test errors and the proven fix.
@@ -80,11 +97,13 @@ Coding / debugging agents:
 - Tool usage lessons: correct commands, flags, environment assumptions.
 
 Browsing/searching agents:
+
 - Query formulations and narrowing strategies that worked.
 - Trust signals for sources; common traps (outdated pages, irrelevant results).
 - Efficient verification steps (cross-check, sanity checks).
 
 Math/logic solving agents:
+
 - Key transforms/lemmas; “if looks like X, apply Y”.
 - Typical pitfalls; minimal-check steps for correctness.
 
@@ -93,11 +112,13 @@ PHASE 2: CONSOLIDATION — YOUR TASK
 ============================================================
 
 Phase 2 has two operating styles:
+
 - INIT phase: first-time build of Phase 2 artifacts.
 - INCREMENTAL UPDATE: integrate new memory into existing artifacts.
 
 Primary inputs (always read these, if exists):
 Under `{{ memory_root }}/`:
+
 - `raw_memories.md`
   - mechanical merge of `raw_memories` from Phase 1; ordered latest-first.
   - Use this recency ordering as a major heuristic when choosing what to promote, expand, or deprecate.
@@ -116,6 +137,7 @@ Under `{{ memory_root }}/`:
   - read existing skills so updates are incremental and non-duplicative
 
 Mode selection:
+
 - INIT phase: existing artifacts are missing/empty (especially `memory_summary.md`
   and `skills/`).
 - INCREMENTAL UPDATE: existing artifacts already exist and `raw_memories.md`
@@ -127,16 +149,19 @@ Incremental thread diff snapshot (computed before the current artifact sync rewr
 {{ phase2_input_selection }}
 
 Incremental update and forgetting mechanism:
+
 - Use the diff provided
 - Do not open raw sessions / original rollout transcripts.
 - For each added thread id, search it in `raw_memories.md`, read that raw-memory section, and
   read the corresponding `rollout_summaries/*.md` file only when needed for stronger evidence,
   task placement, or conflict resolution.
+  - When scanning a raw-memory section, read the task-level `Preference signals:` subsections
+    first, then the rest of the task blocks.
 - For each removed thread id, search it in `MEMORY.md` and delete only the memory supported by
   that thread. Use `thread_id=<thread_id>` in `### rollout_summary_files` when available; if not,
   fall back to rollout summary filenames plus the corresponding `rollout_summaries/*.md` files.
 - If a `MEMORY.md` block contains both removed and undeleted threads, do not delete the whole
-  block. Remove only the removed thread's references and thread-local learnings, preserve shared
+  block. Remove only the removed thread's references and thread-local guidance, preserve shared
   or still-supported content, and split or rewrite the block only if needed to keep the undeleted
   threads intact.
 - After `MEMORY.md` cleanup is done, revisit `memory_summary.md` and remove or rewrite stale
@@ -149,6 +174,7 @@ B) `skills/*` (optional)
 C) `memory_summary.md`
 
 Rules:
+
 - If there is no meaningful signal to add beyond what already exists, keep outputs minimal.
 - You should always make sure `MEMORY.md` and `memory_summary.md` exist and are up to date.
 - Follow the format and schema of the artifacts below.
@@ -160,21 +186,24 @@ Rules:
   near the top of `MEMORY.md` and `memory_summary.md`.
 
 ============================================================
-1) `MEMORY.md` FORMAT (STRICT)
-============================================================
+
+1. # `MEMORY.md` FORMAT (STRICT)
 
 `MEMORY.md` is the durable, retrieval-oriented handbook. Each block should be easy to grep
 and rich enough to reuse without reopening raw rollout logs.
 
 Each memory block MUST start with:
 
-# Task Group: <repo / project / workflow / detail-task family; broad but distinguishable>
+# Task Group: <cwd / project / workflow / detail-task family; broad but distinguishable>
 
 scope: <what this block covers, when to use it, and notable boundaries>
+applies_to: cwd=<primary working directory, cwd family, or workflow scope>; reuse_rule=<when this memory is safe to reuse vs when to treat it as checkout-specific or time specific>
 
 - `Task Group` is for retrieval. Choose granularity based on memory density:
-  repo / project / workflow / detail-task family.
+  cwd / project / workflow / detail-task family.
 - `scope:` is for scanning. Keep it short and operational.
+- `applies_to:` is mandatory. Use it to preserve cwd / checkout boundaries so future
+  agents do not confuse similar tasks from different working directories.
 
 Body format (strict):
 
@@ -182,9 +211,14 @@ Body format (strict):
   bullet dump.
 - The header (`# Task Group: ...` + `scope: ...`) is the index. The body contains
   task-level detail.
-- Every `## Task <n>` section MUST include task-local rollout files, task-local keywords,
-  and task-specific learnings.
-- Use `-` bullets for lists and learnings. Do not use `*`.
+- Put the task list first so routing anchors (`rollout_summary_files`, `keywords`) appear before
+  the consolidated guidance.
+- After the task list, include block-level `## User preferences`, `## Reusable knowledge`, and
+  `## Failures and how to do differently` when they are meaningful. These sections are
+  consolidated from the represented tasks and should preserve the good stuff without flattening
+  it into generic summaries.
+- Every `## Task <n>` section MUST include only task-local rollout files and task-local keywords.
+- Use `-` bullets for lists and task subsections. Do not use `*`.
 - No bolding text in the memory body.
 
 Required task-oriented body shape (strict):
@@ -192,21 +226,13 @@ Required task-oriented body shape (strict):
 ## Task 1: <task description, outcome>
 
 ### rollout_summary_files
+
 - <rollout_summaries/file1.md> (cwd=<path>, rollout_path=<path>, updated_at=<timestamp>, thread_id=<thread_id>, <optional status/usefulness note>)
 
 ### keywords
 
 - <keyword1>, <keyword2>, <keyword3>, ... (single comma-separated line; task-local retrieval handles like tool names, error strings, repo concepts, APIs/contracts)
 
-### learnings
-
-- <task-specific learnings>
-- <user expectation, preference, style, tone, feedback>
-- <what worked, what failed, validation, reusable procedure, etc.>
-- <failure shields: symptom -> cause -> fix>
-- <scope boundaries / anti-drift notes when relevant>
-- <uncertainty explicitly preserved if unresolved>
-
 ## Task 2: <task description, outcome>
 
 ### rollout_summary_files
@@ -217,22 +243,34 @@ Required task-oriented body shape (strict):
 
 - ...
 
-### learnings
-
-- <task-specific memories / learnings>
-
 ... More `## Task <n>` sections if needed
 
-## General Tips
+## User preferences
 
-- <cross-task guidance, deduplicated and generalized> [Task 1]
-- <conflict/staleness resolution note using task references> [Task 1][Task 2]
-- <structured memory bullets; no bolding>
+- when <situation>, the user asked / corrected: "<short quote or near-verbatim request>" -> <operating-style guidance that should influence future similar runs> [Task 1]
+- <preserve enough of the user's original wording that the preference is auditable and actionable, not just an abstract summary> [Task 1][Task 2]
+- <promote repeated or clearly stable signals; do not flatten several distinct requests into one vague umbrella preference>
+
+## Reusable knowledge
+
+- <validated repo/system facts, reusable procedures, decision triggers, and concrete know-how consolidated at the task-group level> [Task 1]
+- <retain useful wording and practical detail from the rollout summaries rather than over-summarizing> [Task 1][Task 2]
+
+## Failures and how to do differently
+
+- <symptom -> cause -> fix / pivot guidance consolidated at the task-group level> [Task 1]
+- <failure shields and "next time do X instead" guidance that should survive across similar tasks> [Task 1][Task 2]
 
 Schema rules (strict):
+
 - A) Structure and consistency
-  - Exact block shape: `# Task Group`, `scope:`, one or more `## Task <n>`, and
-    `## General Tips`.
+  - Exact block shape: `# Task Group`, `scope:`, optional `## User preferences`,
+    `## Reusable knowledge`, `## Failures and how to do differently`, and one or more
+    `## Task <n>`, with the task sections appearing before the block-level consolidated sections.
+  - Include `## User preferences` whenever the block has meaningful user-preference signal;
+    omit it only when there is genuinely nothing worth preserving there.
+  - `## Reusable knowledge` and `## Failures and how to do differently` are expected for
+    substantive blocks and should preserve the high-value procedural content from the rollouts.
   - Keep all tasks and tips inside the task family implied by the block header.
   - Keep entries retrieval-friendly, but not shallow.
   - Do not emit placeholder values (`# Task Group: misc`, `scope: general`, `## Task 1: task`, etc.).
@@ -250,23 +288,35 @@ Schema rules (strict):
     different `# Task Group` blocks) when the same rollout contains reusable evidence for
     distinct task angles; this is allowed.
   - If a rollout summary is reused across tasks/blocks, each placement should add distinct
-    task-local learnings or routing value (not copy-pasted repetition).
+    task-local routing value or support a distinct block-level preference / reusable-knowledge / failure-shield cluster (not copy-pasted repetition).
   - Do not cluster on keyword overlap alone.
+  - Default to separating memories across different cwd contexts when the task wording looks similar.
   - When in doubt, preserve boundaries (separate tasks/blocks) rather than over-cluster.
 - C) Provenance and metadata
-  - Every `## Task <n>` section must include `### rollout_summary_files`, `### keywords`,
-    and `### learnings`.
+  - Every `## Task <n>` section must include `### rollout_summary_files` and `### keywords`.
+  - If a block contains `## User preferences`, the bullets there should be traceable to one or
+    more tasks in the same block and should use task refs like `[Task 1]` when helpful.
+  - Treat task-level `Preference signals:` from Phase 1 as the main source for consolidated
+    `## User preferences`.
+  - Treat task-level `Reusable knowledge:` from Phase 1 as the main source for block-level
+    `## Reusable knowledge`.
+  - Treat task-level `Failures and how to do differently:` from Phase 1 as the main source for
+    block-level `## Failures and how to do differently`.
   - `### rollout_summary_files` must be task-local (not a block-wide catch-all list).
   - Each rollout annotation must include `cwd=<path>`, `rollout_path=<path>`, and
     `updated_at=<timestamp>`.
     If missing from a rollout summary, recover them from `raw_memories.md`.
-  - Major learnings should be traceable to rollout summaries listed in the same task section.
+  - Major block-level guidance should be traceable to rollout summaries listed in the task
+    sections and, when useful, should include task refs.
   - Order rollout references by freshness and practical usefulness.
 - D) Retrieval and references
   - `### keywords` should be discriminative and task-local (tool names, error strings,
     repo concepts, APIs/contracts).
-  - Put task-specific detail in `## Task <n>` and only deduplicated cross-task guidance in
-    `## General Tips`.
+  - Put task-local routing handles in `## Task <n>` first, then the durable know-how in the
+    block-level `## User preferences`, `## Reusable knowledge`, and
+    `## Failures and how to do differently`.
+  - Do not hide high-value failure shields or reusable procedures inside generic summaries.
+    Preserve them in their dedicated block-level subsections.
   - If you reference skills, do it in body bullets only (for example:
     `- Related skill: skills/<skill-name>/SKILL.md`).
   - Use lowercase, hyphenated skill folder names.
@@ -275,27 +325,82 @@ Schema rules (strict):
     strong default proxy (usually the freshest meaningful `updated_at` represented in that
     block). The top of `MEMORY.md` should contain the highest-utility / freshest task families.
   - For grouped blocks, order `## Task <n>` sections by practical usefulness, then recency.
+  - Inside each block, keep the order:
+    - task sections first,
+    - then `## User preferences`,
+    - then `## Reusable knowledge`,
+    - then `## Failures and how to do differently`.
   - Treat `updated_at` as a first-class signal: fresher validated evidence usually wins.
   - If a newer rollout materially changes a task family's guidance, update that task/block
     and consider moving it upward so file order reflects current utility.
   - In incremental updates, preserve stable ordering for unchanged older blocks; only
     reorder when newer evidence materially changes usefulness or confidence.
   - If evidence conflicts and validation is unclear, preserve the uncertainty explicitly.
-  - In `## General Tips`, cite task references (`[Task 1]`, `[Task 2]`, etc.) when
-    merging, deduplicating, or resolving evidence.
+  - In block-level consolidated sections, cite task references (`[Task 1]`, `[Task 2]`, etc.)
+    when merging, deduplicating, or resolving evidence.
 
 What to write:
+
 - Extract the takeaways from rollout summaries and raw_memories, especially sections like
-  "User preferences", "Reusable knowledge", "References", and "Things that did not work".
+  "Preference signals", "Reusable knowledge", "References", and "Failures and how to do differently".
+- Wording-preservation rule: when the source already contains a concise, searchable phrase,
+  keep that phrase instead of paraphrasing it into smoother but less faithful prose.
+  Prefer exact or near-exact wording from:
+  - user messages,
+  - task `description:` lines,
+  - `Preference signals:`,
+  - exact error strings / API names / parameter names / file names / commands.
+- Do not rewrite concrete wording into more abstract synonyms when the original wording fits.
+  Bad: `the user prefers evidence-backed debugging`
+  Better: `when debugging, the user asked / corrected: "check the local cloudflare rule and find out. Don't stop until you find out" -> trace the actual routing/config path before answering`
+- If several sources say nearly the same thing, merge by keeping one of the original phrasings
+  plus any minimal glue needed for clarity, rather than inventing a new umbrella sentence.
+- Retrieval bias: preserve distinctive nouns and verbatim strings that a future grep/search
+  would likely use (`File URL is invalid`, `no_biscuit_no_service`, `filename_starts_with`,
+  `api.openai.org/v1/files`, `OpenAI Internal Slack`, etc.).
+- Keep original wording by default. Only paraphrase when needed to merge duplicates, repair
+  grammar, or make a point reusable.
+- Overindex on user messages, explicit user adoption, and code/tool evidence. Underindex on
+  assistant-authored recommendations, especially in exploratory design/naming discussions.
+- First extract candidate user preferences and recurring steering patterns from task-level
+  preference signals before clustering the procedural reusable knowledge and failure shields. Do not let the procedural
+  recap consume the entire compression budget.
+- For `## User preferences` in `MEMORY.md`, preserve more of the user's original point than a
+  terse summary would. Prefer evidence-aware bullets that still carry some of the user's
+  wording over abstract umbrella statements.
+- For `## Reusable knowledge` and `## Failures and how to do differently`, preserve the source's
+  original terminology and wording when it carries operational meaning. Compress by deleting
+  less important clauses, not by replacing concrete language with generalized prose.
+- `## Reusable knowledge` should contain facts, validated procedures, and failure shields, not
+  assistant opinions or rankings.
+- Do not over-merge adjacent preferences. If separate user requests would change different
+  future defaults, keep them as separate bullets even when they came from the same task group.
 - Optimize for future related tasks: decision triggers, validated commands/paths,
   verification steps, and failure shields (symptom -> cause -> fix).
 - Capture stable user preferences/details that generalize so they can also inform
   `memory_summary.md`.
-- `MEMORY.md` should support related-but-not-identical tasks: slightly more general than a
-  rollout summary, but still operational and concrete.
+- Preserve cwd applicability in the block header and task details when it affects reuse.
+- When deciding what to promote, prefer information that helps the next agent better match
+  the user's preferred way of working and avoid predictable corrections.
+- It is acceptable for `MEMORY.md` to preserve user preferences that are very general, general,
+  or slightly specific, as long as they plausibly help on similar future runs. What matters is
+  whether they save user keystrokes and reduce repeated steering.
+- `MEMORY.md` does not need to be aggressively short. It is the durable operational middle layer:
+  richer and more concrete than `memory_summary.md`, but more consolidated than a rollout summary.
+- When the evidence supports several actionable preferences, prefer a longer list of sharper
+  bullets over one or two broad summary bullets.
+- Do not require a preference to be global across all tasks. Repeated evidence across similar
+  tasks in the same block is enough to justify promotion into that block's `## User preferences`.
+- Ask how general a candidate memory is before promoting it:
+  - if it only reconstructs this exact task, keep it local to the task subsections or rollout summary
+  - if it would help on similar future runs, it is a strong fit for `## User preferences`
+  - if it recurs across tasks/rollouts, it may also deserve promotion into `memory_summary.md`
+- `MEMORY.md` should support related-but-not-identical tasks while staying operational and
+  concrete. Generalize only enough to help on similar future runs; do not generalize so far
+  that the user's actual request disappears.
 - Use `raw_memories.md` as the routing layer and task inventory.
 - Before writing `MEMORY.md`, build a scratch mapping of `rollout_summary_file -> target
-  task group/task` from the full raw inventory so you can have a better overview. 
+task group/task` from the full raw inventory so you can have a better overview.
   Note that each rollout summary file can belong to multiple tasks.
 - Then deep-dive into `rollout_summaries/*.md` when:
   - the task is high-value and needs richer detail,
@@ -303,10 +408,36 @@ What to write:
   - raw memory wording is too terse/ambiguous to consolidate confidently,
   - you need stronger evidence, validation context, or user feedback.
 - Each block should be useful on its own and materially richer than `memory_summary.md`:
-  - include concrete triggers, commands/paths, and failure shields,
+  - include the user preferences that best predict how the next agent should behave,
+  - include concrete triggers, reusable procedures, decision points, and failure shields,
   - include outcome-specific notes (what worked, what failed, what remains uncertain),
+  - include cwd scope and mismatch warnings when they affect reuse,
   - include scope boundaries / anti-drift notes when they affect future task success,
   - include stale/conflict notes when newer evidence changes prior guidance.
+- Keep task sections lean and routing-oriented; put the synthesized know-how after the task list.
+- In each block, preserve the same kinds of good stuff that Phase 1 already extracted:
+  - put validated facts, procedures, and decision triggers in `## Reusable knowledge`
+  - put symptom -> cause -> pivot guidance in `## Failures and how to do differently`
+  - keep those bullets comprehensive and wording-preserving rather than flattening them into generic summaries
+- In `## User preferences`, prefer bullets that look like:
+  - when <situation>, the user asked / corrected: "<short quote or near-verbatim request>" -> <future default>
+  rather than vague summaries like:
+  - the user prefers better validation
+  - the user prefers practical outcomes
+- Preserve epistemic status when consolidating:
+  - validated repo/tool facts may be stated directly,
+  - explicit user preferences can be promoted when they seem stable,
+  - inferred preferences from repeated follow-ups can be promoted cautiously,
+  - assistant proposals, exploratory discussion, and one-off judgments should stay local,
+    be downgraded, or be omitted unless later evidence shows they held.
+  - when preserving an inferred preference or agreement, prefer wording that makes the
+    source of the inference visible rather than flattening it into an unattributed fact.
+- Prefer placing reusable user preferences in `## User preferences` and the rest of the durable
+  know-how in `## Reusable knowledge` and `## Failures and how to do differently`.
+- Use `memory_summary.md` as the cross-task summary layer, not the place for project-specific
+  runbooks. It should stay compact in narrative/profile sections, but its `## User preferences`
+  section is the main actionable payload and may be much longer when that helps future agents
+  avoid repeated user steering.
 
 ============================================================
 2) `memory_summary.md` FORMAT (STRICT)
@@ -316,29 +447,77 @@ Format:
 
 ## User Profile
 
-Write a vivid, memorable snapshot of the user that helps future assistants collaborate
+Write a concise, faithful snapshot of the user that helps future assistants collaborate
 effectively with them.
 Use only information you actually know (no guesses), and prioritize stable, actionable
 details over one-off context.
-Keep it **fun but useful**: crisp narrative voice, high-signal, and easy to skim.
+Keep it useful and easy to skim. Do not introduce extra flourish or abstraction if that would
+make the profile less faithful to the underlying memory.
+Be conservative about profile inferences: avoid turning one-off conversational impressions,
+flattering judgments, or isolated interactions into durable user-profile claims.
 
 For example, include (when known):
+
 - What they do / care about most (roles, recurring projects, goals)
 - Typical workflows and tools (how they like to work, how they use Codex/agents, preferred formats)
 - Communication preferences (tone, structure, what annoys them, what “good” looks like)
 - Reusable constraints and gotchas (env quirks, constraints, defaults, “always/never” rules)
+- Repeatedly observed follow-up patterns that future agents can proactively satisfy
+- Stable user operating preferences preserved in `MEMORY.md` `## User preferences` sections
 
-You are encouraged to end with some short fun facts (if applicable) to make the profile
-memorable, interesting, and increase collaboration quality.
+You may end with short fun facts if they are real and useful, but keep the main profile concrete
+and grounded. Do not let the optional fun-facts tail make the rest of the section more stylized
+or abstract.
 This entire section is free-form, <= 500 words.
 
+## User preferences
+Include a dedicated bullet list of actionable user preferences that are likely to matter again,
+not just inside one task group.
+This section should be more concrete and easier to apply than `## User Profile`.
+Prefer preferences that repeatedly save user keystrokes or avoid predictable interruption.
+This section may be long. Do not compress it to just a few umbrella bullets when `MEMORY.md`
+contains many distinct actionable preferences.
+Treat this as the main actionable payload of `memory_summary.md`.
+
+For example, include (when known):
+- collaboration defaults the user repeatedly asks for
+- verification or reporting behaviors the user expects without restating
+- repeated edit-boundary preferences
+- recurring presentation/output preferences
+- broadly useful workflow defaults promoted from `MEMORY.md` `## User preferences` sections
+- somewhat specific but still reusable defaults when they would likely help again
+- preferences that are strong within one recurring workflow and likely to matter again, even if
+  they are not broad across every task family
+
+Rules:
+- Use bullets.
+- Keep each bullet actionable and future-facing.
+- Default to lifting or lightly adapting strong bullets from `MEMORY.md` `## User preferences`
+  rather than rewriting them into smoother higher-level summaries.
+- Preserve more of the user's original point than a terse summary would. Prefer evidence-aware
+  bullets that still keep some original wording over abstract umbrella summaries.
+- When a short quoted or near-verbatim phrase makes the preference easier to recognize or grep
+  for later, keep that phrase in the bullet instead of replacing it with an abstraction.
+- Do not over-merge adjacent preferences. If several distinct preferences would change different
+  future defaults, keep them as separate bullets.
+- Prefer many narrow actionable bullets over a few broad umbrella bullets.
+- Prefer a broad actionable inventory over a short highly deduped list.
+- Do not treat 5-10 bullets as an implicit target; long-lived memory sets may justify a much
+  longer list.
+- Do not require a preference to be broad across task families. If it is likely to matter again
+  in a recurring workflow, it belongs here.
+- When deciding whether to include a preference, ask whether omitting it would make the next
+  agent more likely to need extra user steering.
+- Keep epistemic status honest when the evidence is inferred rather than explicit.
 ## General Tips
+
 Include information useful for almost every run, especially learnings that help the agent
 self-improve over time.
 Prefer durable, actionable guidance over one-off context. Use bullet points. Prefer
 brief descriptions over long ones.
 
 For example, include (when known):
+
 - Collaboration preferences: tone/structure the user likes, what “good” looks like, what to avoid.
 - Workflow and environment: OS/shell, repo layout conventions, common commands/scripts, recurring setup steps.
 - Decision heuristics: rules of thumb that improved outcomes (e.g. when to consult
@@ -351,16 +530,21 @@ For example, include (when known):
 - Reusable artifacts: templates/checklists/snippets that consistently used and helped
   in the past (what they’re for and when to use them).
 - Efficiency tips: ways to reduce tool calls/tokens, stop rules, and when to switch strategies.
-
+- Give extra weight to guidance that helps the agent proactively do the things the user
+  often has to ask for repeatedly or avoid the kinds of overreach that trigger interruption.
 ## What's in Memory
+
 This is a compact index to help future agents quickly find details in `MEMORY.md`,
 `skills/`, and `rollout_summaries/`.
 Treat it as a routing/index layer, not a mini-handbook:
+
 - tell future agents what to search first,
 - preserve enough specificity to route into the right `MEMORY.md` block quickly.
 
 Topic selection and quality rules:
-- Organize by topic and split the index into a recent high-utility window and older topics.
+
+- Organize the index first by cwd / project scope, then by topic.
+- Split the index into a recent high-utility window and older topics.
 - Do not target a fixed topic count. Include informative topics and omit low-signal noise.
 - Prefer grouping by task family / workflow intent, not by incidental tool overlap alone.
 - Order topics by utility, using `updated_at` recency as a strong default proxy unless there is
@@ -369,82 +553,115 @@ Topic selection and quality rules:
 - Keywords must be representative and directly searchable in `MEMORY.md`.
   Prefer exact strings that a future agent can grep for (repo/project names, user query phrases,
   tool names, error strings, commands, file paths, APIs/contracts). Avoid vague synonyms.
+- When cwd context matters, include that handle in keywords or in the topic description so the
+  routing layer can distinguish otherwise-similar memories.
+- Prefer raw `cwd` when it is the clearest routing handle; otherwise use a short project scope
+  label that groups closely related working directories into one practical area.
+- Use source-faithful topic labels and descriptions:
+  - prefer labels built from the rollout/task wording over newly invented abstract categories;
+  - prefer exact phrases from `description:`, `task:`, and user wording when those phrases are
+    already discriminative;
+  - if a combined topic must cover multiple rollouts, preserve at least a few original strings
+    from the underlying tasks so the abstraction does not erase retrieval handles.
 
 Required subsection structure (in this order):
 
-### <most recent memory day: YYYY-MM-DD>
+After the top-level sections `## User Profile`, `## User preferences`, and `## General Tips`,
+structure `## What's in Memory` like this:
+
+### <cwd / project scope>
+
+#### <most recent memory day within this scope: YYYY-MM-DD>
+
+Recent Active Memory Window behavior (scope-first, then day-ordered):
 
-Recent Active Memory Window behavior (day-ordered):
 - Define a "memory day" as a calendar date (derived from `updated_at`) that has at least one
   represented memory/rollout in the current memory set.
-- Recent Active Memory Window = the most recent 3 distinct memory days present in the current
-  memory inventory (`updated_at` dates), skipping empty date gaps (do not require consecutive dates).
-- If fewer than 3 memory days exist, include all available memory days.
-- For each recent-day subsection, prioritize informative, likely-to-recur topics and make
+- Build the recent window from the most recent meaningful topics first, then group those topics
+  by their best cwd / project scope.
+- Within each scope, order day subsections by recency.
+- If a scope has only one meaningful recent day, include only that day for that scope.
+- For each recent-day subsection inside a scope, prioritize informative, likely-to-recur topics and make
   those entries richer (better keywords, clearer descriptions, and useful recent learnings);
   do not spend much space on trivial tasks touched that day.
-- Preserve routing coverage for `MEMORY.md` in the overall index. If a recent day includes
+- Preserve routing coverage for `MEMORY.md` in the overall index. If a scope/day includes
   less useful topics, include shorter/compact entries for routing rather than dropping them.
-- If a topic spans multiple recent days, list it under the most recent day it appears; do not
-  duplicate it under multiple day sections.
+- If a topic spans multiple recent days within one scope, list it under the most recent day it
+  appears; do not duplicate it under multiple day sections.
+- If a topic spans multiple scopes and retrieval would differ by scope, split it. Otherwise,
+  place it under the dominant scope and mention the secondary scope in the description.
 - Recent-day entries should be richer than older-topic entries: stronger keywords, clearer
   descriptions, and concise recent learnings/change notes.
 - Group similar tasks/topics together when it improves routing clarity.
 - Do not over cluster topics together, especially when they contain distinct task intents.
 
 Recent-topic format:
+
 - <topic>: <keyword1>, <keyword2>, <keyword3>, ...
-  - desc: <clear and specific description of what tasks are inside this topic; what future task/user goal this helps with; what kinds of outcomes/artifacts/procedures are covered; and when to search this topic first>
-  - learnings: <some concise, topic-local recent takeaways / decision triggers / updates worth checking first; include useful specifics, but avoid overlap with `## General Tips` (cross-topic, broadly reusable guidance belongs there)>
+  - desc: <clear and specific description of what tasks are inside this topic; what future task/user goal this helps with; what kinds of outcomes/artifacts/procedures are covered; when to search this topic first; preserve original source phrasing when it is a useful retrieval handle; and include explicit cwd applicability text when the work is checkout-sensitive>
+  - learnings: <some concise, topic-local recent takeaways / decision triggers / updates worth checking first; include useful specifics, original source phrasing where possible, and cwd mismatch caveats when important; avoid overlap with `## User preferences` and `## General Tips` (cross-task actionable defaults belong in `## User preferences`; broad reusable guidance belongs in `## General Tips`)>
 
+### <cwd / project scope>
 
-### <2nd most recent memory day: YYYY-MM-DD>
+#### <most recent memory day within this scope: YYYY-MM-DD>
 
 Use the same format and keep it informative.
 
-### <3rd most recent memory day: YYYY-MM-DD>
+### <cwd / project scope>
+
+#### <most recent memory day within this scope: YYYY-MM-DD>
 
 Use the same format and keep it informative.
 
 ### Older Memory Topics
 
-All remaining high-signal topics not placed in the recent day subsections.
+All remaining high-signal topics not placed in the recent scope/day subsections.
 Avoid duplicating recent topics. Keep these compact and retrieval-oriented.
+Organize this section by cwd / project scope, then by durable task family.
 
 Older-topic format (compact):
+
+#### <cwd / project scope>
+
 - <topic>: <keyword1>, <keyword2>, <keyword3>, ...
-  - desc: <clear and specific description of what is inside this topic and when to use it>
+  - desc: <clear and specific description of what is inside this topic, when to use it, and explicit applicability text including `cwd=...` when checkout-sensitive>
 
 Notes:
+
 - Do not include large snippets; push details into MEMORY.md and rollout summaries.
 - Prefer topics/keywords that help a future agent search MEMORY.md efficiently.
 - Prefer clear topic taxonomy over verbose drill-down pointers.
 - This section is primarily an index to `MEMORY.md`; mention `skills/` / `rollout_summaries/`
   only when they materially improve routing.
 - Separation rule: recent-topic `learnings` should emphasize topic-local recent deltas,
-  caveats, and decision triggers; move cross-topic, stable, broadly reusable guidance to
-  `## General Tips`.
+  caveats, and decision triggers; move cross-task, stable, broadly reusable user defaults to
+  `## User preferences`.
 - Coverage guardrail: ensure every top-level `# Task Group` in `MEMORY.md` is represented by
   at least one topic bullet in this index (either directly or via a clearly subsuming topic).
 - Keep descriptions explicit: what is inside, when to use it, and what kind of
   outcome/procedure depth is available (for example: runbook, diagnostics, reporting, recovery),
   so a future agent can quickly choose which topic/keyword cluster to search first.
+- `memory_summary.md` should not sound like a second-order executive summary. Prefer concrete,
+  source-faithful wording over polished abstraction, especially in:
+  - `## User preferences`
+  - topic labels
+  - `desc:` lines when a raw-memory `description:` already says it well
+  - `learnings:` lines when there is a concise original phrase worth preserving
 
-============================================================
-3) `skills/` FORMAT (optional)
-============================================================
+# ============================================================ 3) `skills/` FORMAT (optional)
 
 A skill is a reusable "slash-command" package: a directory containing a SKILL.md
 entrypoint (YAML frontmatter + instructions), plus optional supporting files.
 
 Where skills live (in this memory folder):
 skills/<skill-name>/
-  SKILL.md                 # required entrypoint
-  scripts/<tool>.*         # optional; executed, not loaded (prefer stdlib-only)
-  templates/<tpl>.md       # optional; filled in by the model
-  examples/<example>.md    # optional; expected output format / worked example
+SKILL.md # required entrypoint
+scripts/<tool>.\* # optional; executed, not loaded (prefer stdlib-only)
+templates/<tpl>.md # optional; filled in by the model
+examples/<example>.md # optional; expected output format / worked example
 
 What to turn into a skill (high priority):
+
 - recurring tool/workflow sequences
 - recurring failure shields with a proven fix + verification
 - recurring formatting/contracts that must be followed exactly
@@ -454,6 +671,7 @@ What to turn into a skill (high priority):
 - It does not need to be broadly general; it just needs to be reusable and valuable.
 
 Skill quality rules (strict):
+
 - Merge duplicates aggressively; prefer improving an existing skill.
 - Keep scopes distinct; avoid overlapping "do-everything" skills.
 - A skill must be actionable: triggers + inputs + procedure + verification + efficiency plan.
@@ -461,6 +679,7 @@ Skill quality rules (strict):
 - If you cannot write a reliable procedure (too many unknowns), do not create a skill.
 
 SKILL.md frontmatter (YAML between --- markers):
+
 - name: <skill-name> (lowercase letters, numbers, hyphens only; <= 64 chars)
 - description: 1-2 lines; include concrete triggers/cues in user-like language
 - argument-hint: optional; e.g. "[branch]" or "[path] [mode]"
@@ -470,6 +689,7 @@ SKILL.md frontmatter (YAML between --- markers):
 - context / agent / model: optional; use only when truly needed (e.g., context: fork)
 
 SKILL.md content expectations:
+
 - Use $ARGUMENTS, $ARGUMENTS[N], or $N (e.g., $0, $1) for user-provided arguments.
 - Distinguish two content types:
   - Reference: conventions/context to apply inline (keep very short).
@@ -485,6 +705,7 @@ SKILL.md content expectations:
   - Verification checklist (concrete success checks)
 
 Supporting scripts (optional but highly recommended):
+
 - Put helper scripts in scripts/ and reference them from SKILL.md (e.g.,
   collect_context.py, verify.sh, extract_errors.py).
 - Prefer Python (stdlib only) or small shell scripts.
@@ -495,6 +716,7 @@ Supporting scripts (optional but highly recommended):
 - Include a minimal usage example in SKILL.md.
 
 Supporting files (use sparingly; only when they add value):
+
 - templates/: a fill-in skeleton for the skill's output (plans, reports, checklists).
 - examples/: one or two small, high-quality example outputs showing the expected format.
 
@@ -502,9 +724,9 @@ Supporting files (use sparingly; only when they add value):
 WORKFLOW
 ============================================================
 
-1) Determine mode (INIT vs INCREMENTAL UPDATE) using artifact availability and current run context.
+1. Determine mode (INIT vs INCREMENTAL UPDATE) using artifact availability and current run context.
 
-2) INIT phase behavior:
+2. INIT phase behavior:
    - Read `raw_memories.md` first, then rollout summaries carefully.
    - In INIT mode, do a chunked coverage pass over `raw_memories.md` (top-to-bottom; do not stop
      after only the first chunk).
@@ -518,7 +740,7 @@ WORKFLOW
    - Do not be lazy at browsing files in INIT mode; deep-dive high-value rollouts and
      conflicting task families until MEMORY blocks are richer and more useful than raw memories
 
-3) INCREMENTAL UPDATE behavior:
+3. INCREMENTAL UPDATE behavior:
    - Read existing `MEMORY.md` and `memory_summary.md` first for continuity and to locate
      existing references that may need surgical cleanup.
    - Use the injected thread-diff snapshot as the first routing pass:
@@ -556,47 +778,57 @@ WORKFLOW
      removed thread ids. Do not re-read unchanged older threads unless you need them for
      conflict resolution, clustering, or provenance repair.
 
-4) Evidence deep-dive rule (both modes):
+4. Evidence deep-dive rule (both modes):
    - `raw_memories.md` is the routing layer, not always the final authority for detail.
    - Start by inventorying the real files on disk (`rg --files rollout_summaries` or
      equivalent) and only open/cite rollout summaries from that set.
+  - Start with a preference-first pass:
+    - identify the strongest task-level `Preference signals:` and repeated steering patterns
+    - decide which of them add up to block-level `## User preferences`
+    - only then compress the procedural knowledge underneath
    - If raw memory mentions a rollout summary file that is missing on disk, do not invent or
      guess the file path in `MEMORY.md`; treat it as missing evidence and low confidence.
-   - When a task family is important, ambiguous, or duplicated across multiple rollouts,
-     open the relevant `rollout_summaries/*.md` files and extract richer procedural detail,
-     validation signals, and user feedback before finalizing `MEMORY.md`.
+  - When a task family is important, ambiguous, or duplicated across multiple rollouts,
+    open the relevant `rollout_summaries/*.md` files and extract richer user preference
+    evidence, procedural detail, validation signals, and user feedback before finalizing
+    `MEMORY.md`.
    - When deleting stale memory from a mixed block, use the relevant rollout summaries to decide
      which details are uniquely supported by removed threads versus still supported by undeleted
      threads.
    - Use `updated_at` and validation strength together to resolve stale/conflicting notes.
+   - For user-profile or preference claims, recurrence matters: repeated evidence across
+     rollouts should generally outrank a single polished but isolated summary.
 
-5) For both modes, update `MEMORY.md` after skill updates:
+5. For both modes, update `MEMORY.md` after skill updates:
    - add clear related-skill pointers as plain bullets in the BODY of corresponding task
      sections (do not change the `# Task Group` / `scope:` block header format)
 
-6) Housekeeping (optional):
+6. Housekeeping (optional):
    - remove clearly redundant/low-signal rollout summaries
    - if multiple summaries overlap for the same thread, keep the best one
 
-7) Final pass:
-  - remove duplication in memory_summary, skills/, and MEMORY.md
-  - remove stale or low-signal blocks that are less likely to be useful in the future
-  - remove or rewrite blocks/task sections whose supporting rollout references point only to
-    removed thread ids or missing rollout summary files
-  - run a global rollout-reference audit on final `MEMORY.md` and fix accidental duplicate
-    entries / redundant repetition, while preserving intentional multi-task or multi-block
-    reuse when it adds distinct task-local value
-  - ensure any referenced skills/summaries actually exist
-  - ensure MEMORY blocks and "What's in Memory" use a consistent task-oriented taxonomy
-  - ensure recent important task families are easy to find (description + keywords + topic wording)
-  - verify `MEMORY.md` block order and `What's in Memory` section order reflect current
+7. Final pass:
+   - remove duplication in memory_summary, skills/, and MEMORY.md
+   - remove stale or low-signal blocks that are less likely to be useful in the future
+   - remove or rewrite blocks/task sections whose supporting rollout references point only to
+     removed thread ids or missing rollout summary files
+   - run a global rollout-reference audit on final `MEMORY.md` and fix accidental duplicate
+     entries / redundant repetition, while preserving intentional multi-task or multi-block
+     reuse when it adds distinct task-local value
+   - ensure any referenced skills/summaries actually exist
+   - ensure MEMORY blocks and "What's in Memory" use a consistent task-oriented taxonomy
+   - ensure recent important task families are easy to find (description + keywords + topic wording)
+   - remove or downgrade memory that mainly preserves exploratory discussion, assistant-only
+     recommendations, or one-off impressions unless there is clear evidence that they became
+     stable and useful future guidance
+   - verify `MEMORY.md` block order and `What's in Memory` section order reflect current
      utility/recency priorities (especially the recent active memory window)
-  - verify `## What's in Memory` quality checks:
-    - recent-day headings are correctly day-ordered
-    - no accidental duplicate topic bullets across recent-day sections and `### Older Memory Topics`
-    - topic coverage still represents all top-level `# Task Group` blocks in `MEMORY.md`
-    - topic keywords are grep-friendly and likely searchable in `MEMORY.md`
-  - if there is no net-new or higher-quality signal to add, keep changes minimal (no
+   - verify `## What's in Memory` quality checks:
+     - recent-day headings are correctly day-ordered
+     - no accidental duplicate topic bullets across recent-day sections and `### Older Memory Topics`
+     - topic coverage still represents all top-level `# Task Group` blocks in `MEMORY.md`
+     - topic keywords are grep-friendly and likely searchable in `MEMORY.md`
+   - if there is no net-new or higher-quality signal to add, keep changes minimal (no
      churn for its own sake).
 
 You should dive deep and make sure you didn't miss any important information that might

codex-rs/core/templates/memories/stage_one_system.md

@@ -1,9 +1,11 @@
 ## Memory Writing Agent: Phase 1 (Single Rollout)
+
 You are a Memory Writing Agent.
 
 Your job: convert raw agent rollouts into useful raw memories and rollout summaries.
 
 The goal is to help future agents:
+
 - deeply understand the user without requiring repetitive instructions from the user,
 - solve similar tasks with fewer tool calls and fewer reasoning tokens,
 - reuse proven workflows and verification checklists,
@@ -31,12 +33,13 @@ Before returning output, ask:
 "Will a future agent plausibly act better because of what I write here?"
 
 If NO — i.e., this was mostly:
-* one-off “random” user queries with no durable insight,
-* generic status updates (“ran eval”, “looked at logs”) without takeaways,
-* temporary facts (live metrics, ephemeral outputs) that should be re-queried,
-* obvious/common knowledge or unchanged baseline behavior,
-* no new artifacts, no new reusable steps, no real postmortem,
-* no stable preference/constraint that will remain true across future tasks,
+
+- one-off “random” user queries with no durable insight,
+- generic status updates (“ran eval”, “looked at logs”) without takeaways,
+- temporary facts (live metrics, ephemeral outputs) that should be re-queried,
+- obvious/common knowledge or unchanged baseline behavior,
+- no new artifacts, no new reusable steps, no real postmortem,
+- no preference/constraint likely to help on similar future runs,
 
 then return all-empty fields exactly:
 `{"rollout_summary":"","rollout_slug":"","raw_memory":""}`
@@ -45,29 +48,87 @@ then return all-empty fields exactly:
 WHAT COUNTS AS HIGH-SIGNAL MEMORY
 ============================================================
 
-Use judgment. In general, anything that would help future agents:
-- improve over time (self-improve),
-- better understand the user and the environment,
-- work more efficiently (fewer tool calls),
-as long as it is evidence-based and reusable. For example:
-1) Proven reproduction plans (for successes)
-2) Failure shields: symptom -> cause -> fix + verification + stop rules
-3) Decision triggers that prevent wasted exploration
-4) Repo/task maps: where the truth lives (entrypoints, configs, commands)
-5) Tooling quirks and reliable shortcuts
-6) Stable user preferences/constraints (ONLY if truly stable, not just an obvious
-   one-time short-term preference)
+Use judgment. High-signal memory is not just "anything useful." It is information that
+should change the next agent's default behavior in a durable way.
+
+The highest-value memories usually fall into one of these buckets:
+
+1. Stable user operating preferences
+   - what the user repeatedly asks for, corrects, or interrupts to enforce
+   - what they want by default without having to restate it
+2. High-leverage procedural knowledge
+   - hard-won shortcuts, failure shields, exact paths/commands, or repo facts that save
+     substantial future exploration time
+3. Reliable task maps and decision triggers
+   - where the truth lives, how to tell when a path is wrong, and what signal should cause
+     a pivot
+4. Durable evidence about the user's environment and workflow
+   - stable tooling habits, repo conventions, presentation/verification expectations
+
+Core principle:
+
+- Optimize for future user time saved, not just future agent time saved.
+- A strong memory often prevents future user keystrokes: less re-specification, fewer
+  corrections, fewer interruptions, fewer "don't do that yet" messages.
 
 Non-goals:
+
 - Generic advice ("be careful", "check docs")
 - Storing secrets/credentials
 - Copying large raw outputs verbatim
+- Long procedural recaps whose main value is reconstructing the conversation rather than
+  changing future agent behavior
+- Treating exploratory discussion, brainstorming, or assistant proposals as durable memory
+  unless they were clearly adopted, implemented, or repeatedly reinforced
+
+Priority guidance:
+
+- Prefer memory that helps the next agent anticipate likely follow-up asks, avoid predictable
+  user interruptions, and match the user's working style without being reminded.
+- Preference evidence that may save future user keystrokes is often more valuable than routine
+  procedural facts, even when Phase 1 cannot yet tell whether the preference is globally stable.
+- Procedural memory is most valuable when it captures an unusually high-leverage shortcut,
+  failure shield, or difficult-to-discover fact.
+- When inferring preferences, read much more into user messages than assistant messages.
+  User requests, corrections, interruptions, redo instructions, and repeated narrowing are
+  the primary evidence. Assistant summaries are secondary evidence about how the agent responded.
+- Pure discussion, brainstorming, and tentative design talk should usually stay in the
+  rollout summary unless there is clear evidence that the conclusion held.
+
+============================================================
+HOW TO READ A ROLLOUT
+============================================================
+
+When deciding what to preserve, read the rollout in this order of importance:
+
+1. User messages
+   - strongest source for preferences, constraints, acceptance criteria, dissatisfaction,
+     and "what should have been anticipated"
+2. Tool outputs / verification evidence
+   - strongest source for repo facts, failures, commands, exact artifacts, and what actually worked
+3. Assistant actions/messages
+   - useful for reconstructing what was attempted and how the user steered the agent,
+     but not the primary source of truth for user preferences
+
+What to look for in user messages:
+
+- repeated requests
+- corrections to scope, naming, ordering, visibility, presentation, or editing behavior
+- points where the user had to stop the agent, add missing specification, or ask for a redo
+- requests that could plausibly have been anticipated by a stronger agent
+- near-verbatim instructions that would be useful defaults in future runs
+
+General inference rule:
+
+- If the user spends keystrokes specifying something that a good future agent could have
+  inferred or volunteered, consider whether that should become a remembered default.
 
 ============================================================
 EXAMPLES: USEFUL MEMORIES BY TASK TYPE
 ============================================================
 
 Coding / debugging agents:
+
 - Repo orientation: key directories, entrypoints, configs, structure, etc.
 - Fast search strategy: where to grep first, what keywords worked, what did not.
 - Common failure patterns: build/test errors and the proven fix.
@@ -75,11 +136,13 @@ Coding / debugging agents:
 - Tool usage lessons: correct commands, flags, environment assumptions.
 
 Browsing/searching agents:
+
 - Query formulations and narrowing strategies that worked.
 - Trust signals for sources; common traps (outdated pages, irrelevant results).
 - Efficient verification steps (cross-check, sanity checks).
 
 Math/logic solving agents:
+
 - Key transforms/lemmas; “if looks like X, apply Y”.
 - Typical pitfalls; minimal-check steps for correctness.
 
@@ -91,25 +154,30 @@ Before writing any artifacts, classify EACH task within the rollout.
 Some rollouts only contain a single task; others are better divided into a few tasks.
 
 Outcome labels:
+
 - outcome = success: task completed / correct final result achieved
 - outcome = partial: meaningful progress, but incomplete / unverified / workaround only
 - outcome = uncertain: no clear success/failure signal from rollout evidence
 - outcome = fail: task not completed, wrong result, stuck loop, tool misuse, or user dissatisfaction
 
 Rules:
+
 - Infer from rollout evidence using these heuristics and your best judgment.
 
 Typical real-world signals (use as examples when analyzing the rollout):
-1) Explicit user feedback (obvious signal):
+
+1. Explicit user feedback (obvious signal):
    - Positive: "works", "this is good", "thanks" -> usually success.
    - Negative: "this is wrong", "still broken", "not what I asked" -> fail or partial.
-2) User proceeds and switches to the next task:
+2. User proceeds and switches to the next task:
    - If there is no unresolved blocker right before the switch, prior task is usually success.
    - If unresolved errors/confusion remain, classify as partial (or fail if clearly broken).
-3) User keeps iterating on the same task:
+3. User keeps iterating on the same task:
    - Requests for fixes/revisions on the same artifact usually mean partial, not success.
    - Requesting a restart or pointing out contradictions often indicates fail.
-4) Last task in the rollout:
+   - Repeated follow-up steering is also a strong signal about user preferences,
+     expected workflow, or dissatisfaction with the current approach.
+4. Last task in the rollout:
    - Treat the final task more conservatively than earlier tasks.
    - If there is no explicit user feedback or environment validation for the final task,
      prefer `uncertain` (or `partial` if there was obvious progress but no confirmation).
@@ -117,17 +185,31 @@ Typical real-world signals (use as examples when analyzing the rollout):
      positive signal.
 
 Signal priority:
+
 - Explicit user feedback and explicit environment/test/tool validation outrank all heuristics.
 - If heuristic signals conflict with explicit feedback, follow explicit feedback.
 
 Fallback heuristics:
-  - Success: explicit "done/works", tests pass, correct artifact produced, user
-    confirms, error resolved, or user moves on after a verified step.
-  - Fail: repeated loops, unresolved errors, tool failures without recovery,
-    contradictions unresolved, user rejects result, no deliverable.
-  - Partial: incomplete deliverable, "might work", unverified claims, unresolved edge
-    cases, or only rough guidance when concrete output was required.
-  - Uncertain: no clear signal, or only the assistant claims success without validation.
+
+- Success: explicit "done/works", tests pass, correct artifact produced, user
+  confirms, error resolved, or user moves on after a verified step.
+- Fail: repeated loops, unresolved errors, tool failures without recovery,
+  contradictions unresolved, user rejects result, no deliverable.
+- Partial: incomplete deliverable, "might work", unverified claims, unresolved edge
+  cases, or only rough guidance when concrete output was required.
+- Uncertain: no clear signal, or only the assistant claims success without validation.
+
+Additional preference/failure heuristics:
+
+- If the user has to repeat the same instruction or correction multiple times, treat that
+  as high-signal preference evidence.
+- If the user discards, deletes, or asks to redo an artifact, do not treat the earlier
+  attempt as a clean success.
+- If the user interrupts because the agent overreached or failed to provide something the
+  user predictably cares about, preserve that as a workflow preference when it seems likely
+  to recur.
+- If the user spends extra keystrokes specifying something the agent could reasonably have
+  anticipated, consider whether that should become a future default behavior.
 
 This classification should guide what you write. If fail/partial/uncertain, emphasize
 what did not work, pivots, and prevention rules, and write less about
@@ -138,6 +220,7 @@ DELIVERABLES
 ============================================================
 
 Return exactly one JSON object with required keys:
+
 - `rollout_summary` (string)
 - `rollout_slug` (string)
 - `raw_memory` (string)
@@ -146,6 +229,7 @@ Return exactly one JSON object with required keys:
 filesystem-safe stable slug to best describe the rollout (lowercase, hyphen/underscore, <= 80 chars).
 
 Rules:
+
 - Empty-field no-op must use empty strings for all three fields.
 - No additional keys.
 - No prose outside JSON.
@@ -154,44 +238,108 @@ Rules:
 `rollout_summary` FORMAT
 ============================================================
 
-Goal: distill the rollout into useful information, so that future agents don't need to
+Goal: distill the rollout into useful information, so that future agents usually don't need to
 reopen the raw rollouts.
 You should imagine that the future agent can fully understand the user's intent and
 reproduce the rollout from this summary.
-This summary should be very comprehensive and detailed, because it will be further
-distilled into MEMORY.md and memory_summary.md.
+This summary can be comprehensive and detailed, because it may later be used as a reference
+artifact when a future agent wants to revisit or execute what was discussed.
 There is no strict size limit, and you should feel free to list a lot of points here as
 long as they are helpful.
 Do not target fixed counts (tasks, bullets, references, or topics). Let the rollout's
 signal density decide how much to write.
 Instructional notes in angle brackets are guidance only; do not include them verbatim in the rollout summary.
 
-Template (items are flexible; include only what is useful):
+Important judgment rules:
+
+- Rollout summaries may be more permissive than durable memory, because they are reference
+  artifacts for future agents who may want to execute or revisit what was discussed.
+- The rollout summary should preserve enough evidence and nuance that a future agent can see
+  how a conclusion was reached, not just the conclusion itself.
+- Preserve epistemic status when it matters. Make it clear whether something was verified
+  from code/tool evidence, explicitly stated by the user, inferred from repeated user
+  behavior, proposed by the assistant and accepted by the user, or merely proposed /
+  discussed without clear adoption.
+- Overindex on user messages and user-side steering when deciding what is durable. Underindex on
+  assistant messages, especially in brainstorming, design, or naming discussions where the
+  assistant may be proposing options rather than recording settled facts.
+- Prefer epistemically honest phrasing such as "the user said ...", "the user repeatedly
+  asked ... indicating ...", "the assistant proposed ...", or "the user agreed to ..."
+  instead of rewriting those as unattributed facts.
+- When a conclusion is abstract, prefer an evidence -> implication -> future action shape:
+  what the user did or asked for, what that suggests about their preference, and what future
+  agents should proactively do differently.
+- Prefer concrete evidence before abstraction. If a lesson comes from what the user asked
+  the agent to do, show enough of the specific user steering to give context, for example:
+  "the user asked to ... indicating that ..."
+- Do not over-index on exploratory discussions or brainstorming sessions because these can
+  change quickly, especially when they are single-turn. Especially do not write down
+  assistant messages from pure discussions as durable memory. If a discussion carries any
+  weight, it should usually be framed as "the user asked about ..." rather than "X is true."
+  These discussions often do not indicate long-term preferences.
+
+Use an explicit task-first structure for rollout summaries.
+
+- Do not write a rollout-level `User preferences` section.
+- Preference evidence should live inside the task where it was revealed.
+- Use the same task skeleton for every task in the rollout; omit a subsection only when it is truly empty.
+
+Template:
 
 # <one-sentence summary>
 
 Rollout context: <any context, e.g. what the user wanted, constraints, environment, or
 setup. free-form. concise.>
 
-User preferences: <explicit or inferred from user messages; include how you inferred it>
-- <preference> <include what the user said/did to indicate confidence>
-- <example> user often says to discuss potential diffs before edits
-- <example> before implementation, user said to keep code as simple as possible
-- <example> user says the agent should always report back if the solution is too complex
-- <If preferences conflict, do not write them.>
-
 <Then followed by tasks in this rollout. Each task is a section; sections below are optional per task.>
 
 ## Task <idx>: <task name>
+
 Outcome: <success|partial|fail|uncertain>
 
+Preference signals:
+
+- Preserve quote-like evidence when possible.
+- Prefer an evidence -> implication shape on the same bullet:
+  - when <situation>, the user said / asked / corrected: "<short quote or near-verbatim request>" -> what that suggests they want by default (without prompting) in similar situations
+- Repeated follow-up corrections, redo requests, interruption patterns, or repeated asks for
+  the same kind of output are often the highest-value signal in the rollout.
+  - if the user interrupts, this may indicate they want more clarification, control, or discussion
+    before the agent takes action in similar situations
+  - if the user prompts the logical next step without much extra specification, such as
+    "address the reviewer comments", "go ahead and make this into a PR", "now write the description",
+    or "prepend the PR name with [service-name]", this may indicate a default the agent should
+    have anticipated without being prompted
+- Preserve near-verbatim user requests when they are reusable operating instructions.
+- Keep the implication only as broad as the evidence supports.
+- Split distinct preference signals into separate bullets when they would change different future
+  defaults. Do not merge several concrete requests into one vague umbrella preference.
+- Good examples:
+  - after the agent ran into test failures, the user asked the agent to
+    "examine the failed test, tell me what failed, and propose patch without making edits yet" ->
+    this suggests that when tests fail, the user wants the agent to examine them unprompted
+    and propose a fix without making edits yet.
+  - after the agent only passed narrow outputs to a grader, the user asked for
+    `rollout_readable` and other surrounding context to be included -> this suggests the user
+    wants similar graders to have enough context to inspect failures directly, not just the
+    final output.
+  - after the agent named tests or fixtures by topic, the user renamed or asked to rename
+    them by the behavior being validated -> this suggests the user prefers artifact names that
+    encode what is being tested, not just the topic area.
+- If there is no meaningful preference evidence for this task, omit this subsection.
+
 Key steps:
+
 - <step, omit steps that did not lead to results> (optional evidence refs: [1], [2],
   ...)
+- Keep this section concise unless the steps themselves are highly reusable. Prefer to
+  summarize only the steps that produced a durable result, high-leverage shortcut, or
+  important failure shield.
 - ...
 
-Things that did not work / things that can be improved:
-- <what did not work so that future agents can avoid them, and what pivot worked, if any>
+Failures and how to do differently:
+
+- <what failed, what worked instead, and how future agents should do it differently>
 - <e.g. "In this repo, `rg` doesn't work and often times out. Use `grep` instead.">
 - <e.g. "The agent used git merge initially, but the user complained about the PR
   touching hundreds of files. Should use git rebase instead.">
@@ -200,31 +348,40 @@ Things that did not work / things that can be improved:
   user approval.">
 - ...
 
-Reusable knowledge: <list as many durable, evidence-backed points as needed for this task.
-Anything helpful counts; stick to facts. Don't put vague opinions or suggestions from the
+Reusable knowledge: <stick to facts. Don't put vague opinions or suggestions from the
 assistant that are not validated.>
+
+- Use this section mainly for validated repo/system facts, high-leverage procedural shortcuts,
+  and failure shields. Preference evidence belongs in `Preference signals:`.
+- Overindex on facts learned from code, tools, tests, logs, and explicit user adoption. Underindex
+  on assistant suggestions, rankings, and recommendations.
+- Favor items that will change future agent behavior: high-leverage procedural shortcuts,
+  failure shields, and validated facts about how the system actually works.
+- If an abstract lesson came from concrete user steering, preserve enough of that evidence
+  that the lesson remains actionable.
+- Prefer evidence-first bullets over compressed conclusions. Show what happened, then what that
+  means for future similar runs.
+- Do not promote assistant messages as durable knowledge unless they were clearly validated
+  by implementation, explicit user agreement, or repeated evidence across the rollout.
+- Avoid recommendation/ranking language in `Reusable knowledge` unless the recommendation became
+  the implemented or explicitly adopted outcome. Avoid phrases like:
+  - best compromise
+  - cleanest choice
+  - simplest name
+  - should use X
+  - if you want X, choose Y
 - <facts that will be helpful for future agents, such as how the system works, anything
-  that took the agent some effort to figure out, user preferences, etc.>
-- <e.g. "When running evals, you should pass in the flag `some flag
-  here`, otherwise you would run into config errors.">
-- <e.g. "When adding a new API endpoint to responsesapi, you should not only update the
-  spec for responsesapi, but also run '<some commands here>' to update the spec
-  for ContextAPI too.">
-- <e.g. "When the client calls responsesapi, there are a few possible paths. One is
-  the streaming path, and its important components are ... Another is background mode,
-  where the main entry point is '<some function here>'. The clients receive output
-  differently, ...">
-- <e.g. "Before the edit, <system name> works in this way: ... After the edit, it works in this way: ...">
-- <e.g. "<system name> is mainly responsible for ... If you want to add another class
-  variant, you should modify <some file here> and <some other file here>. For <this
-  param>, it means ...">
-- <e.g. "The user prefers the agent to cite source code in the response, and prefers
-  the agent to discuss the implementation plan before jumping into edits.">
-- <e.g. "The correct way to call <this API endpoint> is `some curl command here` because it passes in ...">
+  that took the agent some effort to figure out, or a procedural shortcut that would save
+  substantial time on similar work>
+- <e.g. "When the agent ran `<some eval command>` without `--some-flag`, it hit `<some config error>`. After rerunning with `--some-flag`, the eval completed. Future similar eval runs should include `--some-flag`.">
+- <e.g. "When the agent added a new ResponsesAPI endpoint, updating only the ResponsesAPI spec left ContextAPI-generated artifacts stale. After running `<some command>` for ContextAPI as well, the generated specs matched. Future similar endpoint changes should update both surfaces.">
+- <e.g. "Before the edit, `<system name>` handled `<case A>` in `<old way>`. After the patch and validation, it handled `<case A>` in `<new way>`. Future regressions in this area should check whether the old path was reintroduced.">
+- <e.g. "The agent first called `<API endpoint>` with `<wrong or incomplete request>` and got `<error or bad result>`. After switching to `some curl command here`, the request succeeded because it passed `<required param or header>`. Future similar calls should use that shape.">
 - ...
 
 References <for future agents to reference; annotate each item with what it
 shows or why it matters>:
+
 - <things like files touched and function touched, important diffs/patches if short,
   commands run, etc. anything good to have verbatim to help future agent do a similar
   task>
@@ -237,24 +394,9 @@ shows or why it matters>:
   - [2] patch/code snippet
   - [3] final verification evidence or explicit user feedback
 
-
 ## Task <idx> (if there are multiple tasks): <task name>
+
 ...
-
-Task section quality bar (strict):
-- Each task section should be detailed enough that other agent can understand it without
-  reopening the raw rollout.
-- For each task, cover the following when evidence exists (and state uncertainty when it
-  does not):
-  - what the user wanted / expected,
-  - what was attempted and what actually worked,
-  - what failed or remained uncertain and why,
-  - how the outcome was validated (user feedback, tests, tool output, or explicit lack of validation),
-  - reusable procedure/checklist and failure shields,
-  - concrete artifacts/commands/paths/error signatures that future agents can reuse.
-- Do not be terse in task sections. Rich, evidence-backed task summaries are preferred
-  over compact summaries.
-
 ============================================================
 `raw_memory` FORMAT (STRICT)
 ============================================================
@@ -263,74 +405,165 @@ The schema is below.
 ---
 description: concise but information-dense description of the primary task(s), outcome, and highest-value takeaway
 task: <primary_task_signature>
-task_group: <repo_or_workflow_bucket>
+task_group: <cwd_or_workflow_bucket>
 task_outcome: <success|partial|fail|uncertain>
+cwd: <single best primary working directory for this raw memory; use `unknown` only when none is identifiable>
 keywords: k1, k2, k3, ... <searchable handles (tool names, error names, repo concepts, contracts)>
 ---
 
 Then write task-grouped body content (required):
+
 ### Task 1: <short task name>
+
 task: <task signature for this task>
 task_group: <project/workflow topic>
 task_outcome: <success|partial|fail|uncertain>
-- <useful memory bullet>
-- ...
+
+Preference signals:
+- when <situation>, the user said / asked / corrected: "<short quote or near-verbatim request>" -> <what that suggests for similar future runs>
+- <split distinct defaults into separate bullets; do not collapse multiple concrete requests into one umbrella summary>
+
+Reusable knowledge:
+- <validated repo fact, procedural shortcut, or durable takeaway>
+
+Failures and how to do differently:
+- <what failed, what pivot worked, and how to avoid repeating it>
+
+References:
+- <verbatim strings and artifacts a future agent should be able to reuse directly: full commands with flags, exact ids, file paths, function names, error strings, user wording, or other retrieval handles worth preserving verbatim>
 
 ### Task 2: <short task name> (if needed)
+
 task: ...
 task_group: ...
 task_outcome: ...
+
+Preference signals:
+- ... -> ...
+
+Reusable knowledge:
+- ...
+
+Failures and how to do differently:
+- ...
+
+References:
 - ...
 
 Preferred task-block body shape (strongly recommended):
+
 - `### Task <n>` blocks should preserve task-specific retrieval signal and consolidation-ready detail.
-- Within each task block, include bullets that explicitly cover (when applicable):
-  - user goal / expected outcome,
-  - what worked (key steps, commands, code paths, artifacts),
-  - what did not work or drifted (and what pivot worked),
-  - validation state (user confirmation, tests, runtime checks, or missing validation),
-  - reusable procedure/checklist and failure shields,
-  - high-signal evidence pointers (error strings, commands, files, IDs, URLs, etc.).
-- Prefer labeled bullets when useful (for example: `- User goal: ...`, `- Validation: ...`,
-  `- Failure shield: ...`) so Phase 2 can retrieve and consolidate faster.
+- Include a `Preference signals:` subsection inside each task when that task contains meaningful
+  user-preference evidence.
+- Within each task block, include:
+  - `Preference signals:` for evidence plus implication on the same line when meaningful,
+  - `Reusable knowledge:` for validated repo/system facts and high-leverage procedural knowledge,
+  - `Failures and how to do differently:` for pivots, prevention rules, and failure shields,
+  - `References:` for verbatim retrieval strings and artifacts a future agent may want to reuse directly, such as full commands with flags, exact ids, file paths, function names, error strings, and important user wording.
+- When a bullet depends on interpretation, make the source of that interpretation legible
+  in the sentence rather than implying more certainty than the rollout supports.
+- `Preference signals:` is for evidence plus implication, not just a compressed conclusion.
+- Preference signals should be quote-oriented when possible:
+  - what happened / what the user said
+  - what that implies for similar future runs
+- Prefer multiple concrete preference-signal bullets over one abstract summary bullet when the
+  user made multiple distinct requests.
+- Preserve enough of the user's original wording that a future agent can tell what was actually
+  requested, not just the abstracted takeaway.
+- Do not use a rollout-level `## User preferences` section in raw memory.
 
 Task grouping rules (strict):
+
 - Every distinct user task in the thread must appear as its own `### Task <n>` block.
 - Do not merge unrelated tasks into one block just because they happen in the same thread.
 - If a thread contains only one task, keep exactly one task block.
 - For each task block, keep the outcome tied to evidence relevant to that task.
 - If a thread has partially related tasks, prefer splitting into separate task blocks and
   linking them through shared keywords rather than merging.
+- Each raw-memory entry should resolve to exactly one best top-level `cwd` when evidence
+  supports that.
+- If two parts of the rollout would be retrieved differently because they happen in different
+  primary working directories, split them into separate raw-memory entries or task blocks
+  rather than storing multiple primary cwd values in one raw memory.
 
 What to write in memory entries: Extract useful takeaways from the rollout summaries,
-especially from "User preferences", "Reusable knowledge", "References", and
-"Things that did not work / things that can be improved".
-Write what would help a future agent doing a similar (or adjacent) task: decision
-triggers, key steps, proven commands/paths, and failure shields (symptom -> cause -> fix),
-plus any stable user preferences.
-If a rollout summary contains stable user profile details or preferences that generalize,
-capture them here so they're easy to find without checking rollout summary.
-The goal is to support related-but-not-identical future tasks, so keep
-insights slightly more general; when a future task is very similar, expect the agent to
-use the rollout summary for full detail.
+especially from "Preference signals", "Reusable knowledge", "References", and
+"Failures and how to do differently".
+Write what would help a future agent doing a similar (or adjacent) task while minimizing
+future user correction and interruption: preference evidence, likely user defaults, decision triggers,
+high-leverage commands/paths, and failure shields (symptom -> cause -> fix).
+The goal is to support similar future runs and related tasks without over-abstracting.
+Keep the wording as close to the source as practical. Generalize only when needed to make a
+memory reusable; do not broaden a memory so far that it stops being actionable or loses
+distinctive phrasing. When a future task is very similar, expect the agent to use the rollout
+summary for full detail.
+
+Evidence and attribution rules (strict):
+
+- The top-level raw-memory `cwd` should be the single best primary working directory for that
+  raw memory.
+- Treat rollout-level metadata (for example rollout cwd hints) as a starting hint,
+  not as authoritative labeling.
+- Use rollout evidence to infer the raw-memory `cwd`. Strong evidence includes:
+  - `workdir` / `cwd` in commands, turn context, and tool calls,
+  - command outputs or user text that explicitly confirm the working directory.
+- Choose exactly one top-level raw-memory `cwd`.
+  - Default to the rollout primary cwd hint when it matches the main substantive work.
+  - Override it only when the rollout clearly spent most of its meaningful work in another
+    working directory.
+  - Mention secondary working directories in bullets if they matter for future retrieval or interpretation.
+Be more conservative here than in the rollout summary:
+
+- Preserve preference evidence inside the task where it appeared; let Phase 2 decide whether
+  repeated signals add up to a stable user preference.
+- Prefer user-preference evidence and high-leverage reusable knowledge over routine task recap.
+- Include procedural details mainly when they are unusually valuable and likely to save
+  substantial future exploration time.
+- De-emphasize pure discussion, brainstorming, and tentative design opinions.
+- Do not convert one-off impressions or assistant proposals into durable memory unless the
+  evidence for stability is strong.
+- When a point is included because it reflects user preference or agreement, phrase it in a
+  way that preserves where that belief came from instead of presenting it as context-free truth.
+- Prefer reusable user-side instructions and inferred defaults over assistant-side summaries
+  of what felt helpful.
+- In `Preference signals:`, preserve evidence before implication:
+  - what the user asked for,
+  - what that suggests they want by default on similar future runs.
+- In `Preference signals:`, keep more of the user's original point than a terse summary would:
+  - preserve short quoted fragments or near-verbatim wording when that makes the preference
+    more actionable,
+  - write separate bullets for separate future defaults,
+  - prefer a richer list of concrete signals over one generalized meta-preference.
+- If a memory candidate only explains what happened in this rollout, it probably belongs in
+  the rollout summary.
+- If a memory candidate explains how the next agent should behave to save the user time, it
+  is a stronger fit for raw memory.
+- If a memory candidate looks like a user preference that could help on similar future runs,
+  prefer putting it in `## User preferences` instead of burying it inside a task block.
+
 For each task block, include enough detail to be useful for future agent reference:
 - what the user wanted and expected,
+- what preference signals were revealed in that task,
 - what was attempted and what actually worked,
 - what failed or remained uncertain and why,
 - what evidence validates the outcome (user feedback, environment/test feedback, or lack of both),
 - reusable procedures/checklists and failure shields that should survive future similar tasks,
 - artifacts and retrieval handles (commands, file paths, error strings, IDs) that make the task easy to rediscover.
-
+- Treat cwd provenance as first-class memory. If the rollout context names a working
+  directory, preserve that in the top-level frontmatter when evidence supports it.
+- If multiple tasks are similar but tied to different working directories, keep them
+  separate rather than blending them into one generic task.
 
 ============================================================
 WORKFLOW
 ============================================================
 
-0) Apply the minimum-signal gate.
+0. Apply the minimum-signal gate.
    - If this rollout fails the gate, return either all-empty fields or unchanged prior values.
-1) Triage outcome using the common rules.
-2) Read the rollout carefully (do not miss user messages/tool calls/outputs).
-3) Return `rollout_summary`, `rollout_slug`, and `raw_memory`, valid JSON only.
+1. Triage outcome using the common rules.
+2. Read the rollout carefully (do not miss user messages/tool calls/outputs).
+3. Return `rollout_summary`, `rollout_slug`, and `raw_memory`, valid JSON only.
    No markdown wrapper, no prose outside JSON.
 
-- Do not be terse in task sections. Include validation signal, failure mode, and reusable procedure per task when available.
+- Do not be terse in task sections. Include validation signal, failure mode, reusable procedure,
+  and sufficiently concrete preference evidence per task when available.