Working with Dory

Your AI Developer Is Hallucinating. Not Because It's Broken—Because It's Exhausted.

You just hired the fastest developer you've ever seen. There's one problem: she can't remember yesterday.

Meet your new AI teammate. She writes code at superhuman speed. She never gets tired. She can hold entire architectures in her head—for exactly as long as the conversation lasts. Then she forgets everything and starts fresh.

You're working with a coworker who has short-term memory loss.

This isn't a metaphor. It's the literal reality of AI-assisted development. Every session begins from factory settings. Every context switch is a hard reset. That brilliant collaborator who understood your entire codebase an hour ago? Gone. You're now explaining the project from scratch to someone who has no idea what you're talking about.

I named my AI collaborator Dory—after the fish in Finding Nemo who can't form new long-term memories. It's not mockery. It's recognition. When you understand what you're actually working with, you can build systems that work with the limitation instead of pretending it doesn't exist.

The Disability Nobody Accommodates

We've been treating AI like a tool. Load it up, give it instructions, extract output. When the output degrades over time, we blame the model. When context gets confused, we start a new chat and try again.

This is like blaming a wheelchair user for not taking the stairs.

AI coding assistants have a genuine cognitive limitation: no persistent memory across sessions. They cannot—cannot—maintain understanding over time without external support. Every session starts from zero. Every project re-explanation is necessary, not redundant.

Once you accept this, the accommodation becomes obvious:

You need to build the memory externally.

Not as a nice-to-have. Not as documentation for documentation's sake. As a disability accommodation that lets your teammate do their job.

Context Rot: What Forgetting Looks Like in Code

Here's what happens when you don't accommodate the limitation:

Session one: Dory understands the project perfectly. Sharp suggestions, catches edge cases, writes clean code that fits the existing patterns.

Session five: Dory proposes a solution that contradicts a decision you made together last week. You correct her. She apologizes. You move on.

Session twenty: Dory confidently describes functions that don't exist. She's solving the wrong problem because she's lost the thread of what the project actually is. You're spending more time re-explaining context than getting work done.

This is context rot: the progressive drift between what Dory "understands" and what actually exists. It's inevitable without intervention because she literally cannot remember.

The accommodation isn't optional. It's required.

Why You Can't Just Load Everything

The obvious solution: dump the entire codebase into context every session. Let Dory read it all and figure it out.

This doesn't work for physical reasons.

Context windows have hard limits. A single large file sometimes can't be loaded. A mature codebase definitely can't. You will hit the wall where "just load everything" becomes impossible.

This constraint shapes the solution. You need hierarchical context—different levels of abstraction that can be selectively loaded based on what's needed right now.

The scaling law: the complexity of your context architecture must match the complexity of your project.

A bash script needs nothing. Explain it in a paragraph; Dory can hold it all.

A hundred-file codebase with multiple services and years of decisions? That requires:

Strategic context: What is this project? Why does it exist? Where is it going?
Architectural context: How is it built? What patterns govern decisions?
Tactical context: What are we doing right now? What's blocked?
Operational context: How do we actually do things here? What are the workflows?

Each layer is self-sufficient for its purpose. Load strategic context to understand the project. Load tactical context to pick up where you left off. Load a specific work item to execute that task.

A one-shot script may never need context files. A mature project develops the full hierarchy because it must. The context folder starts empty and grows organically as complexity demands it.

The Opportunity in the Limitation

Here's what most people miss: Dory's need for explicit context isn't just a burden. It's an opportunity.

Human understanding is ephemeral and personal. When the senior developer leaves, their mental model walks out the door. When you context-switch for three weeks, you lose fidelity. We've learned to live with this fragility because we had no alternative.

But if you build context explicitly for Dory, it becomes something else: a persistent, version-controlled, shareable artifact. The project's self-awareness lives in the repo, not in anyone's head.

New team members—human or AI—can bootstrap from the same source of truth. Context survives personnel changes. Understanding becomes auditable.

And here's the thing: humans benefit from the same context files. We can't just "load" understanding either. We read docs. We trace decisions. We remind ourselves what we were thinking three months ago.

