# BrainDrive Memory Architecture Source Of Truth - Draft 1

Date: 2026-05-24  
Status: Draft 1  

## Position

BrainDrive memory architecture exists to keep owner memory understandable, editable, and scalable as BrainDrive moves from orientation and planning into doing useful work.

The core position:

> BrainDrive should keep high-level orientation short, place rules at the lowest useful level, use owner-facing Apps for work, and rely on progressive disclosure so both the AI and the owner can understand the memory system without loading every instruction at once.

## 1. Core Architecture

BrainDrive memory follows a five-stage workflow:

1. Orient.
2. Align.
3. Plan.
4. Execute.
5. Propagate.

These are process stages, not all file types.

The architecture has a stable set of primitives:

| 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 | No file primitive; behavior only |

Domain complexity should scale by adding app instances, instruction depth, source collections, reports, and indexes. It should not scale by inventing new primitive types for every feature.

## 2. Natural-Language-First Principle

BrainDrive's differentiator is that much of its behavior can live in owner-readable memory.

Default rule:

> If a behavior can be clearly expressed as natural-language instructions, templates, indexes, or documents, start there before adding code.

Code is still correct for:

- File I/O.
- Upload plumbing.
- Runtime validation.
- Authentication and authorization.
- Versioning and migration mechanics.
- Deterministic safety checks.
- Audit logs.
- Model/tool routing.
- Anything natural language cannot reliably enforce.

Prompts, app instructions, project workflows, and owner-customizable behavior should start as documents.

## 3. Canonical Vocabulary

| Term | Meaning |
|---|---|
| App | Owner-facing work artifact where the work happens. |
| Instructions | AI-facing procedure, rule set, or composition logic. |
| Index | Folder map with file listing and optional routing hints. |
| Sources | Uploaded or imported data consumed by apps or instructions. |
| Reports | Regenerated synthesis outputs the owner reads. |
| Active file | A file that does something and carries instructions. |
| Reference material | A file consumed by an active file but not instruction-bearing. |
| Propagate | Post-execution behavior that syncs affected memory and returns up the scope chain. |

Retire "Executable" as a canonical noun.

Use:

- Execute = stage.
- App = owner-facing work artifact.
- Instructions = supporting procedure/rules/composition files.

Architecture docs should use App for owner-facing work artifacts and Execute for the stage.

## 4. Layer Model

| Layer | Purpose | What Belongs Here |
|---|---|---|
| System prompt | Universal BrainDrive behavior | Rules that apply everywhere |
| `base/AGENT.md` | Cross-project orientation and routing | Project list, global routing signals, active cross-project state |
| `me/profile.md` | Cross-project owner context | Stable owner facts, values, preferences, life context |
| Project `AGENT.md` | Domain orientation | What this domain is, boundaries, available apps/files |
| Project `spec.md` | Align | Goals, current state, success criteria, constraints |
| Project `plan.md` | Plan | Milestones, sequence, next steps, dependencies |
| App | Execute | Owner-facing work and local operating instructions |
| Instruction file | Execute support | Narrow procedure, rule set, or composition |
| Source | Evidence/data | Uploaded or imported documents/data |
| Report | Output | Regenerated synthesis for the owner |

Higher-level rules apply to everything below them. The higher a rule is placed, the more universal it must be.

## 5. Orient

Orient answers:

- Where am I?
- Who am I helping?
- What project or domain is active?
- What files and apps exist here?
- Where should I route this request?

Orient files should be short. They should not carry detailed app workflows.

Correct pattern:

- `base/AGENT.md` says Finance exists and routes finance work there.
- Finance `AGENT.md` says Budget exists and points to the Budget app.
- `budget.md` says what the Budget app is and points to supporting budget instructions when needed.

Incorrect pattern:

- `base/AGENT.md` explains the whole budget workflow.
- Finance `AGENT.md` contains every bank statement rule.
- `budget.md` becomes an 80-line procedure dump.

Orient can reappear locally at deeper levels. An app can have a short local orientation, and an instruction subtree can have a short local orientation. This is fractal scope, not a new project.

## 6. Align

Align answers:

- What does the owner want?
- What does success look like?
- What constraints matter?
- What context defines the work?

