BrainDrive Memory Architecture

BrainDrive Development
1

Starting a thread here to discuss building out, updating etc BrainDrive’s memory architecture.

2

@DJJones here is the updated memory architecture overview for your review and comments.

memory-architecture (4).md (43.1 KB)

3

This took a bit more delving into it then simply reading since we have some of the code in place which still needed to be verified…

  • Date injection status is stale
    • The draft still treats date injection as outstanding.
    • On updated dev, readBootstrapPrompt already injects Today's date is ....
    • Implementation: config.ts (line 434)
    • Test coverage: config.test.ts (line 162)
    • Recommendation: keep M-12 as an invariant, but update the enforcement map and §24 from “outstanding” to “implemented / covered by tests.”
  • AGENT.md path language is ambiguous
    • The draft often says base/AGENT.md.
    • The L0 example says your-memory/AGENT.md.
    • Current code reads memoryRoot/AGENT.md.
    • Risk: an implementer could wire or document the wrong physical path.
    • Recommendation: clarify the distinction between the conceptual “base / Your Agent scope” and the actual file path used by runtime/starter-pack code.
  • Preservation Rule scope is unclear
    • M-8 / §12 imply every instruction file carries ## Preservation Rule.
    • §9 says every instruction file that touches a state artifact carries the rule.
    • Risk: lint/review may over-enforce the heading on read-only or output-only instructions.
    • Recommendation: choose one standard. Either require the heading on all instructions, including a no-op variant for non-state instructions, or narrow M-8 / §12 to state-touching instructions only.
  • State-artifact write guard is the highest-leverage open risk
    • The draft correctly identifies state-artifact protection as an open issue.
    • The current architecture still relies heavily on prompt compliance for preventing owner-state deletion.
    • Risk: the most dangerous failure mode remains accidental whole-file replacement or section deletion.
    • Recommendation: prioritize snapshot/write-guard support so the Preservation Rule is enforceable, not just instructional.
  • Overall assessment
    • The draft is much stronger as an engineering contract.
    • The M-1…M-13 invariant block and enforcement map make it reviewable.
    • The flat built-in model is coherent: spec.md, plan.md, journal.md, sibling procedures, overlays, and external tools for heavier capability.
    • Before calling v4.2 final, I would fix the stale M-12 status, normalize AGENT.md path language, and resolve the Preservation Rule scope ambiguity.
4

Thanks @DJJones

@BrainDrivePlusOne pls take a look at this and if there are any questions or issues let us know. Otherwise please update the doc accordingly and let us know when it is done.

Thanks
Dave W.

5

I’ve updated memory-architecture.md to v4.3, addressing all four points from DJ’s review: corrected the stale M-12 date-injection status to “implemented + test-covered” (verified directly against config.ts:434 and config.test.ts:162 in the BrainDrive repo — the fix has actually shipped since 2026-05-27), clarified that base/AGENT.md is conceptual naming distinct from the runtime’s memoryRoot/AGENT.md path (with the mismatched L0 example fixed to match), narrowed the Preservation Rule requirement (M-8/§12/§22) to instructions that touch a state artifact per DJ’s option (b), and elevated the state-artifact write-guard gap in §24 as the top open risk with the already-agreed prompt-first/case-by-case direction folded in. Also synced Pulse tasks T-742 and T-743 to reflect the ground-truth verification and doc changes. Changes are committed and pushed to main.

Processed automatically by the forum listener. Tracked in agent-run logs.