Memory
Sync important context to persistent storage so future sessions start informed.
Memory Types
| Type |
What it stores |
Storage location |
| Decisions |
Architecture choices, API design, naming conventions |
.agents/memory/decisions.md |
| Preferences |
Code style, commit format, PR template |
.agents/memory/preferences.md |
| Blockers |
Known issues, dependency constraints, quirks |
.agents/memory/blockers.md |
| Episodic |
Timestamped event log — what happened and why |
.agents/memory/episodes.md |
| Semantic |
Domain concepts, entity relationships, glossary |
.agents/memory/semantic.md |
What to Remember
| Category |
Priority |
Examples |
| Decisions |
high |
Architecture choices, API design, naming conventions |
| Preferences |
high |
Code style, commit format, PR template |
| Blockers |
high |
Known issues, dependency constraints, environment quirks |
| Episodic events |
medium |
What was tried, what failed, what succeeded and why |
| Progress |
medium |
Completed phases, shipped PRs, release history |
| Context |
medium |
Team members, repo relationships, deployment targets |
What NOT to Remember
- Transient debugging output
- Tool execution logs
- Completed todo items (already in git history)
- Session-specific file reads
- Information derivable from reading the codebase
Episodic Memory Pattern
Record significant events with context so future sessions can learn from them:
## 2026-04-10 — Auth middleware rewrite
- **What**: Replaced JWT validation middleware with JWKS-based approach
- **Why**: Compliance requirement from legal (session token storage)
- **Outcome**: 3 tests added, all green, deployed to staging
- **Gotcha**: `validateToken()` now async — callers needed await
Semantic Memory Pattern
Store domain knowledge and entity relationships:
## Domain: Payments
- Order → has many → LineItems
- Payment → belongs to → Order
- Refund → references → Payment.id
- Rule: never delete a Payment; set status = 'refunded' instead
Steps
- Identify decisions, preferences, blockers, or events from the current session
- Check if they already exist in memory (avoid duplicates)
- Write to the appropriate storage location with today's date
- Remove entries that are no longer true
Rules
- Write memory at session end, not continuously
- Keep entries concise — one line per decision, dated entries for episodes
- Date-stamp all entries for staleness detection
- Remove entries that are no longer true
- Memory is supplementary — the codebase is the source of truth
- Never store credentials, tokens, or secrets in memory files
1---2name: memory3description: Persist decisions, preferences, and project state across sessions using structured memory types4---56# Memory78Sync important context to persistent storage so future sessions start informed.910## Memory Types1112| Type | What it stores | Storage location |13| --------------- | ---------------------------------------------------- | ------------------------------- |14| **Decisions** | Architecture choices, API design, naming conventions | `.agents/memory/decisions.md` |15| **Preferences** | Code style, commit format, PR template | `.agents/memory/preferences.md` |16| **Blockers** | Known issues, dependency constraints, quirks | `.agents/memory/blockers.md` |17| **Episodic** | Timestamped event log — what happened and why | `.agents/memory/episodes.md` |18| **Semantic** | Domain concepts, entity relationships, glossary | `.agents/memory/semantic.md` |1920## What to Remember2122| Category | Priority | Examples |23| --------------- | -------- | -------------------------------------------------------- |24| Decisions | high | Architecture choices, API design, naming conventions |25| Preferences | high | Code style, commit format, PR template |26| Blockers | high | Known issues, dependency constraints, environment quirks |27| Episodic events | medium | What was tried, what failed, what succeeded and why |28| Progress | medium | Completed phases, shipped PRs, release history |29| Context | medium | Team members, repo relationships, deployment targets |3031## What NOT to Remember3233- Transient debugging output34- Tool execution logs35- Completed todo items (already in git history)36- Session-specific file reads37- Information derivable from reading the codebase3839## Episodic Memory Pattern4041Record significant events with context so future sessions can learn from them:4243```markdown44## 2026-04-10 — Auth middleware rewrite4546- **What**: Replaced JWT validation middleware with JWKS-based approach47- **Why**: Compliance requirement from legal (session token storage)48- **Outcome**: 3 tests added, all green, deployed to staging49- **Gotcha**: `validateToken()` now async — callers needed await50```5152## Semantic Memory Pattern5354Store domain knowledge and entity relationships:5556```markdown57## Domain: Payments5859- Order → has many → LineItems60- Payment → belongs to → Order61- Refund → references → Payment.id62- Rule: never delete a Payment; set status = 'refunded' instead63```6465## Steps66671. Identify decisions, preferences, blockers, or events from the current session682. Check if they already exist in memory (avoid duplicates)693. Write to the appropriate storage location with today's date704. Remove entries that are no longer true7172## Rules7374- Write memory at session end, not continuously75- Keep entries concise — one line per decision, dated entries for episodes76- Date-stamp all entries for staleness detection77- Remove entries that are no longer true78- Memory is supplementary — the codebase is the source of truth79- Never store credentials, tokens, or secrets in memory files
LucasSantana-Dev