In BrainDrive, Align is project `spec.md`.

The spec is not a rigid universal form. Each domain may need different questions and different success criteria. Finance, Fitness, Career, and Relationships can each have different spec shapes, but they all serve the same purpose: alignment.

When alignment behavior changes, update the relevant `spec.md` template.

## 7. Plan

Plan answers:

- How does the owner move from current state to desired state?
- What sequence is realistic?
- What should happen first?
- What gaps block execution?

In BrainDrive, Plan is project `plan.md`.

The plan depends on orientation and alignment, but planning instructions should live in the plan template, not in high-level orientation files.

When planning behavior changes, update the relevant `plan.md` template.

## 8. Execute

Execute is where BrainDrive does work for the owner.

Execute answers:

- What useful work can BrainDrive now perform?
- What owner-facing artifact or workflow supports progress?
- What source files, instructions, and reports are needed?

Execute-stage files fit one of five types:

| Type | Meaning | Examples |
|---|---|---|
| Apps | Owner-facing work artifacts where work happens | `budget.md`, `todo.md`, `workout-log.md`, `journal.md`, `investments.md`, resume |
| Instructions | AI-facing procedures, rules, or composition logic | `compare-months.md`, `budget-rules.md`, `handle-conflicts.md`, `net-worth.md` |
| Index | Folder map and optional request routing | `index.md` |
| Sources | Uploaded/imported evidence or data | Bank statements, receipts, health records, parsed documents |
| Reports | Regenerated outputs the owner reads | `reports/latest.md`, `reports/net-worth-latest.md` |

## 9. Active And Reference Files

Use the Onion Test:

> Does this file do something, or is it consumed by something that does?

If it does something, it is active and carries instructions.

Active files:

- Project `AGENT.md`.
- `spec.md`.
- `plan.md`.
- Apps.
- Instructions.

Reference material:

- Sources.
- Reports.

Indexes are navigational reference. They help the agent route through a scope, but they should not become procedure dumps.

Reports may contain light notes about how to read the report, but detailed workflow belongs in Instructions. Sources should be labeled and organized, not instruction-bearing.

## 10. Progressive Disclosure

Progressive disclosure is the central scaling rule.

The agent should see:

1. A short orientation.
2. A pointer to the relevant next file.
3. Only the detailed instructions needed for the current task.

The agent should not load every possible instruction just in case.

Canonical rule:

> Instructions live in the active file that owns the current scope. If that scope becomes too complex, the active file points to child instruction files that own narrower scopes.

Do not split prematurely. If an app only needs one or two local instructions, keep them in the app. If the instruction section becomes hard for a human to understand comfortably, create a narrower instruction file or index.

## 11. App File Shape

Apps are owner-facing work artifacts. They can carry both instructions and owner data.

Preferred shape:

```markdown
# Budget

## Instructions

What this app is. How to use it. When to update it.
Links to specialized procedures if needed.

---

## Current Budget

[Owner-facing budget content]

## Monthly Notes

[Owner-facing notes]
```

The same file can serve two modes:

- View mode: owner sees the artifact.
- Edit mode: owner can inspect and customize the full file, including instructions.

This preserves natural-language owner customization without hiding all behavior in code.

## 12. Naming Rules

| 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` |
| Rules | `<topic>-rules.md` | `budget-rules.md`, `source-rules.md` |
| Composition | Clear noun or verb phrase | `net-worth.md`, `compute-net-worth.md` |
| Index | `index.md` | `index.md` |

Rules:

- Apps do not need `-app`.
- Procedures do not need `-procedure`.
- `spec.md` is reserved for project-level Align. Do not put `spec.md` inside app folders.
- Naming should clarify ownership and scope.

## 13. Index Rules

Use an index when a scope has multiple files the agent must route through.

Rules:

- A simple one-file app does not need an index.
- Any app folder or instruction subtree should have an `index.md`.
- A project should use an index when `AGENT.md` would otherwise become a file dump.

Index pattern:

```markdown
# Budgeting Index

## Files
- `budget.md` - app: saved budget
- `compare-months.md` - procedure: compare current month against budget
- `generate-report.md` - procedure: create budget report
- `budget-rules.md` - rules: durable owner-approved budget handling
- `statements/` - sources: bank statements
- `reports/` - reports: generated outputs

