Perché una nota alla volta
Misurazioni da uno studio sulla generazione di codice: quando ogni nota porta con sé il proprio contesto, l'input necessario a un modello per ogni task resta costante al crescere del corpus, e modelli locali su hardware consumer producono output corretto dove modelli cloud senza il formato falliscono.
Lo scenario
Un team gestisce 200 note su un mercato. Un agente deve rispondere a una domanda: chi fornisce un componente specifico. La risposta è in una nota, e quella nota lo dichiara nel suo sommario. Ma l'agente non ha modo di sapere quale nota conta, quindi le riceve tutte e 200.
A 200 note il costo è tollerabile. A 2.000 no. L'input cresce linearmente con il corpus, la risposta non migliora e il conto sì. Peggio: più il contesto è lungo, più è probabile che il modello peschi un paragrafo obsoleto tre schermate più in là e contraddica la nota che effettivamente risponde alla domanda.
Non è un problema di retrieval. Un livello di retrieval può ridurre la finestra, ma seleziona comunque frammenti di testo privi di metadati su sé stessi — nessun sommario, nessuna entità dichiarata, nessuna dipendenza esplicita. Il modello riceve testo grezzo e deve inferire di cosa si tratta. Il formato delle note non aiuta.
L'ipotesi
Se ogni nota porta con sé il proprio contesto — un sommario che dice cosa contiene, entità che dicono di cosa tratta, relazioni tipizzate e link espliciti alle note da cui dipende — allora l'input necessario per un task su quella nota è la nota stessa più le sue dipendenze dirette. Quell'input non cresce con la dimensione del corpus. È delimitato dalla nota, non dal vault.
Il Mosaix Format prescrive esattamente questo: dieci chiavi frontmatter su ogni nota (§3.1 della specifica), un grafo di wikilink (§4) e una regola che impone una nota per una domanda (R1). La questione è se la prescrizione funziona nella pratica e quanto costa.
Come abbiamo misurato
Abbiamo condotto uno studio sulla generazione di codice. Il compito era produrre un pacchetto Python completo — dieci dataclass, quattro enum, serializzazione, una suite di test, packaging — suddiviso in 28 task atomici. Ogni task aveva un contratto scritto che ne specificava scopo, input, file di output e dipendenze da altri task. Ogni task riceveva circa 600 token di contesto. Lo stesso pacchetto è stato generato anche con un singolo prompt contenente la specifica completa, circa 7.800 token.
Abbiamo misurato il rapporto di compressione dei token su un benchmark a 30 funzioni (TCG-30): il formato ha ottenuto una riduzione di 5,72× (±0,20, N=5 esecuzioni, intervallo di confidenza al 95%). Il costo unitario è rimasto costante a circa 600 token per task indipendentemente dalla dimensione del corpus, mentre la baseline a contesto pieno cresceva da circa 544 token per una singola funzione a circa 4.055 per trenta.
Cosa è stato controllato. Il modello, l'endpoint API, la temperatura (0) e i criteri di valutazione (struttura corretta, test superati) sono stati mantenuti costanti tra tutte le esecuzioni. La variabile era l'input: un task alla volta rispetto alla specifica completa in un colpo solo. Nelle esecuzioni end-to-end dello stesso studio, 53 task su 56 sono stati completati correttamente (94,6%), 20 su 20 al primo tentativo; eseguire task indipendenti in parallelo ha dato uno speedup wall-clock di 1,79×.
Cosa non è stato controllato. I contratti dei task sono stati scritti dalla stessa persona che ha progettato il formato. Lo studio copre la generazione di codice, non il recupero di conoscenza. I task sono deterministici (esiste un solo output corretto per task), il che favorisce il contesto limitato; task aperti o creativi potrebbero comportarsi diversamente.
| Condizione | Contesto per task | Task completati | Costo | Frozen corretto |
|---|---|---|---|---|
| Specifica completa, prompt singolo, 6 modelli cloud | ~7.800 tok | variabile per modello | $0,002–0,233 | 0 su 6 modelli |
| Un task alla volta, stessi 6 modelli cloud | ~600 tok | 28/28, tutti i modelli | $0,003–0,319 | 6 su 6 modelli |
| Un task alla volta, 8 modelli 4B–Opus | ~600 tok | 28/28, tutti i modelli | $0,00–1,09 | 8 su 8 modelli |
Il risultato più importante: modelli locali
Sei modelli cloud hanno ricevuto la specifica completa in un singolo prompt. Nessuno ha prodotto un pacchetto con annotazioni frozen/mutable corrette. Quattro su sei non hanno generato il file entry point. Il modello più forte, DeepSeek V4 Flash, si è avvicinato di più con 27 test su 28 superati, ma ha comunque mancato il vincolo frozen.
Gli stessi sei modelli, con un task alla volta e circa 600 token di contesto ciascuno, hanno tutti completato 28 task su 28 con annotazioni frozen corrette.
Poi abbiamo eseguito gli stessi task su modelli locali, su una GPU consumer con 12 GB di VRAM, a costo API zero. Qwen 3.5 9B ha ottenuto 40 su 40 su pytest (100%), il primo modello locale a raggiungere un punteggio perfetto su questa suite. Gemma 4 E2B, un modello da 2 miliardi di parametri, ha ottenuto 45 su 47 (96%); i due fallimenti erano un'annotazione frozen su un tipo e un test che il modello ha inventato con logica errata — il codice sorgente prodotto era strutturalmente corretto. Qwen 3.5 4B ha completato 28 task su 28. Otto modelli da 4B a Opus hanno tutti completato 28 su 28 sullo stesso set di task. Claude Opus 4.6 è costato $1,09 per esecuzione; DeepSeek V4 Flash $0,003 per un output identico.
Questa è la conseguenza più importante. Quando il contesto per task è piccolo e auto-contenuto, il modello diventa una scelta per agente. Un modello da 4 miliardi di parametri su un laptop produce lo stesso pacchetto di un modello API flagship. I dati non escono dalla macchina. Il costo per esecuzione è zero.
Non affermiamo che i modelli piccoli siano sempre sufficienti. I task erano deterministici e ben specificati. Su task ambigui o creativi il vantaggio di un modello più grande potrebbe riaffermarsi. Ciò che le misurazioni mostrano è che per task con un contratto chiaro, il contratto conta più del numero di parametri. La causa dominante di fallimento nelle esecuzioni iniziali non erano i modelli — era un'ambiguità nei nostri stessi contratti dei task. Quando abbiamo corretto quell'ambiguità, modelli che prima fallivano hanno iniziato a produrre output corretto senza alcun cambiamento ai pesi o alla configurazione.
Cosa il formato non fa
Il formato non rende un modello più capace. Non sostituisce il retrieval: un vault da 10.000 note ha comunque bisogno di un modo per trovare quella giusta. Non rende i fatti veri: una nota marcata “sourced” con un numero sbagliato è comunque sbagliata. Non garantisce che un agente userà correttamente i metadati.
Quello che fa è rendere il contenuto di ogni nota verificabile dalla nota stessa. Il sommario dice cosa contiene la nota; le entità dicono di cosa tratta; i link dicono da cosa dipende; l'hash rev dice se i metadati sono aggiornati. Un checker (§10) può verificare tutto questo dai file, offline, senza dipendenze. Il formato trasforma convenzioni implicite in struttura esplicita e testabile.
Ulteriori letture
La specifica completa è su spec.html. Il checker di riferimento, audit_reference.py, è nel repository. Entrambi sono rilasciati sotto licenza CC BY-SA 4.0.