[codex] Clarify routed memory update scope

README.md

@@ -42,6 +42,10 @@ The skill separates project knowledge into canonical markdown files, each with a
 
 The AI agent maintains these files during the session. The human usually doesn't write them directly.
 
+project-memory is not a checklist of files to update every time.
+It is a routed memory system: agents update only the canonical files whose responsibility changed.
+Most sessions update 1-3 files, not the whole memory set.
+
 ## What makes this different
 
 **Promotion rules** — A hypothesis cannot be promoted to `CURRENT_STATE.md` without evidence in `RESEARCH_LOG.md` or an explicit decision in `DECISION_LOG.md`. This prevents unverified ideas from silently becoming project assumptions.

SKILL.md

@@ -58,6 +58,41 @@ Capture broadly. Promote narrowly.
 
 Do not let hypotheses, plans, or recovery notes silently become truth.
 
+## Routed memory rule
+
+Project memory is not a full-file synchronization system.
+
+Do not read or update every project-memory file on every run.
+Do not treat the file list or read order as a checklist.
+
+Each piece of information should go to its canonical home.
+Update only the files whose canonical responsibility changed.
+
+Most work sessions should update only 1-3 files.
+Larger updates are appropriate only during major transitions, such as phase changes, major hypothesis confirmation or rejection, architecture or approach changes, release checkpoints, or large migrations.
+
+Before editing memory files, produce a short update plan stating:
+
+- which files will be updated
+- why each file needs an update
+- which relevant files will not be touched
+
+For a small, obvious one-file update, a one-sentence plan is enough.
+If you notice you are about to edit memory files without an update plan, stop and produce the plan first.
+
+When one piece of information seems to belong in multiple files, choose one canonical home according to `DOCS_GUIDE.md` and `CONTEXT_MANIFEST.md`.
+Other files may reference the canonical entry, but should not duplicate the full details.
+
+## Read scope rule
+
+Start with `CONTEXT_MANIFEST.md` when present.
+
+Do not preemptively read the full memory set.
+Use the read order as a priority order, not as a checklist.
+
+Before reading additional memory files, identify which files are relevant to the current task.
+For non-trivial work, briefly state which memory files will be read and which relevant files will not be read.
+
 ## Language behavior
 
 Communicate with the user in the user's language by default.
@@ -105,6 +140,9 @@ If the repository also uses `AGENTS.md`, `CLAUDE.md`, or similar tool-facing gui
 
 When resuming or migrating a project, read in this order unless `CONTEXT_MANIFEST.md` says otherwise:
 
+This is a priority order for orientation, not a checklist to exhaust on every run.
+Read only as far as needed to route the current task safely.
+
 1. `CONTEXT_MANIFEST.md`
 2. latest entry in `RECOVERY_NOTES.md`
 3. `HUMAN_BRIEF.md`

tasks/resume_work.md

@@ -5,12 +5,13 @@ Use this when a user wants to continue after chat loss, a long pause, or model m
 ## Process
 
 1. Read `CONTEXT_MANIFEST.md` if present.
-2. Read the latest checkpoint in `RECOVERY_NOTES.md`.
-3. Read `HUMAN_BRIEF.md` for orientation.
-4. Read `CURRENT_STATE.md` before trusting old claims.
-5. Read only the relevant parts of `ROADMAP.md`, `DECISION_LOG.md`, `RESEARCH_LOG.md`, and `HYPOTHESIS_LAB.md`.
-6. Identify conflicts instead of smoothing them over.
-7. Return a compact restart plan.
+2. Identify which memory files are relevant to the current resume task; do not preemptively read the full memory set.
+3. Read the latest checkpoint in `RECOVERY_NOTES.md` when relevant.
+4. Read `HUMAN_BRIEF.md` for orientation when relevant.
+5. Read `CURRENT_STATE.md` before trusting old claims when relevant.
+6. Read only the relevant parts of `ROADMAP.md`, `DECISION_LOG.md`, `RESEARCH_LOG.md`, and `HYPOTHESIS_LAB.md`.
+7. Identify conflicts instead of smoothing them over.
+8. Return a compact restart plan.
 
 Treat repository docs as the durable memory layer. Do not assume a tool-specific memory feature contains the full truth.
 
@@ -51,6 +52,7 @@ Treat repository docs as the durable memory layer. Do not assume a tool-specific
 ## Common mistakes
 
 - Reading raw logs before canonical docs.
