How starmynd-org/infinite-brain-os works
1. What this repo is
Infinite Brain OS is a git-backed operating system for AI-assisted business operations. The runtime is not a server or database; it is a file-reading agent (Claude Code, Codex, or similar) acting on plain Markdown/YAML in the repository.
2. Core architectural boundary: _system/
_system/ is the contract layer. It contains schemas, registry rules, validation scripts, load-order policies, routing maps, and enforcement tiers. This is the “source of truth” for what node types exist, how they relate, and what must validate before the repo is considered healthy.
3. Knowledge as a namespace graph
knowledge/ is the main knowledge plane and is organized by namespace, not by application feature. Namespaces such as ai-architecture, personal-operator, and emberline-studio each contain canon, concepts, decisions, playbooks, support, and synthesis. The architecture emphasizes “namespace-first” retrieval and explicit promotion from working knowledge to operator-approved canon.
4. Canon vs. support vs. synthesis
The repo distinguishes stable, approved doctrine from supporting material and synthesized guidance. Canon lives inside each namespace’s canon/ folder; support and synthesis are secondary layers. This split matters because agents are expected to draft and operate from lower-trust layers while canon requires operator approval and verification metadata.
5. Executable primitives in entities/
entities/ holds the typed operational building blocks: agents, commands, skills, rules, and related reusable assets. These are not code in the traditional sense; they are structured operational definitions that agents compose into behavior. The duplicate presence of .claude/ and .codex/ mirrors these entities into agent-specific runtime adapters.
6. Work orchestration: workflows/, projects/, departments/, swarms/
- workflows/ contains reasoning and execution loops, including review, onboarding, correction, and weekly/monthly cycles.
- projects/ is the work container layer, with one PLAN.md per project and inline task tracking.
- departments/ assembles entities into operating lanes with charters and indexes.
- swarms/ packages multi-agent sprint execution.
Together these represent the planning-to-execution ladder: doctrine informs workflows, workflows shape projects, projects are assembled into departments, and swarms handle bounded burst work.
7. Inbound flow: intake/
intake/ is the ingress system for external items such as repo sources, web items, research items, and social/media items. It includes playbooks, routing rules, schemas, and processed receipts. The flow is: capture input → route it to a destination/namespace/department → record the routing decision → store a processed receipt. Residual ambiguity is explicitly tracked rather than hidden.
8. Operational data boundaries: data/, memory/, outputs/
These folders separate different kinds of persisted artifacts:
- data/ stores pointers to live numbers, not the numbers themselves.
- memory/ stores reviewed lessons and durable learnings.
- outputs/ stores produced artifacts with lineage.
This boundary is important: the repo avoids acting as a live database and instead stores references, lessons, and deliverables with provenance.
9. Session audit trail: sessions/
sessions/ is the work ledger for AI activity. It includes active, closed, logs, reviews, and templates for session records and closeouts. This makes AI work traceable and reviewable, and it supports the repo’s governance model around closure, accountability, and freshness.
10. Automation and deterministic execution
automations/n8n/ is the main deterministic workflow area and shows that the repo supports machine-executed processes alongside agentic reasoning. The split is clear: agentic workflows live in workflows/, while deterministic automations are represented as n8n JSON plus companion docs. That separation is a key architectural boundary.
11. Runtime adapters and editor surfaces
.claude/ and .codex/ contain runtime-specific shims: agents, commands, skills, hooks, and settings tailored to each AI toolchain. .obsidian/ config makes the repo usable as an Obsidian vault. These surfaces do not define the architecture, but they shape how humans and agents enter and operate the graph.
12. Validation and governance
The repository is held together by validation scripts in _system/checks/ and validate.sh, plus repo-level rules for linting, session status, output linkage, and adapter sync. The architectural assumption is that the repo stays correct through continuous contract checks, not through a database or centralized service.
13. Worked-example pattern
The knowledge/_examples/ and departments/example-studio-ops/ content form a complete reference implementation. The README’s Emberline Studio walkthrough demonstrates the intended data flow end to end: canon informs rules, rules inform skills, skills inform agents, workflows produce outputs, and departments assemble the whole operating lane.
14. What to draw in an architecture diagram
The diagram should center on _system/ as the contract spine, knowledge/ as the retrieval and doctrine graph, entities/ as the executable primitive layer, and workflows/projects/departments as the orchestration layers. Around that core, show intake as the inbound funnel, sessions as the audit trail, outputs/memory/data as distinct persistence classes, and .claude/.codex/.obsidian as runtime/editor access surfaces.
Main entry points: ai-architecture AI arch · entities Entities · _system _system · sessions Sessions
Components 21
Contracts
Repository-wide schemas, rules, validation, and registry policies.
- _system · Source-of-truth layer for schemas, rules, routing maps, validation, and enforcement tiers.
_system - Checks · Repository validation scripts and contract checks.
_system/checks - Namespace rules · Namespace index, profiles, routing, load-order, and promotion policies.
_system/namespaces
Knowledge
Namespace-first doctrine graph with canon, support, and synthesis layers.
- AI arch · Primary doctrine namespace for repository architecture and operating model.
knowledge/ai-architecture - Personal op · Namespace for operator profile, goals, and review cadence.
knowledge/personal-operator - Examples · Worked examples that demonstrate the namespace pattern and canonical structure.
knowledge/_examples - Emberline · Brand-specific namespace used as an example operating lane.
knowledge/emberline-studio
Execution
Operational primitives and orchestration layers that turn doctrine into work.
- Entities · Typed operational building blocks for agents, commands, skills, and rules.
entities - Workflows · Reasoning and execution loops for review, onboarding, correction, and cadence work.
workflows - Projects · Project plans and inline task tracking as the unit of managed work.
projects - Departments · Assemblies of entities into structured business operating lanes.
departments - Swarms · Bounded burst execution for multi-agent work.
swarms
Ingress
Inbound routing for external items and intake receipts.
- Intake · Capture, route, and record external items into destinations and namespaces.
intake
Audit
Session ledger and review trail for AI work.
- Sessions · Work ledger for AI activity, closeouts, logs, and reviews.
sessions
Persistence
Distinct stored artifact classes and operational references.
Surfaces
Runtime adapters and editor-facing access points.
Automation
Deterministic machine-executed workflows.
- n8n · Machine-executed workflow artifacts and docs.
automations/n8n
Connections 25
- _system → Checks: validated by · Contract spine is enforced through repository checks and linting.
- _system → Namespace rules: governs · Defines namespace profiles, routing, and load-order policy.
- _system → AI arch: defines · System rules describe how doctrine namespaces are structured and validated.
- _system → Entities: types · System schemas determine the operational primitives available in the repo.
- AI arch → Personal op: frames · Architecture doctrine shapes operator-profile namespaces.
- AI arch → Examples: demonstrates · Example namespaces show the canonical pattern in practice.
- AI arch → Workflows: informs · Doctrine informs workflow design and review loops.
- Emberline → Departments: exemplifies · Brand namespace demonstrates the department assembly pattern.
- Entities → Workflows: composed by · Agents, skills, commands, and rules are assembled into workflows.
- Entities → Departments: assembled into · Operational primitives are packaged into department lanes.
- Workflows → Projects: drives · Workflow loops shape project planning and execution.
- Projects → Swarms: spawns · Projects can trigger bounded multi-agent sprint work.
- Intake → AI arch: routes to · Incoming items are routed into namespaces for processing and canonization.
- Intake → Departments: routes to · Some intake is routed into department lanes.
- Intake → Sessions: records · Routing and processing decisions are captured in sessionable work trails.
- Sessions → Outputs: closes into · Completed work produces outputs with lineage.
- Sessions → Memory: distills · Reviewed sessions become durable lessons.
- Data → AI arch: references · Operational data is kept separate from doctrine and points outward.
- Outputs → AI arch: feeds · Produced artifacts can feed back into knowledge synthesis.
- Claude → Entities: hosts · Claude surface mirrors operational primitives as toolchain assets.
- Codex → Entities: hosts · Codex surface mirrors operational primitives as toolchain assets.
- Obsidian → Examples: browses · Obsidian surface supports human navigation of the knowledge graph.
- n8n → Workflows: automates · Deterministic automations complement agentic workflows.
- Checks → Claude: syncs · Validation includes adapter and surface synchronization.
- Checks → Sessions: checks · Repo checks enforce session ledger status and freshness.