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:

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

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.