Customization: How Implementations Build on the Architecture
Every AI system has an extension model — plugins, hooks, middleware, SDKs, custom code. So what's different here?
Here, customization is content, not code. The Foundation is a runtime — you don't extend it with code, you write programs that run on it. Your "program" is Your Memory content + tools + configuration + client. The runtime executes it. Components (Your Memory, Agent Loop, Auth, Gateway) stay generic and unmodified. Prompts are the code now — the behavior of the system emerges from what's in Your Memory and what tools are available, not from custom code in the Agent Loop, Gateway, or Auth.
An implementation is a dependency relationship, not a fork (D112). Your product repo imports the Architecture as a dependency. Architecture improvements flow to every implementation automatically. BrainDrive is the reference implementation.
The audience is builders — product developers, AI agents, or product team members who want to know what ships by default, what's customizable, and how. Without this doc, every builder has to reverse-engineer the customization model from six component specs.
Architecture: This spec defines customization mechanisms that apply to any system built on the Architecture — the same mechanisms implementers and Level 3 owners both use.
Related documents: foundation-spec.md (architecture overview, links to all component specs)
The Customization Model
Defaults, Not Fixed Contracts
The Foundation ships sensible defaults for everything a working system needs — runtime config shape, tool discovery mechanism, basic configuration behavior. These are defaults, not fixed contracts. Override any of them.
The only fixed contracts are the two APIs:
| Contract | Fixed? | Why |
|---|---|---|
| Gateway API | Yes | This is how clients talk to the system. Without a stable contract, clients break when internals change. |
| Model API | Yes | This is how the Agent Loop talks to models. Without a stable contract, model swapping breaks. |
| Everything else | Defaults | Bootstrap mechanism, tool discovery, configuration — all overridable. |
This is the same "drop-down menu" principle from the foundation spec (Principle 2) applied to the Foundation's own internals. Bootstrap via minimal Agent Loop config? That's the default. Tool discovery via configured sources + self-description? That's the default. Change either if your product needs something different.
What the Levels Mean (Working Model)
| Level | What it is | Functional? | Who provides it |
|---|---|---|---|
| Architecture | Components + APIs + sensible defaults. The working generic system. | Yes — minimal but working | Architecture repo |
| Implementation | Architecture + product opinions (methodology, skills, starter content, branded client, default tools). | Yes — opinionated product | Product repo (e.g., BrainDrive) |
| Level 3 — Personalization | Implementation + owner customization (life pages, custom skills, preferences, industry packages). | Yes — personalized | The owner |
Implementation and Level 3 use the same customization mechanisms. The difference is who does it and when — a product builder ships implementation opinions as a product, an owner adds Level 3 opinions after the fact. The technical operations are identical.
Every recipient is an owner, not a user. When a coach ships a coaching product, each coaching client gets their own personal AI system with the coach's defaults. The client owns their data, their Memory, their system. They're not registering for the coach's platform — they're receiving their own system that happens to start with the coach's methodology. This is the fundamental difference from traditional SaaS.
An implementation can be as thin as "Architecture + specialized Your Memory for coaching" or as thick as BrainDrive (which adds opinions across Your Memory, tools, config, and client). There's no minimum requirement — if you add one opinion to the Architecture and ship it, that's an implementation.
The Four Customization Mechanisms
There are four ways to customize the Architecture. All implementation and Level 3 customization works through these mechanisms.
1. Your Memory Content
What it is: Files, folders, and structured data that ship with your product.
How it works: Your Memory is an unopinionated substrate (D43). It stores anything. Your product provides the content that gives the system personality, methodology, and purpose. The model reads Your Memory through tools and gives it meaning.
What you provide:
| Content | What it does | Example (BrainDrive) |
|---|---|---|
| Bootstrap target file | First instruction target the model reads at startup | AGENT.md with BrainDrive methodology and instructions |
| Folder structure | Organizes the owner's workspace | library/, projects/, system/ with starter content |
| Skills | Prompts that teach the model workflows | Interview skill, spec generation skill, build plan skill |
| Starter content | Pre-populated files the owner starts with | Starter library pages, templates, example projects |
| Preference data | Product defaults stored as data in Your Memory | Default model preference, default tool policies, interaction style |
Architecture default: The Architecture provides the bootstrap mechanism (minimal Agent Loop bootstrap prompt/config). The implementation provides the bootstrap target content in Your Memory (for example, AGENT.md) and can override path/format conventions.
What stays generic: Your Memory itself has no opinions. It stores and retrieves. It doesn't know what AGENT.md means or why your folder structure exists. The model reads the content and acts on it.
2. Tools
What it is: Capabilities in the environment that the Agent Loop can execute.
How it works: Tools are data — definitions, code, instructions — that live in the environment (D51, D52). Your product ships the tools needed for its use case. The Agent Loop executes tool calls without knowing what the tools do. Auth controls who can use which tools.
What you provide:
| Tool concern | What you decide | Example (BrainDrive) |
|---|---|---|
| Which tools ship | The default tool set for your use case | Filesystem tools, skill loader, Git tool, approval gate |
| Always-send set | Which tools are in every prompt by default (D109) | Filesystem read/write/search, skill tool, approval gate |
| Tool protocol | What protocol your tools use | MCP as default (D32), CLI for Git, native for approval gate |
| Discoverable set | What's available on demand but not in every prompt | Future: marketplace tools, third-party integrations |
Architecture default: The Architecture ships a tool discovery mechanism — runtime config declares tool_sources, the Agent Loop scans those sources, and tools self-describe (MCP/manifest/code). Tool preferences (always-send, policies) live in Your Memory. Override the mechanism if your product needs different discovery.
What stays generic: The Agent Loop is a pass-through executor. It doesn't care what tools exist or what they do. It calls whatever the model asks for and returns the result.
3. Config
What it is: Settings that control system behavior without modifying code.
How it works: Configuration tells the Foundation's components how to behave. Your product provides sensible defaults; the owner can override them. See configuration-spec.md for the three-category model (preferences, runtime config, tool self-description) and layered overrides.
What you provide:
| Config area | What you decide | Example (BrainDrive) |
|---|---|---|
| Model provider | Default provider and model | OpenRouter with configurable model selection |
| Provider settings | API key references (env var names), temperature, token limits | $OPENROUTER_API_KEY, sensible defaults |
| Auth settings | Authentication and authorization config | V1: owner-only (see auth-spec.md) |
| Deployment settings | How the system runs | Docker configuration, port assignments, resource limits |
| Tool plumbing | Which tool sources to scan and how to connect | MCP server endpoints, CLI tool paths, manifest directories |
Architecture default: The Architecture ships defaults for all configuration. An implementation overrides whatever it needs — model provider, auth mode, deployment config — and leaves the rest. Provider and model swaps are config-only, zero code changes (see adapter-spec.md for how adapters make this work).
What stays generic: Configuration is data. The Foundation reads it. Components behave accordingly. No code changes needed.
4. Client
What it is: The interface that connects to the system through the Gateway API.
How it works: Clients are external (D57). They connect to the system through the Gateway API — the same way any client connects. Your product ships its own branded client. Third-party clients work the same way.
What you provide:
| Client concern | What you decide | Example (BrainDrive) |
|---|---|---|
| Client type | What kind of interface | Web app (V1), CLI (MVP) |
| Branding | Look, feel, identity | BrainDrive branding, theme, design language |
| UX patterns | How the owner interacts | Chat-based interaction, approval cards, action cards |
| Feature surface | What the client exposes | Conversation view, library browser, settings |
Architecture default: The Architecture doesn't ship a client. A client is an implementation decision. Any client that speaks the Gateway API is valid.
What stays generic: The Gateway API is client-agnostic (D59). It doesn't know or care what the client looks like. Multiple clients can coexist — web, mobile, CLI, voice, Discord, all connecting to the same system through the same API.
Branding is a client concern, not an architecture concern. A coaching product built on the Foundation can have its own branding, its own name, its own look — the Foundation has no branding baked into its components or APIs.
User Stories
CS-1: Build an Implementation from Scratch — Open
As a product builder, I want to build a new product on the Architecture so that I get a working AI system without building the infrastructure myself.
Details — source, steps, acceptance criteria
Source: Customization interview (Dave W + Claude, 2026-02-26)
Steps:
- Builder adds the Architecture as a dependency (package, not fork)
- Builder creates Your Memory content for their use case (bootstrap target file, folder structure, skills, starter content)
- Builder configures tools for their use case (which tools ship, always-send set, tool protocols)
- Builder sets runtime/adapter configuration (provider adapter, auth mode, deployment config,
tool_sources) - Builder optionally creates a branded client that speaks the Gateway API
- Builder packages the product (repo for developers, Docker image for owners)
- System boots with minimal Agent Loop bootstrap config, reads product entrypoint from Your Memory, discovers tools from configured sources, and is ready for use
Acceptance Criteria (Given-When-Then):
Given the Architecture installed as a dependency
When a builder provides Your Memory content, tool preferences, and runtime/adapter config
Then the system boots and functions as the builder's product
And no architecture code has been modified
Given an implementation built on the Architecture
When the Architecture repo ships an update (bug fix, new capability)
Then the implementation can adopt the update without conflict
Because it depends on the Architecture as a package, not a fork
Status: Open
CS-2: Customize Your Memory Content — Open
As a product builder, I want to ship custom Your Memory content (bootstrap file, folder structure, skills) so that my product has a specific methodology and personality.
Details — source, steps, acceptance criteria
Source: Customization interview, Your Memory spec (D40, D43, D50)
Steps:
- Builder creates a bootstrap target file (e.g., AGENT.md) with product-specific instructions
- Builder creates a folder structure for the use case
- Builder creates skills as markdown files
- Builder creates starter content (templates, examples)
- System boots with minimal Agent Loop bootstrap config that points to the target file, then model discovers the rest from Your Memory
Acceptance Criteria (Given-When-Then):
Given an implementation with custom Your Memory content
When the Agent Loop starts and applies bootstrap configuration
Then the model follows the product's methodology
And the model discovers skills, folder structure, and starter content from Your Memory
And Your Memory itself has zero knowledge of the product's conventions
Given two different implementations with different Your Memory content
When both run on the same Architecture
Then each behaves according to its own Your Memory content
And the architecture code is identical in both cases
Status: Open
CS-3: Ship Custom Tools — Open
As a product builder, I want to ship tools specific to my use case so that the system has the capabilities owners need.
Details — source, steps, acceptance criteria
Source: Customization interview, Tools spec (D51, D104, D109)
Steps:
- Builder creates or selects tools for the use case (MCP servers, CLI tools, native functions)
- Builder configures which tools are in the always-send set (sent with every prompt)
- Builder configures which tools are in the discoverable set (available on demand)
- Builder configures tool plumbing in runtime config (
tool_sources) and sets tool preferences in Your Memory - Agent Loop discovers tools from configured sources at startup, connects to available tools, and includes self-described definitions in prompts
Acceptance Criteria (Given-When-Then):
Given an implementation with custom tools configured
When the Agent Loop starts
Then it discovers and connects to the configured tools
And tool definitions appear in prompts sent to the model
And the Agent Loop has zero knowledge of what the tools do
Given an implementation that ships different tools than BrainDrive
When the system runs
Then the model uses the product's tools, not BrainDrive's
And the Agent Loop, Your Memory, Auth, and Gateway code is identical
Status: Open
CS-4: Create a Branded Client — Open
As a product builder, I want to create my own branded client so that my product has its own identity and experience.
Details — source, steps, acceptance criteria
Source: Customization interview, Gateway spec (D57, D59)
Steps:
- Builder creates a client application (web, mobile, CLI, etc.)
- Client connects to the system through the Gateway API
- Client uses its own branding, design, and UX patterns
- System serves the client identically to any other client
Acceptance Criteria (Given-When-Then):
Given an implementation with a custom branded client
When the client sends a message through the Gateway API
Then the system processes it identically to any other client
And the Gateway has zero knowledge of the client's branding or identity
Given multiple clients connecting to the same Foundation instance
When each client sends messages
Then each receives the same quality of service
And conversations are portable across clients (start on one, continue on another)
Status: Open
CS-5: Industry-Specific Implementation (Coaching Example) — Open
As an industry professional (e.g., a coach), I want to build a domain-specific product on the Architecture so that I can ship personal AI systems to my clients without building the infrastructure myself.
Details — source, steps, acceptance criteria
Source: Customization interview — coaching platform example (Dave W + Claude, 2026-02-26)
Steps:
- Coach starts with the Architecture as a dependency
- Coach creates coaching-specific Your Memory content (client intake templates, session notes structure, goal tracking, coaching frameworks)
- Coach creates coaching skills (intake interview, session summary, progress review)
- Coach optionally adds coaching tools (scheduling API integration, CRM connector)
- Coach creates a branded client ("CoachDrive" or similar)
- Coach ships as repo + Docker image
Acceptance Criteria (Given-When-Then):
Given a coaching product built on the Architecture
When a coaching client receives their own system
Then it behaves as a personal coaching AI with the coach's methodology
And the client owns their data and Memory
And no architecture code has been modified
And the coaching product can take architecture updates without conflict
Given a coaching product and BrainDrive both built on the same Foundation
When tools are developed for one product
Then compatible tools work on the other product without modification
Because both share the same APIs and contracts
Status: Open
CS-6: Owner Personalization (Level 3) — Open
As an owner, I want to customize my system beyond the implementation defaults so that it fits my specific needs.
Details — source, steps, acceptance criteria
Source: Customization interview, Ecosystem concept (D110, D113)
Steps:
- Owner starts with a working implementation
- Owner adds personal Your Memory content (life pages, projects, personal context)
- Owner adds custom skills for their workflows
- Owner adjusts tool configuration (adds tools, changes always-send set)
- Owner adjusts config (model preferences, provider settings)
Acceptance Criteria (Given-When-Then):
Given an implementation with Level 3 personalization
When the system runs
Then it reflects both the product opinions (Implementation) and owner preferences (Level 3)
And the customization mechanisms are identical to what the product builder used
Given an owner who personalizes their BrainDrive
When BrainDrive ships a product update (Implementation)
Then the owner's personalizations (Level 3) are preserved
And the update applies cleanly because Level 3 content doesn't conflict with implementation defaults
Status: Open
Invariants & Edge Cases
Properties That Must Always Hold
- Architecture code is never modified by an implementation — all customization is through Your Memory, tools, config, and client
- Any Agent Loop that implements the architecture contract can boot any implementation — the product's behavior comes from Your Memory, not from Agent Loop customization
- Removing all implementation customization leaves a working architecture system — the Architecture stands alone
- Implementation and Level 3 customization use identical mechanisms — there is no technical difference between product builder customization and owner customization
- Architecture updates can be adopted by implementations without merge conflicts — because an implementation is a dependency layer, not a fork
- Multiple implementations can run on the same Architecture without interfering with each other
- All customization must work through the four mechanisms — no backdoor code-level modification of architecture components
- Secrets never appear in Your Memory or tracked config files — API key references only (see security-spec.md)
Edge Cases to Test
- Implementation ships no custom tools — uses only architecture defaults. System should still work.
- Implementation ships no bootstrap file — overrides the default with a different bootstrap mechanism. System should still work.
- Implementation overrides an architecture default (e.g., different bootstrap path) — the override takes precedence cleanly.
- Two implementations ship conflicting configuration for the same Architecture instance — should be impossible (each implementation is its own deployment).
- Owner (Level 3) overrides an implementation default — owner preference takes precedence.
- Architecture ships a new default that conflicts with an existing implementation override — implementation override should continue to work.
Failure Modes
| Scenario | Expected Behavior |
|---|---|
| Implementation ships malformed bootstrap file | Agent Loop reports error at startup — model can't load instructions. Clear error message pointing to the bootstrap file. |
| Implementation ships tools that aren't available | Agent Loop reports tool connection failure. Model informed of unavailable tools. System continues with available tools. |
| Architecture update changes a default that an implementation was relying on | Implementation's explicit override takes precedence. If the implementation relied on the old default implicitly, the change surfaces as different behavior — caught by the implementation's test suite. |
| Owner tries to customize something the managed hosting deployment restricts | System rejects the customization with a clear message explaining the managed hosting constraint. |
Open Questions
- OQ-1: What exactly are the architecture defaults? Partially resolved (D153, D158). Runtime config:
memory_root: ./your-memory,provider_adapter: openai-compatible,auth_mode: local,tool_sources: [built-in memory tools]. Bootstrap: minimal generic system prompt, implementations override viabootstrapTarget. Memory tools: native read/write/edit/delete/search/list/history. Defaultyour-memory/is empty on first boot. Remaining defaults will emerge during implementation. - OQ-2: How does an implementation depend on the Architecture technically? Resolved (D155). npm package. The Architecture publishes as a package, implementations
npm installit, import components, configure, add opinions, run. Standard semver versioning. OQ-3: How do implementation and Level 3 content coexist without conflicts?Partially answered: configuration-spec.md defines layered overrides (Architecture → Implementation → Level 3, owner wins). Remaining conventions (file-level coexistence) deferred to implementation.- OQ-4: Does the Architecture repo ship runnable code or specs + contracts? Resolved (D153): Runnable code. The Architecture is a working runtime —
npm install, provide Your Memory content + tools + config + client, and it runs. Ships sensible defaults (generic OpenAI-compatible provider adapter, local auth,./your-memoryfilesystem, built-in memory tools). All defaults overridable. Specs, schemas, conformance tests ship alongside as documentation and validation. OQ-5: How do we handle versioning across two repos?Deferred to implementation. Depends on delivery mechanism (see OQ-2).
Success Criteria
- Builders can understand the customization model — Foundation is a runtime, defaults not contracts, four mechanisms
- Builders know what to provide to build an implementation — Your Memory content, tools, config, client
- BrainDrive serves as the reference implementation
- An implementation boots correctly on the Architecture with custom Your Memory content, tools, and config — no architecture code modified
- Implementations ship as their own repo (dependency on the Architecture) and as Docker images for owners
- An AI agent can read this spec and build a working implementation without additional guidance
Decisions Made
| # | Decision | Rationale |
|---|---|---|
| D43 | Your Memory is an unopinionated substrate — it stores anything, has no opinions about structure | Customization content (bootstrap, skills, folders) lives in Your Memory, but Your Memory doesn't know what any of it means. The model gives it meaning. |
| D51 | Tools are data — definitions, code, instructions that live in the environment | Products ship tools for their use case. The Engine executes tool calls without knowing what the tools do. |
| D50 | Bootstrap prompt is Engine configuration; product entrypoint content lives in Your Memory | Foundation provides minimal bootstrap mechanism. Level 2 products provide/override entrypoint content and conventions. |
| D57 | Clients are external — not a system component | Products ship branded clients that connect through the Gateway API. The system doesn't know or care what the client looks like. |
| D109 | Always-send tool set vs. discoverable set | Products configure which tools appear in every prompt (always-send) and which are available on demand (discoverable). |
| D110 | Three-level ecosystem: Foundation → Product → Personalization | Level 1 provides mechanisms. Level 2 provides product opinions. Level 3 provides owner preferences. All use the same four customization mechanisms. |
| D112 | Level 2 is a dependency relationship, not a fork | Product repos import Level 1 as a package. Foundation updates flow to every Level 2 product automatically. |
| D141-refined | Tool definitions/plumbing/preferences are split across source/mechanism/owner | Definitions self-describe from tools (D146), plumbing is runtime environment config, preferences are personal data in Your Memory (D145). |
| D153 | Foundation repo ships runnable code — working runtime with sensible defaults | Level 2 builders npm install, configure, run. Specs/schemas/conformance ship alongside. |
| D155 | Level 2 depends on Level 1 via npm package | Standard dependency management, semver, npm update for Foundation improvements. |
| D158 | Level 1 default bootstrap is a minimal generic system prompt | Level 2 overrides via bootstrapTarget pointing to product content in Your Memory (e.g., AGENT.md). |
Changelog
| Date | Change | Reason |
|---|---|---|
| 2026-03-01 | "No users, only owners" pass: added ownership framing paragraph (every recipient is an owner), reframed CS-5 (ship systems to clients, not offer platform), CS-3/CS-4/CS-6 language fixes, "end users" → "owners" throughout, "coaching platform" → "coaching product" | Ownership model alignment (Dave W + Claude) |
| 2026-03-01 | Cross-doc alignment: fixed §Config (API key references not values, removed technology names from auth, added cross-references to configuration-spec and adapter-spec), added security invariant, consolidated invariants, deferred OQs 1-3/5, consolidated success criteria, removed feature-spec boilerplate sections | Cross-spec review (Dave W + Claude) |
| 2026-02-27 | Opener reframe + trim | Consistency with other specs: "How we define customization" opener, folded "Runtime, Not a Framework" into opener, added Level 1 note + related docs line, removed Security Considerations + Conversation References |
| 2026-02-26 | Initial spec created | /interview + /feature-spec |
The Foundation is a runtime. You don't extend it — you write programs that run on it. Your Memory is your content. Tools are your capabilities. Config is your settings. The client is your interface. Everything else stays generic, stays swappable, stays out of your way.