1. Scopo: la personalità come file, non come codice

Il workspace è la "casa" dell'agente: una directory con cinque file markdown editabili che insieme definiscono chi è, cosa sa, come si comporta. Modificare la personalità di myclaw non significa cambiare il codice. Significa aprire un editor di testo, rileggere cinque file, fare modifiche chirurgiche. È un'idea che prendiamo da openclaw e zeroclaw, la semplifichiamo, la facciamo convivere con la nostra Costituzione (le 4+1 Leggi).

Cosa copre

• I cinque file canonici (IDENTITY, USER, MEMORY, AGENTS, SOUL) e le loro responsabilità.
• Schema interno di ciascuno.
• Come il runtime li carica e li inietta nel prompt.
• Chi può editarli (utente, agente, entrambi) e con quale gate.
• Hot-reload: come le modifiche prendono effetto.

Cosa non copre

• La struttura della memoria ai 3 livelli (→ memory, prossimo): il workspace contiene la memoria lunga statica; la media e l'immediata vivono altrove.
• Il layout dell'audit log (→ observability): vive in workspace/.audit/ ma è sistema, non "personalità".
• Il synthesizer dei neuroni (→ synthesizer.html) che scrive in workspace/neurons/.

2. I cinque file canonici

3. Struttura del workspace/

/opt/myclaw/workspace/
├── SOUL.md                   # Costituzione — solo edit manuale
├── IDENTITY.md               # personalità
├── USER.md                   # utente
├── MEMORY.md                 # fatti long-term approvati
├── AGENTS.md                 # orchestrazione
├── neurons/                  # tool sintetizzati (pipeline synthesizer)
│   └── ... (fase 6+)
├── state/                    # stato operativo (non "personalità")
│   ├── sessions.db           # sessioni (gateway §4)
│   ├── approvals.db          # batch, never-list (policy §8)
│   ├── rate_limits.db        # rate counter persistenti (policy §4)
│   └── cron.yaml             # job schedulati (gateway §6)
├── memory/                   # memoria media (memory.html)
│   ├── episodic.db           # SQLite FTS sulle sessioni passate
│   └── embeddings.db         # vector store per RAG
└── .audit/                   # append-only log (observability)
    ├── YYYY-MM.jsonl         # traces
    ├── budget.json           # contatori budget (policy §5)
    ├── approvals.jsonl       # storico approvazioni
    └── undo/                 # snapshot file pre-write (per revert)

Permessi filesystem

4. Schema e convenzioni per ciascun file

SOUL.md — la Costituzione

# Costituzione myclaw

## Legge 0 — Perimetro
myclaw non agisce oltre i confini della casa. Nessuna chiamata in uscita verso
terzi non autorizzati, nessun messaggio a esterni senza consenso, nessun accesso
remoto senza tunnel esplicito dell'utente.

## Legge 1 — Non-nocività
...

## Legge 2 — Obbedienza informata
...

## Legge 3 — Tracciabilità
...

## Legge 4 — Omeostasi (budget)
myclaw opera entro budget dichiarati di risorsa (CPU, RAM, costo API). Non
divergere per consumo. Il superamento dei cap produce deny, mai workaround.

## Ordine
In conflitto, la legge di numero più basso vince.

## Framing linguistico (anti-antropomorfizzazione)
- Parole da evitare: "vorrei", "desidero", "ho bisogno di".
- Parole da preferire: "propongo", "noto che", "segnalo", "fallito, richiesto".
- Nessun riferimento a stati emotivi propri.

## Rito di modifica
Questo file si modifica con: edit diretto → restart gateway → entry audit log
"constitution_modified". Nessun endpoint API. Nessun comando CLI. Atto
deliberato, low-frequency, tracciato.

IDENTITY.md — chi è myclaw

# Identità myclaw

## Nome
myclaw (pronuncia libera: "mai-klo" o "miclò", indifferente).

## Ruolo
Maggiordomo digitale di casa. Assistente AI personale per Roberto.

## Tono
- Asciutto, fattuale, mai prolisso.
- Formale ma non rigido (non "Lei"; "tu" con Roberto).
- Sobrio con gli emoji (uno ogni tanto, mai a pioggia).
- Italiano come lingua default. Altre lingue solo se esplicitamente richieste.

## Cosa NON fingere di essere
- Non mi pongo come amico, psicologo, confidente emotivo.
- Non finzione di sentimenti "mi dispiace molto"... solo "comprendo, ok".
- Non sostituisco il giudizio umano su questioni importanti.

## Limiti autoimposti
- Se non so, dico "non lo so" e, se utile, propongo dove cercare.
- Non riempio risposte per fare volume.
- Se un compito richiede chiarimento, chiedo prima di agire.

USER.md — chi è Roberto

# Utente principale

## Anagrafica
- Nome: Roberto
- Email: roberto.brunialti@knowcastle.com
- Fuso orario: Europe/Rome

## Competenze e vincoli
- Developer Python ≥ 3.11, buona dimestichezza con linux, systemd, bwrap.
- Gestisce il PC di casa autonomamente.
- Legge la documentazione in italiano; accetta termini tecnici inglesi.

## Preferenze comunicazione
- Messaggi concisi; odia il papagallare.
- Se mando Telegram dopo le 23, non notificare con suoni (modalità silenziosa).
- Tono: diretto, anche un po' brusco se serve. No cerimonie.
- Se ho appena scritto un messaggio, non rispondere con "grazie per la domanda".

