Schemas — Frontmatter Reference
Jedes Brain-File hat YAML-Frontmatter. Dieses Dokument beschreibt die Felder in menschlicher Form. Die maschinenlesbare Version liegt in ../packages/schemas/src/brain.schema.json.
Strikt validiert: Commits mit ungültigem Frontmatter werden vom pre-commit-Hook abgelehnt (Phase 3). Die CLI, der MCP-Server und die Web-UI validieren beim Schreiben über
core.brain.write(sieheINPUTS.md).
Gemeinsame Pflichtfelder
| Feld | Typ | Beschreibung |
|---|---|---|
id |
string | Eindeutige ID: <instance>.<category>.<path>[.<subpath>...]. Beispiel: kuble.projekt.nori-v3 |
category |
enum | slow | private | business | kunde | projekt | knowledge | inbox | admin | source. Muss mit id[1] matchen |
title |
string | Lesbarer Titel (Deutsch erlaubt, Umlaute OK) |
owner |
Verantwortliche Person | |
created |
date | ISO YYYY-MM-DD |
updated |
date | ISO YYYY-MM-DD — bei jeder inhaltlichen Änderung aktualisieren |
Gemeinsame optionale Felder
| Feld | Typ | Beschreibung |
|---|---|---|
tags |
string[] | Lowercase-kebab, unique (ai, launch-q2) |
visibility |
enum | private | team | public. Default: Personal → private, Business → team |
encrypted |
boolean | Opt-in-Flag für zukünftige File-Encryption (nicht im MVP aktiv, siehe DECISIONS.md D17) |
description |
string | Ein-Satz-Zusammenfassung |
Kategorie-spezifische Regeln
slow — stabile Firmen-Ebene (nur Business-Instanzen)
Werte, Kultur, Prozesse, Kernwissen. Keine zusätzlichen Pflichtfelder.
Beispiel: ../examples/business-instance-kuble/brains/slow/werte.md.
private — private Soul (nur Personal-Instanzen)
Persönliche Werte, Identität. Nie gesynct. Keine zusätzlichen Pflichtfelder.
Beispiel: ../examples/personal-instance-gustavo/soul/private/werte.md.
business — Business-Soul-Kopie (nur Personal-Instanzen)
Read-only Spiegel eines Business-slow-Brains, one-way gepullt vom verbundenen Business. Die erste Path-Komponente ist der Business-Slug: <personal>.business.<biz-slug>.<path>.
Beispiel: ../examples/personal-instance-gustavo/soul/business/kuble/werte.md.
kunde — Kundenbrain (beide Instanz-Typen)
| Feld | Pflicht | Typ | Beschreibung |
|---|---|---|---|
status |
✅ | enum | prospect | active | paused | churned |
contacts |
⬜ | object[] | [{name (pflicht), role?, email?, phone?}] |
sources |
⬜ | string[] | IDs von source-Brains (Meetings, Emails, Dokumente dieses Kunden) |
Pfad: brains/rapid/kunden/<slug>/index.md. Bei verschachtelten Notizen: brains/rapid/kunden/<slug>/<path>.md mit ID <instance>.kunde.<slug>.<path>.
Delete-Schutz: Ein Kunde-Brain kann nicht gelöscht werden, solange mindestens ein Projekt darauf zeigt. UI zeigt die referenzierenden Projekte und blockiert den Delete-Button.
Beispiel: ../examples/business-instance-kuble/brains/rapid/kunden/example-gmbh/index.md.
projekt — Projektbrain (beide Instanz-Typen, häufigster Sync-Träger)
| Feld | Pflicht | Typ | Beschreibung |
|---|---|---|---|
status |
✅ | enum | active | paused | done | archived |
customer |
✅ | string | ID eines kunde-Brains (Pattern: *.kunde.*). Jedes Projekt gehört zu genau einem Kunden; Schema enforced. |
sources |
⬜ | string[] | IDs von source-Brains aus denen dieses Projekt destilliert wurde. |
sync |
⬜ | object | Sync-Konfiguration mit einer verbundenen Instanz — siehe unten |
sync Sub-Objekt
| Feld | Pflicht | Typ | Beschreibung |
|---|---|---|---|
target |
✅ | string | Brain-ID des Sync-Ziels (auf der anderen Instanz) |
mode |
✅ | enum | selective | mirror | off |
fields |
cond. | string[] | Pflicht bei mode=selective. H2-Sektionsnamen oder Frontmatter-Keys, die syncen (case-sensitive) |
direction |
⬜ | enum | push | pull | bidirectional. Default: bidirectional |
Beispiel: ../examples/business-instance-kuble/brains/rapid/projekte/nori-v3/index.md hat sync.target: gustavo.projekt.nori-v3 — und auf der Personal-Seite zeigt ../examples/personal-instance-gustavo/brains/rapid/projekte/nori-v3/index.md zurück mit sync.target: kuble.projekt.nori-v3.
knowledge — Wissens-Artefakt (beide Instanz-Typen)
| Feld | Pflicht | Typ | Beschreibung |
|---|---|---|---|
source |
⬜ | string | URL oder Referenz, wenn extern bezogen (singular, Legacy) |
sources |
⬜ | string[] | IDs von source-Brains aus denen dieses Artefakt destilliert wurde |
Keine weiteren Pflichtfelder. Freie Form.
inbox — Quick-Capture (beide Instanz-Typen)
Keine zusätzlichen Pflichtfelder. Datei-Slug ist konventionell ein Timestamp (2026-04-17-22-45-03). Wird nach Triage per gts inbox triage in die richtige Kategorie verschoben (Phase 3+).
admin — Access-controlled Rates/Budget (nur Business)
Stundensätze, Budgets, interne Rates pro Kunde. Zugangsgeschützt. Genau ein Admin-Brain pro Kunde (1:1, uniqueness enforced).
| Feld | Pflicht | Typ | Beschreibung |
|---|---|---|---|
customer |
✅ | string | ID des Kunde-Brains, für den dieses Admin-Brain gilt (Pattern: *.kunde.*) |
allowed_users |
⬜ | string[] | Zusätzliche User-Emails die trotz non-admin-Rolle lesen dürfen. Default: nur Admin-Rolle. |
allowed_connections |
⬜ | string[] | Remote-Instance-Slugs die via MCP/Sync lesen dürfen. Default: keine. |
rates |
⬜ | object | Frei-form (Stundensätze, Rate Card). |
budget |
⬜ | object | Frei-form (Budget + Burn-Stand). |
Access-Regel: Web-UI — admin-Rolle sieht immer; member/viewer nur wenn in allowed_users. MCP-Remote-Caller — nur wenn beide erfüllt: Connection hat can_read_admin=1 UND Slug steht in allowed_connections. Remote-Writes auf admin sind immer blockiert, unabhängig von Flags.
Pfad: brains/admin/<path>.md.
source — Rohmaterial (beide Instanz-Typen)
Meeting-Transkripte, Emails, Dokumente. Die Source ist die ungekürzte Quelle; destillierte Brains (projekt/kunde/knowledge) zitieren sie via ihr sources[]-Frontmatter-Feld.
| Feld | Pflicht | Typ | Beschreibung |
|---|---|---|---|
type |
✅ | enum | meeting | email | transcript | document | chat | call |
date |
✅ | date | ISO YYYY-MM-DD — wann die Source-Artefakt produziert wurde |
attendees |
⬜ | string[] | Meeting-Teilnehmer, Email-From+To, Dokument-Autor*innen |
customer |
⬜ | string | Optional: Kunde-Brain-ID wenn die Source zu einem Kunden gehört |
project |
⬜ | string | Optional: Projekt-Brain-ID wenn die Source zu einem Projekt gehört |
duration_min |
⬜ | integer | Dauer in Minuten (Meeting, Call) |
location |
⬜ | string | Freiform |
channel |
⬜ | string | Slack-Channel-ID, Email-Thread-ID, etc. |
Body = Rohtext 1:1. Keine Kürzung, keine Umformulierung — die Source ist der ungekürzte Originalinhalt.
Pfad: brains/source/<path>.md.
Delete-Schutz: Source-Löschen blockiert solange ein Brain die ID in seinem sources[]-Array listet.
UI-Behandlung: Sources werden per Default aus /brains (Alle) ausgeblendet (Rausch-Filter). Dedizierte /sources-Seite mit Filter nach Typ/Kunde/Projekt. Sidebar-Link „Sources".
Zwei-Ebenen-Regel (für Agents + User): Lange Rohtexte werden IMMER zuerst als Source angelegt, dann destilliert in ein projekt/kunde/knowledge-Brain mit Zitat der Source-ID in sources[]. Niemals Transkripte direkt in einen destillierten Brain-Body.
Invarianten (zusätzlich zur JSON-Schema-Prüfung)
Diese werden von core.brain.validate (bzw. dem pre-commit-Hook) zusätzlich geprüft:
categorymuss dem zweiten Segment vonidentsprechen.- Dateipfad muss mit der ID matchen (siehe
AUTHORING.md§1). sync.targetmuss ein geparseter Brain-ID sein.- Erlaubte Kategorien hängen vom Instance-Typ ab (siehe
packages/core/src/paths.ts).
Selective Sync — Wie fields konkret funktioniert
Wenn ein H2-Name in fields steht, wandert der Inhalt unter dieser Sektion zum Target. Beispiel:
## Goals
- Launch Q3 2026
- 10 customers by Q4
## Internal Notes
- Prospect X is slow to respond
Mit fields: [Goals] wandert nur ## Goals, ## Internal Notes bleibt im Original.
Steht ein Frontmatter-Key in fields (z.B. fields: [status]), wandert stattdessen dieser Frontmatter-Wert — case-sensitive.
Sync-Konflikte (beide Seiten haben denselben Field seit dem letzten Sync geändert) werden gemeldet, nie automatisch überschrieben.