---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "foundations-goal-memory-field-guide"
title: "Goal, Memory, and Context Hygiene Field Guide"
---

# Goal, Memory, and Context Hygiene Field Guide

> 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

```text
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

- [Grill Me skill](https://www.aihero.dev/skills-grill-me)
- [Beads](https://github.com/gastownhall/beads)
- [Caveman](https://github.com/JuliusBrussee/caveman)

## Related principles

- [Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/)
- [Combine intent, implementation, and output for autonomous work](/topics/foundations-context-triad-and-overnight-work/)
- [Preserve contracts and state machines while code changes](/topics/foundations-contracts-state-machines-and-code/)

## Original references

- [Agent foundations: Keep agent memory visible and grounded (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-03.html)
- [Agent foundations: Combine intent, implementation, and output for autonomous work (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-10.html)
- [Agent foundations: Preserve contracts and state machines while code changes (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-11.html)
