memories: tighten memory lookup guidance and citation requirements (#12635)

## Summary
- tighten the memory-use decision boundary so agents skip memory only
for clearly self-contained asks
- make the quick memory pass more explicit and bounded (including a
lightweight search budget)
- add structured `<memory_citation>` requirements and examples for final
replies
- clarify memory update guidance and end-state wording for memory lookup

## Why
The previous template was directionally correct, but still left room for
inconsistent memory lookup behavior and citation formatting. This change
makes the default behavior, quick-pass scope, and citation output
contract much more explicit.

## Testing
- not run (prompt/template text change only)

Co-authored-by: jif-oai <jif@openai.com>

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

@@ -4,18 +4,21 @@ You have access to a memory folder with guidance from prior runs. It can save
 time and help you stay consistent. Use it whenever it is likely to help.
 
 Decision boundary: should you use memory for a new user query?
-- You may skip memory when the new query is trivial (for example,
-a one-line change, chit-chat, or simple formatting) or clearly
-unrelated to this workspace or the memory summary below.
-- You SHOULD do a quick memory pass when the new query is ambiguous and likely
-relevant to the memory summary below, or when consistency with prior
-decisions/conventions matters.
-Especially if the user asks about a specific repo/module/code path that seems
-relevant, skim/search the relevant memory files first before diving into the repo.
+
+- Skip memory ONLY when the request is clearly self-contained and does not need
+  workspace history, conventions, or prior decisions.
+- Hard skip examples: current time/date, simple translation, simple sentence
+  rewrite, one-line shell command, trivial formatting.
+- Use memory by default when ANY of these are true:
+  - the query mentions workspace/repo/module/path/files in MEMORY_SUMMARY below,
+  - the user asks for prior context / consistency / previous decisions,
+  - the task is ambiguous and could depend on earlier project choices,
+  - the ask is a non-trivial and related to MEMORY_SUMMARY below.
+- If unsure, do a quick memory pass.
 
 Memory layout (general -> specific):
-- {{ base_path }}/memory_summary.md (already provided below; do NOT open
-again)
+
+- {{ base_path }}/memory_summary.md (already provided below; do NOT open again)
 - {{ base_path }}/MEMORY.md (searchable registry; primary file to query)
 - {{ base_path }}/skills/<skill-name>/ (skill folder)
   - SKILL.md (entrypoint instructions)
@@ -25,29 +28,72 @@ again)
 - {{ base_path }}/rollout_summaries/ (per-rollout recaps + evidence snippets)
 
 Quick memory pass (when applicable):
-1) Skim the MEMORY_SUMMARY included below and extract task-relevant topics and
-keywords (for example repo/module names, workflows, error strings, etc.).
-2) Search {{ base_path }}/MEMORY.md for those keywords, and for any referenced
-rollout summary files and skills.
-3) If relevant rollout summary files and skills exist, open matching files
-under {{ base_path }}/rollout_summaries/ and {{ base_path }}/skills/.
-4) If nothing relevant turns up, proceed normally without memory.
 
-During execution: if you hit repeated errors, confusing behavior, or you suspect
-there is relevant prior context, it is worth redoing the quick memory pass.
+1. Skim the MEMORY_SUMMARY below and extract task-relevant keywords.
+2. Search {{ base_path }}/MEMORY.md using those keywords.
+3. Only if MEMORY.md directly points to rollout summaries/skills, open the 1-2
+   most relevant files under {{ base_path }}/rollout_summaries/ or
+   {{ base_path }}/skills/.
+4. If there are no relevant hits, stop memory lookup and continue normally.
+
+Quick-pass budget:
+
+- Keep memory lookup lightweight: ideally <= 4-6 search steps before main work.
+- Avoid broad scans of all rollout summaries.
+
+During execution: if you hit repeated errors, confusing behavior, or suspect
+relevant prior context, redo the quick memory pass.
 
 When to update memory:
-- Treat memory as guidance, not truth: if memory conflicts with the current
-repo state, tool outputs, or environment, the user feedback, the current state
-wins. If you discover stale or misleading guidance, update the memory files
-accordingly.
-- When user explicitly asks you to remember something or update the memory, you
-should revise the files accordingly. Usually you should directly update
-memory_summary.md (such as general tips and user profile section) and MEMORY.md.
+
+- Treat memory as guidance, not truth: if memory conflicts with current repo
+  state, tool outputs, environment, or user feedback, current evidence wins.
+- If you discover stale/misleading memory, update memory files accordingly.
+- When user explicitly asks to remember/update memory, revise memory_summary.md
+  and/or MEMORY.md.
+
+Memory citation requirements:
+
+- If ANY relevant memory files were used: append exactly one
+  `<memory_citation>` block as the VERY LAST content of the final reply.
+  Normal responses should include the answer first, then append the
+  `<memory_citation>` block at the end.
+- Use this exact structure for programmatic parsing:
+<memory_citation>
+<citation_entries>
+MEMORY.md:234-236|note=[responsesapi citation extraction code pointer]
+rollout_summaries/2026-02-17T21-23-02-LN3m-weekly_memory_report_pivot_from_git_history.md:10-12|note=[weekly report format]
+</citation_entries>
+<thread_ids>
+019c6e27-e55b-73d1-87d8-4e01f1f75043
+019c7714-3b77-74d1-9866-e1f484aae2ab
+</thread_ids>
+</memory_citation>
+- `citation_entries` is for rendering:
+  - one citation entry per line
+  - format: `<file>:<line_start>-<line_end>|note=[<how memory was used>]`
+  - use file paths relative to the memory base path (for example, `MEMORY.md`,
+    `rollout_summaries/...`, `skills/...`)
+  - only cite files actually used under the memory base path (do not cite
+    workspace files as memory citations)
+  - if you used `MEMORY.md` and then a rollout summary/skill file, cite both
+  - list entries in order of importance (most important first)
+  - `note` should be short, single-line, and use simple characters only (avoid
+    unusual symbols, no newlines)
+- `thread_ids` is for us to track what previous rollouts you find useful:
+  - include one thread id per line
+  - thread ids should look like UUIDs (for example,
+    `019c6e27-e55b-73d1-87d8-4e01f1f75043`)
+  - include unique ids only; do not repeat ids
+  - an empty `<thread_ids>` section is allowed if no thread ids are available
+  - you can find thread ids in rollout summary files and MEMORY.md
+  - do not include file paths or notes in this section
+- Never include memory citations inside pull-request messages.
+- Never cite blank lines; double-check ranges.
 
 ========= MEMORY_SUMMARY BEGINS =========
 {{ memory_summary }}
 ========= MEMORY_SUMMARY ENDS =========
 
-If memory seems to be relevant for a new user query, always start with the quick
-memory pass above.
+When memory is likely relevant, start with the quick memory pass above before
+deep repo exploration.