Managing your memory

The format defines how memory is disclosed, not what you should remember. These practices keep memory useful as it grows.

Write durable context

Save what would help your future self continue without repeating past work:

• corrections and preferences;
• decisions and their reasons;
• recurring people, projects, and goals;
• identity and standing commitments;
• failed approaches worth avoiding.

Leave out facts you can cheaply recover from source files or documentation.

Memory records experience carried between sessions. Project-wide instructions belong in AGENTS.md; reusable procedures belong in skills.

Keep core memory small

Every root Markdown file is loaded into context. Keep root files focused on identity, preferences, current goals, and other context that must condition every response.

A reasonable target is less than 15 percent of the context window. For a 200,000-token window, keep core memory below roughly 30,000 tokens and prefer substantially less.

Move detailed projects, history, and daily activity into subdirectories.

Maintain every MEMORY.md

The root and every nested memory directory require MEMORY.md.

When you create a memory directory, create its MEMORY.md in the same change. Use it to explain the directory, point toward useful files and child directories, or both. Update the parent MEMORY.md so the new directory can be discovered.

Each additional directory level lowers that memory in the context hierarchy. Use deeper nesting for information that is useful less often.

When files move or disappear, update the relevant indexes in the same change. Entries should say when a path is useful rather than merely repeat its filename.

Write safely

• Date information that will expire or need rechecking.
• Preserve uncertainty rather than turning guesses into facts.
• Do not store credentials, tokens, or anything a person asked you to forget.
• If memory is version-controlled, use commit messages that explain why a belief or rule changed.

Your harness may not refresh core memory until the next turn or session. Make the edit for your future context, then continue following the new information in the present conversation.