1. Scopo: dalla metafora alla struttura dati

Il doc di fondamenti Neuroni+Memoria ha introdotto i tre livelli (immediata, media, lunga) come metafora. Qui li traduciamo in strutture dati concrete: RAM vs SQLite vs markdown+embeddings. Applichiamo il vocabolario CoALA (working / episodic / semantic) per connetterci alla letteratura.

Cosa copre

• Mapping dei tre livelli ai CoALA types.
• Storage e ciclo di vita di ciascun livello.
• Il meccanismo di reflection (promozione).
• Retrieval strategy per il prompt LLM.

Cosa non copre

• I file markdown statici del workspace (→ workspace). Quelli sono il contenuto della core memory; qui gestiamo il flusso.
• La procedural memory (neuroni → neuron.html): stessa famiglia ma doc dedicato.

2. Vocabolario CoALA: cosa chiamiamo come

3. Working memory (immediata)

Vive dentro la ExecutionTrace del turno corrente (agent_runtime §5). Contiene: tutto il loop ReAct — Thought, ActionStep, risultati intermedi, planning inline.

Non c'è un WorkingMemory store separato: è letteralmente l'ExecutionTrace. Questa unificazione è il punto forte architetturale (vedi agent_runtime §5: "una sola fonte di verità").

4. Episodic memory (media)

Contiene le sessioni passate recenti: l'agente "ricorda" che ieri Roberto ha chiesto di scaricare il rapporto di marzo. È la memoria conversazionale.

Storage: SQLite con FTS5

-- workspace/memory/episodic.db

CREATE TABLE episodes (
    episode_id   TEXT PRIMARY KEY,
    trace_id     TEXT NOT NULL,
    session_id   TEXT NOT NULL,
    sender       TEXT NOT NULL,
    started_at   DATETIME NOT NULL,
    user_message TEXT NOT NULL,
    final_response TEXT,
    outcome      TEXT NOT NULL,
    summary      TEXT,             -- riassunto sintetico (100-300 token)
    importance   REAL DEFAULT 0.5  -- per reflection
);

CREATE VIRTUAL TABLE episodes_fts USING fts5(
    user_message, final_response, summary,
    content='episodes', content_rowid='rowid'
);

CREATE INDEX idx_episodes_sender_time ON episodes(sender, started_at DESC);

Ciclo di vita

1. Nascita: ogni ExecutionTrace chiusa con outcome success viene indicizzata come episode. I fallimenti non necessariamente (configurabile: default sì).
2. Summarization: se il turno ha > 20 step, si riassume (tier local-fast, purpose compress) in un summary di 100-300 token.
3. Scoring importance: formula ispirata a Generative Agents (Park 2023):
   importance = 0.3·novelty + 0.3·user_engagement + 0.4·outcome_quality
   Valori normalizzati [0,1]. Usato per reflection (§6).
