# Persistent Memory Management

> What to save, when to update, and how to keep agent memory useful over months of development.

## When to Use

- After completing a significant piece of work (new module, refactor, bug fix)
- When you notice agents repeating mistakes or asking for the same context
- When architecture or naming changes (rebrands, migrations)
- When you establish a new pattern you want agents to follow

## The Pattern

AI coding agents have **ephemeral context** (current conversation) and **persistent memory** (saved across conversations). The skill is knowing what to persist and in what format.

### Memory Types

| Type                      | Example                                                                          | Lifespan                           |
| ------------------------- | -------------------------------------------------------------------------------- | ---------------------------------- |
| **Architectural facts**   | "Service consolidation: only 2 services remain (platform:4003, extraction:4005)" | Long — until architecture changes  |
| **Implementation status** | "Telemetry Phase 2 complete, Phase 3 pending"                                    | Medium — update as work progresses |
| **User preferences**      | "User prefers running commands themselves, paste output back"                    | Long — rarely changes              |
| **Gotchas/pitfalls**      | "Multi-line commands don't execute in IDE terminal"                              | Long — environment-specific        |
| **Naming decisions**      | "Rebranded myWisprAI → LysnrAI, all env vars WISPR*\* → LYSNR*\*"                | Long — reference during migrations |

## Step-by-Step

### 1. What to memorize

**Always memorize:**

- Architecture decisions (which services exist, which were consolidated)
- Naming/branding changes (old name → new name mappings)
- Environment quirks (corporate proxy blocks, terminal limitations)
- Build/deploy commands that are non-obvious
- Test counts as baselines ("847 tests passing")
- Completed work summaries ("4 ChronoMind modules: timers, routines, households, shared-timers")

**Never memorize:**

- Temporary debugging state
- File contents (they change; read them fresh)
- Things already in AGENTS.md (avoid duplication)
- Secrets or credentials (obviously)

### 2. Memory format

Keep memories **structured and scannable**:

```
## Project X — Implementation Status

**Repo:** learning_ai_example
**Modules completed:** auth, billing, notifications
**Tests:** 342 passing
**Last commit:** abc1234

**What's done:**
- Auth module with JWT + refresh tokens (12 endpoints)
- Billing via Stripe (webhooks, subscriptions, usage)

**What's pending:**
- Email delivery (needs SendGrid setup)
- Password reset flow
```

### 3. When to update vs. create new

- **Update** existing memory when the same topic evolves (e.g., test count changes, new module added)
- **Create new** memory for unrelated topics
- **Delete** memories that are obsolete (e.g., after a migration is fully complete)

### 4. Cross-conversation memory bridges

When starting a new conversation about ongoing work:

1. The agent's memory system retrieves relevant memories automatically
2. If memories are stale, correct them early: "Update: test count is now 847, not 621"
3. For complex multi-session work, maintain a `progress.md` file in the repo (see [06 — Multi-Session Continuity](./06-multi-session-continuity.md))

## Anti-Patterns

- **Too many memories** — 50+ memories become noise. Consolidate related ones
- **Memories that duplicate AGENTS.md** — Agent reads both, gets confused by slight differences
- **Stale implementation status** — "Phase 2 pending" when Phase 2 was completed 3 sessions ago
- **Vague memories** — "Fixed some bugs in auth" is useless. Include file names and test counts
- **Memorizing file contents** — Files change. Memorize patterns and decisions, not code

## Real-World Example

After rebranding a project (myWisprAI → LysnrAI), this memory was created:

```
Project rebranded from myWisprAI → LysnrAI. Key mappings:
- Display name: myWisprAI → LysnrAI
- Package/lowercase: mywisprai → lysnrai
- Config dir: ~/.myWisprAI/ → ~/.lysnrai/
- License prefix: WISPR-XXXX → LYSNR-XXXX
- Env vars: WISPR_* → LYSNR_*
- Key Vault secrets: wispr-* → lysnr-*
- 168 files changed, 401 tests passing
```

This memory was referenced in 10+ subsequent conversations where the old names appeared.

## Editor-Specific Notes

| Editor          | Memory System                                                                     |
| --------------- | --------------------------------------------------------------------------------- |
| **Windsurf**    | Built-in memory DB (create_memory tool). Auto-retrieved. Can create/update/delete |
| **Claude Code** | CLAUDE.md at repo root + conversation context                                     |
| **Cursor**      | .cursorrules + conversation context. No persistent cross-session memory           |
| **Copilot**     | .github/copilot-instructions.md only. No memory system                            |
| **Aider**       | .aider.conf.yml + repo files. Use committed docs for persistence                  |

For editors without memory systems, use **committed documentation** (AGENTS.md, docs/progress.md) as the persistence layer.

## Related Skills

- [01 — AGENTS.md Pattern](./01-agents-md-pattern.md)
- [06 — Multi-Session Continuity](./06-multi-session-continuity.md)
- [19 — Session Summaries & Playbooks](./19-session-playbooks.md)
