1. Scopo e confini

Una volta nati, i neuroni vivono in un grafo emergente: i nodi sono i neuroni, gli archi sono le co-attivazioni reali. Questo documento definisce come il grafo viene costruito, aggiornato, letto, e come alimenta la legge darwiniana (fitness) che regola chi resta e chi viene potato.

Cosa copre

• Struttura dati del grafo (nodi, archi, counter).
• Formula di fitness e aggiornamento incrementale.
• Peso della sinapsi e decadimento temporale.
• Algoritmo di retrieval darwiniano (selezione + esplorazione).
• Job di potatura: dormienza, quarantena, estinzione.

Cosa non copre

• Struttura fisica del singolo neurone → neuron.html.
• Come nasce un neurone → synthesizer.html.
• Memoria episodica/semantica delle sessioni → memory.html (vocabolario diverso, non confondere).

2. Il grafo: nodi e archi

Il grafo è costruito per aggregazione dai journal.sqlite di ogni neurone (vedi neuron §6) e materializzato in un DB SQLite centrale workspace/neurons/_graph.sqlite aggiornato da un job periodico.

-- workspace/neurons/_graph.sqlite

CREATE TABLE nodes (
    name             TEXT PRIMARY KEY,
    version          TEXT NOT NULL,
    state            TEXT NOT NULL,        -- neonato|attivo|dormiente|quarantena|estinto
    fitness          REAL DEFAULT 0.0,     -- aggregato; vedi §3
    invocations      INTEGER DEFAULT 0,
    last_invoked_at  DATETIME,
    last_success_at  DATETIME,
    strikes          INTEGER DEFAULT 0,    -- error streak recente
    updated_at       DATETIME NOT NULL
);

CREATE TABLE edges (
    src              TEXT NOT NULL,
    dst              TEXT NOT NULL,
    declared         BOOLEAN NOT NULL,     -- da manifest.may_call
    co_activations   INTEGER DEFAULT 0,    -- observed
    last_co_at       DATETIME,
    weight           REAL DEFAULT 0.0,     -- vedi §4
    PRIMARY KEY (src, dst)
);

CREATE INDEX idx_edges_src ON edges(src);
CREATE INDEX idx_edges_weight ON edges(weight DESC);

Un arco può essere:

• Solo dichiarato (declared=1, co_activations=0): permesso ma mai usato. Candidato a "sinapsi promessa ma vana".
• Solo osservato: una chiamata osservata fuori dal may_call → errore, viene loggata ma non genera arco (il loader di neuron solleva UndeclaredSynapseError).
• Dichiarato e osservato: il caso normale. Il peso cresce con l'uso.

3. Fitness di un neurone

La fitness misura riduzione del gap nel tempo. Non "quante volte è stato invocato" ma "quanto ha avvicinato myclaw al suo scopo". È la quantità che decide visibilità nel retriever e, sotto soglia, potatura.

Utilità di una singola invocazione

Il Gap viene calcolato dal caller (reasoning loop) secondo la metrica associata al tipo di task:

Aggregazione nel tempo

fitness(n) = sum over invocations i of:
    u(i) * decay_factor(age_days(i))
  + exploration_bonus(n)

decay_factor(d) = exp(-d / TAU)        # TAU = 30 giorni (Ebbinghaus-like)

exploration_bonus(n) =
    B0 if state == "neonato" else 0    # B0 = 0.5, decade a 0 appena attivo

Le invocazioni con u=null non contribuiscono alla fitness ma contano nel contatore invocations (per far uscire i neuroni dalla fase "sconosciuto").

4. Peso di una sinapsi

Il peso di un arco (src, dst) cresce con la co-attivazione e decade con il silenzio:

weight(src, dst) =
    log(1 + co_activations)         # saturazione sublineare: evita dominanza
  * decay_factor(days_since_last_co)
  * success_ratio(src -> dst)       # frazione di co-attivazioni in trace con outcome=success

• Il decay usa lo stesso TAU della fitness.
• Il success_ratio penalizza coppie di neuroni che si invocano ma falliscono insieme.
• Peso sotto 0.05 per 60 giorni → l'arco è candidato alla potatura.

5. Decadimento: Ebbinghaus + ACT-R

