# BrainDrive Memory Architecture **Status:** Draft — in Library for iteration. Once locked, canonical version migrates to BrainDrive repo (`docs/architecture/memory-architecture.md`) with a Library breadcrumb pointing at it. **Authors:** Dave W (with Claude as thinking partner), 2026-05-21 **Audience:** Anyone building features in BrainDrive, reviewing owner-memory changes, or making product decisions that touch the owner's file system / memory layout. **When to consult this doc:** Before adding any new file type, folder, or content structure to the owner's memory layout. Before writing prompt content that tells the agent how to do something. Before reviewing a PR that touches the starter pack or any owner-facing memory file. --- ## 1. Core Model BrainDrive's memory architecture follows a five-level process: 1. **Orient** — bring the agent up to speed. 2. **Align** — define the owner's goals and what success looks like. 3. **Plan** — design the concrete path to reach those goals. 4. **Execute** — do the work through owner-facing apps and supporting files. 5. **Propagate** — keep affected memory up to date after state changes. The architecture is built from **11 primitives** across the four file-bearing stages. Propagate is a behavior, not a file type. | Stage | Primitives | |---|---| | Orient | System prompt, `base/AGENT.md`, project `AGENT.md`, `me/profile.md` | | Align | `spec.md` | | Plan | `plan.md` | | Execute | Apps, Instructions, Index, Sources, Reports | | Propagate | — | Domain complexity scales freely; primitive count stays flat. ### Technical Layers | Layer | Required across all projects? | Universal in... | Varies by domain | |---|---|---|---| | L0 system prompt | Yes | Everything | Nothing | | L1 BD+1 base | Yes | Everything | Nothing | | L2 project `AGENT.md` | Yes | Shape | Persona, file list, boundary | | L3 `spec.md` | Yes | Purpose: align on success | Structure, questions, success criteria | | L3 `plan.md` | Yes | Purpose: plan a path | Milestones, sequence, first steps | | L4+ apps + supporting files | No | — | Which apps exist, how deep they go | Owner UX implication: every project starts with the same top-level contract — what this is (`AGENT.md`), what success means (`spec.md`), and how to get there (`plan.md`). The work itself happens below that. --- ## 2. Execute-Stage File Types Every Execute-stage file is one of five stable types: | Type | Meaning | Examples | |---|---|---| | **Apps** | Owner-facing work artifacts where the work happens. Carry instructions + owner data. | `budget.md`, `workout-log.md`, `journal.md`, `todo.md`, `investments.md`, resume | | **Instructions** | AI-facing procedures, rules, or composition logic. No owner-maintained artifact. | `compare-months.md`, `handle-conflicts.md`, `budget-rules.md`, `net-worth.md` | | **Index** | Folder map with file listing and optional routing hints. | `index.md` | | **Sources** | Uploaded or imported source data consumed by apps. | bank statements, receipts, parsed documents | | **Reports** | Regenerated synthesis outputs the owner reads. May carry light template-use notes, but detailed workflow belongs in Instructions. | `reports/latest.md`, `reports/net-worth-latest.md` | **Strategic framing:** Apps are the unit of owner-facing BrainDrive functionality. BrainDrive is a platform with apps owners adopt, customize, and eventually share or extend. The word "app" is not just a file label; it carries the product direction. Instructions has three common subtypes: **Procedures**, **Rules**, and **Composition files**. These are naming and usage subtypes, not separate primitives. ### Active vs Reference Use the Onion Test: > Does this file do something, or is it consumed by something that does? - **Does something** → active file → carries self-describing instructions. - **Consumed** → reference material → labeled, but not instruction-bearing. Apps and Instructions are active. Sources and Reports are reference material. Index is reference material that helps the agent navigate. Report templates can include lightweight "how to use this report" notes; they should not carry full procedures. --- ## 3. Progressive Disclosure Core principle: > **Instructions live inside the files they describe — and nowhere else.** When the agent enters a scope, it reads that scope's instructions. Sibling scopes stay invisible until entered. This keeps each turn focused, lets the architecture grow without loading everything, and makes owner customization possible through natural-language instruction edits. An active file uses this shape: ```markdown # Budget ## Instructions What this file is. How to use it. When it is read-only. Links to specialized procedures if needed. --- ## Monthly Context [Owner-facing content] ## Category Limits [Owner-facing content] ``` The same file serves both audiences: - **View mode:** owner sees the content. - **Edit mode:** owner sees the full file, including instructions. Reference material does not carry instructions. The active file consuming it knows how to read it. ### Simple Example When Katie asks, "how am I doing on my budget?", the agent loads: 1. Orientation files: `base/AGENT.md`, `me/profile.md`, and Finance `AGENT.md`. 2. The budget app: `budget.md`. 3. The budgeting instruction index: `budgeting/index.md`. 4. The specific workflow files the index routes to, such as `monthly-comparison.md`, `source-evidence.md`, and `report-contract.md`. 5. Relevant statement sources for the requested period. It does not load unrelated projects, unrelated apps, or deep instruction files that the current scope did not point to. ### Fractal Scope-Relative Depth Depth is relative to the current scope, not absolute. A file can be four levels down from root and still be the broad entry point for its own local scope. The same broad-to-specific shape recurses at every scope — fractally. - **Project scope:** `AGENT.md` → `spec.md` / `plan.md` → apps → child instructions - **App scope:** app header → linked instruction docs - **Instruction scope:** instruction header → child instructions, if needed Test for going deeper: > Does this app have multiple specialized concerns that each need detailed instructions? - Yes → spawn child instruction files. - No → keep it as a leaf. Depth is set by the work, not by uniformity. --- ## 4. Naming and Index Convention ### App Folder Naming | Function | Pattern | Examples | |---|---|---| | App | Bare noun | `budget.md`, `journal.md`, `workout-log.md` | | Procedure | Verb-first | `compare-months.md`, `generate-report.md`, `save-budget.md`, `handle-conflicts.md` | | Rules | `-rules.md` | `budget-rules.md`, `source-rules.md`, `comparison-rules.md` | Notes: - Apps do not need `-app`; the file is the artifact. - Procedures are Instructions that describe an action flow. They do not need `-procedure`; the verb signals action. - Rules are Instructions that capture durable constraints or owner-approved handling. They use a topic qualifier because multiple rules files can coexist. - Composition files are Instructions that combine apps or outputs. They can use noun-form when the noun cleanly names the derived view (`net-worth.md`) or verb-form when action reads cleaner (`compute-net-worth.md`). - No `spec.md` inside app folders. `spec.md` is reserved for project-level Align. ### Index Files Every app folder contains an `index.md`. The pattern is hybrid: - **File listing:** auto-maintained from folder contents. - **Intent hints:** optional curated routes for common requests. Example: ```markdown # Budgeting Index ## Files - `budget.md` — saved budget plan - `create-first-budget.md` — procedure: build the initial budget from sources - `compare-months.md` — procedure: compare current month vs saved budget - `generate-report.md` — procedure: produce a comparison report - `budget-rules.md` — rules: when/how to save the budget - `source-rules.md` — rules: how to handle uploaded sources ## Common Requests - New owner, no budget yet -> `create-first-budget.md` - Monthly check-in -> `compare-months.md` + `generate-report.md` - "What should I cut?" -> `compare-months.md` + `budget-rules.md` ``` Agent behavior: 1. Check intent hints for a matching pattern. 2. If no hint matches, scan the file listing and decide what to load. The listing is the floor; intent hints are the optimization. --- ## 5. Cross-Project Layer The BD+1 layer has the same structural shape as a project layer, one scope up: - `base/AGENT.md` — cross-project orientation. - `me/profile.md` — cross-project orientation to the owner. - `me/todo.md` — cross-project app for active tasks across projects. There is no BD+1 `spec.md` or `plan.md` for now. The BD+1 scope is the platform itself; project-level Align and Plan stay inside projects. ### `base/AGENT.md` Loaded on every project conversation. It is the single source of truth for cross-project context, routing signals, and active state that affects multiple projects. Target size: ~50 lines. It is orientation, not a dump. Belongs here: - Project names with one-line descriptions. - Cross-cutting correlations the agent should always carry. - Routing signals. - Active state that affects multiple projects. Does not belong here: - Project-specific procedures. - Detailed project state. - Owner identity facts. When in doubt, push detail down into the project. ### `me/profile.md` Canonical cross-project context about the owner. Read by every project's agent before conversation. Boundary rule: > Relevant in multiple projects → profile. Relevant in one project → that project's `spec.md`. Examples: | Fact | Goes to | Why | |---|---|---| | "I'm 47" | Profile | Identity, cross-cutting | | "I'm self-employed" | Profile | Affects Finance, Career, taxes, work-life | | "Wife is on maternity leave" | Profile, time-marked | Temporary but cross-cutting | | "I value financial independence over career prestige" | Profile | Deep value, cross-cutting | | "I want to retire at 55" | Finance spec | Domain-specific goal | | "I carry $30K credit card debt at 22% APR" | Finance spec | Domain-specific situation | | "I do Stronglifts 3x/week" | Fitness spec | Domain-specific | Suggested structure: ```markdown ## Identity & Situation Basic identity, family, location, work, health, life stage. ## What Matters To Them Deep values and cross-cutting priorities. ## How to Work with Me Communication and interaction preferences. ``` Stated facts can be written silently. Inferred facts require confirmation before adding. Example: "Your kids have come up a few times — should I add them to your profile?" Profile is the highest-trust file in the system. No tiering for now. If profile grows too large to load efficiently, revisit. --- ## 6. Composition When apps combine, the composition is just another file. No new primitive. Example: `net-worth.md` - Reads `budget.md`. - Reads `investments.md`. - Carries instructions for how to compose them. - Produces `reports/net-worth-latest.md`. In Finance, net worth is typically Instructions + Report, not an app, because the owner does not maintain net-worth state directly. They ask "what's my net worth?", the agent uses `net-worth.md`, and the output lands in a report. The architecture is closed under composition: - budget + investments -> net worth - net worth + fitness -> wellness score - finance + career + relationships -> life dashboard Composition can live at project scope or BD+1 scope, depending on what it combines. --- ## 7. Placement and Review Tests ### Where Does This Content Go? 1. **Scope** - Identity / cross-project context → `me/profile.md` - Cross-project tasks → `me/todo.md` - Project orientation → project `AGENT.md` - Project goals / current state / success criteria → `spec.md` - Project sequence / milestones / next steps → `plan.md` - App-specific work → app file or child instruction tree 2. **Active or Reference** - Orients, holds work, or carries procedure → active file with instructions. - Consumed as data or generated output → reference material. 3. **Execute-stage Type** - Owner uses or maintains it directly → App. - AI-only procedure, rules, or composition → Instructions. - Folder map / routing → Index. - Uploaded or imported data → Sources. - Regenerated synthesis output → Reports. 4. **Leaf or Subtree** - Multiple specialized concerns → child instruction files. - Single coherent concern → leaf. ### When Adding Rules Before adding a rule to a file, ask: - Is this restating something a template already enforces? Trust the template. - Is this a runtime invariant? Enforce it in code. - Is this about how to use a different file? Move it into that file's header. - Is this a workflow procedure? Put it in the app or instruction file that owns that operation. If most answers point elsewhere, the current file is doing too many jobs. ### Bloat Signals - A file restates rules that exist elsewhere. - Repeated "don't do X" phrasing. - `AGENT.md` grows past ~80 lines in a complex domain or ~50 in a simple one. - The same procedure appears in multiple files. - Prompt content tries to enforce runtime invariants. ### PR Review Checklist When reviewing owner-memory changes: - Does every new file fit one of the existing primitives? - Is it at the right scope? - If active, does it self-describe in its header? - If reference material, is it labeled and free of detailed procedures? - Does it duplicate instructions from another file? - Are runtime invariants enforced by tools/templates instead of prompt repetition? - Does the index route common requests without hiding the general file listing? --- ## 8. Deliberate Non-Choices These were considered and rejected or deferred. | Option | Decision | Why | |---|---|---| | **Skills as a separate primitive** | Rejected for now | Owner-facing needs reduce to composition files, AGENT-described conversation modes, or scheduled triggers that read existing apps. Triggering is runtime, not memory architecture. | | **BD+1 `spec.md` / `plan.md`** | Deferred | Profile handles owner identity/values; project specs handle domain goals. Revisit when Whyfinder introduces a life-level "why" artifact. | | **Importance tiers inside profile** | Rejected for now | Adds maintenance burden before there is a load-efficiency problem. | | **Separate `.instructions.md` files for every app** | Rejected | Unified files make natural-language owner customization possible; the display layer separates owner view from edit view. | | **"Executable" as file-type noun** | Retired | Collided with the Execute stage and obscured the owner-facing distinction between Apps and supporting files. | The current `memory/starter-pack/skills/` folder is dev-process residue that ships into owner installs but is not invoked by owner-facing flows. Clean it up separately. If a real owner-facing use case appears that does not fit existing primitives, add a primitive then, not preemptively. --- ## 9. Vocabulary | Term | Meaning | |---|---| | **Primitive** | Atomic file type in the architecture. The count stays flat while domain complexity grows. | | **Active file** | A file that does something: orients, holds app state, or carries procedure. Carries instructions. | | **Reference material** | A file consumed by active files but not instruction-bearing itself. | | **App** | Owner-facing work artifact at Execute stage. The unit of BrainDrive functionality. | | **Instructions** | AI-facing procedure, rules, or composition logic. | | **Index** | Folder map with file listing and optional intent hints. | | **Sources** | Uploaded or imported source data consumed by apps. | | **Reports** | Regenerated synthesis output the owner reads. | | **Onion Test** | Does this file do something, or is it consumed by something that does? | | **BD+1 scope** | Cross-project layer: `base/AGENT.md`, `me/profile.md`, and `me/todo.md`. | | **Fractal** | The broad-to-specific gradient resets at every scope. | | **Propagate** | Post-execution behavior that updates affected memory and returns the agent to higher-level context. | --- ## 10. Worked Example — Adding Investments to Finance Katie has a working Finance budget app. She now wants to track investments and see net worth. New files: ```text documents/finance/ ├── investments.md # app ├── manage-accounts.md # instructions, if needed ├── investment-statements/ # sources collection │ ├── README.md # collection label │ └── 2026-Q1-vanguard.md # source ├── net-worth.md # instructions: compose budget + investments └── reports/ └── net-worth-latest.md # report ``` Where pieces live: - `investments.md` is an App. It stores accounts/current values and says how to update from statements. - `investment-statements/` is Sources. The collection root labels the folder; statements are data. - `net-worth.md` is Instructions. It composes `budget.md` + `investments.md`. - `reports/net-worth-latest.md` is a Report. It is regenerated, not maintained edit-by-edit. What did not need to change: - No new layer. - No new primitive. - No new skill. - No universal-layer change. - `budget.md` does not need to know investments exist. On "what's my net worth?", the agent loads: 1. System prompt. 2. `base/AGENT.md`. 3. `me/profile.md`. 4. Finance `AGENT.md`. 5. `net-worth.md`. 6. Files named by `net-worth.md`: `budget.md`, `investments.md`, relevant sources. It does not load unrelated projects or unrelated deep instruction files. After a state-changing turn such as "I just put $5K into Vanguard," Propagate should: - Update `investments.md`. - Add source material if applicable. - Mark dependent reports stale or regenerate when asked. - Check Finance `spec.md` / `plan.md` for affected goals or milestones. - Check `me/profile.md` only if a cross-project life fact changed. - Check `me/todo.md` for new actions. --- ## 11. How to Use This Document When adding a feature to BrainDrive: 1. Identify the scope. 2. Classify every file using Active/Reference and the five Execute-stage types. 3. Place files at the right layer. 4. Put instructions in active-file headers. 5. Keep sources instruction-free; keep report instructions limited to lightweight template-use notes. 6. Add or update the index. 7. Run the bloat and rule-placement tests. 8. Do not invent a new primitive unless the existing model genuinely cannot express the use case. Status and open items: - Vocabulary locked: Apps, Instructions, Index, Sources, Reports. - Index pattern locked: auto-maintained listing + optional intent hints. - Cross-project context locked: always-loaded `base/AGENT.md`, kept tight. - BD+1 spec/plan deferred until Whyfinder or a similar life-level artifact requires it. - Open implementation alignment: the current BrainDrive repo still treats BrainDrive+1 as a seeded special project in some places; reconcile that with this BD+1-scope model before locking the canonical repo copy. - Strategic commitment: BrainDrive as a platform with owner-facing apps. - Next application: Finance cleanup / source-of-truth doc alignment, then future apps such as Fitness and resume builder. - Follow-up: clean up dev-side `memory/starter-pack/skills/`. - Open: add a worked example for creating a new project type from scratch when the next vertical scaffolds.