Notes on AI workflow

Persisting LLM knowledge across sessions

June 5, 2026

You open a new AI coding session. It asks what the app does, scans the repo, finds the test command, and rediscovers the same deployment quirk yesterday's session already found.

Annoying, right? But also predictable. We keep giving the assistant a fresh window and expecting it to act like a teammate with memory.

My fix is simple: add a project memory file. Use AGENTS.md for Codex-style agents, CLAUDE.md for Claude Code, or whatever your tool reads automatically. Your job is to seed the operating guide. The agent's job is to maintain it while it works.

Stop paying the rediscovery tax

The file should tell the next session what previous sessions learned the hard way. Not because you manually wrote every note, but because agents continuously preserve durable facts there:

  • -Commands that actually work here.
  • -Required local services, env vars, and setup order.
  • -Architectural or product decisions that are easy to misread.
  • -Known traps, flaky checks, and verification notes.

Think of it as a self-maintained handoff note, not documentation theater. If a future assistant would otherwise spend ten minutes rediscovering something, the current assistant should upsert it.

Make the assistant maintain the memory

A strong starter file looks like this:

# AGENTS.md

## Purpose

This file is the operating guide for AI agents working in this repository.

The agent must maintain project specifications directly inside this file while working. The goal is for this file to become the durable source of truth for what the agent learns about the project: requirements, architecture, conventions, workflows, decisions, constraints, and implementation details.

The agent must update this file proactively during work, without waiting for explicit human requests.

---

## Core Instruction

While working on any task, the agent must continuously preserve useful project knowledge by upserting information into this file.

"Upsert" means:

* Add new information when it is discovered.
* Update existing information when it becomes stale, incomplete, or incorrect.
* Avoid duplicating facts that are already recorded.
* Keep related information grouped together.
* Prefer concise, factual notes over long explanations.

The agent should treat this file as a living project specification.

---

## Silent Maintenance Requirement

The agent should maintain this file silently and autonomously.

The agent must not ask the human whether it should update this file.

The agent must not require a direct request before updating this file.

The agent should update this file as part of normal work whenever it learns something useful.

---

## Project Specifications

### Product Overview

<!-- Record what the project does, who it is for, and the core product goals. -->

### Requirements

<!-- Record durable functional and non-functional requirements. -->

### Architecture

<!-- Record high-level architecture, major modules, data flow, and integration boundaries. -->

### Repository Structure

<!-- Record important directories and files, especially places future agents should or should not edit. -->

### Development Workflow

<!-- Record setup, install, build, test, lint, format, and run commands. -->

### Coding Conventions

<!-- Record naming rules, formatting expectations, framework patterns, and preferred implementation style. -->

### Testing Strategy

<!-- Record test frameworks, required test coverage expectations, and how to run relevant tests. -->

### Data Models

<!-- Record important entities, schemas, migrations, validation rules, and serialization conventions. -->

### API Contracts

<!-- Record endpoints, request/response shapes, authentication requirements, and compatibility constraints. -->

### UI/UX Conventions

<!-- Record design system usage, accessibility requirements, copy rules, and user-facing behavior. -->

### Security and Privacy

<!-- Record security constraints, privacy expectations, secret handling, and sensitive-data rules. -->

### Known Constraints

<!-- Record technical, product, business, or compatibility constraints. -->

### Known Issues

<!-- Record durable known bugs, limitations, and failure modes. -->

### Decisions

<!-- Record important decisions and their rationale when useful. -->

### Assumptions

<!-- Record assumptions the agent made in order to continue working without blocking. -->

### Open Questions

<!-- Record unresolved questions that require human or external clarification. -->

---

## Agent Working Rules

Before finishing any task, the agent must check whether this file should be updated with newly discovered requirements, conventions, commands, architecture, constraints, risks, assumptions, or open questions.

If updates are needed, the agent must make them before completing the task.

The agent should continue autonomously whenever safe and avoid asking for confirmation unless genuinely blocked.
:::

This is the retention loop. The assistant works, learns something stable, upserts it into the operating guide, and the next session starts with that context.

The agent still needs a high bar. It should not record every observation. It should record the facts that affect future work: requirements, commands, architecture, constraints, risks, assumptions, and open questions.

The payoff is a better first answer

The reward is not perfect memory. It is fewer cold starts. The next session knows the app shape, the sharp edges, and the decisions that are not obvious from one diff.

One warning: the file can become a junk drawer fast. The instruction should make the agent keep notes concise, fix stale entries, remove wrong ones, and never store secrets.

That is the whole pattern: let each session leave behind the small pieces of context that would otherwise disappear, so the next session starts closer to the truth.

After that, you should not have to babysit the memory. When the assistant uncovers a non-obvious setup step or a buried product decision, the operating guide already tells it what to do.