From 3fe365ad8a915e6a9c6f1b73f57ccc993d5273c6 Mon Sep 17 00:00:00 2001 From: zuxin-oai Date: Tue, 24 Feb 2026 03:46:28 -0800 Subject: [PATCH] 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 `` 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 --- codex-rs/core/templates/memories/read_path.md | 102 +++++++++++++----- 1 file changed, 74 insertions(+), 28 deletions(-) diff --git a/codex-rs/core/templates/memories/read_path.md b/codex-rs/core/templates/memories/read_path.md index ec123fb55..b472a66c4 100644 --- a/codex-rs/core/templates/memories/read_path.md +++ b/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 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 + `` block as the VERY LAST content of the final reply. + Normal responses should include the answer first, then append the + `` block at the end. +- Use this exact structure for programmatic parsing: + + +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] + + +019c6e27-e55b-73d1-87d8-4e01f1f75043 +019c7714-3b77-74d1-9866-e1f484aae2ab + + +- `citation_entries` is for rendering: + - one citation entry per line + - format: `:-|note=[]` + - 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 `` 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. \ No newline at end of file