## Common Requests
- Monthly check-in -> `compare-months.md` + `generate-report.md`
- New statement uploaded -> `source-rules.md` + relevant source file
- "What should I cut?" -> `compare-months.md` + `budget-rules.md`
```

The file listing is the floor. Common request hints are an optimization.

## 14. Cross-Project Scope

BD+1 is a cross-project scope, not a normal domain project.

It contains:

- `base/AGENT.md`.
- `me/profile.md`.
- `me/todo.md`.

There is no BD+1 `spec.md` or `plan.md` for now.

Reason:

- Owner identity and values belong in profile.
- Domain goals belong in project specs.
- Domain plans belong in project plans.
- A universal spec/plan would likely duplicate project truth until a real life-level artifact requires it.

Revisit if Whyfinder or another life-level artifact needs a cross-project Align/Plan layer.

## 15. Profile Rules

`me/profile.md` is the highest-trust owner memory file because it affects every project.

Boundary rule:

> Relevant in multiple projects -> profile. Relevant in one project -> that project's `spec.md`.

Examples:

| Fact | Placement |
|---|---|
| Owner age | `me/profile.md` |
| Communication preference | `me/profile.md` |
| Self-employed | `me/profile.md` |
| Wants to retire at 55 | Finance `spec.md` |
| Carries credit card debt | Finance `spec.md` |
| Does StrongLifts 3x/week | Fitness `spec.md` |

Write rule:

- Stated cross-project facts can be added.
- Inferred facts require confirmation.
- Do not silently turn a project-specific fact into a profile fact.
- No profile tiering for now.

## 16. Composition

When apps combine, composition is an Instruction file. It is not a new primitive.

Example: `net-worth.md`

- Reads `budget.md`.
- Reads `investments.md`.
- Defines how to compose them.
- Produces `reports/net-worth-latest.md`.

Composition can live at project scope or cross-project scope depending on what it combines.

Examples:

- Budget + investments -> net worth.
- Finance + Career -> income runway.
- Fitness + Finance -> affordability-aware wellness plan.
- Finance + Career + Relationships -> life dashboard.

Lower-level apps should not need to know every higher-level composition that might use them.

## 17. Propagate

Propagate is behavior, not a file primitive.

It should be designed modestly until Execute has proven patterns.

Minimum responsibilities:

1. Report what happened.
2. Sync affected memory.
3. Return up the scope chain.
4. Decide what the owner should see or do next.

After execution, BrainDrive may need to update:

- App state.
- Reports.
- Indexes or source manifests.
- Project `spec.md` if goals/current state changed.
- Project `plan.md` if milestones or next steps changed.
- `me/profile.md` only for confirmed cross-project facts.
- `me/todo.md` for new active tasks.
- Audit logs where needed.

The agent must not get stuck deep inside a narrow execution task. After completing a subtask, it should return upward and ask:

- What changed?
- Which parent artifacts need updating?
- Which reports are stale?
- Which next actions should be created?
- What should the owner see now?

## 18. Finance Direction

Finance/Budgeting is the first serious proof of the Execute architecture.

Correct pattern:

- Finance `AGENT.md` orients the domain.
- Finance `spec.md` aligns on financial goals/current state.
- Finance `plan.md` sequences financial action.
- `budget.md` is the Budget app.
- Budget procedures/rules live in Instructions.
- Bank statements are Sources.
- Budget outputs are Reports.
- Indexes route when the scope has multiple files.

Do not put full budget execution behavior in Finance `AGENT.md`.

Candidate shape:

```text
documents/finance/
  AGENT.md
  spec.md
  plan.md
  budget.md
  index.md
  budget-rules.md
  compare-months.md
  statements/
  reports/