+- Treating the read order as a checklist.
 - Treating recovery notes as the whole truth.
 - Treating hypotheses as facts.
 - Reconstructing old context from memory when files disagree.

tasks/update_memory.md

@@ -10,12 +10,32 @@ The AI agent should route and write updates during the chat or coding session.
 Treat repository markdown files as the durable shared memory layer.
 Do not treat tool-specific hidden memory as the canonical source of truth.
 
+## Update scope protocol
+
+Project memory is a routed memory system, not a checklist of files to update every time.
+
+Before reading beyond `CONTEXT_MANIFEST.md`, identify which memory files are relevant to the current update.
+For non-trivial work, briefly state which files will be read and which relevant files will not be read.
+Do not preemptively read the full memory set.
+
+Before editing memory files, produce a short update plan that says:
+
+- which files will be updated
+- why each file needs an update
+- which relevant files will not be touched
+
+Then apply only the necessary changes.
+Most sessions should update 1-3 files.
+Larger updates are appropriate only for major transitions such as phase changes, major hypothesis confirmation or rejection, architecture or approach changes, release checkpoints, or large migrations.
+
+If you are about to edit memory files without an update plan, stop and produce the plan first.
+
 ## Process
 
 1. Read `CONTEXT_MANIFEST.md` if present.
 2. Read the latest `RECOVERY_NOTES.md` checkpoint.
 3. Read `HUMAN_BRIEF.md` and `CURRENT_STATE.md`.
-4. Read only the relevant parts of `ROADMAP.md`, `DECISION_LOG.md`, `RESEARCH_LOG.md`, and `HYPOTHESIS_LAB.md`.
+4. Read only the relevant parts of `ROADMAP.md`, `DECISION_LOG.md`, `RESEARCH_LOG.md`, and `HYPOTHESIS_LAB.md`; do not treat the file list as a checklist.
 5. Classify each new piece of information by status.
 6. Write patch-ready updates only to the files that should change.
 7. After routing updates, check whether the human-facing picture changed.

templates/CONTEXT_MANIFEST.md

@@ -20,6 +20,11 @@ If the repository also uses `AGENTS.md`, `CLAUDE.md`, or similar files, those fi
 
 ## Read first
 
+This is a priority order for orientation, not a checklist.
+Read only the files needed to understand and route the current work safely.
+Do not preemptively read the full memory set.
+For non-trivial work, briefly state which memory files will be read and which relevant files will not be read.
+
 1. `RECOVERY_NOTES.md` — latest resume checkpoint
 2. `HUMAN_BRIEF.md` — human-facing project orientation
 3. `CURRENT_STATE.md` — current truth
@@ -87,6 +92,12 @@ If private material matters, summarize it and link to the private location only
 
 ## Update policy
 
+Project memory is routed by responsibility.
+Update only the canonical files whose responsibility changed.
+Most sessions should update 1-3 files, not the whole memory set.
+
+Before editing memory files, produce a short update plan listing the files to update, why they need updates, and relevant files that will not be touched.
+
 Update this file when:
 
 - the canonical file set changes

templates/DOCS_GUIDE.md

@@ -12,6 +12,26 @@ The AI agent should update them during the chat or coding session.
 Treat repository markdown files as the durable shared memory layer.
 Do not treat tool-internal memory as the canonical source of truth.
 
+## Routed memory rule
+
+Project memory is not a full-file synchronization system.
+Do not read or update every project-memory file on every run.
+
+Information should be routed to its canonical home.
+Update only the files whose responsibility changed.
+Most sessions should update 1-3 files, not the whole memory set.
+
+Before editing memory files, produce a short update plan covering:
+
+- which files will be updated
+- why each file needs an update
+- which relevant files will not be touched
+
+For small, obvious one-file updates, a one-sentence plan is enough.
+
+If information seems to belong in multiple files, choose the most canonical file using this guide and `CONTEXT_MANIFEST.md`.
+Other files may reference the canonical entry, but should not duplicate the full details.
+
 ## Language policy
 
 - Communicate with the human in their preferred language when practical.

templates/README.md

@@ -11,6 +11,10 @@ It should answer:
 
 It should not carry the full current truth, full decision history, raw research log, or recovery checkpoints.
 
+project-memory is not a checklist of files to update every time.
+It is a routed memory system: update only the canonical files whose responsibility changed.
+Most sessions update 1-3 files, not the whole memory set.
+
 ## Purpose
 
 <!-- Write a concise description of the project, research area, product, writing task, or long-running work. -->