{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "foundations-goal-memory-field-guide",
  "slug": "goal-memory-field-guide",
  "title": "Goal, Memory, and Context Hygiene Field Guide",
  "summary": "Keep long-running Codex work grounded with local files, compact prompts, and receipt checkpoints.",
  "category": "Context",
  "tags": [
    "field guide",
    "goal memory"
  ],
  "sources": [
    {
      "label": "Agent foundations: Keep agent memory visible and grounded (authorized access required)",
      "url": "https://codex-workshop-followup.pages.dev/lesson-03.html"
    },
    {
      "label": "Agent foundations: Combine intent, implementation, and output for autonomous work (authorized access required)",
      "url": "https://codex-workshop-followup.pages.dev/lesson-10.html"
    },
    {
      "label": "Agent foundations: Preserve contracts and state machines while code changes (authorized access required)",
      "url": "https://codex-workshop-followup.pages.dev/lesson-11.html"
    }
  ],
  "sourceUnits": [
    "field-guides/guides.mjs#goal-memory/overview",
    "field-guides/guides.mjs#goal-memory/decision",
    "field-guides/guides.mjs#goal-memory/agentPrompt",
    "field-guides/guides.mjs#goal-memory/stories",
    "field-guides/guides.mjs#goal-memory/tips",
    "field-guides/guides.mjs#goal-memory/refs"
  ],
  "collection": "foundations",
  "categoryId": "context",
  "wordCount": 393,
  "url": "/topics/foundations-goal-memory-field-guide/",
  "markdownUrl": "/markdown/foundations-goal-memory-field-guide.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/foundations-goal-memory-field-guide.json",
  "headings": [
    {
      "id": "choose-the-right-mechanism",
      "text": "Choose the right mechanism",
      "level": 2
    },
    {
      "id": "agent-ready-prompt",
      "text": "Agent-ready prompt",
      "level": 2
    },
    {
      "id": "applied-stories",
      "text": "Applied stories",
      "level": 2
    },
    {
      "id": "goal-that-will-not-converge",
      "text": "Goal that will not converge",
      "level": 3
    },
    {
      "id": "memory-drift-cleanup",
      "text": "Memory drift cleanup",
      "level": 3
    },
    {
      "id": "tips-and-gotchas",
      "text": "Tips and gotchas",
      "level": 2
    },
    {
      "id": "references",
      "text": "References",
      "level": 2
    },
    {
      "id": "related-principles",
      "text": "Related principles",
      "level": 2
    }
  ],
  "markdown": "# Goal, Memory, and Context Hygiene Field Guide\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nKeep long-running Codex work grounded with local files, compact prompts, and receipt checkpoints.\n\nUse this when /goal work burns tokens, drifts, or cannot converge because context is not being externalized.\n\n## Choose the right mechanism\n\n| Mechanism | Use when | Agent responsibility | Artifact |\n|---|---|---|---|\n| .goals/ | Durable objective and checkpoints | Long-running work | .goals/<task>.md |\n| .notes/ | Receipts and scratch state | Verification, logs, decisions | .notes/<task>/ |\n| Grill-me | Clarify before a big goal | Ambiguous or risky scope | .notes/<task>/questions.md |\n| Compact summaries | Keep Codex in the useful zone | Large sessions and repeated loops | .notes/<task>/handoff.md |\n\n## Agent-ready prompt\n\n```text\nBefore starting this goal, externalize state.\nCreate .goals/<task>.md with objective, constraints, stop condition, and verification.\nCreate .notes/<task>/ for receipts.\nEvery major phase must write a checkpoint: research, plan, implementation, verification, final diff review.\nIf context gets large, compact to .notes/<task>/handoff.md and resume from that artifact.\n```\n\n## Applied stories\n\n### Goal that will not converge\n\n**Role:** Solo developer\n\nCodex keeps exploring alternatives and never ships.\n\n**Agent brief:** Narrow to one shippable slice, write explicit stop condition, and require a verification receipt before continuing.\n\n**Done when:**\n\n- goal file\n- single next slice\n- verification command\n- final receipt\n\n### Memory drift cleanup\n\n**Role:** Repo maintainer\n\nAgent memory says old commands are true, but package scripts changed.\n\n**Agent brief:** Audit memories against package.json/CI, write corrections to local notes, and update durable instructions only after verification.\n\n**Done when:**\n\n- memory audit\n- verified commands\n- updated AGENTS.md or skill\n- stale facts removed\n\n## Tips and gotchas\n\n- Use local markdown as the durable memory for a task; do not rely on hidden conversational state.\n- Ask for numbered options with a recommended pick when you need to steer quickly.\n- Treat /goal as research + plan + implement + verify in one bounded loop, not infinite autoresearch.\n- Use compact summaries when receipts are better than raw chat history.\n\n## References\n\n- [Grill Me skill](https://www.aihero.dev/skills-grill-me)\n- [Beads](https://github.com/gastownhall/beads)\n- [Caveman](https://github.com/JuliusBrussee/caveman)\n\n## Related principles\n\n- [Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/)\n- [Combine intent, implementation, and output for autonomous work](/topics/foundations-context-triad-and-overnight-work/)\n- [Preserve contracts and state machines while code changes](/topics/foundations-contracts-state-machines-and-code/)"
}
