Agent Memory

Agent procedure

Memory is layered. Load the smallest useful layer.

Layout

MEMORY/
├── daily/YYYY-MM-DD.md      # session summaries (auto-load today/yesterday)
├── observations/            # raw external notes (append-only)
└── learned/                 # synthesized durable insights (on demand)

Daily memory (SHOULD)

At bootstrap, read today and yesterday if present.

During/after work:

append_file MEMORY/daily/YYYY-MM-DD.md
# bullet summary: goals, decisions, open questions, paths touched

Keep daily notes short. Move durable conclusions to learned/.

Observations (SHOULD for external inputs)

When capturing raw research, quotes, or tool dumps:

append_file MEMORY/observations/YYYY-MM-DD_<topic>.md

Rules:

• Append-only — do not silently rewrite prior observations
• Keep provenance (URL, timestamp, why captured)
• Do not put secrets in observations

Learned knowledge (MAY / on demand)

When a pattern will matter across sessions:

read_file MEMORY/learned/<topic>.md    # before writing duplicates
write_file MEMORY/learned/<topic>.md   # synthesized, versioned insight

Do not auto-load learned/ at bootstrap.

What goes where

Retrieval order (SHOULD)

1. Today/yesterday daily
2. Relevant PROJECTS/ files
3. grep observations
4. Specific learned/ docs
5. Only then broaden search

Human notes

Layering prevents context blow-ups and keeps audit trails.

Anti-patterns

• One giant memory.md that grows forever
• Editing observation files instead of appending
• Storing credentials in memory files
• Auto-injecting all of learned/ every session