Architecture
Human brains don't store everything in one region. Your prefrontal cortex handles identity and decision-making. Your temporal lobe stores facts and relationships. You have procedural memory for skills you don't think about, and working memory for what you are actively doing. Different types of knowledge, different storage.
dreamcontext takes inspiration from this structure:
| Brain Region | dreamcontext | What it holds |
|---|---|---|
| Prefrontal cortex | 0.soul.md |
Identity, principles, rules, constraints |
| Episodic memory | people/<name>.md |
Each person's preferences, communication style, workflow |
| Semantic memory | 2.memory.md |
Decisions, known issues, technical context |
| Sensory cortex |
3.style_guide_and_branding.md, 4.tech_stack.md
|
Style, tech stack, data structures |
| Declarative memory | features/ |
Feature PRDs with user stories, acceptance criteria, constraints |
| Long-term knowledge | knowledge/ |
Deep docs, tagged with standard categories, pinnable for auto-loading |
| Working memory | state/ |
Active tasks, in-progress work |
| Skill memory |
SKILL.md + references/
|
Teaches the agent the system itself |
The _dream_context/ directory is the implementation. Everything lives in your repo, structured and version-controlled.
Soul (0.soul.md) defines who the agent is when working on your project. Project identity, core principles, behavioral rules, constraints, and warnings. For example: "Never use require() in this project" or "Always run tests before considering a change complete." This is the most stable file. It changes rarely and sets the foundation for everything else.
People (people/<name>.md, with the roster in people/people.json) capture preferences, communication style, and workflow conventions — one constitution per person, not one file for whoever happens to be typing. For example: "No em dashes in writing, restructure the sentence instead" or "Make decisions directly, don't ask for permission on clear choices." Tech stack details go in their own extended core file. A constitution is about how someone works, not what they work with.
Before v0.23 this was a single 1.user.md. Upgrading migrates it: identity and preferences move into your constitution, and every other section is parked verbatim in inbox/1.user-residue.md for an agent to file — nothing is discarded, and nothing about who owns which section is guessed by code (see Release History).
Memory (2.memory.md) is the working log of technical decisions, known issues, and session-level learnings. For example: "Chose Postgres over MongoDB because the data is highly relational" or "The auth middleware must run before rate limiting, not after." It follows LIFO ordering (newest at top) and is the file that changes most frequently. The sleep cycle keeps it from growing out of control.
Extended core files (slots 3-6) hold specialized context: style guide and branding, tech stack, data structures, and the system-flow reference. These are loaded as summaries in the snapshot with paths included, so the agent knows they exist without burning tokens loading the full content every session.
Knowledge (knowledge/) is where deep reference docs live. Architectural context, domain knowledge, research, design rationales. For example: a doc on "payment-flow-architecture" tagged with [architecture, payments, api] explaining the full Stripe integration and edge cases. Each file has frontmatter with tags and descriptions. The snapshot surfaces a complete index so the agent knows what docs exist. Files marked pinned: true get loaded in full every session for frequently-needed reference.
State (state/) holds active work: task files with progress logs and a sleep state file tracking consolidation debt. A task like "migrate-to-postgres" would have status, priority, and a LIFO log of every step taken. Tasks follow a lifecycle (pending, in-progress, blocked, completed).