# Agent Memory: Mental Models That Compound

**June 9, 2026**

The biggest problem with agents is they forget. Every session starts from zero. Mental models solve this.

## What a Mental Model Is

A YAML file that the agent owns. It reads it at startup and updates it after work:

```yaml
expertise:
  - topic: "API patterns"
    notes: "We use tRPC for type-safe API calls"
    evidence: "src/server/routers/*.ts"
    confidence: HIGH
    last_updated: "2026-05-24"

observations:
  - type: failure_pattern
    observation: "WebSocket reconnection needs backoff"
    status: unaddressed
```

## The Rules

1. **Agents own their mental models.** You do not touch them. The agent reads, writes, and updates its own expertise file.

2. **Self-improve commands validate against the codebase.** The agent greps for evidence, checks if its knowledge is still accurate, and updates stale entries.

3. **Read-only expertise for critical knowledge.** Billing workflows, deployment procedures, and security policies should never change.

4. **Knowledge compounds across sessions.** Session 1: agent learns project structure. Session 2: learns common patterns. Session 3: learns failure modes. By session N, it operates at a senior engineer level for that codebase.

## The Self-Improve Loop

```bash
just self-improve-backend
```

This command triggers the agent to scan the codebase, validate its expertise against actual file contents, and update anything that has drifted.

## Why This Matters

Without mental models, every agent session is Day 1. The agent rediscovers the same things repeatedly: "Oh, this project uses tRPC. Oh, tests go in the tests directory. Oh, we deploy via Docker." Mental models turn every session into Day 100.

---

*From Module 4 of the [Agentic Engineering Course](/). The full module covers multi-agent systems with domain locking, delegation, and P2P communication.*