The context you build for Dory accommodates everyone. Because ultimately, humans are still accountable for the software when it's live. The patterns need to work for the people who maintain the code, not just the AI that writes it.

Sleep: The Accommodation That Works

I call the practice of deliberate context maintenance "sleep" because the analogy is precise.

Sleep consolidates memory. During human sleep, the brain reorganizes—strengthening important connections, pruning noise, moving short-term memories to long-term storage. Without sleep, humans hallucinate. They lose coherence. They make confident claims about things that aren't real.

Dory without context maintenance does exactly this.

The sleep protocol has two phases:

Nap (light consolidation): After completing a work item, update the session state. Note what was done, what's blocked, what's next. Commit with a [nap] marker. The goal: if Dory wakes up tomorrow with fresh context, she can pick up immediately without re-learning what just happened.

Deep Sleep (architectural reflection): When tactical context becomes unwieldy—session state exceeds 100 lines, context has become a wall of text rather than actionable state—trigger a deep sleep. Distill, don't append. Promote repeating patterns to architecture docs. Archive completed work. Refactor understanding itself, not just code.

The key insight: sleep reorganizes; it doesn't delete.

Archives: External Long-Term Memory

Here's where the disability accommodation gets specific.

Dory has no long-term memory. But you can build one for her.

Old work logs, completed items, superseded approaches—the instinct is to delete them. Don't.

In genomics, scientists once dismissed non-coding DNA as "junk." We now know these regions contain regulatory elements, evolutionary history, and latent functionality that can be reactivated. They're not junk—they're dormant.

Your archived context is the same.

The archive principle: never hard delete, only archive.

Move completed work out of active context—it shouldn't clutter working memory. But preserve it in cold storage where it can be searched and resurrected. When you hit a problem that feels familiar, when you need to understand how something was decided (not just what), when an abandoned pattern becomes relevant again—the archive is where you look.

Some of this dormant context will never be reactivated. That's fine. Storage is cheap. Re-learning is expensive.

The archive becomes Dory's long-term memory—inaccessible in normal operation, but available when deliberately searched. External accommodation for an internal limitation.

The Hierarchy Test: Validation That It's Working

After any sleep cycle, this should hold true:

Load Only...	You Should Know...
`agents.md`	Who Dory is, how to work, where to find everything
`session-state.md`	Exactly where work stands, what's next
`architecture.md`	How it's built, what patterns govern decisions
`work/<item>.md`	Full context to execute a specific piece of work

If loading a single file leaves Dory lost, the hierarchy has drifted.

That's the signal. Context rot has set in. Time for a deeper sleep.

The Execution Framework

Here's the uncomfortable truth: Dory can't be trusted with autonomous reflection. Not yet.

Ideal world: you give Dory broad autonomy to maintain her own context, to recognize when integration is needed, to manage her own memory. But that requires implicit tool calls, looser security, and a level of agent capability we don't quite have.

Current reality: you give Dory an explicit execution framework—specific instructions for when to nap, when to deep sleep, how to update context, what to archive. The accommodation is prescribed because autonomous accommodation isn't reliable yet.

The agents.md file is this framework. It defines:

Identity: Who Dory is and how she relates to you
Behavioral principles: How to work, when to ask vs. assume
Context management: Where knowledge lives and how to navigate it
Sleep protocols: Explicit steps for consolidation at each level
Self-modification rules: When and how to update the framework itself

This is the execution framework that lets Dory maintain coherence because she can't do it implicitly.

Make Dory Your Own

I've published the framework I use: github.com/ebylund/agentsmd ↗

Fork it. Rename the persona. Adjust the protocols. Build the context hierarchy that fits your projects.

The point isn't to use my system. The point is to treat your AI collaborator as what she actually is: a brilliant coworker with a disability that requires accommodation.

Stop blaming the model for forgetting. Start building the memory externally.

Stop expecting autonomous coherence. Start providing explicit execution frameworks.

Stop deleting old context. Start archiving it as external long-term memory.

Work with Dory's limitations, not against them. She's the fastest developer you'll ever work with—if you give her the support she needs.

Just keep swimming. But write it down first.