```

Exact migration shape can evolve, but each file's type and ownership should be clear.

## 19. Fitness And Health Direction

Health records are currently Fitness context, not a standalone Health product.

Current boundary:

- Health records support Fitness alignment and planning.
- Uploaded health documents are Sources under the Fitness scope.
- Fitness `spec.md` captures relevant health constraints and context.
- Fitness `plan.md` uses that context for safe, realistic planning.
- BrainDrive should not become symptom triage, diagnosis, or disease-management software through this path.

Examples:

- Blood work.
- Doctor visit notes.
- Height, weight, age, blood pressure.
- Injury status.
- Constraints relevant to fitness goals.

Fitness/Health is the second proof that the document-processing substrate generalizes beyond Finance.

## 20. Owner Customization

Owner-authored memory is owner data.

Rules:

- Default templates define the supported path.
- Owners can edit natural-language app and instruction files.
- Do not silently overwrite owner-authored specs, plans, apps, instructions, or reports.
- Starter-pack updates must merge carefully, request approval, or defer.
- Heavy customization may move a file outside default guarantees, but owner changes should still be preserved unless the owner approves reset/merge.

## 21. Harness Direction

Harness work supports real product proof. It should not become the main objective.

Two harness purposes remain distinct:

- Full application harness: UI, upload flow, front-end behavior.
- Starter-pack/persona harness: lower-cost prompt and memory testing.

Use the full UI harness when testing UI/upload behavior. Use lower-cost starter-pack/persona testing for prompt and memory behavior once the UI path is proven.

Finance and Fitness/Health validation are the priority.

## 22. Placement Workflow

When adding or reviewing a file, follow this workflow:

1. Identify scope.
   - Cross-project, project, app, instruction subtree, source collection, or report.

2. Identify whether the file is active or reference.
   - Active files do something and carry instructions.
   - Reference files are consumed and should not carry detailed procedures.

3. Classify the file.
   - Orient primitive, `spec.md`, `plan.md`, App, Instructions, Index, Sources, or Reports.

4. Place instructions at the lowest useful level.
   - Do not move narrow rules upward for convenience.

5. Add an index only when there is a navigable scope.
   - Avoid ceremony for leaf files.
   - Require indexes for folders/subtrees.

6. Check for bloat.
   - If a file is becoming hard to understand, split into narrower files.

7. Check propagation impact.
   - Decide what should update after the work runs.

## 23. Review Tests

Before accepting a memory architecture change, ask:

- Does every new file fit an existing primitive?
- Is the file at the right scope?
- If active, does it self-describe in its header?
- If reference, is it free of detailed workflow instructions?
- Does it duplicate instructions from another file?
- Does it push narrow rules too high?
- Does it rely on prompt text for runtime invariants that code should enforce?
- Does an index route common requests without hiding the full file listing?
- Does Propagate know what may need to change afterward?

## 24. Anti-Patterns

Avoid:

- Giant system prompts.
- Giant `base/AGENT.md`.
- Giant project `AGENT.md`.
- Hiding full app workflows in project orientation.
- Moving a giant procedure from `AGENT.md` into an app header and calling it fixed.
- Loading every instruction file just in case.
- Turning Sources into procedure files.
- Turning Reports into procedure files.
- Creating a new primitive before proving the current primitives cannot express the use case.
- Overbuilding Propagate before Budget and Fitness/Health prove Execute.

## 25. Current Decisions

Locked for Draft 1:

- Five-stage workflow: Orient, Align, Plan, Execute, Propagate.
- Canonical Execute vocabulary: Apps, Instructions, Index, Sources, Reports.
- "Executable" retired as a canonical noun.
- Propagate is behavior, not a primitive.
- BD+1 is cross-project scope, not a standard project.
- No BD+1 `spec.md` or `plan.md` for now.
- Profile is highest-trust cross-project memory.
- Finance/Budgeting is first Execute proof.
- Fitness/Health documents are Fitness context for MVP.

Still open:

- Exact migration path from current repo layout to this model.
- Exact threshold for when a one-file app becomes an app folder.
- Minimum Propagate protocol after the first app examples are stable.
- How to audit whether the agent followed progressive disclosure.
- How starter-pack updates merge into owner-customized memory.

## 26. One-Sentence Source Of Truth

BrainDrive scales by keeping high-level orientation short, using specs to align, plans to sequence work, apps to do owner-facing work, instructions/indexes/sources/reports to support that work, and Propagate to sync the results, with every rule placed at the lowest useful level where both the AI and the owner can understand it.