# BrainDrive Memory Architecture **Version:** v4.2 · **Locked:** 2026-07-01 (v4.2 — purpose declared as the owner-memory contract; Enforced Invariants M-1…M-13 + enforcement map added as permanent anchors, D280; invariants tightened + M-13 added per Codex post-review. v4.1 — OAPEP reframed to the owner+AI operating model, D279. v4.0 — normative model reframed to flat built-ins. Prior lock: v3.0, 2026-05-27) > **Purpose:** This document is the **owner-memory contract** — the normative rules a starter-pack change or memory-touching code change must satisfy, checkable at review. Its consumers are the runtime, the architecture-lint, the test harness, and pack/spec reviews — not owners (they read the pack) and not the agent (it reads `base/AGENT.md`). The product story (the OAPEP loop) appears here only as context; its canonical home is product-level. Authoring guidance is progressively moving to the starter-pack spec (D280 staged split); **cite invariants by ID (M-1…), not by section number** — IDs never renumber. > Proposal history and superseded drafts live in [`archive/`](archive/) and the decision log. This file is the source of truth. --- ## 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 keeps high-level orientation short, structures page built-in work as **flat owner artifacts paired with sibling procedures** (`spec.md` + `run-interview.md`, `plan.md` + `run-planning.md`, `journal.md` + `run-journal.md`), separates **state from methodology** so weak models can't accidentally overwrite owner content, provides explicit **`*-user.md` overlay files** for owner customization, and relies on progressive disclosure so both the AI and the owner can understand the memory system without loading every instruction at once. ### Current built-ins | Built-in | State artifact | Procedure | Scope | |---|---|---|---| | Your Goals | `spec.md` | `run-interview.md` | page | | Your Plan | `plan.md` | `run-planning.md` | page | | Your Journal | `journal.md` | `run-journal.md` | page | | Your Todos *(deferred → V.1.1)* | `me/todo.md` | — | cross-project (base) | Page built-ins are flat artifacts + sibling procedures. **The to-do list is deferred to V.1.1** ([[braindrive-repo]] D272) — when it ships it's a flat cross-project file at `me/todo.md` with its own task shape (`Active` / `Completed`), not an `artifact` + `run-*` pair (see [`../../your-agent/braindrive-todo-list/spec.md`](../../your-agent/braindrive-todo-list/spec.md)). The canonical current proof of the flat page pattern is [`../page-journal/spec.md`](../page-journal/spec.md). Heavier capability (budgeting, document processing, trackers) is **external tool calling** (V.1.1, spec [[T-695]]), not an in-product app — BrainDrive does not build nested "apps" into memory. ## Enforced Invariants (M-1 … M-13) The contract in one place. Each invariant is stated once, here, with a permanent ID — the sections below elaborate; other docs (starter-pack guidelines, lint, harness, sibling specs) **cite the ID rather than restating the rule**. A change that violates any of these is wrong, whatever else it improves. - **M-1 — State/methodology separation.** Owner state lives in the artifact; methodology lives in the sibling procedure (`journal.md` + `run-journal.md`). Never both in one file. *Why:* weak models overwrite owner content when "editing" instructions co-located with state (the F-002 failure class). (§8) - **M-2 — Preservation Rule.** Every procedure/instruction that touches a state artifact updates sections in place — never whole-file replacement — and keeps every section header, italic description, Status / Last-updated line, and Changelog. *Why:* the bedrock protection for owner data. (§9) - **M-3 — Overlay read order.** Managed base first, matching `*-user.md` second; the overlay wins on conflict unless it conflicts with a higher-level safety rule, a Preservation Rule, a code-enforced invariant, or explicit owner data in a state artifact. (§14) - **M-4 — Overlay preservation.** Starter-pack updates preserve `*-user.md` files **byte-for-byte** — no rewriting, reformatting, or migrating overlay content. (§14) - **M-5 — Write ownership.** Updates may create or replace managed base files; the agent puts owner customization in overlays, not managed bases; owner-authored files are never silently overwritten. (§14) - **M-6 — Flat built-ins.** Page built-in features are flat artifacts + sibling `run-*.md` procedures; the deferred cross-project to-do is a flat file (`me/todo.md`) with no procedure. No app folders; heavier capability is external tool calling. (§Position, §20) - **M-7 — Naming patterns.** `AGENT.md` orients active scopes; artifacts are bare nouns; built-in procedures are `run-*.md` and other instructions are verb-first (e.g. `compute-net-worth.md`); overlays add `-user`; rules split as `-rules.md` / `-rules-user.md`. (§15) - **M-8 — Required shape.** Standard state artifacts carry Status / Last updated / Changelog; instruction files carry the `## Preservation Rule` heading and the common seven-section shape. Logs and lists (`journal.md`, `me/todo.md`) use their own defined required sections. (§12, §13) - **M-9 — Orient brevity / progressive disclosure.** Orient files stay short (base ~50 lines; page `AGENT.md` one screen) and never carry feature workflows; the agent loads only what the current scope points to. (§5, §11, §16) - **M-10 — Placement.** Writes go to the narrowest correct home: confirmed cross-project facts → `me/profile.md` (inferred facts require owner confirmation); page goals/state → page `spec.md`; plan → `plan.md`; journal entries **append** to `journal.md`. (§4, §17; journal append-only per §13 and the Page-Journal spec) - **M-11 — Propagation.** After execution, affected parent memory is synced up the scope chain as **summaries, never copies** — spec/plan change only when something material changed. (§19) - **M-12 — Date injection.** The runtime injects `Today's date is YYYY-MM-DD.` into the bootstrap prompt; the agent never invents a date and asks the owner if none is available. (§9) - **M-13 — Thin, model-agnostic L0.** The L0 system prompt stays a thin shim whose only job is to point at `base/AGENT.md`, and neither it nor the base orient hardcodes model identity ("powered by X"). (§16) ### Enforcement map Who enforces what today. "—" is an honest gap, not an omission; gaps are tracked in §24 / [`implementation-friction.md`](implementation-friction.md). | Invariant | Runtime code | Architecture-lint | Harness | Human review | |---|---|---|---|---| | M-1 state/methodology | — | partial (knows the file set; journal pair pending [[T-712]]/[[T-732]]) | ✓ journal gates (no-rewrite) | ✓ | | M-2 Preservation Rule | — (snapshot/write-guard backstop is a §24 open item) | partial (checks the `## Preservation Rule` heading) | ✓ gates: append-only, no-rewrite, entry-written | ✓ | | M-3 overlay read order | — (prompt-level only) | — | — | ✓ | | M-4 overlay byte-for-byte | — (no pack-update path exists today — updates are code-only, [[T-730]] — so the guarantee is untested, not enforced) | — | — | ✓ | | M-5 write ownership | — | — | partial (parent-unchanged gate) | ✓ | | M-6 flat built-ins | — | partial (no app-folder enforcement needed; journal files pending [[T-712]]) | — | ✓ | | M-7 naming | — | partial (canonical overlay names) | — | ✓ | | M-8 required shape | — | partial (procedure heading check) | — | ✓ | | M-9 orient brevity | — | — | — | ✓ | | M-10 placement | — | — | ✓ journal gates: placement, parent-unchanged, entry-written; profile-confirmation is LLM-judge advisory, not a gate | ✓ | | M-11 propagation | — | — | partial (parent-unchanged; propagation stories are LLM-judged, advisory) | ✓ | | M-12 date injection | **— outstanding** (~2-line `readBootstrapPrompt` change, §24) | — | journal mode injects a date; cold-start runs do not (gap) | ✓ | | M-13 thin model-agnostic L0 | — | partial (rejects "powered by" / model-identity text in `base/AGENT.md`) | — | ✓ | ## 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. **OAPEP is the operating model — how the owner and the AI use BrainDrive together.** The cycle runs fully at **page scope**, and the built-in artifacts are its stage outputs: Orient (page `AGENT.md`), Align (the interview → Your Goals `spec.md`), Plan (Your Plan `plan.md`), Execute (Your Journal `journal.md` + the work itself), Propagate (journal sessions keeping the spec/plan current). The **root scope** (Your Agent) orients and routes into that loop — it deliberately has no `spec.md`/`plan.md` (§16) because the loop runs per page, not at the root. Within a **feature**, the cycle is procedural — carried by the sibling procedure and its workflow files — never structural (no feature-level `spec.md`/`plan.md`; see §11). Learning OAPEP once lets the agent navigate every page. This is the *single* operating model — everything else is an implementation detail of how OAPEP gets carried out. (D279 — OAPEP was previously framed as a fractal property of the memory tree; with flat built-ins only two active scopes exist, so the fractal framing is retired.) The architecture has a stable set of primitives, laid out file by file in the Layer Model (§4) — plus the rare index (§8). Propagate has no file primitive at all; it is behavior only (§19). Domain complexity scales by adding artifacts and their procedures, instruction depth, and (where genuinely navigational) indexes. It does 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, and anything natural language cannot reliably enforce. Prompts, feature instructions, project workflows, and owner-customizable behavior should start as documents. ## 3. Canonical Vocabulary | Term | Meaning | |---|---| | Built-in feature | Owner-facing built-in capability, structured as a **flat state artifact paired with a sibling procedure file** (`journal.md` + `run-journal.md`; `spec.md` + `run-interview.md`; `plan.md` + `run-planning.md`). | | State artifact | Owner-readable file capturing the current state of a feature (e.g., `journal.md`). The owner's data lives here. Procedures/instructions must not overwrite it whole-file. | | Instructions | AI-facing instruction, rule framework, owner-rule overlay, or composition logic. Lives in instruction files or rules files. | | Instruction file | A file describing *how* a workflow runs (e.g., `run-interview.md`, `run-planning.md`, `run-journal.md`). Carries a Preservation Rule. | | Rules framework | Optional BrainDrive-managed default rule framework a feature may use (a managed `*-rules.md`). Defines how to interpret rules, defaults, safety notes, and starter examples. | | Rules overlay | Owner-managed accumulated rules for a feature (`*-rules-user.md`). Captures owner-approved mappings, preferences, and recurring exceptions. | | AGENT.md | Orient file for an active scope — a place that *does* things (project/page). | | User overlay | Optional owner-managed instruction file read after its managed base file and given precedence where it conflicts (e.g., `AGENT-user.md`, `run-journal-user.md`, `-rules-user.md`). | | Index | Folder map and optional routing — used rarely, where there is a navigable collection with no active scope. | | Active scope | A scope that does something — project/page. Has an `AGENT.md` and may have an `AGENT-user.md`. | | Propagate | Post-execution behavior that syncs affected memory and returns up the scope chain. | ## 4. Layer Model | Layer | Purpose | What Belongs Here | |---|---|---| | System prompt | Universal BrainDrive behavior | Rules that apply everywhere; current date (see §9) | | `base/AGENT.md` | Cross-project orientation and routing | Project list, global routing signals, active cross-project state | | `base/AGENT-user.md` | Owner overlay for cross-project behavior | Owner-authored global custom instructions; read after `base/AGENT.md` | | `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 features/files | | Project `AGENT-user.md` | Owner overlay for a domain | Project-specific owner instructions that override or narrow the project orient | | Project `spec.md` (+ `run-interview.md`) | Align | Goals, current state, success criteria, constraints | | Project `plan.md` (+ `run-planning.md`) | Plan | Milestones, sequence, next steps, dependencies | | Project `journal.md` (+ `run-journal.md`) | Execute (repeat / learn loop) | Owner follow-up log kept current after the plan — a flat state artifact + sibling procedure, Preservation Rule at the procedure top | | Procedure overlay (`run-*-user.md`) | Owner overlay for a procedure | Owner customizations read after the managed procedure (e.g., `run-journal-user.md`) | | Instruction file | Execute support | Narrow instruction for one workflow, with Preservation Rule | | Instruction overlay | Execute support | Optional owner customization for a managed instruction | 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 features exist here? Where should I route this request? Orient files should be short. They should not carry detailed feature workflows. Correct pattern: - `base/AGENT.md` says Fitness exists and routes fitness work there. - `base/AGENT-user.md`, if present, adds owner-specific global guidance after the base orient. - Fitness `AGENT.md` orients the page, names its artifacts (Your Goals `spec.md`, Your Plan `plan.md`, Your Journal `journal.md`) and their sibling procedures (`run-interview.md`, `run-planning.md`, `run-journal.md`), and routes to them. - Fitness `AGENT-user.md`, if present, adds or narrows Fitness-specific guidance after Fitness `AGENT.md`. - A sibling procedure (`run-journal.md`) says how *one* workflow runs and carries the Preservation Rule for its artifact (`journal.md`); nothing more. Incorrect pattern: - `base/AGENT.md` explains the whole journaling workflow. - Fitness `AGENT.md` contains every journaling rule. - Fitness `AGENT.md` becomes an 80-line instruction dump. Orient reappears at every active scope: root (`base/AGENT.md`), project/page (project `AGENT.md`). If a matching `AGENT-user.md` exists, it is read immediately after the base orient for that scope (read order per §14). Orient is the one stage both active scopes share; the full OAPEP cycle runs per page (§1). Rules for orient files: - An active scope — a folder that *does* things (a project/page, e.g. `documents/finance/`) — gets an `AGENT.md`, optionally with an `AGENT-user.md` overlay. It is short (one screen). - A simple project with one feature may still benefit from listing it in the project `AGENT.md`. - A flat `index.md` is used only when there is genuinely no active behavior to orient — navigation-only listings. - The file listing is the floor; common-request routing hints are an optimization where the routing isn't obvious. ## 6. Align 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 — and, if the instruction for filling it changes, update the project's `run-interview.md`. ## 7. Plan In BrainDrive, Plan is project `plan.md`. The plan depends on orientation and alignment, but planning instructions live in `run-planning.md` (the instruction file), not in high-level orientation. ## 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 artifacts, procedures, and instructions are needed? Execute-stage files fit three types: | Type | Meaning | Shape | Examples | |---|---|---|---| | Built-in features | Owner-facing work as a flat artifact + sibling procedure | `.md` + `run-.md` (+ optional `*-user.md` overlays); Preservation Rule at the procedure's top | `journal.md`+`run-journal.md`, `me/todo.md` | | Instructions | AI-facing instructions, rule frameworks, and owner-rule overlays | Instruction files (verb-named), optional instruction overlays, managed rule frameworks (`*-rules.md`), and owner-rule overlays (`*-rules-user.md`) | `run-journal.md`, `run-journal-user.md`, `-rules.md`, `-rules-user.md` | | Indexes | (Optional) flat folder listings | `index.md` when there is no active scope to orient — rare | Used sparingly; default is `AGENT.md` | The boundary between state and methodology matters: **state lives in the artifact, methodology lives in the sibling procedure / instructions**. Procedures may read the state artifact and write to it according to the Preservation Rule, but they never replace the state artifact whole-file. Owner customizations to managed methodology belong in `*-user.md` overlays when possible, not as edits inside starter-pack-owned base files. ## 9. Preservation Rule Every instruction file that touches a state artifact carries a Preservation Rule at the top. The Preservation Rule says: - **Update sections in place — never replace the whole file.** - **Always keep:** every section header, every italic section description, every `*Last updated: …*` line, the `**Status:**` line, the `## Changelog`. If a section has no owner content yet, leave its placeholder text in place. - **You may remove:** generic example blockquotes once a section has real owner content (unless the examples are still useful for orientation). - **Use today's date** from your current system context for "Last updated" lines and changelog entries. Do not invent a date — if today's date is not available in your context, ask the owner. Instructions that build new files (e.g., a new generated document) do not need a Preservation Rule for their *output*, but they do need one for any state artifact they read. This rule is the bedrock. Without it, weak models conflate "edit a section" with "rewrite the file" and the owner's data is gone. With it (and the separation of state from methodology — artifact vs. sibling procedure), state artifacts survive byte-for-byte across instruction runs. It was validated empirically under Gemini 3.5 Flash (`test-run-2026-05-24-run2-claude.md`); that run used the earlier app-folder mechanism, but what it proved is the **principle** — separate state from methodology — which the flat artifact + sibling-procedure shape now carries. The Preservation Rule depends on the current date being available. **The bootstrap prompt should inject `Today's date is YYYY-MM-DD.`** at the top, so the rule has something real to refer to. This is an app-side change in `readBootstrapPrompt` (still outstanding). ## 10. Active Files Use the Onion Test: > Does this file do something, or is it consumed by something that does? Either way, it is **active**. Files that do something (orients, procedures, instructions) carry instructions, almost always including a Preservation Rule. Files consumed by something that does (state artifacts) hold owner state and self-describe per their artifact shape (§13). A file that neither acts nor is consumed — an archived draft, a superseded proposal, a one-off generated document the owner has already read — is inactive and carries none of these obligations. Active files: - Project `AGENT.md`. - Project `AGENT-user.md` when present. - `spec.md`, `plan.md`. - Feature procedures and instruction files (`run-interview.md`, `run-planning.md`, `run-journal.md`). - Procedure overlays (`run-journal-user.md`) when present. - State artifacts (`journal.md`, `spec.md`, `plan.md`) — active in the sense that they hold owner state and are read by procedures; they are owner-facing and rarely carry procedural instructions themselves. - Rules frameworks and rules overlays (`-rules.md`, `-rules-user.md`) when a feature uses them. ## 11. Progressive Disclosure Progressive disclosure is the central scaling rule. The agent should see: a short orientation, a pointer to the relevant next file, any matching user overlay for that file, and 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. Overlay rule: > When a managed file has a matching `*-user.md` overlay, read the managed file first and the user overlay second. The overlay may add, narrow, or personalize behavior. It does not replace higher-level safety, Preservation Rules, or runtime validation. Do not split prematurely. If a feature only needs one or two local instructions, keep them in its sibling procedure (or the page `AGENT.md`). If the instruction section becomes hard for a human to understand comfortably, create narrower instruction files. If the owner wants personal behavior that should survive starter-pack updates, place it in the matching `*-user.md` overlay instead of editing the managed file. ### Simple Example When Katie asks, *"how's my fitness going?"* (a journal follow-up), the agent loads: 1. Orientation files: `base/AGENT.md`, `me/profile.md`, and Fitness `AGENT.md` — plus any matching `AGENT-user.md` overlays. 2. The journal procedure: `run-journal.md` (Preservation Rule + method), plus `run-journal-user.md` if present. 3. The owner's journal state: `journal.md` (recent entries), plus Fitness `spec.md` / `plan.md` for goal/plan context. 4. Only the files the current request needs — nothing more. It does **not** load unrelated projects, unrelated features, or deep instruction files that the current scope did not point to. ### Scope-Relative Depth Depth is relative to the current scope, not absolute — a file can be several levels down from root and still be the broad entry point for its own local scope. This recursion is a property of **progressive disclosure** (broad orient → narrower instruction), not of OAPEP: a feature may run the OAPEP flow internally, but that flow is expressed through its sibling procedure and workflow files — **not** by creating duplicate feature-level `spec.md` or `plan.md` files. The cycle is procedural, not structural. Test for going deeper: > Does this feature 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. ## 12. Common Instruction-File Shape Every instruction file follows the same shape so weak models have a predictable form: ```markdown # *One-line italic descriptor — what this workflow does and who runs it.* ## Preservation Rule (see §9) ## What This Instruction Accomplishes The two jobs this instruction delivers on. Brief. ## When to Run Bullet list of triggers. ## Method How the agent runs the workflow. Behavioral defaults, applied conversationally — not a checklist. ## Done Criteria What "good enough to stop" looks like. ## After Running What to update once the workflow completes (state artifact, changelog, propagation). ## What This Instruction Is Not Anti-patterns specific to this workflow. ``` An instruction file with all seven sections in this order is well-formed. Instructions may add a "Reference" section at the bottom (e.g., pointing to example shapes) but they should not invent new top-level sections without a reason. ## 13. Common Artifact-File Shape Standard state artifacts (`spec.md`, `plan.md`) follow the same shape: ```markdown # *One-line italic descriptor — what this artifact is and how it's used.* **Status:** **Last updated:** ##
*Italic section description — what content goes here.*
##
… ## Changelog Material changes only. *Example entries left for reference until real entries replace them.* ``` The mandatory header fields are Status, Last updated, and the existence of a `## Changelog` section, with domain-specific sections inside (Finance's `spec.md` differs from Fitness's). **Append-only logs and task lists define their own required sections instead** — e.g. `journal.md` uses the dated-entry format (see the Page-Journal spec), and `me/todo.md` uses `Active` / `Completed`. The wrapper is not mandatory for those. ## 14. Managed Base, User Overlays, And Owner Customization Owner-authored memory is owner data. Default templates define the supported path, and the agent must not silently overwrite owner-authored specs, plans, features, or instructions. Owners can edit any natural-language feature or instruction file, but persistent custom behavior should default to `*-user.md` overlays. BrainDrive distinguishes **managed base files** from **owner-managed overlay files**. Managed base files are shipped by BrainDrive and may be updated by starter-pack updates: - `AGENT.md` - instruction files such as `run-interview.md`, `run-planning.md`, `run-journal.md` - rule-framework files such as `-rules.md` User overlay files are created or edited by the owner and are never overwritten by starter-pack updates: - `AGENT-user.md` - `-user.md` (e.g., `run-journal-user.md`) - `-rules-user.md` Read order: 1. Read the managed base file. 2. If the matching user overlay exists, read it next. 3. Apply the overlay where it adds, narrows, or personalizes behavior. 4. If base and overlay conflict, the overlay wins unless it conflicts with a higher-level safety rule, a Preservation Rule, code-enforced invariant, or explicit owner data in a state artifact. Write ownership: - Starter-pack updates may create or replace managed base files; they must preserve `*-user.md` overlay files **byte-for-byte** (no rewriting, reformatting, or migrating overlay content). - The agent may create or edit an overlay when the owner asks for persistent customization. - The agent should avoid editing managed base files for owner preference changes unless the owner is intentionally authoring a new reusable default. This turns owner customization from accidental starter-pack drift into a supported extension point, and keeps heavy customization inside default guarantees. It also reduces reliance on LLM merges: the normal update path is "update base, preserve overlay"; only legacy customized base files still require merge, approval, or defer. Overlay files are not state artifacts. They carry instructions, preferences, and owner-approved rules; they do not replace `spec.md`, `plan.md`, `journal.md`, `me/profile.md`, or other owner-state files. Rules frameworks follow the same split: `-rules.md` carries BrainDrive-managed default rule semantics; `-rules-user.md` carries owner-approved accumulated rules. The Preservation Rule (§9) is the per-turn equivalent of this section: even within a single instruction run, the agent does not overwrite owner content. ## 15. Naming Rules | Function | Pattern | Examples | |---|---|---| | Built-in artifact | Bare noun `.md` at page/base scope | `journal.md`, `me/todo.md` | | Built-in procedure | Verb-first `run-*.md` sibling, named for the workflow. New built-ins default to `run-.md` | `run-journal.md`; `run-interview.md` (pairs with `spec.md`) and `run-planning.md` (pairs with `plan.md`) are grandfathered workflow names | | Instruction | Verb-first | `run-interview.md`, `run-planning.md`, `run-journal.md` | | Rules framework | `-rules.md` | `-rules.md` | | Owner rules overlay | `-rules-user.md` | `-rules-user.md` | | User overlay | Add `-user` before `.md` | `AGENT-user.md`, `run-journal-user.md`, `-rules-user.md` | | Composition instruction | Verb-first | `compute-net-worth.md` | | Composition output (when persisted) | Bare noun | `net-worth.md` | | Active-scope orient | `AGENT.md` | At project/page level | | Index (rare) | `index.md` | Only where a navigable listing exists with no active scope | Rules: - Instructions do not need `-instruction`. - User overlays always use `-user`, not `custom`, `local`, `mine`, or owner initials. - `AGENT-user.md` pairs with `AGENT.md`; do not name it `user-AGENT.md`. - `spec.md` is reserved for project-level Align; it is not a feature-level file. - Active scopes get `AGENT.md`. ## 16. Cross-Project Scope Your Agent is the cross-project scope, not a normal domain project. It contains: - `base/AGENT.md` (the Your Agent orient file). - `base/AGENT-user.md` (optional owner overlay for global custom instructions). - `me/profile.md`. - `me/todo.md` *(deferred → V.1.1, per [[braindrive-repo]] D272)*. There is no Your Agent `spec.md` or `plan.md` for now. Your Agent remains orientation and routing, not a normal domain project. Revisit if a future life-level artifact needs a cross-project Align/Plan layer. ### L0 / System Prompt Contract The L0 system prompt is a **thin shim**, not a content surface. Its only job is to instruct the agent to read `base/AGENT.md` to start: ```text Read your-memory/AGENT.md to orient. Follow its instructions. ``` Everything else — BrainDrive identity and persona, the OAPEP process, quality bar, operational rules, project routing — lives in `base/AGENT.md`, and L0 never hardcodes model identity (BrainDrive runs multiple providers; the system prompt is model-agnostic). Two surfaces with overlapping content drift; keeping L0 empty-of-content makes `base/AGENT.md` the single editable source of truth that owners customize and developers update — text-first, code-only-when-forced. Per [[braindrive-repo]] D223. ### `base/AGENT.md` Contract 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 instructions. - Detailed project state. - Owner identity facts (those live in `me/profile.md`). When in doubt, push detail down into the project. ## 17. 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 silently. - Inferred facts require confirmation. Example: *"Your kids have come up a few times — should I add them to your profile?"* - Do not silently turn a project-specific fact into a profile fact. - No profile tiering for now. Standard `me/profile.md` section template: ```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. ``` ## 18. Composition When features/artifacts combine, composition is an instruction file — not a new primitive. A composition instruction is verb-named (`compute-net-worth.md`), reads the relevant page artifacts (`spec.md` / `plan.md` / `journal.md`) and any external-tool outputs — orient first, then state — and produces a synthesis the owner reads. By default the synthesis is delivered in conversation, not written to a file. If the owner wants it persisted, the output is a noun-named state artifact (`net-worth.md`) and the composition instruction carries a Preservation Rule for it like any other procedure (§9). Composition can live at project scope (e.g. `documents/finance/compute-net-worth.md`) or cross-project scope (e.g., a `compose-life-dashboard.md` reading from multiple projects) depending on what it combines. Lower-level features should not need to know every higher-level composition that might use them. ## 19. Propagate Propagate is behavior, not a file primitive. 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: - Feature/artifact state (when the workflow's job is to change it). - Indexes, if any. - Project `spec.md` if goals/current state changed materially. - 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 *(once the to-do list ships, V.1.1; until then commitments stay in the journal)*. - Audit logs where needed. **Propagation rule:** summarize material changes, don't copy. When a session surfaces an insight, the agent updates `spec.md`'s "Where You Are" or `plan.md`'s phase status with a brief summary — it does not paste raw content into the parent. The journal keeps the history; specs and plans hold the current orientation. 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 next actions should be created? What should the owner see now? ### Where propagation rules live Each procedure/instruction carries its own Propagate section describing what to update after work in that scope: - Workflow files name **propagation triggers** — when the workflow's output should prompt a project-level update. - A feature's sibling procedure (`run-journal.md`) carries the **Propagate** section with the rules and examples for that feature. - Project-level `run-interview.md` / `run-planning.md` propagate to `spec.md` / `plan.md` directly as part of After Running. Without propagation, project-level files drift from reality while the owner keeps making progress. The goal is **signal, not noise** — routine updates clutter; meaningful updates orient. ## 20. Applying the Model to a Page Every page uses the same shape — an `AGENT.md` orient plus the flat artifacts and their sibling procedures, with optional `*-user.md` overlays. Finance is the reference layout: ```text documents/finance/ ├── AGENT.md ← managed project orient ├── AGENT-user.md ← optional owner overlay ├── spec.md ← Your Goals (Align) ├── run-interview.md ← procedure for spec.md ├── plan.md ← Your Plan ├── run-planning.md ← procedure for plan.md ├── journal.md ← Your Journal (once journaling lands) └── run-journal.md ← procedure for journal.md ``` Fitness, Career, Relationships, and every other page are the same — only the domain content of the artifacts differs (a Fitness `spec.md` captures health constraints; a Finance `spec.md` captures money goals). **Heavier capability is an external tool, not an in-product app.** Budgeting is not a built-in (the Budget app is retired, D268); it returns as a future external tool ([[T-695]]). Uploaded documents (health records, financial statements) are handled by document processing (a future external tool, D271) and surface as page context — BrainDrive should not become symptom triage, diagnosis, or disease-management software through that path. (Empirical proof of the state/methodology separation: §9.) ## 21. Placement Workflow > *Authoring workflow — future home: the starter-pack spec (D280 staged split). Kept here until the move; the invariants it applies are M-1…M-13.* When adding or reviewing a file, follow this workflow: 1. **Identify scope.** Cross-project, project, feature, or instruction. 2. **Identify whether the file is active.** Active files do something (AGENT.md, overlays, procedures/instructions, state artifacts, rule frameworks, owner-rule overlays). 3. **Classify the file.** Orient (AGENT.md), user overlay, `spec.md`, `plan.md`, `journal.md`, state artifact, instruction, or rule framework. 4. **A new built-in feature is a flat artifact + a sibling procedure.** Create `.md` + `run-.md` (Preservation Rule at the procedure top, optional `*-user.md` overlays), not a nested folder. Heavier capabilities are **external tools**, not in-product apps. 5. **Place instructions at the lowest useful level.** Do not move narrow rules upward for convenience. 6. **Decide ownership.** BrainDrive defaults go in managed base files; owner-specific custom behavior goes in `*-user.md` overlays. 7. **If active and updateable, write a Preservation Rule.** Every instruction that touches a state artifact carries one. 8. **Check for bloat.** If an instruction file is becoming hard to understand, split into narrower instruction files. 9. **Check propagation impact.** Decide what should update after the work runs. ## 22. Review Tests > *Authoring workflow — future home: the starter-pack spec (D280 staged split). Kept here until the move; the invariants it applies are M-1…M-13.* Before accepting a memory architecture change, ask: - Does every new file fit an existing primitive? - Is the file at the right scope? - If the new file is a built-in feature, is it a flat artifact + a sibling `run-*.md` procedure (not a nested folder)? - If it is owner customization for a managed instruction file, is it in the matching `*-user.md` overlay? - If it is an owner-approved accumulated rule, is it in `-rules-user.md` rather than the managed `-rules.md` framework? - Is the base/overlay read order clear? - If active, does it self-describe in its header? Status, Last updated, Changelog for artifacts; Preservation Rule for 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 the active-scope `AGENT.md` route common requests without hiding the full file listing? - Does Propagate know what may need to change afterward? - Will the static-pack lint pass? (Lives in the app repo, `~/BrainDrive/builds/typescript/tools/architecture-lint/`, not this Library.) Project has its `AGENT.md` + required files, artifacts have metadata, overlay names are canonical, no stale paths, no `memory_edit` leakage. ## 23. Anti-Patterns Avoid: - Giant system prompts. - Giant `base/AGENT.md`. - Giant project `AGENT.md`. - Hiding full feature workflows in project orientation. - Moving a giant instruction from `AGENT.md` into a feature's header and calling it fixed. - Loading every instruction file just in case. - Creating a new primitive before proving the current primitives cannot express the use case. - **State and methodology in the same file** — F-002 class: how weak models overwrite owner content (§9). - **Nesting a built-in as an "app" folder** — built-ins are flat; heavier capability is an external tool. - **Inventing a date** (§9). - **Editing managed base files for personal preference drift** — overlays exist for this (§14). - **Writing owner-learned rules into managed rule frameworks** — they belong in `-rules-user.md` (§14). - **Treating overlays as safety overrides** — overlays cannot cancel Preservation Rules, authorization checks, or runtime invariants (§14). ## 24. Current Decisions Locked: the body of this document **is** the locked state — every rule above is current. Decision provenance lives in the [[braindrive-repo]] decision log. One nuance not stated elsewhere: the **rules split** (`-rules.md` + `-rules-user.md`) is available but **optional** — no current built-in uses it; don't create it by default. Still open: - **Staged split (D280):** once the M-IDs have stabilized (survive DJ's review + lint adoption), move the authoring material (§21 Placement Workflow, §22 Review Tests, placement routing narrative, profile examples, shape guidance) to the starter-pack spec, promote the guidelines out of Draft, and re-point the sibling specs **once** — to M-IDs, not section numbers. Until then, nothing moves. - Minimum Propagate protocol once the next feature example is stable. - How to audit whether the agent followed progressive disclosure. - Migration path for legacy owners who customized managed base files before overlays existed. - Date injection — the architecture assumes `Today's date is YYYY-MM-DD.` is prepended by `readBootstrapPrompt` (~2-line app change, still outstanding). - **Code backstop for state artifacts** — the Preservation Rule (§9) is currently enforced only by prompt text, which §22's own review test flags. Candidate deterministic complements (per §2's code-is-correct list): auto-snapshot before any agent write to a state artifact, and/or a write guard that rejects (or requires confirmation for) writes that delete a section header, the Changelog, or a large fraction of the file. The Preservation Rule then becomes the first line of defense, not the only one. - **Journal growth** — `run-journal.md` already sets the behavioral defaults (read recent entries first; don't load the whole file; no automatic summary; compaction only with owner approval). The open gap is the **mechanism**: runtime file reads are whole-file, so "recent entries" needs runtime support at scale, and the archive/rotation shape (e.g. yearly archive files) is undecided. Decide before long-running journals bloat page context. - **Overlay count per page** — a fully customized page is ~11+ files (orient + overlay, three artifact/procedure pairs, per-procedure overlays, optional rules pairs). One option: the page-level `AGENT-user.md` carries per-procedure sections, collapsing the owner's mental model to "each page has one file that's mine" — but that loads all page customizations at orient time and moves narrow rules up a level, against the lowest-useful-level rule (§11, §21). So this may resolve as an edit-UX answer (one owner-facing "customize" surface that writes to the right overlay file) rather than a file-shape change. Resolve before building the sidebar/edit UX below around the current shape. - Owner-facing sidebar UX — should the project sidebar hide agent-instruction files behind an Advanced toggle? - Owner-facing edit UX — should the default "customize" action open/create the `*-user.md` overlay instead of the managed base file? ---