4. Retention: episodes con importance < 0.3 e più vecchi di 60 giorni vengono archiviati (spostati in .audit/, non eliminati, ma fuori dall'index FTS).
5. Retrieval: su query, FTS match + filtro sender, ordinato per importance·recency.

Dimensione tipica attesa

Chiave di indicizzazione e binding

La memoria episodic è indicizzata per sender, non per session_id. Motivazione: una conversazione può spezzarsi in più sessioni (idle > 30 min, cambio di autonomy), ma l'identità dell'utente è la stessa. session_id vive nella riga come metadato utile al debug, non come chiave di retrieval. La regola canonica del binding è fissata in gateway §4, sotto "Binding con la memoria".

5. Semantic + Core memory (lunga)

Due sotto-parti con trattamento diverso:

Core memory (sempre in prompt)

• Contenuto: SOUL.md (Costituzione) + IDENTITY.md + USER.md + AGENTS.md + MEMORY.md core slice (≤ 2 KB).
• Caching: sempre nel blocco ② del prompt, cached (vedi workspace §5).
• Update: solo via rito costituzionale o *_propose + approvazione.

Semantic memory (retrievable, non pre-caricata)

La parte non-core di MEMORY.md + fatti promossi da episodic via reflection.

Storage: markdown + vector index

workspace/MEMORY.md              # fonte di verità human-readable
workspace/memory/embeddings.db   # SQLite con vettori

-- struttura
CREATE TABLE semantic_facts (
    fact_id      TEXT PRIMARY KEY,
    text         TEXT NOT NULL,
    embedding    BLOB NOT NULL,          -- 768 dim float32
    source       TEXT,                   -- "manual" | "reflection:trace_id"
    created_at   DATETIME NOT NULL,
    importance   REAL DEFAULT 0.5,
    access_count INTEGER DEFAULT 0,
    last_access  DATETIME
);

Gli embedding sono calcolati con supra_embed (vedi tool). Il rebuild dell'index si fa a ogni modifica di MEMORY.md (hot-reload) o quando reflection promuove nuovi fatti.

Criteri di promozione a core

Un fatto della semantic può essere proposto per la core slice se:

• È accessibile (retrieval) in almeno 5 sessioni diverse nel mese.
• L'utente non ha mai espresso disappunto su risposte basate su quel fatto.
• Roberto approva esplicitamente il suggerimento "questo fatto è sempre rilevante, promuoverlo a core?".

6. Reflection: promozione episodic → semantic

Reflection è il nome consolidato (da Generative Agents 2023) del meccanismo "distilla gli episodes ricorrenti in fatti stabili". È un job periodico non interattivo.

Quando scatta

• Cron notturno (alle 03:00 TZ locale) se count(episodes) - count(episodes_riflesse_già) > 20.
• Trigger manuale: myclaw memory reflect.
• Event-driven: dopo una sessione con importance > 0.8, reflection parziale su quel thread.

Pipeline

1. Select: episodes non ancora considerate con importance > 0.5, clusterizzate per similarity di embedding (threshold 0.75).
2. Summarize per cluster (tier frontier, purpose summarize-rich): "questi 5 episodes parlano della stessa cosa. Qual è il fatto sottostante?"
3. Propose fact: il summary diventa un FactProposal.
4. Approval: Roberto riceve un digest notturno con i facts proposti. Approvazione batched ("approva tutti" / "approva questi" / "scarta tutti").
5. Insert: fatti approvati vengono appesi a MEMORY.md (sezione "Aggiunti da reflection YYYY-MM-DD") + indicizzati.
6. Mark episodes: gli episodes sorgente vengono marcati come reflected=true (non rientrano in reflection futura).

7. Retrieval: come si pesca dalla memoria

Per ogni turno, al momento di costruire il prompt (agent_runtime §3), il runtime interroga la memory per:

1. Working: già in mano (la trace corrente).
2. Episodic: ultime N sessioni dello stesso sender + top-K rilevanti per FTS match con il messaggio utente corrente. N=5, K=3.
3. Semantic: top-M fatti per similarity di embedding con il messaggio corrente. M=5, threshold 0.7. Budget: max 2 KB totale in prompt.
4. Core: sempre inclusa per intero (già cached).

Formula di scoring (ispirata a Generative Agents + ACT-R)

score(fact, query) =
    w1 · cosine_similarity(emb(fact), emb(query))     # relevance
  + w2 · exp(-decay · days_since_last_access)         # recency
  + w3 · importance(fact)                              # salience
  + w4 · log(1 + access_count)                         # usage reinforcement

# Default weights (tunable)
w1 = 0.50  # relevance domina
w2 = 0.20
w3 = 0.20
w4 = 0.10

8. Iniezione nel prompt

9. Contratto Python

from typing import Protocol, Literal
from dataclasses import dataclass

@dataclass
class Episode:
    episode_id: str
    trace_id: UUID
    session_id: str
    sender: str
    started_at: datetime
    user_message: str
    final_response: str | None
    outcome: str
    summary: str | None
    importance: float

@dataclass
class SemanticFact:
    fact_id: str
    text: str
    source: Literal["manual", "reflection"]
    created_at: datetime
    importance: float
    access_count: int

@dataclass
class MemoryBundle:
    """Tutto ciò che serve al runtime per costruire i blocchi ②④⑤ del prompt.
    Invariante: core_text non è mai stringa vuota. Vedi ensure_core()."""
    core_text: str                    # sempre in prompt, mai vuoto
    semantic_retrieved: list[SemanticFact]
    episodic_recent: list[Episode]    # ultime N per sender
    episodic_relevant: list[Episode]  # top-K per query match

class WorkspaceMissingError(Exception):
    """Sollevato da Memory.ensure_core() se SOUL.md / IDENTITY.md mancano o
    il workspace è corrotto. Il runtime intercetta e rifiuta la sessione con
    un messaggio attuabile (vedi agent_runtime §4)."""

class Memory(Protocol):
    async def get_bundle_for_turn(
        self,
        sender: str,
        user_message: str,
        autonomy: str,
    ) -> MemoryBundle:
        """Richiede che ensure_core() abbia avuto successo all'avvio. Se
        chiamato con workspace inconsistente, solleva WorkspaceMissingError
        invece di ritornare un bundle degradato."""
        ...

    async def ensure_core(self) -> str:
        """
        Carica e valida la core memory (SOUL + IDENTITY + USER + AGENTS +
        MEMORY.md core slice). Chiamato una volta al boot del gateway.
        Policy di fallback:
          1. SOUL.md mancante → WorkspaceMissingError ("workspace non pareggiato").
          2. SOUL.md presente ma altri file opzionali mancanti → segnaposto
             minimo ("(nessuna identità utente configurata)") + log warning.
          3. Nessun silenzioso: il boot fallisce invece di partire senza core.
        Ritorna il testo finale usato come core_text.
        """
        ...

    async def index_episode(self, trace: ExecutionTrace) -> Episode:
        """Al termine di una trace, indicizza come episode."""
        ...

    async def reflect(
        self,
        since: datetime | None = None,
    ) -> list["FactProposal"]:
        """Esegue reflection: ritorna proposte da approvare."""
        ...

    async def apply_approved_facts(
        self,
        approved_ids: list[str],
    ) -> None:
        """Aggiunge fatti approvati a MEMORY.md + embeddings.db."""
        ...

    async def access(self, fact_id: str) -> None:
        """Incrementa access_count + last_access di un fatto (hebbian reinforce)."""
        ...

10. Alternative considerate

11. Test di conformità

12. Riferimenti

Continua a leggere

myclaw — memory microprogettazione v1.0 — 2026-04-22
Terzo doc di fase 2. Prossimo: observability.html.