TUTORIAL 12

Memory Management

You've completed 3 sprints. Memory files need maintenance. Learn to keep the AI's knowledge healthy and efficient.

⏱ ~15 min · Hands-on

/agile-memory-recall /agile-memory-remember /agile-memory-learn /agile-setup-health

Scenario

Three sprints have passed. The team has shipped a profile page, notifications, and an admin dashboard. Along the way, decisions were made, conventions were established, and lessons were learned. But memory files have drifted — some are stale, some are missing new conventions. Time to do memory maintenance.

Step 1: Recall Current Memory State

Start by seeing what the AI currently "knows." The memory index is the table of contents for all project knowledge.

/agile-memory-recall

.memory/MEMORY_INDEX.md

Memory Index — Task Manager App
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Semantic Memory (what the project IS):
  📄 .memory/semantic/project.md        Project brief, name, tech stack
  📄 .memory/semantic/architecture.md   System design, module map
  📄 .memory/semantic/conventions.md    Coding standards, naming, patterns
  📄 .memory/semantic/codebase.md       File structure, key entry points
  📄 .memory/semantic/testing.md        Test strategy, coverage targets
  📄 .memory/semantic/deployment.md     Environments, CI/CD pipeline config

Episodic Memory (what HAPPENED):
  📄 .memory/episodic/decisions.md      ADRs and key technical decisions
  📄 .memory/episodic/learnings.md      Sprint retro learnings, insights
  📄 .memory/episodic/incidents.md      Production incidents and post-mortems

Domain Knowledge:
  📄 .memory/semantic/domain/api.md            API endpoint reference
  📄 .memory/semantic/domain/database.md       Schema, migrations, indexes
  📄 .memory/semantic/domain/design.md         UI component library reference
  📄 .memory/semantic/domain/integrations.md   Third-party service configs

Step 2: Understand Memory Types

Not all memory is created equal. Understanding the two types helps you maintain them correctly.

Semantic Memory — What the Project IS

Semantic Memory:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Nature:     Stable facts about the project
  Changes:    Rarely — only on major refactors
  Examples:   Architecture, conventions, tech stack
  Update:     REPLACE outdated content with current truth
  Risk:       Goes stale silently if not verified

  Files:
    .memory/semantic/project.md       — "TaskFlow: REST API for task management"
    .memory/semantic/architecture.md  — "We use React + Express + PostgreSQL"
    .memory/semantic/conventions.md   — "All components use PascalCase"
    .memory/semantic/codebase.md      — "Auth module lives in src/api/auth/"
    .memory/semantic/testing.md       — "80% coverage minimum, Jest + RTL"

Episodic Memory — What HAPPENED

Episodic Memory:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Nature:     Events, decisions, learnings over time
  Changes:    Sprint-scoped — entries archived to sprint files at sprint end
  Examples:   ADRs, retro notes, incident reports
  Update:     ADD new entries within the sprint; at sprint end, /agile-sprint-retro archives all to .memory/episodic/sprints/sprint_NNN.md
  Risk:       Max ~10 entries per file per sprint; bounded to current sprint

  Files:
    .memory/episodic/decisions.md   — "ADR-007: Use SSE for notifications"
    .memory/episodic/learnings.md   — "Integration tests caught 3 bugs unit tests missed"
    .memory/episodic/incidents.md   — "2026-03-15: Payment timeout due to DB lock"

Key Difference

Semantic memory is updated in place — you replace old facts with current ones. Episodic memory is sprint-scoped — entries accumulate during the sprint (max ~10 per file), then /agile-sprint-retro archives them to .memory/episodic/sprints/sprint_NNN.md and resets the active files to template state.

Step 3: Check Memory Health

Every memory file has a last_verified date in its frontmatter. If it's older than 30 days or a major refactor happened, the file is considered stale.

/agile-setup-health

Memory Health Check
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  .memory/semantic/architecture.md  ⚠️  last verified: 45 days ago
                               3 new modules added since then

  .memory/semantic/conventions.md   ✅  last verified: 12 days ago
                               up to date

  .memory/semantic/codebase.md      ✅  last verified: 8 days ago
                               up to date

  .memory/semantic/testing.md       ❌  last verified: 90 days ago
                               coverage target changed, new test patterns

  .memory/semantic/deployment.md    ✅  last verified: 15 days ago
                               up to date

  .memory/episodic/decisions.md     ✅  sprint-scoped, 7 entries (current sprint)
  .memory/episodic/learnings.md     ✅  sprint-scoped, 12 entries (current sprint)
  .memory/episodic/incidents.md     ✅  sprint-scoped, 2 entries (current sprint)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Stale files: 2 (.memory/semantic/architecture.md, .memory/semantic/testing.md)
  Action: Verify and update stale files

Stale Memory Is Dangerous

If .memory/semantic/architecture.md says "monolith" but you refactored to microservices, the AI will generate code for the wrong architecture. Stale memory causes wrong decisions. Always fix stale files before starting new work.

Step 4: Fix Stale Memory

Read the stale file, verify against current code, update the content, and refresh the last_verified date.

Updating .memory/semantic/architecture.md

Verification — .memory/semantic/architecture.md
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Checking against codebase...

  ❌ Missing: ProfileService module (added Sprint 4)
  ❌ Missing: NotificationService module (added Sprint 5)
  ❌ Missing: AdminService module (added Sprint 6)
  ✅ Correct: UserService, AuthService, OrderService
  ✅ Correct: Tech stack (React, Express, PostgreSQL)
  ✅ Correct: API structure and routing

  Action: Added 3 missing modules to .memory/semantic/architecture.md
  Updated: last_verified → 2026-04-04

Updating .memory/semantic/testing.md

