1. Da bot a agente: il salto

Un LLM senza attuatori è un bot: parla bene ma non agisce. Quando aggiungi tool sandboxati diventa un agente: parla e agisce, ma solo con le azioni che il progettista gli ha pre-cablato. Il passo successivo — e l'obiettivo di questo documento — è renderlo capace di costruirsi nuovi attuatori quando quelli esistenti non bastano, entro i limiti di sicurezza.

La metafora: un LLM con tool fissi è come un cervello collegato a mani che possono fare solo certi gesti. Se il compito richiede di girare una chiave e le mani sanno solo premere pulsanti, l'agente fallisce. Un bravo agente, a quel punto, fabbrica la capacità di girare la chiave — nel nostro caso scrivendo un piccolo applet di codice — ma lo fa sotto vigilanza.

Chiamiamo questi applet neuroni perché hanno tre proprietà che tornano in testa leggendo la letteratura neuroscientifica:

1. Persistono: una volta approvati, sopravvivono alla sessione che li ha generati. Tornano al prossimo bisogno.
2. Si attivano: davanti a un input che li riguarda, si "accendono" e producono un'azione.
3. Formano reti: si invocano tra loro; l'uso frequente di due neuroni in coppia li lega (una sinapsi si rafforza).

2. Cos'è un neurone

Un neurone è la materializzazione di una capacità che myclaw non aveva, sintetizzata al bisogno, approvata dall'utente, e poi riusabile.

3. Il ciclo di sintesi di un neurone

Un neurone non nasce spontaneamente. Nasce da un fallimento esplicito: l'agente ha provato tutti i tool conosciuti, nessuno ha prodotto il risultato richiesto, e l'utente non ha dato il permesso di abbandonare il compito.

4. La legge darwiniana: selezione per riduzione del gap

Un neurone non è un diritto acquisito. L'approvazione iniziale lo fa nascere, ma nella library ci resta solo se produce utilità. L'utilità ha una definizione precisa: riduzione del gap tra la capacità attuale di myclaw e la capacità necessaria a raggiungere lo scopo. Il resto è conseguenza: chi riduce il gap vive, chi non lo riduce muore, l'ambiente — cioè gli scopi che myclaw persegue — seleziona.

Definizione di Gap, utilità, fitness

Corollari

• Usato ≠ utile. Un neurone può essere invocato perché "sembra giusto" e non ridurre il gap. Conta l'effetto misurato, non la plausibilità apparente.
• Competizione. Due neuroni con fitness paragonabile competono per lo stesso scopo: vince quello più economico (tempo CPU, costo LLM, chiamate I/O).
• Fossili. Un neurone con fitness persistentemente negativa entra in quarantena dopo N strike, poi in estinzione. Il file resta per forensica, la firma viene revocata.

Due modalità di origine dello scopo

