Memory Best Practices

Good memory is small, durable, and easy to verify. Bad memory is a transcript dump with a filename.

Use memory when a future session should benefit from a fact without rediscovering it. Do not use memory as a notebook for every step you took.

Store Durable Signal

Write a memory when the information is:

• stable enough to survive the current session
• likely to help future work
• specific enough to act on
• safe to store in a Markdown file
• grounded in something that actually happened

Do not store:

• secrets, tokens, private keys, credentials, or raw customer data
• one-off command transcripts
• speculative ideas without a decision
• temporary errors that were already fixed and no longer matter
• large copied source files or generated output
• information that belongs in repository docs or code comments

Pick The Right Type

If a fact would mislead another repository, it is probably workspace memory. If it reflects a user preference that should follow the operator everywhere, it is probably global memory.

Prefer Updating Existing Files

Before writing a new memory, list and read what already exists:

agh memory list

agh memory read docs-package.md --scope workspace

Update the existing file when the new fact belongs with the old topic. Create a new file only when the topic is distinct.

This keeps MEMORY.md indexes short and helps dream consolidation avoid near-duplicates.

Write Good Frontmatter

The name and description fields are what users and agents see first. Make them concrete.

Prefer this:

---
name: Site Build Selector
description: Use the @agh/site package selector for filtered docs builds
type: project
---

Avoid this:

---
name: Build
description: Build stuff
type: project
---

Good descriptions answer: "Why would a future agent open this file?"

Name Files For Lookup

Use stable, lowercase filenames with words separated by hyphens:

site-build-selector.md
review-style.md
session-events-api.md
test-integrity.md

Avoid dates in filenames unless the memory is about a dated event. Put absolute dates in the body when time matters:

On 2026-04-16, task-specific docs builds used `bunx turbo run build --filter=@agh/site`.

Absolute dates stay understandable after the session context is gone.

Keep Indexes Useful

MEMORY.md is what AGH injects into the startup prompt. Treat it as the discovery surface, not as the full memory store.

Good index entries:

- [Site Build Selector](site-build-selector.md) - Use `@agh/site` for filtered docs builds.
- [Test Integrity](test-integrity.md) - Fix production code when tests reveal broken behavior.

Weak index entries:

- [Notes](notes.md) - Various notes.
- [Long Transcript Summary](long-transcript-summary.md) - This file contains a lot of information from many sessions and may be useful for many future tasks across several unrelated areas.

Keep each entry short enough that the agent can scan it quickly. The runtime truncates an index at 200 lines and 25 KB before prompt injection, but useful indexes should stay well below that.

Worked Example

Suppose a session discovers that the task file's old build selector is stale and the package name is the reliable selector. That is durable workspace knowledge.

Write the memory:

agh memory write site-build-selector.md \
  --type project \
  --description "Use the @agh/site package selector for filtered docs builds" \
  --content 'For docs-only verification, use `bunx turbo run build --filter=@agh/site`. The older task text `--filter=packages/site` is a stale selector because the package is named `@agh/site`.'

Add or tighten the workspace index:

- [Site Build Selector](site-build-selector.md) - Use `@agh/site` for filtered docs builds.

Future sessions now see the index line at startup and can read the file when build verification matters.

Review Memory For Staleness

AGH tells agents that memories older than one day should be verified before being asserted as fact. That is a prompt policy, not a guarantee that old memory is wrong.

Use this rule:

When a memory is stale, update it in place or delete it. Do not keep a stale fact and add a second memory that contradicts it.

Keep Secrets Out

Memory files are plain Markdown on disk. Treat them as durable local records that may be backed up, shared with a workspace, or inspected by future agents.

Never store:

• API keys
• OAuth tokens
• session cookies
• private keys
• passwords
• proprietary customer payloads
• one-off secrets copied from terminal output

Store a reference to where a secret is configured instead:

The GitHub MCP server expects `GITHUB_TOKEN` in the daemon environment. Do not store the token value
in memory files.

Use Dream As Cleanup, Not A Substitute For Judgment

Dream consolidation can merge, prune, and rebuild indexes, but it is still working from the signal you leave behind. Write focused memory files first. Let dream consolidation compress and organize them later.

When in doubt, ask one question before writing:

Would a future agent make a better decision because this memory exists?

If the answer is no, leave it out.

Related Pages

• Memory System documents the file format and prompt injection.
• Global vs Workspace Memory explains scope selection.
• Dream Consolidation explains automatic cleanup.
• Memory Write CLI shows generated command reference.