---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "foundations-agent-memory-playbook"
title: "Agent-managed memory folders playbook"
---

# Agent-managed memory folders playbook

> 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.

[Core principles](/topics/foundations-visible-agent-memory/)

## 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

```text
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 .goals` creates the two local memory folders.
- `git config --global core.excludesFile ~/.gitignore_global` then 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 right` opens 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`)](https://git-scm.com/docs/gitignore), [CMUX](https://cmux.com/).

## Reusable skill

Install as `~/.agents/skills/agent-memory-folders/SKILL.md`, then restart Codex.

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

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

[Open reference](/topics/foundations-visible-agent-memory/)

[Open reference](/topics/foundations-agent-memory-playbook/)

[Open reference](/topics/foundations-agent-memory-playbook/)

```text
mkdir -p .notes .goals
```

```text
git config --global core.excludesFile ~/.gitignore_global
```

```text
cmux markdown open .notes/tracker.md --direction right
```

```text
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.md` contains numbered items with A/B/C options and clear recommended picks.
- `.notes/tracker.md` is 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 checking `git status --ignored` and 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 `3B` before 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

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

[Open reference](/topics/foundations-visible-agent-memory/)

[Open reference](/topics/foundations-visible-agent-memory/)

[Open reference](/topics/foundations-agent-memory-playbook/)

[Open reference](/topics/foundations-cmux-orchestrate-playbook/#command-reference)

```text
cmux markdown open .notes/tracker.md --direction right
```

```text
cmux list-panes
```

```text
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.md` includes a `Stale or revalidated assumptions` section.
- 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

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

[Open reference](/topics/foundations-visible-agent-memory/)

[Open reference](/topics/foundations-agent-memory-playbook/)

[Open reference](/topics/foundations-agent-memory-playbook/)

```text
git status --ignored
```

```text
git config --global core.excludesFile ~/.gitignore_global
```

```text
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/`, and `git status --ignored` confirms the folders are local-only.
- The shared repo `.gitignore` is unchanged unless explicitly approved.
- `.goals/component-a11y-investigation.md` gives steerable numbered options rather than a single vague recommendation.
- `.notes/tracker.md` contains 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 `5B` is 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 `.gitignore` changes 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.

[Open reference](/topics/foundations-visible-agent-memory/)

### Existing setup prompt

Use this when generating copy-paste setup instructions for a coding agent.

[Open reference](/topics/foundations-agent-memory-playbook/)

### Existing Codex skill

Use this when implementing or checking the repo-local skill for agent-memory folders.

[Open reference](/topics/foundations-agent-memory-playbook/)

### CMUX live Markdown command

Use this to open the live-refreshing tracker pane beside the agent session.

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

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

```text
git status --ignored
```

## Original references

- [Agent foundations: Keep agent memory visible and grounded (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-03.html)
