The Brain Knowledge System: Cross-Machine Architecture & Sync

[!NOTE]

Executive Overview

Attribute	Details
Status	🛠️ Active Production / Estate-Wide Knowledge Base
What It Is	Cross-machine Git-backed markdown knowledge repository (~/brain) synchronized across development machines, powering the public Knowledge Tree and AI recruiter assistant.
Core Problem & Solution	Architectural decisions and project state fragment across multiple physical machines and private workspaces. The Brain enforces strict session pull/push operational rules, modular index navigation, and an automated regex leak-prevention sync pipeline.
Tech Stack	Git, Markdown, Node.js (sync-brain.mjs), Regex Leak Detectors, SvelteKit
Key Highlights	Strict session lifecycle rules, automated credential/IP scrubbing, precomputed manifest.json generation, grounds the Gemini Live voice agent.

The Brain (andrea-de/brain) is the foundational knowledge infrastructure of Andrea's engineering ecosystem. Living at ~/brain across multiple physical and virtual development machines, it serves as the single source of truth for architectural designs, operational runbooks, hardware topology, and project statuses.

1. Cross-Machine Topography & Operational Rules

The Brain spans multiple development environments:

[ Dev Machines: hel / nur / mac / xps ]
                   │
                   ▼ ( git pull at session start )
        [ Local ~/brain Workspace ]
                   │
                   ├─► INDEX.md ( Modular root index; never scan whole tree )
                   ├─► projects/ ( Status and state of active/paused repos )
                   ├─► machines/ ( Hardware capabilities, IP bindings, ports )
                   ├─► tools/ ( Developer CLI environments, harnesses )
                   ├─► media-harnesses/ ( Normative media production contracts )
                   └─► public/ ( Sanitized public portfolio notes & architecture )
                   │
                   ▼ ( git commit & push before finishing work )
          [ GitHub Master Remote ]

Strict Operational Conventions

1. Session Start Synchronization: At the beginning of any work session, the agent/developer runs git pull and inspects <brain-path>/INDEX.md, drilling into only relevant nodes to conserve context.
2. State Transition Updates: Before concluding work that changes an entity's state (shipped, decided, discovered, abandoned), the matching project node is updated, committed, and pushed.
3. No Whole-Tree Scans: Navigation relies on structured indexes to preserve token efficiency.

2. The Public Knowledge Tree Sync Pipeline (`sync-brain.mjs`)

To expose curated architectural notes to technical recruiters, clients, and autonomous agents without risking private credential leakage, Andrea built a deterministic sync engine:

[ ~/brain/public/ Source Nodes ]
                │
                ▼
[ Regex Leak Detection Gates ] ──► ( Blocks Private IPs, Passwords, Hostnames, Traversal )
                │
                ▼
[ Frontmatter & Schema Validation ] ──► ( Validates slug, title, category, tags )
                │
                ▼
[ Target Ingestion (src/lib/brain/) ] ──► ( Sanitized Copy + manifest.json Compilation )
                │
                ▼
[ Dual Presentation Surfaces ]
    ├─► Knowledge Tree Digital Garden (/tree)
    └─► Gemini Live Voice & Chat Recruiter Assistant (/api/chat, /api/live-token)

Automated Leak Detection Gates

The sync script strictly scans all ingested files against sensitive regex patterns:

• Private IPs: Flags RFC 1918 addresses (192.168.x.x, 10.x.x.x, 172.16-31.x.x).
• Secret Assignments: Blocks any environment variable assignments matching KEY, SECRET, PASSWORD, TOKEN.
• Private Machine Hostnames: Blocks references to private internal hardware nodes (hel.md, nur.md, xps.md, mac.md).
• Directory Traversal: Flags ../ traversal escaping the public sandbox.

3. Dual Consumption: Digital Garden & Real-Time AI Grounding

1. Digital Garden (/tree): SvelteKit reader route with syntax-highlighted code blocks, copy buttons, responsive cards, category filters, and rendered Mermaid diagrams.
2. Gemini Live AI Grounding: Ingests the precomputed manifest.json into the system prompt of the Gemini 3.1 Flash Live API, enabling the voice recruiter assistant to speak authoritatively about every shipped project and architectural decision.