Scrivere memorie

Una memoria è una breve nota in Markdown che il tuo team mette per iscritto perché l'assistente possa leggerla in seguito. Le memorie risiedono in un percorso del workspace ed emergono solo quando l'assistente lavora sotto quel percorso. Sono il tipo di contenuto più comune in Pathrule e il più semplice da cui partire.

Questa pagina spiega quando scrivere una memoria, come strutturarla e come funzionano ambito e versioni.

Quando scrivere una memoria

Ricorri a una memoria quando hai un'informazione che non risulta evidente dal codice e che probabilmente tornerà utile.

• Decisioni. "In questo repository usiamo Postgres su Supabase per tutto. Non introdurre un ORM. Usa direttamente il client supabase-js."
• Insidie. "Se modifichi l'enum orders.status devi eseguire la migrazione dei dati prima della migrazione dello schema. L'ordine è invertito rispetto al resto dello schema."
• Postmortem. "Il 2026-04-12 abbiamo rilasciato un gestore di webhook che addebitava due volte i clienti perché non controllavamo la chiave di idempotenza di Stripe. Ora va passata sempre."
• Convenzioni. "I test stanno accanto al file che testano, non in una directory parallela __tests__."
• Conoscenza tacita. "Solo una persona ricorda perché esiste questo flag. È ancora necessario a causa di un comportamento anomalo a runtime nel progetto upstream."

Evita le memorie per ciò che il codice dice già chiaramente, per ciò che cambia ogni settimana o per ciò che è puramente una preferenza personale.

Struttura

Ogni memoria ha un titolo e un corpo in Markdown. Mantieni entrambi brevi.

• Titolo: breve, assertivo, deve entrare in una barra laterale. "Solo Postgres. Niente ORM." è meglio di "Note sui pattern di accesso al database".
• Corpo: la quantità minima di Markdown che basta a esprimere il concetto. Gli elenchi puntati sono di solito più chiari dei paragrafi. Includi un esempio se aiuta.

Non c'è un modello obbligatorio, ma un buon punto di partenza è questo:

The constraint or fact in one sentence.

Why:
- The reason this matters or the incident that prompted it.

How to apply:
- The concrete thing the assistant should do when the topic comes up.

Ambito di percorso

Il percorso è metà della memoria: decide dove la memoria emerge.

• Una memoria in /apps/api/payments emerge per qualsiasi lavoro sotto apps/api/payments.
• Una memoria in /apps/api emerge per l'intera directory api.
• Una memoria in / emerge ovunque nel workspace.

Scegli il percorso più specifico che copra comunque i casi che ti interessano. Una memoria sui pagamenti a livello di workspace, che diventa rumore altrove, è peggio di una memoria sui pagamenti nella cartella dei pagamenti.

Versioni e modifiche concorrenti

Ogni salvataggio viene confrontato con la versione da cui sei partito. Se nel frattempo qualcun altro ha salvato, il tuo salvataggio viene rifiutato invece di sovrascrivere il suo. Questo evita che due persone, o una persona e un agente, si sovrascrivano a vicenda senza accorgersene.

• In Pathrule per VS Code una memoria è una scheda Markdown. Un salvataggio che sovrascriverebbe una modifica più recente di un collega propone Reload, Copy My Version & Reload (il tuo testo viene prima copiato negli appunti) oppure Keep Mine (Overwrite).
• Tramite MCP l'assistente può passare l'ultima versione che ha letto. In caso di mancata corrispondenza riceve un conflitto con la versione corrente, rilegge e unisce le modifiche invece di sovrascriverle.

Anche l'eliminazione è reversibile. In VS Code un'eliminazione propone subito Undo, e in un workspace Pathrule Cloud una memoria eliminata resta nell'archivio del workspace finché non viene eliminata definitivamente: un owner o un admin può ripristinarla dalle impostazioni della console web (Workspace, Archive) oppure eliminarla per sempre. Nella pratica i conflitti sono rari, perché le memorie sono di solito brevi e mirate, ma la rete di sicurezza è sempre attiva.

Chi le scrive

• Le persone, scrivendo in Pathrule per VS Code (New Memory… o Save Selection as Memory) oppure con la CLI.
• L'assistente, scrivendo tramite lo strumento MCP pathrule_write_memory quando gli chiedi di salvare qualcosa. Durante la configurazione propone memorie, regole e skill per il progetto e scrive solo gli elementi che approvi.

Dal terminale, una memoria è un solo comando. Senza --body, la CLI apre il tuo editor per il corpo; puoi anche passare --body o inviare il testo tramite pipe. pathrule memory list e pathrule memory read "Exact title" --print rileggono le memorie.

pathrule memory add --path /apps/api/payments --title "Always pass the Stripe idempotency key"

Entrambe le fonti finiscono nello stesso posto. L'assistente legge ciò che ha scritto una persona e una persona legge ciò che ha scritto l'assistente. Ogni record conserva chi l'ha creato, chi l'ha modificato per ultimo e la sua origine, che l'azione Info in VS Code mostra, così le memorie scritte dall'IA sono facili da individuare.

Come la qualità delle memorie resta verificabile

Pathrule mantiene ogni memoria circoscritta e ispezionabile tramite diversi controlli indipendenti:

• La documentazione generica viene proposta durante la configurazione invece di essere importata automaticamente. I file di istruzioni attivi, la loro catena di import, le regole degli strumenti e i registri delle decisioni offrono prove più solide di essere conoscenza effettivamente in uso.
• A un agente viene chiesto di proporre la conoscenza duratura prima di salvarla. Tutto ciò che salva è attribuito, ha una versione ed è visibile nel workspace come qualsiasi altro elemento, così puoi aprirlo, modificarlo o rimuoverlo.
• L'ambito di percorso limita dove la voce può emergere, e una voce fuori dal percorso corrente deve comunque superare la soglia minima di pertinenza.
• L'utilizzo misurato può riordinare le voci idonee, ma non può portare una memoria non pertinente oltre quella soglia.
• Un agente che nota che una memoria non corrisponde più al codice può segnalarla come attività di aggiornamento, che un assistente riprende in seguito e corregge sotto il tuo controllo. Vedi Suggerimenti e autoverifica. Le modifiche hanno una versione e l'eliminazione è reversibile.
• Una nuova memoria il cui titolo coincide con quello di una memoria esistente nello stesso percorso viene rifiutata per impostazione predefinita invece di essere salvata come seconda copia, così la stessa decisione non viene consegnata due volte né lasciata divergere. Puoi forzare deliberatamente il salvataggio (--allow-duplicate nella CLI) dopo aver controllato la voce esistente.

Il modello operativo che ne risulta è un piccolo insieme di decisioni e insidie circoscritte e verificabili, non un grande archivio copiato nel workspace. Vedi Come Pathrule dimostra le affermazioni impegnative per il contratto tecnico completo.

Leggere o citare

Le memorie più pertinenti arrivano con il corpo completo, su cui l'assistente può agire direttamente. I candidati meno certi arrivano come titoli con id; l'assistente ne legge uno per intero con pathrule_read_memory prima di farci affidamento. In questo modo il materiale incerto resta fuori dal payload predefinito senza trasformare le corrispondenze forti in passaggi aggiuntivi.

In VS Code, Browse Knowledge Here… mostra cosa riceve una sessione IA su un percorso, incluso ciò che eredita dai percorsi padre.

Anti-pattern

• Un'unica enorme memoria "tutti i miei appunti". Suddividi per argomento e per ambito. Breve e legata a un percorso batte sempre lunga e globale.
• Memorie che ripetono ciò che dice già il codice. L'assistente sa leggere il codice. Riserva le memorie al perché e alle insidie.
• Memorie obsolete. Aggiornale o eliminale quando la decisione di fondo cambia. Un assistente può segnalare una memoria non più allineata come attività di aggiornamento, ma un occhio umano è più rapido.

Creazione in locale e su Cloud

Gli esempi di add da terminale in questa pagina si riferiscono a un workspace Cloud. In modalità locale, crea e modifica le voci in Local Console, in VS Code o tramite MCP locale; i comandi di conoscenza della CLI le elencano, le leggono e le cercano.

Cosa leggere dopo

• Scrivere regole per i vincoli con priorità.
• Scrivere skill per le procedure riutilizzabili.
• Concetti fondamentali per l'albero del workspace a cui si associano.