Goal, Memory, and Context Hygiene Field Guide

Keep long-running Codex work grounded with local files, compact prompts, and receipt checkpoints.

Original source pages and recordings require authorized access. The full article text here is public.

Keep long-running Codex work grounded with local files, compact prompts, and receipt checkpoints.

Use this when /goal work burns tokens, drifts, or cannot converge because context is not being externalized.

Choose the right mechanism

Mechanism Use when Agent responsibility Artifact
.goals/ Durable objective and checkpoints Long-running work .goals/<task>.md
.notes/ Receipts and scratch state Verification, logs, decisions .notes/<task>/
Grill-me Clarify before a big goal Ambiguous or risky scope .notes/<task>/questions.md
Compact summaries Keep Codex in the useful zone Large sessions and repeated loops .notes/<task>/handoff.md

Agent-ready prompt

Before starting this goal, externalize state.
Create .goals/<task>.md with objective, constraints, stop condition, and verification.
Create .notes/<task>/ for receipts.
Every major phase must write a checkpoint: research, plan, implementation, verification, final diff review.
If context gets large, compact to .notes/<task>/handoff.md and resume from that artifact.

Applied stories

Goal that will not converge

Role: Solo developer

Codex keeps exploring alternatives and never ships.

Agent brief: Narrow to one shippable slice, write explicit stop condition, and require a verification receipt before continuing.

Done when:

  • goal file
  • single next slice
  • verification command
  • final receipt

Memory drift cleanup

Role: Repo maintainer

Agent memory says old commands are true, but package scripts changed.

Agent brief: Audit memories against package.json/CI, write corrections to local notes, and update durable instructions only after verification.

Done when:

  • memory audit
  • verified commands
  • updated AGENTS.md or skill
  • stale facts removed

Tips and gotchas

  • Use local markdown as the durable memory for a task; do not rely on hidden conversational state.
  • Ask for numbered options with a recommended pick when you need to steer quickly.
  • Treat /goal as research + plan + implement + verify in one bounded loop, not infinite autoresearch.
  • Use compact summaries when receipts are better than raw chat history.

References

Source references