{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "foundations-visible-agent-memory",
  "slug": "visible-agent-memory",
  "title": "Keep agent memory visible and grounded",
  "summary": "Create agent-managed notes/goals folders the harness can read and write; Partition context by globally gitignoring those agent-managed folders; Track progress with a live, auto-refreshing Markdown side pane as a visual checklist.",
  "category": "Context",
  "tags": [
    "memory",
    "goals",
    "CMUX"
  ],
  "sources": [
    {
      "label": "Agent foundations: Keep agent memory visible and grounded (authorized access required)",
      "url": "https://codex-workshop-followup.pages.dev/lesson-03.html"
    }
  ],
  "sourceUnits": [
    "oracle/lessons.json#03/objectives",
    "oracle/03-references.json#recap",
    "oracle/03-references.json#concepts/0",
    "oracle/03-references.json#concepts/1",
    "oracle/03-references.json#concepts/2",
    "oracle/03-references.json#concepts/3",
    "oracle/03-references.json#concepts/4",
    "oracle/03-references.json#references",
    "oracle/03-references.json#recommendations",
    "oracle/03-interactive.json#intro",
    "oracle/03-interactive.json#checklist",
    "oracle/03-interactive.json#challenges",
    "oracle/03-interactive.json#quiz",
    "oracle/03-interactive.json#reflect",
    "oracle/03-references.json#goDeeper",
    "materials/exercises.md#Chunk-03",
    "materials/qa-index.md#Q010",
    "materials/qa-index.md#Q011",
    "materials/qa-index.md#Q013",
    "materials/qa-index.md#Q014",
    "final/qa-index.md#Chunk-03",
    "materials/keyframes.md#Chunk-03",
    "lesson-03.html#resource-packet",
    "lesson-03.html#clip-map",
    "lesson-03.html#recording"
  ],
  "collection": "foundations",
  "categoryId": "context",
  "wordCount": 2416,
  "url": "/topics/foundations-visible-agent-memory/",
  "markdownUrl": "/markdown/foundations-visible-agent-memory.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/foundations-visible-agent-memory.json",
  "headings": [
    {
      "id": "working-outcomes",
      "text": "Working outcomes",
      "level": 2
    },
    {
      "id": "concepts-and-consequences",
      "text": "Concepts and consequences",
      "level": 2
    },
    {
      "id": "agent-managed-folders",
      "text": "Agent-managed folders",
      "level": 3
    },
    {
      "id": "global-gitignore-partitioning",
      "text": "Global gitignore partitioning",
      "level": 3
    },
    {
      "id": "plan-first-goal-grounding",
      "text": "Plan-first goal grounding",
      "level": 3
    },
    {
      "id": "numbered-option-planning",
      "text": "Numbered option planning",
      "level": 3
    },
    {
      "id": "live-markdown-side-panes",
      "text": "Live Markdown side panes",
      "level": 3
    },
    {
      "id": "reference-tools-and-resources",
      "text": "Reference tools and resources",
      "level": 2
    },
    {
      "id": "codex-trainer",
      "text": "Codex Trainer",
      "level": 3
    },
    {
      "id": "cmux-extensions",
      "text": "CMUX Extensions",
      "level": 3
    },
    {
      "id": "grillme-skill",
      "text": "GrillMe skill",
      "level": 3
    },
    {
      "id": "git-global-gitignore",
      "text": "Git global gitignore",
      "level": 3
    },
    {
      "id": "recommendations-and-best-practices",
      "text": "Recommendations and best practices",
      "level": 2
    },
    {
      "id": "practice-and-acceptance-criteria",
      "text": "Practice and acceptance criteria",
      "level": 2
    },
    {
      "id": "checklist",
      "text": "Checklist",
      "level": 3
    },
    {
      "id": "ignored-memory-folders",
      "text": "Ignored Memory Folders",
      "level": 3
    },
    {
      "id": "steer-a-plan-by-coordinates",
      "text": "Steer a Plan by Coordinates",
      "level": 3
    },
    {
      "id": "live-markdown-progress-view",
      "text": "Live Markdown Progress View",
      "level": 3
    },
    {
      "id": "questions-to-test-understanding",
      "text": "Questions to test understanding",
      "level": 2
    },
    {
      "id": "what-is-the-main-purpose-of-keeping-folders-like-notes-and-goals-inside-a-project",
      "text": "What is the main purpose of keeping folders like `.notes/` and `.goals/` inside a project?",
      "level": 3
    },
    {
      "id": "why-prefer-a-global-git-ignore-rule-for-notes-and-goals-instead-of-adding-them-to-every-repo-s-gitignore",
      "text": "Why prefer a global Git ignore rule for `.notes/` and `.goals/` instead of adding them to every repo's `.gitignore`?",
      "level": 3
    },
    {
      "id": "a-plan-from-the-agent-is-long-and-hard-to-steer-which-instruction-best-applies-the-lesson-s-numbered-option-planning-pattern",
      "text": "A plan from the agent is long and hard to steer. Which instruction best applies the lesson's numbered option planning pattern?",
      "level": 3
    },
    {
      "id": "what-problem-does-a-live-markdown-side-pane-solve-during-longer-agent-runs",
      "text": "What problem does a live Markdown side pane solve during longer agent runs?",
      "level": 3
    },
    {
      "id": "reflection-prompts",
      "text": "Reflection prompts",
      "level": 2
    },
    {
      "id": "further-applications",
      "text": "Further applications",
      "level": 2
    },
    {
      "id": "applied-exercises",
      "text": "Applied exercises",
      "level": 2
    },
    {
      "id": "questions-and-answers",
      "text": "Questions and answers",
      "level": 2
    },
    {
      "id": "how-do-you-keep-goal-grounded-do-you-use-grill-me-then-create-a-plan",
      "text": "how do you keep goal grounded? do you use grill-me? then create a plan?",
      "level": 3
    },
    {
      "id": "do-you-caveman-what-if-too-much-to-read",
      "text": "do you caveman? what if too much to read?",
      "level": 3
    },
    {
      "id": "are-you-using-the-memory-features-of-these-harneses-i-noticed-they-get-out-of-date-when-i-use-them-and-shifted-to-beads-but-even-that-has-some-clunk-still-https-github-com-gastownhall-beads",
      "text": "Are you using the memory features of these harneses? I noticed they get out of date when I use them and shifted to beads but even that has some clunk still https://github.com/gastownhall/beads",
      "level": 3
    },
    {
      "id": "do-you-mind-your-own-conversations-do-you-have-anything-that-goes-in-and-create-skills-or-or-reflects-on-your-conversations-it-automatically-improves",
      "text": "Do you mind your own conversations? Do you have anything that goes in and… Create skills, or… or reflects on… Your conversations, it automatically improves.",
      "level": 3
    },
    {
      "id": "operational-playbooks",
      "text": "Operational playbooks",
      "level": 2
    },
    {
      "id": "recording-references",
      "text": "Recording references",
      "level": 2
    },
    {
      "id": "visual-reference-index",
      "text": "Visual reference index",
      "level": 3
    }
  ],
  "markdown": "# Keep agent memory visible and grounded\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nThe practice is giving agents visible, local working memory without mixing that scratch work into production code. John shows a lightweight pattern: keep agent-written Markdown plans and notes in `.notes/` and `.goals/`, globally ignore those folders in Git, steer plans with numbered-and-lettered options, and use an auto-refreshing Markdown pane as a visual progress view while agents work.\n\n## Working outcomes\n\n- Create agent-managed notes/goals folders the harness can read and write\n- Partition context by globally gitignoring those agent-managed folders\n- Track progress with a live, auto-refreshing Markdown side pane as a visual checklist\n\n## Concepts and consequences\n\n### Agent-managed folders\n\nUse local folders like `.notes/` and `.goals/` inside each project as places where agents can write Markdown plans, notes, and goals. John describes these as agent-managed files and as a way to write plans into files you can resume from later.\n\n**Why it matters:** This keeps agent working context close to the codebase while clearly separating it from the source files you intend to commit.\n\n### Global gitignore partitioning\n\nInstead of adding `.notes/` and `.goals/` to every repository's `.gitignore`, John suggests globally ignoring those directories on your machine. That lets the same local agent-memory folders exist across projects without being checked into repos.\n\n**Why it matters:** It creates a machine-level boundary between private local agent scratch work and shared source control.\n\n### Plan-first goal grounding\n\nJohn says he often has the agent create a full plan document first, then reads it and dictates or types feedback about specific sections. He may use GrillMe only when he is still uncertain after seeing the plan.\n\n**Why it matters:** Reacting to a concrete plan can be faster than answering a long sequence of upfront questions.\n\n### Numbered option planning\n\nAsk the agent for a numbered list where each item has options such as A, B, and C, and have the agent explain which option it thinks is best. You can then review the document and respond with precise targets like `5B` or `27D`.\n\n**Why it matters:** It turns a large plan into an editable map, so you can steer the agent precisely without rewriting or quoting long sections.\n\n### Live Markdown side panes\n\nA Markdown file can become a live visual progress view if the agent updates it while working and the client auto-refreshes the rendered pane. John demonstrates this with a simple `test.md` file in CMUX and describes using Markdown as a checklist, progress view, summary, or conversation-history display.\n\n**Why it matters:** It lets you step away from the noisy agent transcript and return to a cleaner status view of what changed or what is happening.\n\n## Reference tools and resources\n\n### Codex Trainer\n\nA browser-based keyboard shortcut trainer John demonstrated for terminal and editor movement commands such as jumping to line start, deleting words, deleting lines, and yanking lines.\n\n**Use when:** Use it when terminal text editing feels slow or you feel stuck navigating text in command prompts; John specifically pointed to Editor Basics Forever Mode as the part he had worked on most.\n\n[Reference](https://codex-trainer.johnlindquist.workers.dev/)\n\n### CMUX Extensions\n\nJohn's public repository for CMUX extension examples, including file editing panes, Quick Markdown viewing, and launching tools such as LazyGit in a pane.\n\n**Use when:** Use it when you want to inspect or adapt the extension patterns John demonstrated for customizing an agent-first CMUX workspace.\n\n[Reference](https://github.com/johnlindquist/cmux-extensions)\n\n### GrillMe skill\n\nA structured clarification skill mentioned in the goal-grounding Q&A. John said he sometimes uses it after reading a drafted plan, but he did not demonstrate the skill in this section.\n\n**Use when:** Consider it when a drafted plan exposes unresolved questions; do not treat it as the main demonstrated workflow from this lesson.\n\n[Reference](https://www.aihero.dev/skills-grill-me)\n\n### Git global gitignore\n\nGit's mechanism for applying ignore patterns across all repositories on your machine.\n\n**Use when:** Use it when you want local-only folders like `.notes/` and `.goals/` to stay out of every repo by default.\n\nsearch: Git global gitignore core.excludesFile documentation\n\n## Recommendations and best practices\n\n- Create `.notes/` and `.goals/` in active projects for agent-written Markdown plans, notes, and goals, but treat them as local working files rather than source files.\n- Add `.notes/` and `.goals/` to your global Git ignore so the pattern works across projects without changing every repo's shared `.gitignore`.\n- Have the agent create a complete plan you can read before implementation, then dictate or type feedback against the plan.\n- Ask agents for numbered plans with lettered alternatives when the output will need review, because `5B` is easier to steer than “that section in the middle.”\n- Do the high-judgment planning pass when your energy is best, then use shorter prompts later to coordinate agents against the plan.\n- Use an auto-refreshing Markdown file as a sidecar checklist, progress view, or summary while an agent works.\n- Keep a file explorer or Git view visible when possible so you can notice unexpected file changes before they become part of the repo.\n\n## Practice and acceptance criteria\n\nPractice making agent work visible, local, steerable, and separate from committed code using hidden Markdown folders, numbered plans, and a live Markdown progress view.\n\n### Checklist\n\n1. In a non-critical test repo, create `.notes/` and `.goals/`.\n2. Put a simple Markdown note or plan file in one of those folders so the agent has a local file to write to.\n3. Configure your global Git ignore so `.notes/` and `.goals/` stay out of repos by default.\n4. Ask your agent to create a full plan in a Markdown file before implementation, then read the plan before proceeding.\n5. Ask the agent to turn the plan into a numbered list with options A, B, and C where useful, then steer it using references like `2B`, `4C`, and `6A`.\n6. Create a simple Markdown tracker file and open it in a Markdown preview or CMUX Quick Markdown side pane.\n7. Prompt the agent to update that Markdown file with checklist items, progress, or a short summary as the work progresses.\n8. Keep a file explorer or Git view visible if possible so you can spot unexpected file changes.\n\n### Ignored Memory Folders\n\n**Difficulty:** Easy\n\nCreate `.notes/` and `.goals/` in a test project, add a simple Markdown file inside one of them, and configure your global Git ignore so those folders stay local across repos.\n\n**Done when:** The folders can exist in the project for agent notes or goals without appearing as files to commit.\n\n### Steer a Plan by Coordinates\n\n**Difficulty:** Medium\n\nGive your agent a small feature idea and ask for a numbered implementation plan where each major item includes options A, B, and C. Do not ask for code yet. Review the plan by issuing targeted feedback such as `keep 1A`, `replace 3C`, `merge 5A and 5B`, and `delete 8C`.\n\n**Done when:** The revised plan reflects your targeted edits without requiring you to rewrite or quote large chunks of the plan.\n\n### Live Markdown Progress View\n\n**Difficulty:** Medium\n\nCreate a Markdown tracker file, open it in a Markdown preview or CMUX Quick Markdown pane, and ask the agent to update it with checklist items, progress, or summaries while it works.\n\n**Done when:** You can understand the task's progress from the Markdown file without rereading the full agent transcript.\n\n## Questions to test understanding\n\n### What is the main purpose of keeping folders like `.notes/` and `.goals/` inside a project?\n\n- **A.** To give agents a local place for Markdown plans, notes, and goals without mixing that scratch work with production code\n- **B.** To replace the project README with agent-generated documentation\n- **C.** To store generated code that should be committed after every agent run\n- **D.** To force the agent to use fewer files while editing the repository\n\n**Answer: A.** John describes these as agent-managed Markdown files: useful and close to the project, but kept separate from code you intend to check in.\n\n### Why prefer a global Git ignore rule for `.notes/` and `.goals/` instead of adding them to every repo's `.gitignore`?\n\n- **A.** Because global Git ignore rules make Git run faster\n- **B.** Because global Git ignore rules prevent Markdown files from being edited\n- **C.** Because it keeps the local agent-memory pattern consistent across projects without changing shared repo config\n- **D.** Because Codex can only read folders listed in a global Git ignore file\n\n**Answer: C.** A global ignore creates a machine-level rule: your local agent scratch folders can exist in every project without being checked into each repo.\n\n### A plan from the agent is long and hard to steer. Which instruction best applies the lesson's numbered option planning pattern?\n\n- **A.** Ask the agent to rewrite the whole thing more briefly, then accept the next version\n- **B.** Ask for a numbered plan where each item has options A, B, and C, then respond with targets like `keep 4B` or `revise 7C`\n- **C.** Ask the agent to hide its alternatives so the final answer is easier to read\n- **D.** Ask the agent to make every decision itself so you do not need to review the plan\n\n**Answer: B.** Numbered and lettered options turn a wall of text into an editable map. You can give precise feedback without restating the whole plan.\n\n### What problem does a live Markdown side pane solve during longer agent runs?\n\n- **A.** It guarantees the agent will never make a mistake\n- **B.** It replaces source control for experimental branches\n- **C.** It lets you monitor progress from a clean visual file instead of rereading the full agent transcript\n- **D.** It prevents the agent from reading any other files in the project\n\n**Answer: C.** John demonstrates using a Markdown file as an auto-refreshing checklist, progress view, summary, or conversation-history display while the agent works.\n\n## Reflection prompts\n\n- Where would local `.notes/` and `.goals/` folders genuinely help your current workflow, and where would they create clutter?\n- What kinds of plans, summaries, or goals are worth writing into local Markdown files near the code, and what should stay out of those files?\n- How would your review behavior change if every longer agent task had a clean live tracker instead of only a transcript?\n\n## Further applications\n\n1. Set up a tiny project template that creates `.notes/`, `.goals/`, and a simple Markdown tracker file, then globally ignores the folders.\n2. Try a planning prompt that asks for a numbered list with options A, B, and C under each item, then practice steering it with references like `2A`, `6C`, and `9B`.\n3. Clone the CMUX extensions repo and inspect how the Quick Markdown viewer is wired so you can adapt it to your own tracker files.\n4. Practice terminal editing in Codex Trainer's Editor Basics Forever Mode until line movement and deletion shortcuts feel automatic.\n5. Try a CMUX layout with your agent session, a Markdown tracker pane, and a file explorer or Git view visible at the same time.\n\n## Applied exercises\n\nGlobal Context Isolation \n\n**Setup:**  Developers should open their local terminal environments and add hidden .notes/ and .goals/ directory references to their global system gitignore setup (~/.gitignore_global). This ensures local AI scratchpads remain separated from production repository tracking.\n\nStructured Matrix Generation Experiment: Run an optimization exercise with a development agent. Instruct the model to build a 10-point structural project roadmap where every step generates three discrete alternative engineering paths labeled A, B, and C. Use specific code targets (e.g., \"Proceed with path 4B, but modify point 7C\") to evaluate prompt steerability.CMUX Extension Assembly: Clone the public cmux-extensions repository to a local workstation. Register and map the Quick Markdown Viewer utility to a custom hotkey combo, then test it using an auto-updating terminal log pipeline.\n\n## Questions and answers\n\n### how do you keep goal grounded? do you use grill-me? then create a plan?\n\nJohn confirms he utilizes Grill Me occasionally but generally prefers to let the agent generate a complete multi-tier plan document first. He reviews the comprehensive text block, uses dictation to call out bad blocks, and runs Grill Me routines only on areas where implementation paths remain ambiguous.\n\n### do you caveman? what if too much to read?\n\nJohn acknowledges the method after a developer provides clarification in the chat thread. He notes that using short, token-efficient phrasing helps clear out dense walls of conversational text. He uses the high-focus hours of the morning to set up structured plans, so that he can simply manage and coordinate agents through shorter prompts later in the day.\n\n### Are you using the memory features of these harneses? I noticed they get out of date when I use them and shifted to beads but even that has some clunk still https://github.com/gastownhall/beads\n\nJohn notes he uninstalled beads because its state-retention behavior felt too aggressive for his daily workflows. He prefers to leave the native client harness memory settings turned on. While native platforms occasionally push problematic state updates, they typically course-correct quickly. He adds that he has built several bespoke setups (like an asset called Basic Memory), but chooses to trust native client systems to handle long-term context state over the long run.\n\n### Do you mind your own conversations? Do you have anything that goes in and… Create skills, or… or reflects on… Your conversations, it automatically improves.\n\nJohn states he intends to demonstrate specific automated pipeline patterns and custom plugins designed exactly for conversational reflex analysis later during the workshop session.\n\n## Operational playbooks\n\n- [Agent-managed memory folders](/topics/foundations-agent-memory-playbook/)\n\n- [CMUX Orchestration Field Guide](/topics/foundations-cmux-orchestration-field-guide/)\n- [Goal, Memory, and Context Hygiene Field Guide](/topics/foundations-goal-memory-field-guide/)\n\n## Recording references\n\n- [Recording](https://codex-workshop-followup.pages.dev/video/lessons/lesson-03.mp4)\n\n[Timestamped source page](https://codex-workshop-followup.pages.dev/lesson-03.html)\n\n### Visual reference index\n\n- [00:54:26](https://codex-workshop-followup.pages.dev/lesson-03.html#clip-03-1): Terminal view showing hidden agent notes and goals directory setup steps\n- [00:54:48](https://codex-workshop-followup.pages.dev/lesson-03.html#clip-03-2): System configuration screen depicting global gitignore assignment prompt syntax\n- [00:56:40](https://codex-workshop-followup.pages.dev/lesson-03.html#clip-03-3): Markdown planning layout utilizing a numbered and indexed choice matrix\n- [00:59:14](https://codex-workshop-followup.pages.dev/lesson-03.html#clip-03-4): Browser output interface rendering the interactive line-editing trainer application tool\n- [00:59:58](https://codex-workshop-followup.pages.dev/lesson-03.html): Selection screen choosing Forever Mode navigation parameters within the trainer workspace\n- [01:02:38](https://codex-workshop-followup.pages.dev/lesson-03.html): CMUX command menu modal invoked via terminal macro short sequence\n- [01:02:53](https://codex-workshop-followup.pages.dev/lesson-03.html): Split screen layout tracking active shell setup file edits inside secondary console split\n- [01:03:06](https://codex-workshop-followup.pages.dev/lesson-03.html): Simultaneous active session view displaying embedded inline instance of LazyGit terminal client\n- [01:04:19](https://codex-workshop-followup.pages.dev/lesson-03.html): Quick Markdown visualization component displaying project README document\n- [01:05:38](https://codex-workshop-followup.pages.dev/lesson-03.html): Triple column workstation view with active workspace file manager and centralized auto-refresh tracking chart"
}
