Brain System

Il Brain è il mio sistema di knowledge management personale. Nato dalla frustrazione con Notion e altri tool proprietari, è una soluzione completamente basata su Git, Markdown e AI processing.

Il Problema

Gestisco 10+ progetti contemporaneamente. Cliente A ha un bug urgente, cliente B vuole una feature, e mentre sono nel mezzo di questi due mi arriva un’email con una proposta per un nuovo progetto. Alle 2 di notte mi viene in mente la soluzione perfetta per quel refactoring che rimandavo da settimane.

Il cervello umano non è fatto per tenere traccia di tutto questo.

La Soluzione

Un sistema che:

• Cattura tutto: Email, note, idee, decisioni tecniche
• Organizza automaticamente: AI processing (Gemini) estrae entità e genera logs
• Resta accessibile: Plain text markdown, versionato con Git
• È ricercabile: Grep, ripgrep, Obsidian, qualsiasi tool
• È mio: I dati sono sul mio server, in formato aperto

I 10 Comandamenti

Principi fondamentali del Brain system (non negoziabili):

I. Devi Essere Portabile

Un git clone + setup minimo → sistema operativo. Zero dipendenze cloud critiche, funziona offline.

In pratica: Il brain è una cartella con file markdown e script Python. La cloni su un’altra macchina e funziona subito, niente database da installare o servizi cloud obbligatori.

ELI5: Come i Lego. Prendi la scatola, la porti dove vuoi, e funziona sempre. Non serve internet, non serve un computer speciale.

II. Devi Essere Interface-Agnostic

Brain non è legato a un’interfaccia. CLI, Telegram, email, API → tutte first-class. Claude, GPT, Gemini → tutti compatibili.

In pratica: Puoi usare il brain dal terminale, da Telegram mentre sei fuori, via email, o chiamando API. Funziona con Claude, GPT-4, Gemini - il brain è il dato, l’AI è intercambiabile.

ELI5: Come parlare italiano. Puoi parlare al telefono, per messaggio, di persona - cambia il modo ma la lingua è sempre quella.

III. Devi Essere Git-Native

Tutto versionabile. Database, log, docs → tutto su Git. History = audit trail completo.

In pratica: Ogni modifica tracciata con git commit. Sbagli qualcosa? git revert. Vuoi vedere cosa è cambiato 3 mesi fa? git log. Sync tra computer? git pull/push.

ELI5: Salvataggio automatico nei videogiochi. Ogni modifica salvata, puoi tornare indietro quando vuoi.

IV. Devi Essere Human-Readable

Plain text over binary. Un umano con vim deve capire tutto. Markdown per docs, JSON/YAML per config. Leggibile tra 50 anni.

In pratica: Normali file di testo. Apri con vim, VSCode, Notepad, Obsidian - funziona tutto. Zero software proprietario, zero corruzione file, zero vendor lock-in.

ELI5: Come scrivere con una penna normale invece che con inchiostro invisibile. Chiunque apre il file e capisce cosa c’è scritto.

V. Devi Essere Low-Tech

Tecnologia semplice e stabile. Python + markdown + git, nulla di più esotico. Se puoi farlo con grep, fallo con grep.

In pratica: Python standard, bash script, niente framework complicati. Preferisci grep a database quando basta. Tool che esistono da decenni e esisteranno per altri decenni.

ELI5: Martello invece di robot complicato. Funziona da 1000 anni, funzionerà per altri 1000.

VI. Devi Essere Coherent

Database coerente sempre. Niente duplicati, contraddizioni, broken links. Health checks automatici, fail fast se incoerenza critica.

In pratica: Script automatici controllano che non ci siano due file per la stessa persona, link rotti, date sbagliate. Se trova un casino, si blocca e avvisa prima che peggiori.

ELI5: Stanza ordinata. Ogni cosa al suo posto, niente doppioni, se qualcosa non torna suona l’allarme.

VII. Devi Essere Incremental

Cambiamenti graduali. Test prima, rollout poi, rollback se serve. Never break existing workflows.

In pratica: Nuovo agent? Lo testi a parte prima di metterlo in produzione. Feature nuova? La metti dietro flag, se rompe la disattivi. Migrazione? Un passo alla volta con backup.

ELI5: Salire le scale un gradino alla volta. Non saltare dieci gradini in un colpo, cadi.

VIII. Devi Essere Tested

Test behavior, not implementation. Pre-commit secret scan (BLOCKING), database health checks, LLM behavioral tests.

In pratica: Prima di ogni commit, lo scanner cerca password e token - se li trova, blocca tutto. Test automatici controllano che il database sia coerente, che gli agent facciano quello che devono.

ELI5: Assaggiare la pasta prima di servirla. Se è cruda, non la porti in tavola.

IX. Devi Essere Secure

Secrets fuori da Git, sempre. .env gitignored, encrypted backup, pre-commit scan. NEVER commit API tokens.

