Generated: 2026-08-31
Purpose: Team onboarding and project review
Milestone: v1.0.0-alpha (AI Second Brain — Obsidian PKM & Digital Garden)
- What This Is: Un Second Brain e Personal Knowledge Management (PKM) su base Obsidian, trasformato in un digital garden intelligente e integrato con Antigravity CLI per operare come un "NotebookLM locale". Permette di raccogliere note, appunti universitari (Ingegneria Informatica), articoli e video YouTube, organizzarli con una tassonomia semantica aperta (ACE Topography) e interrogarli via chat per recuperare memorie, sintesi e connessioni interdisciplinari con citazioni dirette alle fonti.
- Core Value Proposition: Rendere l'acquisizione, la manutenzione e l'interrogazione della conoscenza personale fluidi, immediati e a zero attrito, eliminando la frammentazione degli strumenti con fondamenta strutturali solide, standardizzazione AST dei metadati e governance a puro Markdown statico.
- Target Users & Context: Studenti universitari, ricercatori e sviluppatori che necessitano di una base di conoscenza ad alta densità informativa, sincronizzata localmente, esportabile staticamente via Quartz Digital Garden, senza dipendenze da server vettoriali proprietari o plugin dinamici bloccanti (No Dataview).
- Status: Tutte le 8 fasi pianificate e inserite (16 piani su 16) sono state eseguite, testate (101/101 test unitari green) e verificate con successo.
Principali scelte architetturali e ingegneristiche effettuate durante la milestone:
-
Topografia ACE rivisitata a 6 cartelle radice (
01 - Map of Content,02 - Atlas,03 - Inbox,04 - Calendar,05 - Blog,99 - Meta):- Motivazione: Previene la proliferazione di micro-silos caotici, garantisce portabilità cross-platform su Quartz ed elimina percorsi annidati fragili.
- Fase: Phase 01 (Fondamenta & Riorganizzazione Strutturale)
-
Schema YAML frontmatter canonico a 10 campi con
ruamel.yamlAST RoundTrip:-
Motivazione: Standardizza i metadati orientati al retrieval (
summary,source,type,area,related,tags,title,date,updated,status/stage+draft) con array flow-style compatti senza corrompere il Markdown, LaTeX o commenti. - Fase: Phase 02 (Standardizzazione YAML & Frontmatter Funzionale)
-
Motivazione: Standardizza i metadati orientati al retrieval (
-
Consolidamento a 3 sole macro-skills ufficiali (
brain-health,brain-ingest,brain-recall):-
Motivazione: Elimina l'attrito cognitivo e la frammentazione di 8 micro-skills legacy in
.agents/skills/, offrendo workflow chiari, robusti e autodocumentati. - Fase: Phase 03 (Consolidamento Flussi AI & Riduzione Frammentazione)
-
Motivazione: Elimina l'attrito cognitivo e la frammentazione di 8 micro-skills legacy in
-
Motore ibrido di retrieval a 3 vie (YAML Scorer + Okapi BM25 puro + Smart Connections Dense Vectors) con Reciprocal Rank Fusion (RRF
$k=60$ ):- Motivazione: Raggiunge latenza sub-secondo (<15ms sull'intero corpus di oltre 700 note) con graceful degradation quando gli embeddings mancano, e Zero-Hallucination Guard rigorosa.
- Fase: Phase 04 (Esperienza NotebookLM & Retrieval Conversazionale)
-
Demone watcher asincrono (
watch.sh) con PID tracking, auto-healing e log rotation a 5MB:-
Motivazione: Permette l'acquisizione in background di video YouTube (trascrizioni + keyframe JPEG a 720p
-q:v 2in99 - Meta/Clipboard/) e file Inbox senza bloccare il flusso utente. - Fase: Phase 05 (Pipeline Ingestion Background & Multimedia Watcher)
-
Motivazione: Permette l'acquisizione in background di video YouTube (trascrizioni + keyframe JPEG a 720p
-
Riscrittura da zero di
brain_ingest.py(<450 righe) con stagingDraft//Source/eNoteLockSHA-256:-
Motivazione: Elimina il codice legacy monolitico (1528 righe) e i prefissi mutabili dei file (
seen-,proposed-,raw-), garantendo concorrenza fine-grained e sicurezza transazionale. - Fase: Phase 06.1 (Riprogettare da Zero brain-ingest)
-
Motivazione: Elimina il codice legacy monolitico (1528 righe) e i prefissi mutabili dei file (
-
Anatomia note flessibile, pulita e organica (0 emoji nei titoli H1-H3, assorbimento organico dei link nel testo e frontmatter
related: [...], evidenziazioni Style Guide<mark>, Mermaid quotati, LaTeX):-
Motivazione: Rimuove il blocco rigido
## Collegamentie purifica le note da sponsor, convenevoli ed AI slop, garantendo trattazioni dense e professionali. - Fase: Phase 06.2 (Ristrutturazione sezioni note e fasi brain-ingest)
-
Motivazione: Rimuove il blocco rigido
-
Razionalizzazione a 2 soli template universali (
Nota Vault.mdeArticolo Blog.md):-
Motivazione: Purge di 9 template legacy e
Folder Templates/, standardizzando la generazione dinamica su Templater<%* ... %>. - Fase: Phase 06.2 (Ristrutturazione sezioni note e fasi brain-ingest)
-
Motivazione: Purge di 9 template legacy e
| Phase | Name | Status | Key Accomplishments & Deliverables |
|---|---|---|---|
| 01 | Fondamenta & Riorganizzazione Strutturale | Complete | Riorganizzazione fisica di 02 - Atlas/ nelle 5 macro-aree (Tech & AI, Education & Learning, Personal Growth & Health, Finance, Projects), rilocazione archivio scolastico da 03 - Inbox/School/ a 02 - Atlas/Education & Learning/Archivio Scuola/ (583 file spostati con migrate_structure.py), e rete Map of Content a 0 link rotti e 1 sola nota orfana. |
| 02 | Standardizzazione YAML & Frontmatter Funzionale | Complete | Formalizzazione dello schema YAML canonico a 10 campi (ruamel.yaml AST parser), batch normalization di 669 note, e backfilling AI di summary esecutivi (120-180 car) con checkpointing atomico (.backfill_checkpoint.json). |
| 03 | Consolidamento Flussi AI & Riduzione Frammentazione | Complete | Accorpamento di 8 micro-skills legacy nelle 3 macro-skills unificate (brain-health, brain-ingest, brain-recall), eliminazione definitiva di 8 script obsoleti in 99 - Meta/Scripts/, e sync globale della governance. |
| 04 | Esperienza NotebookLM & Retrieval Conversazionale | Complete | Motore di ricerca ibrido a 3 vie (recall_engine.py con Okapi BM25, vettori float32 Smart Connections, scoring YAML, RRF |
| 05 | Pipeline Ingestion Background & Multimedia Watcher | Complete | Demone asincrono watch.sh con comandi CLI (start/stop/status/restart), tracciamento PID, rotazione log a 5MB, estrazione trascrizioni/frame YouTube a 720p -q:v 2 in Clipboard/, duplicate detection globale e Review Dashboard tri-state. |
| 06 | Verifica Generale & Collaudo Milestone | Complete | Standardizzazione dei template con script dinamici Templater <%* ... %>, hardening dell'ingestione note con ready: true, audit salute globale con brain_health.py (0 fix pendenti) e stesura del protocollo di collaudo pratico 06-UAT.md. |
| 06.1 | Riprogettare da Zero brain-ingest (INSERTED) | Complete | Riscrittura integrale di brain_ingest.py (<450 righe), staging dedicato in Draft/ e Source/, NoteLock SHA-256 atomico con auto-healing, autolinking deterministico rigoroso su note reali con code masking, e GTD tri-state con archiviazione selettiva in 99 - Meta/Archive/. |
| 06.2 | Ristrutturazione sezioni note e fasi brain-ingest (INSERTED) | Complete | Riforma dell'anatomia delle note (0 emoji nei titoli, no ## Collegamenti, link organici nella prosa e frontmatter related: [...], evidenziazioni Style Guide), ciclo a 3 macro-fasi snelle (1/3 Estrazione -> 2/3 Rielaborazione AI -> 3/3 Autolinking & Staging), --depth approfondimento di default, 2 soli template universali e 101/101 test unitari green. |
| Requirement ID | Category | Status | Verification Evidence |
|---|---|---|---|
| STRUC-01 | Struttura & Tassonomia | ✅ Met | Consolidamento di 02 - Atlas/ nelle 5 macro-cartelle tematiche (Tech & AI, Education & Learning, Personal Growth & Health, Finance, Projects). |
| STRUC-02 | Struttura & Tassonomia | ✅ Met | Bonifica totale di 03 - Inbox/ con rilocazione dell'archivio scolastico in 02 - Atlas/Education & Learning/Archivio Scuola/ e refactoring atomico di 582 breadcrumbs e wiki-links. |
| STRUC-03 | Struttura & Tassonomia | ✅ Met | Rete MOC allineata in 01 - Map of Content/ (Home MOC.md + 5 Macro-MOC + Sub-MOC tematiche) con 100% dei link interni verificati e note orfane ridotte da 311 a 1. |
| YAML-01 | Frontmatter YAML Funzionale | ✅ Met | Definizione formale dello schema YAML canonico a 10 campi con vocabolario controllato per type e area, source, related inline flow-style e parser ruamel.yaml AST RoundTrip. |
| YAML-02 | Frontmatter YAML Funzionale | ✅ Met | Normalizzazione batch del 100% delle note del Vault (669 note) con rimozione hashtag isolati dal corpo e aggiornamento template di sistema. |
| YAML-03 | Frontmatter YAML Funzionale | ✅ Met | Pipeline di generazione batch dei summary esecutivi (120-180 caratteri, max 200) con checkpointing atomico in 99 - Meta/.backfill_checkpoint.json. |
| SKILL-01 | Flussi AI Unificati | ✅ Met | Implementazione della macro-skill unificata brain-ingest (.agents/skills/brain-ingest/SKILL.md + brain_ingest.py) per l'acquisizione polimorfica di video YouTube, web, note grezze e file locali. |
| SKILL-02 | Flussi AI Unificati | ✅ Met | Scaffolding e integrazione della macro-skill unificata brain-recall (.agents/skills/brain-recall/SKILL.md) per l'interrogazione conversazionale tipo NotebookLM con schema di risposta in 3 sezioni e Zero-Hallucination Guard. |
| SKILL-03 | Flussi AI Unificati | ✅ Met | Implementazione della macro-skill unificata brain-health (.agents/skills/brain-health/SKILL.md + brain_health.py) che unifica audit link, classificazione forward-links, Title Case linting e rigenerazione statica di Vault Health Dashboard.md. |
| RECALL-01 | Esperienza NotebookLM | ✅ Met | Motore ibrido di retrieval a 3 vie (99 - Meta/Scripts/recall_engine.py) con Okapi BM25 puro, decodifica vettoriale float32 Smart Connections, scoring YAML e RRF |
| RECALL-02 | Esperienza NotebookLM | ✅ Met | Risposte sintetiche strutturate per il recupero memorie con schema a 3 sezioni (🎯 Sintesi Esecutiva, 📚 Fonti & Citazioni con timestamp [MM:SS], 🔗 Connessioni Correlate) e guardia anti-allucinazione. |
| RECALL-03 | Esperienza NotebookLM | ✅ Met | Supporto completo a query strutturate e filtri avanzati via CLI (--area, --type, --tag gerarchico, --limit, --similar-to, --format json|pretty|markdown|auto). |
| INGEST-01 | Pipeline Ingestion Background | ✅ Met | Daemon watcher asincrono 99 - Meta/Scripts/watch.sh con comandi CLI (start, stop, status, restart), gestione PID (/tmp/brain_watcher.pid), auto-healing kill -0, e log rotation a 5MB (watch.log.1..3). |
| INGEST-02 | Pipeline Ingestion Background | ✅ Met | Estrazione affidabile di trascrizioni, suddivisione in capitoli e screenshot compressi JPEG a 720p -q:v 2 in 99 - Meta/Clipboard/ via yt-dlp e ffmpeg con guardie per trascrizioni mancanti (TranscriptUnavailableError). |
| INGEST-03 | Pipeline Ingestion Background | ✅ Met | Workflow di revisione GTD tri-state in 03 - Inbox/Review Dashboard.md con approvazione [x], scarto [-], archiviazione selettiva in 99 - Meta/Archive/, duplicate detection globale e registro storico persistente in inbox_history.md. |
Coverage Summary: 15 / 15 requisiti v1 soddisfatti e verificati (100%).
Registro completo delle decisioni di architettura e implementazione:
| ID | Fase | Decisione | Motivazione & Impatto |
|---|---|---|---|
| D-01 (P1) | Phase 01 | Riorganizzazione di 02 - Atlas/ in 5 macro-aree (Tech & AI, Education & Learning, Personal Growth & Health, Finance, Projects) |
Elimina micro-silos caotici e struttura un modello tematico scalabile. |
| D-02 (P1) | Phase 01 | Rilocazione archivio liceale da 03 - Inbox/School/ a 02 - Atlas/Education & Learning/Archivio Scuola/
|
Libera 03 - Inbox/ destinandola esclusivamente all'acquisizione attiva. |
| D-03 (P1) | Phase 01 | Script di migrazione atomico migrate_structure.py con refactoring wiki-links e breadcrumbs |
Spostamento sicuro di 583 file preservando la navigabilità a 0 broken links. |
| D-04 (P1) | Phase 01 | Rete MOC ibrida in 01 - Map of Content/ (Home MOC.md + 5 Macro-MOC + Sub-MOC dense) |
Punto di accesso gerarchico e semantico per tutte le note permanenti. |
| D-01 (P2) | Phase 02 | Vocabolario controllato per type: concept, video, article, lecture, book, project, moc, journal
|
Permette filtri di ricerca precisi e omogenei nel motore di retrieval. |
| D-02 (P2) | Phase 02 | Normalizzazione chiave area: tech, education, mentality, finance, projects, meta, calendar
|
Elimina la vecchia chiave macro_area rendendo i codici compatti e coerenti. |
| D-10 (P2) | Phase 02 | Formato summary: 1-2 frasi dense ed esecutive (120-180 car, max 200) | Condensa i key takeaways essenziali per scansioni sub-secondo da parte dell'AI. |
| D-14 (P2) | Phase 02 | Engine di parsing e serializzazione basato su ruamel.yaml AST RoundTrip |
Garantisce l'integrità del corpo Markdown e dei commenti senza corruzioni. |
| D-15 (P2) | Phase 02 | Flow-style compatto a riga singola per tutti gli array (tags: [...], related: [...], aliases: [...]) |
Mantiene il frontmatter compatto entro 10-12 righe per massima leggibilità. |
| D-20 (P2) | Phase 02 | Checkpoint atomico JSON per processi batch (99 - Meta/.backfill_checkpoint.json) |
Ripresa istantanea senza perdita di dati in caso di interruzioni o rate limits. |
| D-04 (P3) | Phase 03 | Script backend unificato brain_health.py (audit link, linter AST, dashboard statica) |
Elimina la frammentazione di 4 script separati in un unico modulo centrale. |
| D-14 (P3) | Phase 03 | Purge completo di tutte le 7 micro-skills legacy in .agents/skills/
|
Accorpa l'esperienza nelle sole 3 macro-skills ufficiali (brain-health, brain-ingest, brain-recall). |
| D-01 (P4) | Phase 04 | Cache JSON incrementale con convalida mtime del filesystem (.recall_cache.json) |
Garantisce warm boot in <5ms e sincronizzazione automatica su modifiche alle note. |
| D-03 (P4) | Phase 04 | 3-Way Hybrid Retrieval (Okapi BM25 + Smart Connections Dense Vectors + YAML Scorer) con RRF |
Massimizza la precisione combinando corrispondenza lessicale, semantica vettoriale e gerarchica. |
| D-09 (P4) | Phase 04 | Strict Zero-Hallucination Guard | Se un concetto non esiste nel Vault, restituisce un avviso esplicito senza allucinare fatti esterni. |
| D-01 (P5) | Phase 05 | Watcher daemon Unix CLI (start, stop, status, restart) con PID tracking in /tmp/brain_watcher.pid
|
Fornisce controllo trasparente e affidabile del processo di background. |
| D-03 (P5) | Phase 05 | Log rotation a 5MB con preservazione di 3 file di archivio (watch.log.1..3) |
Previene la crescita incontrollata dei log su disco. |
| D-06 (P5) | Phase 05 | Keyframe YouTube compressi JPEG a 720p -q:v 2 salvati in 99 - Meta/Clipboard/
|
Garantisce immagini nitide ma leggere (~100-150KB per frame) accessibili da tutto il Vault. |
| D-11 (P5) | Phase 05 | Duplicate detection globale su tutto il Vault (scansione URL e titoli in Atlas/Blog) | Blocca double-ingestion accidentali prima di creare file di staging. |
| D-01 (P6) | Phase 06 | Standardizzazione di tutti i template con script dinamici Templater <%* ... %>
|
Costruzione dinamica del frontmatter YAML e prompt puliti al momento della creazione nota. |
| D-04 (P6.1) | Phase 06.1 | Riscrittura completa di brain_ingest.py in <450 righe modulari |
Elimina il codice legacy monolitico (1528 righe), ProcessTerminator e prefissi mutabili dei file. |
| D-05 (P6.1) | Phase 06.1 | Sotto-cartelle di staging dedicate 03 - Inbox/Draft/ e 03 - Inbox/Source/
|
Semplifica il ciclo di vita separando chiaramente sorgente grezza e bozza rielaborata. |
| D-07 (P6.1) | Phase 06.1 | Archiviazione selettiva delle sorgenti manuali in 99 - Meta/Archive/ ed eliminazione automatica di video/web |
Preserva le idee originali scritte a mano eliminando i duplicati transitori di web/YouTube. |
| D-02 (P6.2) | Phase 06.2 | Divieto assoluto di emoji nei titoli H1, H2, H3 e nelle intestazioni di sezione | Garantisce un layout sobrio, accademico e compatibile con Quartz. |
| D-03 (P6.2) | Phase 06.2 | Assorbimento organico dei wiki-link nella prosa con sincronizzazione YAML related: [...]
|
Elimina la sezione finale rigida ## Collegamenti intessendo la rete direttamente nel discorso. |
| D-05 (P6.2) | Phase 06.2 | Ciclo di vita a 3 sole macro-fasi (1/3 Estrazione, 2/3 Rielaborazione AI, 3/3 Autolinking & Staging) |
Flusso lineare, trasparente, con monitoraggio reattivo in Review Dashboard.md. |
| D-07 (P6.2) | Phase 06.2 | Filtro aggressivo anti-slop e anti-sponsor con estrazione principi primi | Purifica le trascrizioni da promozioni e convenevoli, estraendo conoscenza densa. |
| D-10 (P6.2) | Phase 06.2 | Modalità --depth approfondimento di default (con --depth sintesi opzionale) |
Assicura trattazioni ricche ed esaustive per ogni nota permanente del Second Brain. |
| D-12 (P6.2) | Phase 06.2 | Razionalizzazione a 2 soli template universali (Nota Vault.md e Articolo Blog.md) |
Purge di 9 template legacy e Folder Templates/ per un'architettura essenziale. |
- Purge script legacy: Rimossi 8 script monolitici/frammentati in
99 - Meta/Scripts/(ingest.sh.bak,migrate_structure.py,audit_vault.py,lint_yaml.py,update_dashboard.py,tidy_vault.py,auto_sort_inbox.py,ingest_manager.py). - Purge micro-skills: Eliminate 7 directory micro-skills ridondanti in
.agents/skills/(audit,meta,tidy,link,process-inbox,nota,dream). - Purge template obsoleti: Eliminati 9 template frammentati e la cartella
99 - Meta/Template/Folder Templates/. - Eliminazione Dataview: Rimosso ogni blocco dinamico
dataviewa favore di tabelle e dashboard Markdown statiche. - Normalizzazione Frontmatter: Corretti 669 frontmatter YAML eterogenei e convertite tutte le intestazioni a Title Case.
- EXT-01 (v2): Sincronizzazione automatica bidirezionale con Kindle / Readwise per highlight di libri.
- EXT-02 (v2): Voice-to-text capture su dispositivi mobili con trascrizione Whisper automatica in Inbox.
- GRAPH-01 (v2): Algoritmo di clustering semantico per suggerire proattivamente nuove MOC quando un cluster tematico supera le 20 note correlate.
-
Gestione del Demone Watcher (Acquisizione in Background):
# Avvia il demone watcher in background ./"99 - Meta/Scripts/watch.sh" start # Verifica lo stato e il PID ./"99 - Meta/Scripts/watch.sh" status # Arresta il demone ./"99 - Meta/Scripts/watch.sh" stop
-
Ingestione Manuale e Interattiva (
brain-ingest):# Ingestione video YouTube o articolo web (approfondito di default) python3 "99 - Meta/Scripts/brain_ingest.py" "https://www.youtube.com/watch?v=..." # Ingestione con estrazione screenshot frame python3 "99 - Meta/Scripts/brain_ingest.py" "https://www.youtube.com/watch?v=..." --extract-frames # Ingestione in modalità sintesi rapida python3 "99 - Meta/Scripts/brain_ingest.py" "https://..." --depth sintesi # Elaborazione approvazioni dalla Review Dashboard python3 "99 - Meta/Scripts/brain_ingest.py" --process-approvals
-
Consultazione e Retrieval NotebookLM (
brain-recall):# Ricerca semantica nel vault python3 "99 - Meta/Scripts/recall_engine.py" "Architettura Transformer e Attention" # Ricerca con filtri di area tematica e tipo di risorsa python3 "99 - Meta/Scripts/recall_engine.py" "Algoritmi di ordinamento" --area education --type concept # Output in formato Markdown a 3 sezioni per chat python3 "99 - Meta/Scripts/recall_engine.py" "RAG Knowledge Base" --format markdown
-
Governance e Manutenzione Vault (
brain-health):# Scansione interattiva con conferma modifiche python3 "99 - Meta/Scripts/brain_health.py" --interactive # Rigenerazione rapida della dashboard statica python3 "99 - Meta/Scripts/brain_health.py" --dashboard-only
-
Esecuzione Suite di Test:
python3 -m unittest discover -s tests -v
-
Mappa delle Risorse Chiave:
- GEMINI.md — Memoria di sistema e regole permanenti del Vault.
- AGENTS.md — Architettura del Second Brain e runtime conventions.
- Home MOC.md — Indice centrale della knowledge base.
- Review Dashboard.md — Dashboard di revisione e approvazione GTD.
- Vault Health Dashboard.md — Report diagnostico statico del Vault.
- Style Guide.md — Guida di stile per evidenziazioni HTML, Mermaid e LaTeX.
- Timeline: 2026-08-24 → 2026-08-29 (5 giorni di sviluppo attivo)
- Phases: 8 / 8 Completate (16 piani eseguiti al 100%)
- Commits: 42 commit
- Files changed: 840 file (+103034 / -147)
- Automated Tests: 101 unit/integration tests (100% green pass rate)
- Contributors: Loacky lorenzoadacher@gmail.com