La scelta del doppio riferimento (Ebbinghaus per la forma, ACT-R per il rinforzo via access-count) è intenzionale:

• Ebbinghaus: curva di oblio pura, validata in psicologia cognitiva. Usata per il decay.
• ACT-R (Anderson): activation = baseline + log(uses). Usata per il rinforzo proporzionale all'uso.
• MemoryBank (Zhong 2023): ha già integrato le due idee per la memoria semantica, ne imitiamo la forma.

6. Retriever: dal grafo al candidato

Dato uno scopo g corrente, il retriever ritorna un piccolo insieme di neuroni candidati ordinati. È il punto in cui il grafo parla al reasoning loop.

Algoritmo (pseudocodice)

def retrieve(goal, top_k=5):
    # 1. Candidati per similarità semantica
    cands = vector_search(embed(goal), table="nodes_purpose", top=20)

    # 2. Filtri duri
    cands = [n for n in cands
             if n.state in {"neonato", "attivo"}
             and policy.allows(n, current_ctx)]

    # 3. Scoring
    scored = []
    for n in cands:
        s = w1 * similarity(n, goal)          # relevance
          + w2 * normalize(n.fitness)         # fitness
          + w3 * neighborhood_bonus(n, goal)  # amici attivi
        scored.append((s, n))

    # 4. Bandit: quota esplorativa
    if random() < EPSILON:
        pick = ucb_choice(cands, exclude=best(scored))
        return [pick] + sorted(scored, reverse=True)[:top_k-1]
    else:
        return sorted(scored, reverse=True)[:top_k]

Default dei pesi

7. Potatura e quarantena

Job notturno (default 03:30)

1. Aggrega: unisce i journal.sqlite dei neuroni in _graph.sqlite.
2. Ricalcola fitness e weight per tutti i nodi/archi.
3. Transizioni di stato:
   • neonato → attivo: 7 giorni o 20 invocazioni, scegliendo il minore.
   • attivo → dormiente: 90 giorni di silenzio.
   • qualsiasi → quarantena: firma invalida o 3 strike consecutivi o policy ha ritirato una capability.
   • quarantena → estinto: 30 giorni senza riabilitazione manuale.
4. Potatura archi: archi con weight < 0.05 da > 60 gg vengono rimossi da edges.
5. Digest per Roberto: riassunto di transizioni non banali (estinzioni, promozioni, cambi forti di fitness), approvazione non richiesta ma visibile.

8. Contratto Python

from typing import Protocol
from dataclasses import dataclass
from datetime import datetime

@dataclass
class GraphNode:
    name: str
    state: str
    fitness: float
    invocations: int
    last_invoked_at: datetime | None
    strikes: int

@dataclass
class GraphEdge:
    src: str
    dst: str
    declared: bool
    co_activations: int
    weight: float
    last_co_at: datetime | None

@dataclass
class RetrievalResult:
    candidates: list[GraphNode]
    picked_by: Literal["score", "exploration"]

class SynapseGraph(Protocol):
    async def rebuild(self) -> None:
        """Job notturno: riaggrega journal, ricalcola fitness e weight,
        applica transizioni di stato, potatura archi."""
        ...

    async def observe_invocation(
        self,
        neuron: str,
        trace_id: str,
        gap_pre: float | None,
        gap_post: float | None,
        outcome: str,
    ) -> None:
        """Hot-path: registra un'invocazione, aggiorna strikes e last_invoked_at.
        Il ricalcolo pieno avviene nel job notturno."""
        ...

    async def observe_co_activation(
        self, src: str, dst: str, trace_id: str, success: bool,
    ) -> None: ...

    async def retrieve(
        self, goal_text: str, context: dict, top_k: int = 5,
    ) -> RetrievalResult: ...

    async def transition(self, name: str, new_state: str, reason: str) -> None: ...

# Errori
class NeuronNotInGraphError(Exception): ...
class PolicyRetrievalVetoError(Exception): ...

9. Implementazione di default

10. Alternative considerate

11. Test di conformità

12. Riferimenti

Continua a leggere

myclaw — synapse microprogettazione v1.0 — 2026-04-22
Terzo doc dell'estensione neuroni. Prossimo: constitution.html.