Verification — .memory/semantic/testing.md
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Checking against current test setup...

  ❌ Wrong: Coverage target says 75% (now 80%)
  ❌ Missing: Integration test patterns for SSE endpoints
  ❌ Missing: Soft-delete test conventions
  ✅ Correct: Jest + React Testing Library
  ✅ Correct: Unit test file naming (*. test.ts)

  Action: Updated coverage target, added new patterns
  Updated: last_verified → 2026-04-04

Step 5: Save a New Convention

During Sprint 3, the team discovered an inconsistency: some API responses used snake_case keys, others used camelCase. They agreed on a convention. Save it.

/agile-memory-remember

New Convention Saved

Saving to: .memory/semantic/conventions.md
Type: Semantic (project convention)

New entry:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ## API Response Format
  All API responses use camelCase keys.
  Example: { "userId": 1, "firstName": "Jane" }
  NOT:     { "user_id": 1, "first_name": "Jane" }

  Enforced by: ESLint rule + Zod response schemas
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Saved to .memory/semantic/conventions.md

Step 6: Capture a Sprint Learning

Sprint 3's retrospective surfaced an important insight. Capture it in episodic memory.

/agile-memory-learn

Learning Captured

Saving to: .memory/episodic/learnings.md
Type: Episodic (sprint-scoped, archived at sprint end)

New entry:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ## Sprint 3 Learning — 2026-04-04
  Integration tests caught 3 bugs that unit tests missed:
    1. Auth middleware not applied to new profile routes
    2. S3 upload failing silently on invalid MIME type
    3. Soft-delete not cascading to user sessions

  Action: Increase integration test coverage for all
  new API endpoints. Add to Definition of Done checklist.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Appended to .memory/episodic/learnings.md

Step 7: Lazy Loading in Action

The AI doesn't load all memory at once. It selectively loads based on what you're doing.

Task-Based Memory Loading

When you say: "Fix the login bug"
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  AI loads:
    ✅ .memory/semantic/codebase.md      → find auth module location
    ✅ .memory/semantic/testing.md       → know test conventions
    ✅ .memory/episodic/incidents.md     → check for related past incidents
  AI skips:
    ⏭️ .memory/semantic/deployment.md   → not relevant to bug fix
    ⏭️ .memory/semantic/domain/design.md → not a frontend task
    ⏭️ .memory/semantic/domain/integrations.md → not an integration issue

When you say: "Plan the notification architecture"
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  AI loads:
    ✅ .memory/semantic/architecture.md  → current system design
    ✅ .memory/episodic/decisions.md     → past ADRs (SSE decision)
    ✅ .memory/semantic/codebase.md      → module structure
  AI skips:
    ⏭️ .memory/episodic/incidents.md    → not an incident
    ⏭️ .memory/semantic/testing.md      → planning, not implementing
    ⏭️ .memory/semantic/domain/database.md → not a data task

Why Lazy Loading Matters

Loading all memory wastes context window tokens and can confuse the AI with irrelevant information. Selective loading keeps the AI focused and efficient. The .memory/MEMORY_INDEX.md is the only file loaded at every conversation start — it tells the AI where to find everything else.

Step 8: What NOT to Save

Not everything belongs in memory. Over-saving creates noise and staleness.

Save vs. Skip

✅ SAVE to memory:
  - Architecture decisions (ADRs)
  - Team conventions and coding standards
  - Module locations and entry points
  - Recurring bug patterns
  - Deployment configurations

❌ DO NOT save:
  - Exact code snippets (they go stale instantly)
  - Information derivable from git log
  - Temporary debug state or experiment notes
  - Dependency version numbers (check package.json)
  - PR review comments (they live in GitHub)

The Staleness Test

Before saving anything, ask: "Will this be true in 30 days?" If yes, save it. If it's likely to change with the next code change, don't — it will become stale and mislead the AI.

Progressive Loading Levels

Memory loads in levels, from lightest to deepest. Most tasks never need Level 3.

📋

Level 0 .memory/MEMORY_INDEX.md only

🗂️

Level 1 route by task type

📄

Level 2 specific sections

📚

Level 3 historical, only when asked

Loading Levels Explained

Level 0 — Always loaded (conversation start)
  → .memory/MEMORY_INDEX.md
  → Just the table of contents, no file content

Level 1 — Loaded by task type (automatic)
  → Bug fix? Load .memory/semantic/codebase.md + .memory/semantic/testing.md
  → Architecture? Load .memory/semantic/architecture.md + .memory/episodic/decisions.md
  → Frontend? Load .memory/semantic/architecture.md + .memory/semantic/domain/design.md

Level 2 — Loaded on demand (specific need)
  → Need database schema? Load .memory/semantic/domain/database.md
  → Need API docs? Load .memory/semantic/domain/api.md

Level 3 — Historical (only when explicitly asked)
  → "What happened in Sprint 1?" → Load full .memory/episodic/learnings.md
  → "Any past incidents with payments?" → Load .memory/episodic/incidents.md

What You Practiced

📋 /agile-memory-recall — viewing the current memory index and what the AI knows
🧠 Understanding semantic memory (stable facts) vs. episodic memory (sprint-scoped events, archived at sprint boundaries)
🏥 /agile-setup-health — checking for stale memory files and fixing them
📝 /agile-memory-remember — saving new conventions to semantic memory
📖 /agile-memory-learn — capturing sprint learnings to episodic memory
⚡ Lazy loading — the AI loads only what's relevant to the current task
🚫 Knowing what NOT to save — avoiding noise and staleness
📊 Progressive loading levels — from index-only to full historical context

Knowledge Check

What is the ONLY memory file loaded at conversation start?

← Autonomous Sprint Back to Course Home →