Hydration Documents: Project Memory for AI Systems

A hydration document is a compressed representation of project state designed to bootstrap a fresh AI conversation.

I use them when a chat becomes slow, when I am getting tired, when I need to switch projects, or whenever valuable context is at risk of becoming trapped inside an old conversation.

The goal is simple: preserve momentum.

The Loop

• Work until the project accumulates useful context
• Generate a hydration document
• Start a fresh AI session
• Load the hydration document
• Interrogate the AI about project status, goals, constraints, observations, invariants, and next actions
• Resume work

Everything else exists to make that loop work.

The loop exists because project context accumulates faster than it can be cleanly reconstructed. As a project grows, decisions, constraints, observations, dead ends, and partial solutions accumulate. Eventually the conversation itself becomes part of the project.

A hydration document compresses that accumulated context into a portable artifact. The result is not a perfect copy of the conversation. It is a useful approximation that preserves the parts most likely to matter in the future.

It is less like writing documentation and more like saving the game.

Written For AI, Used By Humans

Most documentation is written primarily for humans. Hydration documents are usually written primarily for AI.

I often ask the AI to include as much detail as it believes is useful and to optimize the document for state transfer rather than human readability. The next reader is usually another AI session.

Humans benefit as a side effect.

As an analogue human, I can scan the document, ask questions, and allow relevant project context to re-surface naturally. The AI cannot. It requires explicit state.

The hydration document provides that state.

Why Not Just Use Chat History?

Because storage and reconstruction are different problems.

The information may exist somewhere in the chat history, but finding the relevant pieces can be slower than rebuilding them. Worse, the important parts are often mixed with false starts, abandoned branches, casual chatter, and decisions that only mattered for a few minutes.

A hydration document intentionally promotes the useful state into a form optimized for reuse.

It is compression, not archival storage.

Observations, Invariants, And Direction

A hydration document should preserve more than current status.

It should preserve observations and invariants.

Observations are things the project has taught me. Invariants are steering constraints that emerge from repeated observations.

For example:

• Power Browser observation: automatic recovery hides workflow bugs.
• Power Browser invariant: fail visibly during development.
• Workshop observation: publishing operational workflows exposes leverage.
• Workshop invariant: show the work, not the factory.
• Hydration Documents observation: important project context repeatedly becomes trapped inside old conversations.
• Hydration Documents invariant: project state should be periodically serialized into portable hydration documents.

Those invariants did not appear on day one. The projects taught them.

Many projects begin with principles and discover reality. I prefer to begin with reality and let principles emerge from repeated observations.

State tells you where the project is. Observations tell you what the project has learned. Invariants tell you how the project should steer.

That distinction matters because progress is only loosely monotonic.

A project moves forward, backward, sideways, and occasionally into a ditch. Features are added, removed, renamed, simplified, and abandoned. Plans change. Architectures mutate.

The path is messy.

Yet over time the project accumulates observations. Some observations produce invariants. Those invariants help future decisions remain aligned with what the project has already learned.

A project's ideal form is rarely visible at the beginning. Early designs are often guesses. As observations accumulate, weak assumptions are discarded and stronger ones survive. The project gradually reveals what it wants to become.

The goal is not perfect linear progress.

The goal is incremental movement toward the platonic ideal of the project as that ideal becomes clearer.

Hydration documents help preserve that direction across interruptions, chat resets, future collaborators, and future AI sessions.

A Small Fragment

A simplified hydration document fragment might look like this:

• Project: Power Browser
• Current state: Overlay controls complete. Preparing search-run generation.
• Observation: automatic recovery hides workflow bugs.
• Observation: manual fallback is acceptable.
• Invariant: human-in-the-loop.
• Invariant: fail visibly during development.
• Next action: build search profile editor.
• Next action: persist scan queue progress.

That is not a full document. It is enough to show the shape: state, observations, invariants, and next actions.

What Goes In

Not all sections carry equal weight.

The load-bearing sections are:

• Current invariants
• Important observations
• Known constraints
• Open questions

The state sections are:

• Project purpose
• Current state
• Recent work
• Important decisions

The execution sections are:

• Next actions
• Relevant files
• Relevant systems
• Commands, routes, schemas, or artifacts required to resume

The document should be detailed enough for the next AI session to reconstruct useful project state without guessing.

Human readability still matters, but it is not the only priority. The point is not to create a polished article for myself to reread. The point is to create a portable state packet that an AI can ingest and help me navigate.

A hydration document can contain operational knowledge, so I separate the public method from private leverage. The technique is useful to discuss. The full contents are project-dependent.

The Larger Point

I think context is infrastructure.

Source code is infrastructure. Databases are infrastructure. Deployment systems are infrastructure. I believe context is infrastructure too.

A project that cannot survive interruption is fragile. A project that cannot explain its current state to a new AI session is fragile. A project that loses its invariants every time the context resets is not being developed. It is being repeatedly rediscovered.

Hydration documents are a small tool for making work more durable.

They help projects survive time. They help AI systems resume faster. They help humans steer without reloading everything into working memory at once.

And most often, they help my future self avoid paying the tax of rediscovering what I already knew.