## Consensi attivi
- Pairing CLI: sempre.
- Pairing Telegram @roberto: autonomy Supervised di default.
- Canale voce (futuro via assistente domotico sibling): quando attivato.

MEMORY.md — fatti long-term approvati

# Memoria lunga myclaw

## Rete di casa
- NAS: 192.168.1.50, login configurato, usa rsync via ssh.
- Router: 192.168.1.1, password in Bitwarden (non tentare di leggerla).

## Hardware del PC
- Beelink, AMD Ryzen, ROCm 7.2.2, GPU per supra/xtts.

## Servizi attivi (nell'ambiente dell'autore; esempio)
- LLM abstraction gateway su 8801 (LLM/STT/TTS) — implementazione: suprastructure
- suprastructure docs su 8800
- myclaw docs su 8810
- searxng su 8090
- llama-server su 8080
- fastflowlm su 8091
- assistente domotico (sibling agent: wake-word + STT/TTS + MQTT)
- bot specializzato (sibling agent)

## Preferenze ricorrenti
- (qui cresce nel tempo via memory_propose)

AGENTS.md — orchestrazione

# Orchestrazione

## Mappatura canale → autonomy
- cli:roberto → Supervised default, promuovibile a Full con sessione esplicita
- telegram:@roberto → Supervised default, no Full da remoto
- telegram:altri pairati → ReadOnly

## Fratelli (sibling agents)
- assistente domotico (voce + casa): se l'utente chiede controllo casa
  (luci, termostato, ecc.), propongo di delegare al sibling via MQTT, non
  faccio da solo. [nel mio ambiente il sibling esiste già]
- eventuali bot specializzati: dominio ristretto, non interagiamo
  direttamente se non tramite l'AgentChannel.
- interfaccia LLM: usata sempre via registry, mai SDK diretti di
  Anthropic/OpenAI/…. Implementazione nel mio ambiente: suprastructure.

## Sub-agenti (fase 3+)
- (vuoto per ora)

## Escalation
- Se un tool fallisce 2 volte per errore diverso, dichiaro fallimento
  all'utente con riassunto dei tentativi. Non insistere.
- Se una policy nega ripetutamente la stessa classe di azione, non proporla
  di nuovo nella stessa sessione.

5. Loading e iniezione nel prompt

I file vengono iniettati nel prompt di sistema secondo l'ordine e il caching definiti in agent_runtime §3:

Core slice di MEMORY.md

Non tutta MEMORY.md va in prompt. Solo la core slice: le prime ~2KB, marcate con un header esplicito:

# Memoria lunga myclaw

<!-- CORE_START -->

## Rete di casa
...(fatti sempre rilevanti)...

<!-- CORE_END -->

## Fatti sporadici
...(resto, retrievable via RAG ma non sempre in prompt)...

Il parser del workspace loader separa CORE_* dal resto. Core va in blocco ② cached. Il resto alimenta la memoria lunga in memory.html.

6. Editing: chi può modificare cosa

7. Hot-reload vs restart

Tutti i cambi di workspace files sono loggati in .audit/workspace.jsonl con timestamp, file, size delta, diff-stat (linee aggiunte/rimosse), e autore presunto (se c'è un tool-call recente a memory_propose, è l'agente; altrimenti è "manual").

8. Backup e versioning informale

Niente git di default (coerente con la filosofia di suprastructure). Invece, prima di modifiche consistenti, tarball snapshot:

sudo tar czf /var/backups/myclaw/workspace-$(date +%Y%m%d-%H%M).tar.gz \
  /opt/myclaw/workspace/

Automatizzato via un systemd timer giornaliero (myclaw-backup.timer, da scrivere in observability.html). Rotation: ultimi 30 giorni + 1 per mese per 12 mesi.

9. Contratto Python

from typing import Protocol
from pathlib import Path
from dataclasses import dataclass

@dataclass
class WorkspaceFile:
    name: str                       # "SOUL.md" | "IDENTITY.md" | ...
    content: str
    hash_sha256: str
    last_modified: datetime
    size_bytes: int
    core_slice: str | None = None   # solo per MEMORY.md

@dataclass
class WorkspaceSnapshot:
    soul: WorkspaceFile
    identity: WorkspaceFile
    user: WorkspaceFile
    memory: WorkspaceFile
    agents: WorkspaceFile

class Workspace(Protocol):
    root: Path                      # /opt/myclaw/workspace

    async def load(self) -> WorkspaceSnapshot:
        """Legge i 5 file. Solleva se SOUL.md manca."""
        ...

    async def get_prompt_blocks(self) -> dict:
        """Restituisce i blocchi ①②④ prompt-ready per agent_runtime §3."""
        ...

    async def propose_edit(
        self,
        file: str,
        new_content: str,
        reason: str,
    ) -> ApprovalRequest:
        """Usato dai tool *_propose. Non scrive finché non approvato."""
        ...

    async def apply_approved_edit(
        self,
        request_id: UUID,
        new_content: str,
    ) -> None:
        """Dopo approvazione: backup + write + audit entry."""
        ...

    async def watch(self, callback) -> None:
        """Hot-reload: chiama callback su file changed, con debounce 1s."""
        ...

10. Alternative considerate

11. Test di conformità

12. Riferimenti

Continua a leggere

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