In pratica: API token, password, chiavi - tutto nel file .env che Git ignora. Pre-commit hook scansiona ogni commit e se trova anche solo l’odore di un token, si blocca e urla.

ELI5: Password scritta su un foglio nel cassetto, non attaccata in bacheca dove tutti la vedono.

X. Devi Essere Documented

Docs aggiornata = codice funzionante. Docs obsoleta = documentazione falsa. README sempre aggiornato.

In pratica: Aggiungi agent? Documenti come funziona. Cambi workflow? Aggiorni i docs. README che dice cose vecchie è peggio di niente, perché ti fa perdere tempo a capire perché non funziona.

ELI5: Istruzioni Ikea aggiornate. Se il mobile cambia e le istruzioni no, butti via tutto e bestemmie.

Architettura

brain/
├── boot/               # Configurazione AI personality
├── diary/              # Diari personali (vita privata, eventi)
├── log/                # Log tecnici/professionali (progetti, clienti)
├── database/           # Entità auto-generate (people, companies, projects)
├── tools/              # Script automazione (email import, processing)
└── todo/               # Task con reminder dates e priorità

Email Processing Pipeline

1. Import: Gmail API → scarica email mensili
2. Processing: Gemini AI analizza e categorizza
3. Generation: Crea log/diary + aggiorna database entities
4. Commit: Tutto versionato automaticamente

AI Integration

• Claude Code: Interfaccia conversazionale, accesso diretto al brain
• Gemini Flash: Email processing, entity extraction, summarization
• Personality System: Anacleto (AI assistant) con profili configurabili

Stack Tecnico

• Storage: Git repository (~500MB, 1000+ commits)
• Format: Markdown + YAML frontmatter
• Processing: Python scripts + AI APIs
• Automation: Cron jobs (hourly/daily checks)
• Interface: Claude Code CLI + Telegram bot
• Viewer: Obsidian-like Next.js app (basalt.giobi.com)

Workflow Quotidiano

Morning:

• Brain auto-process email della notte
• Log generati automaticamente
• Daily check-in via Telegram (Anacleto mi chiede cosa faccio oggi)

Durante il giorno:

• Note veloci via Telegram → salvate nel brain
• TODO creati al volo con reminder dates
• Claude Code per query/ricerche

Evening:

• Review log giornaliero
• Brain suggerisce task dimenticati
• Commit finale di giornata

Vantaggi vs Notion

✅ Plain text: Grep, sed, awk, qualsiasi tool Unix ✅ Versionato: Git history completa, branch per esperimenti ✅ Offline-first: Lavora senza internet ✅ Portabile: Clone repo = tutto il sistema ✅ Ricercabile: ripgrep è più veloce di qualsiasi DB ✅ Automabile: Bash scripts + cron = infinite possibilità ✅ Privacy: I miei dati sul mio server

Metriche

• Durata: 6+ mesi in produzione attiva
• Commit: 1000+ automatici + manuali
• Email processate: 500+ mensili
• Entities nel database: 100+ (people, companies, projects)
• Daily logs: 180+ (uno per giorno lavorativo)
• TODO completati: 200+

Use Cases Reali

Gestione Clienti

Quando cliente X mi contatta, cerco nel brain:

rg "cliente-x" database/companies/

Vedo immediatamente:

• Progetti passati
• Email history
• Issue risolti
• Preventivi
• Note tecniche

Debugging Storico

“Come avevo risolto quel problema SSH 6 mesi fa?”

rg "ssh.*bug" log/2024/

Trovo il log con soluzione, comandi usati, link documentation.

Decision Log

Ogni decisione tecnica importante va nel log:

• Perché Laravel invece di Django?
• Perché SQLite invece di PostgreSQL?
• Perché questo pattern invece di quello?

Quando rivedo progetto, so perché ho fatto certe scelte.

Progetti Correlati

• Circus Bot: Telegram bot per interagire col brain in mobilità
• Basalt Viewer: Next.js app per navigare brain come Obsidian
• Email Import Tools: Python scripts per Gmail API automation

Limiti & Trade-offs

❌ Curva apprendimento: Serve confidenza con Git, Markdown, CLI ❌ Setup iniziale: Non è “apri app e usa” ❌ Collaborazione: Pensato per uso singolo, non team ❌ UI: Niente GUI fancy, tutto text-based

Ma per me, i vantaggi superano largamente i limiti.

Future Improvements

• Web interface migliorata (basalt.giobi.com)
• Search semantico con embeddings
• Auto-categorization più smart
• Integration con calendar per timeline view
• Export verso altri formati (PDF, HTML static site)

Filosofia

“Notion è bello ma voglio i miei dati in plain text”

Il Brain non è per tutti. Ma se:

• Ami il terminale
• Vuoi possedere i tuoi dati
• Credi in Unix philosophy
• Apprezzi plain text su binary formats
• Vuoi automazione infinita

Allora questo sistema fa per te.

Status: Active development Last update: 2025-11-06 Maintainer: Giobi + Anacleto (AI assistant)