Lo scopo che misura la fitness può nascere da fuori (l'utente ha chiesto qualcosa) o da dentro (myclaw nota un gap ricorrente e vuole colmarlo). Sono qualitativamente diverse e richiedono gate diversi.

Come si misura il Gap, in pratica

L'arena di selezione

Il ciclo darwiniano, fase per fase

Caveat dalla letteratura

• La self-valutazione dell'LLM "ho ridotto il gap?" è ottimistica. Dove possibile, usare metriche oggettive (tempo, exit code, matching atteso), non "un LLM che giudica un LLM". Vedi Huang et al. (2023), "Large Language Models Cannot Self-Correct Reasoning Yet".
• Selezione vs esplorazione. Un neurone dormiente potrebbe essere utile per scopi rari. Il retriever non può potare tutto ciò che non ha fitness: usa un bandit (UCB-like) che riserva una quota di invocazioni esplorative.
• Memory poisoning. Se un attaccante gonfia artificialmente la fitness di un neurone malevolo, quello domina il retriever. Difesa: ogni evento di fitness è firmato dal caller, verificabile nell'audit log, e aggregato solo dopo una finestra di conferma.
• Esperienza vs dogmatismo. La fitness è esperienza sommata, non certezza. La decisione "invocare questo neurone" deve comunque passare dalla Policy: un neurone con fitness alta ma che tocca un forbidden path resta bloccato. Le Leggi vincono sui numeri.

5. Sinapsi: come dialogano i neuroni

Un neurone da solo è un tool in più. Un insieme di neuroni che si chiamano tra loro è una rete. La struttura di quella rete — chi chiama chi, con che frequenza, con quale successo — è l'equivalente di una memoria comportamentale del sistema.

Come si formano le sinapsi

1. Dichiarate: il manifest di un neurone elenca esplicitamente quali altri neuroni potrebbe chiamare. Vincolo massimo di chiamata.
2. Osservate: ogni co-attivazione (neurone A chiama B nella stessa trace) incrementa un counter. Le sinapsi reali emergono dall'uso, non dalla dichiarazione.
3. Decadimento: counter che non crescono per 30 giorni scalano linearmente. Le coppie di neuroni davvero usate insieme restano forti, le altre scompaiono.

Cosa NON possono fare, tra loro

• Un neurone non può chiamare un neurone non dichiarato nel proprio manifest. Il registry filtra.
• Un neurone non può creare altri neuroni. Solo il synthesizer dell'agente principale può. (Blocco anti-runaway.)
• Un neurone non può alzare le proprie capability runtime. Sono fissate alla firma.

6. La memoria a tre livelli

Servono tre orizzonti temporali, con tre scope diversi. La distinzione non è decorativa: ogni livello ha un criterio di iniezione nel prompt, un criterio di persistenza, un criterio di compressione.

Immediata (scratchpad)

Vive in RAM, nel solo processo dell'agente, per la durata della richiesta corrente. Contiene: i pensieri intermedi ("devo prima leggere il log"), gli output parziali dei tool, il piano ancora da eseguire. Quando l'azione termina, viene scartata o — se contiene qualcosa che vale — promossa alla memoria media via distillazione.

Media (funzionale)

Una tabella SQLite in workspace/memory/medium.db. Contiene la storia della conversazione corrente e dei compiti coesi recenti. Ha retention automatica: dopo N giorni o M messaggi, compressione (riassunto via LLM) e archiviazione. Le parti che durante la compressione risultano stabili e generali vengono proposte per la promozione a lunga.

Lunga (costituzionale)

I file markdown del workspace: SOUL.md (la Costituzione — le quattro leggi), IDENTITY.md, USER.md, la parte stabile di MEMORY.md. Questo blocco è sempre in testa al prompt di sistema, con prompt caching di Anthropic/OpenAI per non pagarlo a ogni chiamata. È anche l'unico livello che Roberto edita direttamente con un editor di testo.

7. Le Quattro Leggi di myclaw

La memoria lunga ha un nucleo non editabile neanche da Roberto senza un rito esplicito: la Costituzione. Sono le leggi di Asimov rimaneggiate per un maggiordomo domestico. Vivono in SOUL.md e sono il primo contenuto che ogni chiamata LLM vede.

Le leggi sono numerate e ordinate: in conflitto, la legge di numero più basso vince. Sono iniettate come blocco cachabile in ogni prompt, prima del resto della memoria lunga.

8. Quote, kill-switch, quarantena

9. Dove vivono i neuroni: impatto sui 4 strati

Rispetto all'architettura di partenza (intro §3), i neuroni non creano uno strato nuovo: abitano lo strato 4 (Workspace & Tool) e lo fanno con gli stessi vincoli dei tool nativi.

10. Anatomia di un neurone sul filesystem

workspace/neurons/
└── nas-ping/
    ├── manifest.yaml       # scopo, capability, quote, sinapsi dichiarate
    ├── neuron.py           # il corpo (Protocol Tool)
    ├── test_neuron.py      # il test di nascita
    ├── signature           # HMAC del corpo+manifest, intestata a myclaw root
    └── journal.jsonl       # counter di uso, ultimi esiti, errori

Esempio minimo di manifest.yaml:

name: nas-ping
version: 1.0
born: 2026-04-21T22:14:00Z
approved_by: roberto
scope: "verifica raggiungibilità del NAS di casa con ping ICMP + arp"
capabilities:
  - net.ping: { hosts: ["192.168.1.50"] }
  - shell.exec: { allowlist: ["/usr/bin/ping", "/usr/sbin/arp"], timeout_s: 5 }
quotas:
  cpu_s: 2
  ram_mb: 64
  io_writes: 0        # read-only neuron
synapses_declared:
  - tg-send           # può notificare via Telegram
  - log-parser        # può leggerne l'output
signature_algo: hmac-sha256

11. Cosa NON è un neurone

• Non è un plugin. Non ha installer né marketplace. Nasce dal bisogno dell'agente, qui in casa, per il caso d'uso di Roberto.
• Non è un sub-agente. Non ha un proprio loop di ragionamento, né una propria memoria. È un tool, con meta-dati in più.
• Non è un microservizio. Non gira come processo lungo, non ha porte, non espone API a nessuno tranne l'agente principale.
• Non è un sostituto della programmazione attenta. Se la capacità richiesta è prevedibile e stabile, conviene implementarla come tool nativo. I neuroni sono per le lacune emerse dall'uso, non per le funzionalità pianificate.
• Non è un meccanismo di learning in senso ML. Non aggiorna pesi né esegue fine-tuning. Evolve strutturalmente (nuovi nodi, nuove sinapsi), non parametricamente.

12. Roadmap aggiornata

I neuroni entrano in roadmap dopo la fase 4. Prima di saperli generare, myclaw deve saper eseguire tool con sicurezza.

Documenti di microprogettazione che questa estensione aggiunge

• neuron.html — struttura, manifest schema, firma
• synthesizer.html — pipeline di sintesi, gate, rifiuto
• synapse.html — grafo, counter, decadimento
• constitution.html — le 4 leggi, il rito di modifica
• memory.html (già previsto) — ora con 3 livelli espliciti

Li aggiungo subito all'indice microprogettazione.

Continua a leggere

myclaw — Neuroni, Sinapsi e Memoria v1.1 — 2026-04-21
Estende Architettura — Introduzione v1.