BRAIN OS / TECHNICAL
Four parts.
One working system.
Brain OS combines a knowledge base, tools that connect to live systems, a familiar chat interface, and access controls. Each has a distinct job. Here is how they work together in one freight deployment, including the controls and their limits.
01 · THE SHAPE
Four parts.
One loop per message.
When a message arrives, Brain OS identifies the user’s access tier, reads the relevant knowledge, and calls the tools available to that session. The tools handle live records. Changes follow draft and confirmation steps, with the scope of each control described below.
KNOWLEDGE, COMPILED
What the business already produces
- Process write ups and procedures
- Email and chat threads
- Customer rulebooks
- Rules taught in chat
LIVE SYSTEMS, THROUGH TOOLS
Read live. Written as drafts.
- The system of record, read and write
- Company mailbox
- Driver text number
- Load board, carrier vetting
For every message, inside the asker’s access tier:
- Who is asking? The sender resolves to a person page: book, role, tier.
- What may they see? The session is assembled with only the tools and pages that tier allows.
- Read, call, reason. The brain first, the live tools for anything transactional.
- Answer with sources. Each figure says whether it came from a live read, a rollup or a page.
- Or draft the action. A preview, a yes, a write, an audit line.
WHERE PEOPLE ARE
No new app, no new login
- Teams direct messages and group chats
- Email, from its own mailbox
- Text messages, from its own number
- A load board screen, per load screens, a public tracking link
WHO
Every desk, at its tier
- Dispatch and load management
- Carrier sales
- Billing and finance
- Leadership
THE GUARD, IN THE TOOL LAYER
Access tier
- Money tools and pages absent from a dispatch session, not hidden
Draft, then confirm
- The first call previews. Only a second call writes.
Pause switch
- One phrase stops every write. Fails closed if unreadable.
Access is restricted through the tools and pages made available to a session. Some controls are enforced in code; others, including checking for a person’s approval, also depend on model instructions. The limits section explains the distinction.
02 · THE BRAIN
A knowledge base
people can inspect.
The knowledge base consists of plain files in a Git repository, organized into three layers. Original sources are preserved. The model compiles pages from them using a schema that people define, giving each answer a path back to the material behind it.
raw/SYNC JOBS WRITE. NOBODY EDITS.Immutable source material
Mail and attachments, chat threads, rollups from the system of record, meeting notes. Written only by scheduled sync jobs, dated, never rewritten.
- Mail synced every two minutes
- System of record rollups weekly, lane history daily
- More than 7,000 emails ingested at the reference deployment
wiki/THE MODEL WRITES. PEOPLE DIRECT.Synthesis pages
Pages organize knowledge around people, customers, carriers, systems, offices, processes, rules, and projects. Claims link back to a source or related page, so someone reviewing the knowledge can follow how it was assembled.
- 157 pages: 66 people, 27 processes, 15 systems, and the rest
- The schema requires source links for claims on compiled pages
- When a page disagrees with the system of record, the record wins and the page is flagged
CLAUDE.mdPEOPLE AND THE MODEL, TOGETHER.The schema
What each directory is, the page types, the citation rule, the authority order, and how to ingest and answer. The session starts inside the brain, so the model discovers it on every message.
- Authority order: system of record, then derived calculations, then process docs, then meeting notes, then narrative
- People pages carry the book, the role and the access tier
- The schema co-evolves with the brain, in the same commits
--- type: entity name: Meridian Lumber aliases: Meridian, MLC status: active verified: 2026-09-14 --- # Meridian Lumber Flatbed shipper out of the Ohio yard. Books through the Charlotte office. [[Charlotte-office]] ## Rules - The confirmation number on their load sheet is the BOL. [[2026-08-14-teams-dispatch]] - Pickup window 07:00 to 16:00 unless the sheet says otherwise. [[2026-09-02-teams-dispatch]] ## Lanes - Ohio yard to Alcoa, TN: 41 loads in 2026 to date. [[weekly-2026-37]] (the system of record wins)
An illustrative entity page, with invented names. The frontmatter is what the runtime reads: who this is, whether the page is current, and what the asker may see. The body is the compiled knowledge, each claim carrying the link it came from.
The brain, by page kind
One deployment’s knowledge base on 22 September 2026, after fifteen weeks in production.
Counted from the reference deployment’s wiki directory, 22 September 2026. 157 pages in all.
The numbers
| Kind | Pages |
|---|---|
| People | 66 |
| Everything else | 49 |
| Processes | 27 |
| Systems | 15 |
Rules taught in chat, kept in the brain
When an operator corrects Brain OS, the rule is committed to the brain in the same reply and applies to everyone from the next question. Wrong captures are visible and removed by a person.
Counted from the brain’s commit history, 21 and 25 September 2026.
The numbers
| Window | Rules |
|---|---|
| Rules kept, 24 July to 21 September | 153 |
| Kept in the week of 21 September alone | 71 |
| Kept in the two weeks before that | 21 |
How the knowledge base stays current
Sync jobs are the only writers to the raw layer. Rules taught in chat are committed the moment they are given.
Sync cadence from the reference deployment’s scheduler, 22 September 2026; rule count from the brain’s commit history, 25 September 2026.
03 · THE TOOLS
One tool per action.
Reads live. Writes draft first.
In the freight deployment, transactional records are read from the live system when a question arrives. Write tools first return a preview; a second confirmation call makes the change. Email follows a draft-first instruction rather than the same code-level gate.
Each system of record gets its own Model Context Protocol server. It is a small program that exposes that system’s reads and writes as named tools, with the request and response shapes fixed in code. The model does not compose queries. It picks a tool, and the tool does one thing.
The reference deployment’s server for the transportation management system reuses the client logic already proven in the operation’s own portal software. The integration was tested by payroll before it was trusted by chat.
Every system Brain OS touches, and which way the data moves
Tools read live records and preview changes before a confirmation call. Email uses a draft-first instruction; its limits are described below.
| System | What Brain OS does with it | Access |
|---|---|---|
| McLeod, the transportation management system | Orders, movements, stops, carriers, customers, lane history, credit and receivables, driver texts. Creates and updates orders, stops, rates, carriers and drivers. | Read and write |
| Microsoft Teams | The interface: direct messages, group chats, proactive posts and mentions. | Read and write |
| Microsoft 365 mail | Brain OS’s own mailbox, synced every two minutes and sent from. Personal mailboxes synced with consent, readable only by their owner. | Read and write |
| Twilio | A registered text number: outbound driver texts, inbound replies, photos of signed paperwork. | Read and write |
| Truckstop | Load board posting, updates and removal, each under the broker’s own login. Certified by Truckstop for production. | Write, per user |
| Highway | Carrier identity screening from an email address, and ranked call lists from lane exports. | Read |
| Federal Motor Carrier Safety Administration | Carrier lookup by motor carrier number, behind a local index. | Read |
| OpenStreetMap | A pasted latitude and longitude into a place name. | Read |
| Microsoft Entra | Sign in for the web screens, limited to the company domain. | Sign in |
Not connected at the reference deployment as of 22 September 2026: DAT (in development, not shipped), Samsara, QuickBooks, and documents stored inside the transportation management system. McLeod is one connector. A different system of record needs a different connector; the brain, the guard and the interface carry over.
04 · THE GUARD
Access controls
at the tool boundary.
Commission, payroll, and customer margins need defined access. Actions need defined authority. Brain OS uses session permissions, tool checks, confirmation steps, and a pause control, each with a specific scope.
01
Ask
A person asks for a change in plain language, in the chat they already use.
02
Draft
The first tool call returns a preview only: old and new values, the exact times, the margin, whatever the change touches.
03
Yes
The person reviews the draft and approves it. The model is instructed to wait for that approval; the tool checks for a confirmation call. Specialist desks return drafts and cannot confirm them.
04
Write
A second, explicit confirm call writes to the live system. The tool refuses to write without it.
05
Audit
One line per action in the audit log, credited to the person who asked. Scheduled writes stamp a comment on the record.
One pause switch. Anyone can say “pause writes”. Every write to the system of record, every driver text and every load board post stops, scheduled jobs included. Only leadership or a maintainer releases it. If the switch cannot be read, writes are refused rather than assumed allowed. It exists because an operator once needed a brake, and it has been used deliberately.
REFUSALS BUILT INTO THE TOOLS
- “Cover it with X at $Y.”Refuses a buy above the sell, and shows the margin in the draft.
- “Void this order.”Refuses on delivered or billed orders.
- “Fix the BOL and the weight.”A safelisted set of order fields. Anything off the safelist is refused.
- “Email the carrier a rate confirmation.”Refuses anything titled a rate confirmation. The system of record still sends those.
- “Text this driver.”Refuses opted out numbers and blocked carriers. A location share is one fix per tap, never tracking.
- “Post it at $2,400.”Shipper contact details stripped; stop notes flagged for review before the post.
ACCESS TIERS
Every message is resolved to a person and a tier. Being allowed to talk to Brain OS is not a tier; everyone lands at dispatch unless their page says otherwise. The web screens enforce the same tiers.
| What a session may reach | Dispatch | Billing | Leadership |
|---|---|---|---|
| Loads, carriers, lanes and customers, read live | Yes | Yes | Yes |
| Drafted writes: orders, stops, rates, texts, postings | Yes | Yes | Yes |
| Billing, receivables and customer credit | No | Yes | Yes |
| Settlement history and weekly revenue rollups | No | Set per operation | Yes |
| Commission pages and company wide totals | No | Set per operation | Yes |
| Money digests, in leadership and billing channels only | No | Yes | Yes |
Dispatch sessions receive no financial tools or pages, and shell access is disabled. These restrictions reduce the information and actions available to that session.
ALSO IN THE LAYER
- A spending cap on every messageEach message runs under a cost ceiling. It cannot loop away.
- A financial guard on outbound answersA scan flags commission, payroll, and identifier patterns before an answer leaves. It warns; it does not block the answer.
- Honest about its own stateWhether a capability is on, off or paused is read from the live server at the moment of the question, never recited from a page that may have aged.
- Says so when it cannotWhen it does not know, it says so. When it cannot do something, it logs the request instead of claiming to have passed it on.
05 · SPECIALIST DESKS
Specialists that advise.
Authority earned through testing.
Since 21 September 2026 the reference deployment delegates to three read only specialists: a finance desk, a load manager and a carrier desk. Each returns a sourced brief with at most one drafted action. Brain OS answers from the brief. The confirm step stays with Brain OS.
LEVEL 1
Advise
Read only. Returns a sourced brief and at most one drafted action for Brain OS to confirm with the operator.
All three desks, today
LEVEL 2
Act with confirmation
Holds specific write tools and runs draft and confirm itself, each write behind its switch and the pause.
Two of six gates done
LEVEL 3
Own a task end to end
Runs a bounded task, a book, a lane, a night shift, within a scope a person set. Every action logged, pausable and reversible.
Planned; no release date
TESTED LIKE SOFTWARE
Every desk runs through an automated contract check before a change ships: read only tools, and no figures in its instruction files. Then behavioural test cases, under the exact production setup. The saved trace is read; the grader’s verdict is not trusted on its own.
Every failure that is the desk’s fault becomes a permanent test. The third full run, on 21 September 2026, passed 29 of 31 cases; both misses were the grading, not the desk.
06 · SCHEDULED WORK
About forty jobs
that run without being asked.
Verified on the reference deployment’s server on 21 August 2026. Each runs in shadow first, reporting what it would have done, then is armed with its own switch, capped per run, stamped with an audit comment, and stopped by the pause.
Load watching
The loads board and backhaul scan, late pickup checks, uncovered load alerts as pickup approaches, and carrier shortlists for new loads, posted into the right chat.
Check calls
A morning pulse: drivers texted at 7:30, dispatchers emailed at 8:00, escalations at 8:15. Then estimated arrival refreshes on a fifteen minute cadence, replies matched back to the right load.
Stops and paperwork
When a dock system emails that a truck has arrived, it asks the dispatcher whether to clear the stop. Proof of delivery requests and forwarding. Carrier replies matched to loads.
Order intake
Orders that arrive by email become draft orders posted for approval. The dispatcher replies “build all”.
Money and audit
The carrier invoice audit, the unbilled and missing paperwork digests, and a weekly carrier compliance email.
Leadership
Monday, daily and monthly digests: quiet customers, dormant lanes, hot areas, margin by agent. The Friday usage report. Money only to leadership and billing channels.
07 · WHERE IT RUNS
Your tenant.
A dedicated server.
The bot is registered in the customer’s own Microsoft tenant. Credentials are held only on the server, never in the knowledge base. The reasoning model is Anthropic’s Claude, run with a spending cap on every message, and Brain OS does not train models on customer data.
YOUR MICROSOFT TENANT
Teams
- The bot, registered in your tenant. Direct messages and group chats.
Mailboxes
- Brain OS’s own mailbox. Personal mailboxes only with consent, readable only by their owner.
Entra sign in
- The web screens, limited to your company domain.
THE DEDICATED SERVER
The runtime
- One session per message, started inside the brain, under a spending cap.
The brain
- A private git repository: raw sources, synthesis pages, the schema.
Tool servers
- One per system of record. Draft and confirm built into every write.
Queue, store, audit log
- Jobs, sessions, messages, and one line per action.
Scheduled jobs
- Sync, digests, check calls, each under a lock and the pause.
OUTSIDE, THROUGH TOOLS
System of record
- McLeod, read live and written as drafts.
Load board and text number
- Truckstop under each broker’s login. Twilio for driver texts.
Carrier vetting
- Highway and the federal carrier register, read only.
Model provider
- Anthropic’s Claude. No training on your data.
Credentials are kept on the server, outside the knowledge base. Brain OS does not train models on customer data; provider handling and retention are part of the architecture review.
| Part | What it is | Note |
|---|---|---|
| Reasoning | Anthropic’s Claude, run through the Claude Code agent runtime, with the session started inside the brain so the schema and the tools are discovered on every message. | Spending cap per message |
| Knowledge | Markdown pages in a private git repository: raw sources, synthesis pages, and the schema. Every change is a commit, so the brain has a history. | Git, plain files |
| Tools | One Model Context Protocol server per system of record, exposing named reads and writes with fixed shapes. Draft and confirm built into every write tool. | TypeScript |
| Interface | Microsoft Teams through the Bot Framework, or Slack. A mailbox and a registered text number of its own. Web screens behind Microsoft Entra sign in. | No new login |
| Queue and store | A Redis backed job queue for messages and scheduled work. A small database for sessions, messages and the audit log. | Per deployment |
| Sync | Scheduled jobs on the server, each under a lock, are the only writers to the raw layer. | cron |
| Hosting | A dedicated server per customer. Password sign in off, services bound to the loopback, secrets in the environment and a vault, never in the repository. | One tenant, one box |
THE ARCHITECTURE CONVERSATION
Before connecting systems, we work through these decisions with your team and record the requirements for your implementation.
- Deployment and data location
- Which systems connect? Where will the service run, and where will your data reside?
- Access and permissions
- Which people and tools can read information, change records, or initiate work?
- Model data handling
- Which providers are involved? What information reaches them, and what are their training and retention terms?
- Retention and deletion
- What is stored, for how long, and who is responsible for deletion?
- Actions and accountability
- What can run automatically? Where is approval required, and what activity records does your team need?
The load board declined to certify the first integration, because every post went out under one shared account. We rebuilt it so each broker links their own login and posts as themselves, with no silent fallback, and the load board certified it for production. Before the first real load went up, the operator asked what exactly was being sent, read the preview, and had shipper contact details stripped by default. The preview gave the operator a chance to inspect the data and change what would be shared before the first post.
08 · THE PATTERN TRAVELS
A shared architecture.
Different working lives.
The knowledge structure, tool interfaces, access controls, and chat runtime form a shared architecture. Connectors and operating rules are built for each business. A freight desk and a construction office need different information to make their next decision.
A freight brokerage and its asset carrier
In production since June 2026
Microsoft Teams, a transportation management system read and written live, a mailbox, a text number, the load board and carrier vetting. Thirty three people in one week, about forty scheduled jobs, three specialist desks.
- Interface
- Teams, mail, text, web
- System of record
- McLeod
- Brain
- 157 pages
Our own lab
Running since spring 2026
The same pattern on Slack, for an engineering team. It plans features, files the tickets, implements the change on a branch and answers review comments. Its brain ingests Slack, the issue tracker, GitHub, Notion, Google Docs, meeting transcripts and the sales system.
- Interface
- Slack
- Systems
- GitHub, Linear, Notion
- Work
- Plan, ticket, build, review
A construction company
In build, autumn 2026
Microsoft Teams, a field service platform, and an on premise accounting ledger with no cloud interface. The brain reads a synced copy of the ledger and states its age with every figure. The date lets a reader judge whether the figure is current enough for the decision.
- Interface
- Teams
- Systems
- Field service, accounting
- Brain
- 27 pages at kickoff
09 · WHAT IT IS NOT
Honest limits.
Dated, on purpose.
The controls and capabilities below describe this deployment as of 22 September 2026, with later findings dated in the relevant entries. During use, Brain OS checks capability status on the server. This page records what was verified at the stated dates.
- “The yes is checked by code.”The write tools refuse to write without a second, explicit confirm call. The tool cannot itself prove a person typed yes. The model makes that call under a standing rule. For email, draft first is a standing rule rather than a code gate.
- “The pause covers everything.”It covers the system of record, driver texts, load board posts and the scheduled jobs. It does not cover email.
- “Every action needs a yes.”Every action a person asks for does. A few scheduled jobs write on a standing authorization for a book, each behind its own switch and the pause.
- “It covers loads.”It drafts the carrier and buy rate and refuses a buy above the sell. The write step was repaired on 24 September 2026 and had not been proven on a live load when this page was written.
- “It posts to every load board.”Truckstop only. A DAT connection is in development and has not shipped.
- “It sends rate confirmations.”No. The system of record still sends them, and Brain OS refuses to email anything titled a rate confirmation.
- “It tracks drivers.”No. It reads electronic logging device pings already in the system of record, and a driver can share one location fix per tap.
- “It clears carriers to haul.”Never. It screens identity and history. Authority and insurance are checked in the vetting tool.
- “It reads any file.”PDFs, images, text and short video in a direct message. Not Word or Excel files, yet.
- “The desks run on their own.”Not yet. All three advise only. Level two needs four more gates, including per person write scopes that are designed but not built.
- “Orders it builds are flawless.”Orders it built have had visibility problems in the system of record’s own search. A stop time defect for stops outside Eastern time was found on 25 September. Each incident produced a control. These examples show why a draft still needs review.
- “It works for everyone on day one.”Only for people with a page carrying their book, role and tier. Without one, “my loads” means the whole company’s.
NEXT
Walk the architecture
with your team.
Bring your security lead and someone who knows the daily work. We’ll map the systems involved, the access each role needs, and the points where a person must approve an action.
Talk architecture with usCounts on this page come from the reference deployment’s knowledge base and code on 22 September 2026 and its session logs to 25 September 2026. The operation is not named at their request. Capability status is read from the live server at the time of a question, never from a page. Confirm current capabilities and controls when planning your deployment.