Original source pages and recordings require authorized access. The full article text here is public.
Web developers already run local dev servers, browser checks, and coding agents against real repos. Agent-managed memory folders give those agents a visible place to plan, track, and resume work without polluting source control or turning scratch notes into stale project documentation.
Copy-paste workflow
When to use: At the start of any project where you want agents to keep visible Markdown plans, notes, and goals close to the code without committing them. This creates .notes/ and .goals/, ignores them globally, and opens a live-refreshing Markdown tracker pane.
Copy-paste prompt
You are my coding agent. Set up local agent-managed memory the workshop way, then use it. These are LOCAL working files, not source — keep them boring and close to the repo, and never commit them.
1. Create the memory folders:
mkdir -p .notes .goals
2. Ignore them across ALL my repos via a global gitignore:
git config --global core.excludesFile ~/.gitignore_global
echo '.notes/' >> ~/.gitignore_global
echo '.goals/' >> ~/.gitignore_global
3. Write the current plan into .goals/ as Markdown, then open a live-refreshing tracker pane next to the code:
cmux markdown open .notes/tracker.md --direction right
4. When you plan, use the numbered-option pattern so I can steer with terse refs: give me a NUMBERED list where each item has options A/B/C and YOUR recommended pick. I will reply with refs like "5B" or "27D" to choose.
How it works
mkdir -p .notes .goalscreates the two local memory folders.git config --global core.excludesFile ~/.gitignore_globalthen appending.notes/and.goals/keeps them out of every repo by default — they are working files, not source.cmux markdown open .notes/tracker.md --direction rightopens the Markdown in a formatted viewer with live file watching (auto-refresh) as a side tracker pane.- The numbered-option planning pattern (each item has A/B/C plus the agent's recommended pick) lets you steer with terse references like
5B. - Reference: Git global gitignore (
core.excludesFile), CMUX.
Reusable skill
Install as ~/.agents/skills/agent-memory-folders/SKILL.md, then restart Codex.
---
name: agent-memory-folders
description: Trigger at project start (or when an agent needs visible local working memory) to create .notes/ and .goals/, ignore them via global gitignore, and open a live Markdown tracker. Do NOT use for files meant to be committed.
---
# Agent memory folders
Provision local agent-managed memory: `.notes/` for working notes and `.goals/` for plans, ignored globally so they never get committed, plus a live Markdown tracker pane. These are LOCAL working files — keep them boring and close to the repo.
## Steps
1. Create the folders:
```bash
mkdir -p .notes .goals
```
2. Ignore them across ALL repos via a global gitignore:
```bash
git config --global core.excludesFile ~/.gitignore_global
echo '.notes/' >> ~/.gitignore_global
echo '.goals/' >> ~/.gitignore_global
```
3. Write the current plan into `.goals/` as Markdown, then open a live-refreshing tracker pane (auto-refresh via file watching) next to the code:
```bash
cmux markdown open .notes/tracker.md --direction right
```
4. Use the numbered-option planning pattern: present a NUMBERED list where each item has options A/B/C plus your recommended pick, so the human steers with terse refs like `5B` or `27D`.
## Guardrails
- These are local working files, NOT source — never commit them.
- Keep them boring and close to the repo.
Scenarios
Plan and track a risky checkout-flow fix
Role: As a senior frontend engineer responsible for a Next.js checkout flow
A production-like checkout bug only appears after several UI states: shipping form edits, coupon entry, back navigation, and payment-step refresh. The developer wants Codex to plan before touching code, keep progress visible, and leave no agent scratch files in Git.
As a senior frontend engineer, I want the agent to create local memory folders, write a numbered implementation plan, and maintain a live tracker while fixing the checkout flow, so that I can steer the work precisely and review progress without rereading the whole agent transcript.
Agent brief
Set up local agent-managed memory for this repo, then use it for the checkout fix. Run: `mkdir -p .notes .goals`. Configure global ignores without editing this repo's shared `.gitignore`: `git config --global core.excludesFile ~/.gitignore_global`; then ensure `.notes/` and `.goals/` are present in `~/.gitignore_global` without duplicating lines. Inspect the current checkout code before planning; do not trust old notes as source of truth. Write `.goals/checkout-flow-plan.md` as a numbered plan where each major item has options A/B/C and your recommended pick. Open a live tracker with `cmux markdown open .notes/tracker.md --direction right`. Keep `.notes/tracker.md` updated with current step, files inspected, commands run, browser proof status, and remaining risks. After I choose plan refs like `2B` or `5C`, implement only the approved path. Expected output: changed source files only where needed, `.goals/checkout-flow-plan.md`, `.notes/tracker.md`, and a final summary that separates committed-source changes from local scratch artifacts.
Implementation references
mkdir -p .notes .goals
git config --global core.excludesFile ~/.gitignore_global
cmux markdown open .notes/tracker.md --direction right
cmux --json tree
Browser verification
Use the running local app, preferably in a CMUX browser pane or browser-agent workflow. Start at the checkout page, take an accessibility snapshot, fill the shipping fields, apply a coupon, navigate back and forward, refresh on the payment step, and capture console output plus a screenshot or short written browser receipt. If using agent-browser-style tooling, use snapshot/click/fill/evaluate steps and write the result into .notes/tracker.md.
Definition of done
.notes/and.goals/exist locally and are globally ignored, not added to the repo's shared.gitignore..goals/checkout-flow-plan.mdcontains numbered items with A/B/C options and clear recommended picks..notes/tracker.mdis usable as a live progress receipt and lists the exact files touched, commands run, and browser verification performed.- The checkout flow is verified in the browser with the failing sequence, and the final source diff excludes
.notes/and.goals/.
Failure modes and mitigations
- The agent commits
.notes/or.goals/; mitigate by checkinggit status --ignoredand confirming those folders are ignored globally before implementation. - The agent writes a vague prose plan that is hard to steer; mitigate by requiring numbered items with lettered options and waiting for human refs like
3Bbefore coding.
Resume a paused redesign without stale memory
Role: As a product-minded full-stack developer iterating on a dashboard UI
A dashboard redesign was started yesterday, but the app has changed since then. The developer wants to resume from local agent notes while forcing the agent to re-check current code and verify the UI in the browser.
As a full-stack developer, I want the agent to read prior local goals but treat the current code and running browser as truth, so that yesterday's plan helps me resume without misleading today's implementation.
Agent brief
Use the agent-memory-folder pattern to resume work safely. First inspect `.goals/` and `.notes/` if they exist, but treat them as local scratch context only. Then inspect the current dashboard files and summarize where the existing notes agree or disagree with the current code. If folders do not exist, create them with `mkdir -p .notes .goals` and ensure `.notes/` and `.goals/` are in the global gitignore via `git config --global core.excludesFile ~/.gitignore_global`. Write `.goals/dashboard-resume-plan.md` with numbered implementation items and A/B/C options. Mark any stale assumptions explicitly. Open or update the live tracker using `cmux markdown open .notes/tracker.md --direction right`. Implement only the approved plan choices. Expected output: a resume plan, a stale-assumption section, a live tracker update, a source diff, and browser evidence from the running dashboard.
Implementation references
cmux markdown open .notes/tracker.md --direction right
cmux list-panes
cmux read-screen
Browser verification
Open the dashboard in a local browser or CMUX browser pane, compare the current rendered UI against the resumed plan, and record proof in .notes/tracker.md: current route, visible dashboard sections, any console errors, and a screenshot or browser-agent accessibility snapshot. Use click/fill/evaluate where the redesign affects interactive filters, tabs, or responsive state.
Definition of done
- The agent explicitly distinguishes prior local notes from current source-of-truth code.
.goals/dashboard-resume-plan.mdincludes aStale or revalidated assumptionssection.- The live tracker shows what was resumed, what was discarded, and what was implemented.
- Browser verification proves the dashboard still renders and the changed interaction works after the source diff.
Failure modes and mitigations
- The agent blindly follows yesterday's
.goals/file; mitigate by requiring a current-code inspection and an agreement/disagreement summary before edits. - The live tracker becomes a dumping ground; mitigate by keeping it short: current step, evidence, next action, blockers, and files touched.
Keep agent planning out of a shared library repo
Role: As a maintainer of a shared component library used across several web apps
Multiple agents are about to investigate a flaky component test and accessibility regression. The maintainer wants reusable local planning files, but the repo is shared by a team and must not gain private scratch folders or noisy .gitignore changes.
As a component-library maintainer, I want each agent to write plans and findings into globally ignored local folders, so that exploratory work stays close to the repo but never leaks into the package or team Git history.
Agent brief
Prepare this shared repo for local-only agent planning. Create `.notes/` and `.goals/` with `mkdir -p .notes .goals`. Use the global ignore boundary: `git config --global core.excludesFile ~/.gitignore_global`; ensure `.notes/` and `.goals/` are present there exactly once. Do not edit the repo `.gitignore` unless I explicitly ask. Write `.goals/component-a11y-investigation.md` as a numbered plan with A/B/C options and recommended picks. Use `.notes/tracker.md` to record each agent's assigned area, commands run, and findings. If CMUX is available, open the tracker with `cmux markdown open .notes/tracker.md --direction right`; otherwise leave the Markdown file ready for any preview pane. Expected output: local planning artifacts, no committed scratch files, a concise investigation plan, and a review summary I can use to decide which findings become real tests or source changes.
Implementation references
git status --ignored
git config --global core.excludesFile ~/.gitignore_global
cmux markdown open .notes/tracker.md --direction right
Browser verification
Browser proof is useful only if the component library has a local preview, demo route, or app fixture. If available, run the local preview, inspect the component in a browser, capture an accessibility snapshot or screenshot, and record the result in .notes/tracker.md. If there is no browser fixture, use test output and the rendered component documentation as proof instead of inventing a browser check.
Definition of done
- Global Git ignore contains
.notes/and.goals/, andgit status --ignoredconfirms the folders are local-only. - The shared repo
.gitignoreis unchanged unless explicitly approved. .goals/component-a11y-investigation.mdgives steerable numbered options rather than a single vague recommendation..notes/tracker.mdcontains a clean investigation receipt that can be reviewed without committing the scratch files.
Failure modes and mitigations
- The agent treats local memory as team documentation; mitigate by labeling every file in
.notes/and.goals/as local working memory and excluding it from source diffs. - The agent over-invests in permanent tests for unstable UI exploration; mitigate by using the notes to triage first, then promote only stable, valuable checks into real tests.
Implementation notes
- Keep
.notes/and.goals/boring, local, and close to the repo. They are working files for agents, not production docs. - Have the agent inspect current code before implementation. Memory folders help with continuity, but code remains the source of truth when details matter.
- Use numbered items with lettered options for plans that need human steering. A reply like
5Bis faster and less error-prone than quoting a paragraph back to the agent. - Use the live Markdown tracker as a status view, not a transcript clone. The useful shape is current task, evidence, commands, files touched, blockers, and next step.
- For web app work, pair the tracker with browser evidence: a screenshot, accessibility snapshot, console result, Playwright result, or concise manual browser receipt.
- Before finalizing, require a source diff review that excludes
.notes/and.goals/.
Boundaries and caveats
- Do not reintroduce Beads or other third-party memory systems as a taught workflow for this topic.
- Do not treat GrillMe as the main workflow here; it was mentioned as occasional follow-up after seeing a drafted plan.
- Do not build a complex memory database, RAG system, or automatic commit-synchronized memory layer for this workflow.
- Do not add repo-local
.gitignorechanges unless the human explicitly wants that; the taught boundary is global gitignore partitioning. - Do not over-specify browser automation APIs that were not taught. Use practical browser proof shapes: CMUX browser pane, browser-agent snapshot/click/fill/evaluate, Playwright, or a local browser receipt.
Agent reference map
Validated lesson 03 references
Use this as the ground truth for what was taught: local .notes/ and .goals/, global gitignore partitioning, plan-first grounding, numbered option planning, and live Markdown side panes.
Existing setup prompt
Use this when generating copy-paste setup instructions for a coding agent.
Existing Codex skill
Use this when implementing or checking the repo-local skill for agent-memory folders.
CMUX live Markdown command
Use this to open the live-refreshing tracker pane beside the agent session.
cmux markdown open .notes/tracker.md --direction right
Global gitignore setup
Use this to keep local agent scratch folders out of every repo without modifying shared .gitignore files.
git config --global core.excludesFile ~/.gitignore_global
Verify ignored scratch folders
Use this before final review to prove .notes/ and .goals/ are not part of the source diff.
git status --ignored