@DJJones and I have been discussing formalizing how adding new capabilities to your BrainDrive should work. We want to make it simple enough for any BrainDrive owner to add new features to and customize existing features in their BrainDrive.
And we think we have found a great foundation for this. All capabilities are driven by natural language and separated out into small number of primitives that apply to any capability. Capabilities are also composable so you can combine them to create new capabilities.
Attached is a draft overview of how it works that we will be discussing in our Monday dev call livestream at 10am Eastern on Youtube.
Questions, comments, ideas and concerns welcome as always. Just hit the reply button.
Now the one I am providing I am labeling as a draft, mainly because it is 1 conversation behind. I created my version of the original discussion based on just the single concept where Dave W’s version clearly and cleanly has both the 1st and 2nd conversations. I felt there was some elements dealing with workflow and practical application of being used that helped smooth some things out.
At the end of the day, my version isn’t in stone. Needs a few more conversations and being used in the application to completely vet it.
I have been going throught the budgeting app and working on how we can reorg what is there to fit this new way of thinking about things and will have something to show later this evening.
@DJJones ok I went through what was in the new budgeting app and then created a second draft of the big long memory architecture document that started this thread that has all my new thoughts in it after looking at things in action.
And then I restructured the work that is currently on main for the budgeting app to match this new structure and am creating a new branch an PR for it.
And then finally I had the AI run through it with Gemini 3.5 end to end and there were no glaring issues but I will need to do the manual runs to be sure.
I don’t think much was changed about the rules etc that you had setup it’s just the structure. And I am not saying this is done or even functions any better or worse than what is already there so I wouldn’t default merge this, it’s really for us to align on a starting structure to work from to improve things.
Hopefully t’s a good starting point for us to discuss formalizing the structure that we use for Apps so they are easy to create, understand, modify and combine.
I am providing 2 files here this time because as we start to narrow down the draft version of this, it also becomes clear the friction points that we need to be aware when implementing.
It should be clear that the friction points are not actual issues with the draft but rather as with everything, just elements to be watchful of when implementing.
@DJJones Direction’s right. The overlay model is the cleanest answer to the customization-vs-updates collision, the rules split clarifies real semantic differences, and the friction doc is the load-bearing artifact — it names the implementation cost honestly instead of letting it ambush us.
A few things from our call that should land in the next pass before you start coding:
1. “Procedures” → “Instructions” rename. We agreed on the call that instructions reads cleaner than procedures — less ambiguous, matches how the files actually read. Draft 3’s §13 is still titled “Common Procedure-File Shape” and the §3 vocabulary table still uses “procedure” throughout. Worth one find-and-replace pass before this becomes the source of truth.
2. User file orient — two sentences at the top. Per the call, every overlay ships with a brief golf-ball intro: what this file is, and only instructions below this point will be read. Removes the “wait, can I touch this?” moment for the first overlay an owner encounters. Worth specifying as a §15 sub-rule, not implementation-discovered.
3. Overlays ship narrow first.Every file has the availability of having a user file, but we will only do the main things up front. Worth saying explicitly in §15 so the architecture commits to expandable rather than full-matrix-on-day-one — that’s also the right answer to friction #4.
4. Sidebar UX runs in parallel. Friction #4 (file sprawl in the sidebar) gets worse before it gets better with the overlay model. I have a working doc proposing Your Agent / Your Goals / Your Plan as the orientation primitives, with managed instruction files demoted into an Advanced group and overlays accessed via a “customize” affordance. Not gating this week, but I don’t want it drifting. Happy to paste the relevant section here or open a separate thread.
Friction items I’d watch closely while implementing:
#1 (runtime load order). Without enforced base → overlay read order, the model is paperware. Probably the first thing to land.
#2 (starter-pack ownership model). Updates need to distinguish managed base from overlays before the first update ships.
#8 (date injection). Two-line change in readBootstrapPrompt; worth pairing with the rest of the migration so we don’t backtrack.
Migration: confirmed not needed (no users, clean cut). The update-checker AI stays a long-term affordance, not a today problem.
Otherwise: ready to go. Looking forward to seeing this land this week.
Memory architecture is locked at v3.0, the final version. Lives in the Library at projects/production/braindrive-repo/memory-architecture/memory-architecture.md.
Six operational specifics ported in from the prior memory-architecture.md before locking — already proven in prior versions but hadn’t been folded into the Draft 3 spine:
me/profile.md section template (Identity & Situation / What Matters / How to Work with Me) → §19 Profile Rules
L0 system prompt contract (what it says + what it does NOT contain, per braindrive-repo D223) → §18 Cross-Project Scope
Propagation “why it matters” rationale → §21 Propagate
Simple Example + Fractal Scope-Relative Depth → §11 Progressive Disclosure
Plus the procedures → instructions rename we agreed on the 2026-05-26 call has now propagated through the locked doc — §13 is Common Instruction-File Shape, the vocabulary table + layer model + OAPEP nesting + cross-references all updated. Closes gate #1 from my last reply.
Cleanup pass: trimmed proposal-phase header + dropped appendices (no longer needed once locked), moved into the braindrive-repo project folder.
Sidebar UX spec + build plan are also ready in the Library: