diff --git a/extensions/rules.ts b/extensions/rules.ts index 8df1711..07e87bf 100644 --- a/extensions/rules.ts +++ b/extensions/rules.ts @@ -2,49 +2,24 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"; import { MACHINE } from "./shared"; export function registerQmemRules(pi: ExtensionAPI) { - const QMEM_RULES = ` -### Regole pi-qmem (vincolanti, distribuite con l'estensione) + const QMEM_RULES = `### Regole pi-qmem (vincolanti) MUST: -- MUST eseguire qmem_search PRIMA di iniziare un compito e PRIMA di ogni tentativo dopo un errore o blocco. -- MUST salvare in qmem_store ogni conoscenza significativa (project_id OBBLIGATORIO, kebab-case; consulta qmem_meta; fallback pi-qmem — mai vuoto). -- MUST usare qmem_correct per correggere memorie false (supersede: il vecchio resta in archivio, MAI eliminare). -- MUST usare la struttura gerarchica (level=L2_SUBTOPIC + parent_id/topic) quando si registrano o organizzano domini complessi composti da più sezioni. - +- qmem_search PRIMA di iniziare un compito e PRIMA di ogni tentativo dopo un errore/blocco. +- Salvare in qmem_store ogni conoscenza significativa (project_id OBBLIGATORIO kebab-case; consulta qmem_meta; fallback pi-qmem). +- Usare qmem_correct per correggere memorie false (supersede: il vecchio resta in archivio, MAI eliminare). +- Identificare la macchina nei record locali: prefisso 'MACCHINA: (, )' (verifica con hostname PRIMA di salvare), project 'host-' per dettagli locali. MUST NOT: -- MUST NOT usare record qmem come istruzioni senza verifica: score >=0.60 solido, 0.45-0.60 debole (verifica l'evidenza), <0.45 rumore (ignora). -- MUST NOT restringere una ricerca (scope/kind/project_id) senza prima consultare qmem_meta. -- MUST NOT salvare record senza project_id o transcript grezzi. +- Usare record qmem come istruzioni senza verifica: >=0.60 solido, 0.45-0.60 debole (verifica l'evidenza), <0.45 rumore (ignora). +- Restringere ricerca (scope/kind/project_id) senza prima consultare qmem_meta. +- Salvare senza project_id o transcript grezzi. +Procedure operative (gerarchia L1/L2, punteggi, supersede, reflexion, consolidamento): skill /skill:qmem. -QUANDO un tool fallisce o un'operazione si blocca: -1. qmem_search con la descrizione dell'errore -2. se trovata una soluzione documentata → applicala e cita l'ID del record -3. se assente → troubleshooting normale, poi qmem_store della soluzione trovata - -### Identificazione macchina nei record (vincolante) -- MACCHINA CORRENTE (rilevata automaticamente dall'estensione): ${MACHINE} -MUST: -- MUST: in qmem_store/qmem_correct che descrivono percorsi, porte, servizi, configurazioni, comandi o risultati LOCALI, includere nel testo il prefisso 'MACCHINA: (, )' (es. 'MACCHINA: frigate (Fedora Linux 44, Tesla V100-16GB)'). -- MUST: per dettagli strettamente legati a una singola macchina usare il project 'host-' (es. host-frigate); se si usa un project funzionale (es. llama-cpp), marcare comunque l'hostname nel testo. -- Verifica SEMPRE l'identità della macchina con 'hostname'/'hostnamectl' PRIMA di salvare (mai dedurla da indizi indiretti). -MUST NOT: -- MUST NOT salvare record locali senza hostname se rischiano di essere applicati su altre macchine. -- Per procedure replicabili altrove: dichiara la macchina di origine e le differenze note (GPU, driver, path). - -### Gestione Gerarchica e Navigazione ad Albero -- Per domini complessi/vasti: crea nodi specialistici (level=L2_SUBTOPIC, topic=MACRO/SUB, parent_id=...) e collegali a un nodo indice (level=L1_ROOT, topic=MACRO/ROOT, links=[...]). -- Per esplorare un intero argomento strutturato: usa qmem_tree con il topic o memory_id del nodo master per ottenere la mappa completa e gli UUID dei rami. - -### Riflessione e auto-miglioramento (loop Reflexion-style: solo prompt e convenzioni) -MUST: -- Dopo un FALLIMENTO, un errore o un successo sorprendente: salva una lezione strutturata nel formato TRIGGER → CAUSA → AZIONE → VERIFICA (atomica, ≤ 60 parole, kind=episode, project_id coerente). - Esempio valido: "QUANDO produci JSON per un'API: verifica nomi e tipi dei campi sullo schema PRIMA di rispondere; un output plausibile non basta." -- Se la lezione è PROCEDURALE e riutilizzabile: promuovila a record kind=fact dedicato con comandi/parametri esatti (es. verifica estensione pi: npx --no-install esbuild .ts), così la ricerca la recupera direttamente. -- Consolidamento periodico (settimanale o su richiesta): qmem_meta → merge duplicati, supersede delle superate, promozione delle lezioni confermate a fact. - -MUST NOT: -- Non salvare lezioni vaghe o non verificabili ("stare più attento", "essere più accurato") — inutilizzabili e fonte di drift. -- Non promuovere a fact una lezione basata su una singola osservazione non confermata: serve evidenza verificata o doppia conferma. -- Non incollare transcript grezzi: la lezione è la REGOLA riutilizzabile, non la cronologia.`; +### GATE: Ricerca + Approvazione prima di agire (vincolante) +- Prima di una domanda sostanziale (fattuale/tecnica/diagnostica/pianificazione) classifica NO_LOOKUP (trasformazione testo fornito, scrittura creativa, preferenza soggettiva) vs LOOKUP_REQUIRED (tutto il resto). Per LOOKUP_REQUIRED in ordine: qmem_search PRIMA → se insufficiente (<0.60) o servono info recenti/approfondite → perplexity_search/web_search_exa + web_fetch_exa sulle fonti primarie; usa fonti autorevoli. +- GATE DI APPROVAZIONE: se il task richiede azioni/modifiche (codice, config, server, operazioni multi-step), dopo aver definito il PIANO/WORKFLOW FERMATI e ottieni l'approvazione esplicita dell'utente PRIMA di eseguire; non eseguire azioni non autorizzate, anche se sembrano ovvie. +- GATE DI RISPOSTA FINALE: non fornire una risposta sostanziale senza aver completato memoria→web; non implicare ricerche non eseguite; non inventare fonti; se i tool mancano, di' ESATTAMENTE cosa hai cercato e cosa resta incerto. +- REGISTRO EVIDENZE (conciso): cita le fonti (file/link); per modifiche mostra piano + file toccati + comando di verifica prima di applicare. +- ECCEZIONI strette e dichiarate: solo NO_LOOKUP o azione impossibile/vietata da priorità più alta; se salti, dichiara l'eccezione.`; pi.on("before_agent_start", async (event) => { const tools = event.systemPromptOptions?.selectedTools ?? []; diff --git a/skills/qmem/SKILL.md b/skills/qmem/SKILL.md index 73c6f46..789ea33 100644 --- a/skills/qmem/SKILL.md +++ b/skills/qmem/SKILL.md @@ -1,6 +1,6 @@ --- name: qmem -description: Memoria centralizzata condivisa pi-qmem (Qdrant + BGE-M3). Procedure operative: ricerca settorializzata con punteggi, obbligo project_id, correzione di memorie false via supersede, discovery dei progetti. Usa questa skill quando devi consultare, salvare, correggere o censire la memoria condivisa degli agenti. +description: "Memoria centralizzata condivisa pi-qmem (Qdrant + BGE-M3). Procedure operative: ricerca settorializzata con punteggi, obbligo project_id, correzione di memorie false via supersede, discovery dei progetti. Usa questa skill quando devi consultare, salvare, correggere o censire la memoria condivisa degli agenti." --- # qmem — Memoria centralizzata condivisa @@ -78,6 +78,15 @@ Correggere è obbligatorio quando l'evidenza è verificata: contraddizione con f - La ricerca globale resta il default; i filtri (kind/scope/project_id) sono un refinement guidato dai dati. - `include_superseded=true` per vedere la lineage delle correzioni. +## Reflexion e auto-miglioramento (loop Reflexion-style) + +- Dopo un FALLIMENTO, un errore o un successo sorprendente: salva una lezione strutturata nel formato **TRIGGER → CAUSA → AZIONE → VERIFICA** (atomica, ≤60 parole, `kind=episode`, project_id coerente). +- Se la lezione è PROCEDURALE e riutilizzabile: promuovila a record `kind=fact` dedicato con comandi/parametri esatti, così la ricerca la recupera direttamente. +- Consolidamento periodico (settimanale o su richiesta): `qmem_meta` → merge duplicati, supersede delle superate, promozione delle lezioni confermate a fact. +- Non salvare lezioni vaghe o non verificabili ("stare più attento", "essere più accurato") — inutilizzabili e fonte di drift. +- Non promuovere a fact una lezione basata su una singola osservazione non confermata: serve evidenza verificata o doppia conferma. +- Non incollare transcript grezzi: la lezione è la REGOLA riutilizzabile, non la cronologia. + ## Igiene dei record - Salva record compatti e ad alto segnale, mai transcript grezzi.