Skip to content

# 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.