Mental Models and Knowledge Pages: Memory That Writes Documentation

Reflect can answer a recurring question, but repeated reflection has a predictable cost: the agent keeps rediscovering a conclusion that the bank has already supported. Hindsight's mental models and knowledge pages address that problem by storing a maintained projection of memory. This chapter explains when that projection is worth creating, how full and delta refreshes behave, and why tags, staleness, inspection, and rebuildability determine whether the projection remains trustworthy.

A recurring question can become a maintained answer

A mental model is a named, bank-scoped answer to a question that an agent asks often. “What are this user's durable preferences?” and “What conventions does this project follow?” are different from one-off questions about a single event. They describe topics that will be useful again, so recomputing them from raw facts on every reflect call wastes work and can produce small variations each time.

The design criterion is recurrence plus stability. A mental model is a good fit when the question will be asked repeatedly, its answer should evolve as new evidence arrives, and a standing summary is more useful than a fresh list of facts. It is a poor fit for a one-time incident lookup, a rapidly changing number that must be read directly from a source, or a question whose scope is not yet settled. Creating a model for every query would simply turn transient questions into a collection of stale documents.

When a mental model is refreshed, Hindsight runs reflection against the bank and stores the result. The model has a source query, content, trigger settings, tags, and refresh metadata. Its content is a projection of the bank's current evidence, not a second raw-memory store. If the model is deleted, the source facts and observations remain; the model can be rebuilt later. That rebuildability is what makes it safe to treat the model as a convenience layer rather than the only copy of understanding.

There are two refresh postures. Full refresh regenerates the answer from the current evidence. It is the simpler choice when the topic or document shape may change substantially, or when periodic re-derivation is more important than preserving the exact wording of untouched sections. Delta refresh starts from the existing structured document and applies typed edits based on new evidence. Sections not targeted by an operation can remain byte-for-byte unchanged, which is useful for long-lived playbooks, checklists, or project conventions that should not be casually paraphrased.

Delta is not a guarantee that a document can never drift. Many small edits can accumulate a mistaken interpretation, especially if the source question changes or the bank receives ambiguous evidence. Hindsight falls back to full refresh when a delta baseline is missing or the source query has changed. The project also recommends periodic clear-and-rebuild behavior for long-lived models. Incremental refresh is a way to control churn, not a substitute for rechecking the whole topic.

Consider a project-conventions model containing an approved review checklist and a short explanation of why each rule exists.