MemoryCustodian

1) Installa MemoryCustodian (scegli il percorso che corrisponde al tuo agente/workflow): Scegli un metodo di installazione: - Chiedi al tuo agente di codifica di installare la skill dal repository: https://github.com/waittim/MemoryCustodian - Codex (marketplace locale): esegui `codex plugin marketplace add .` da un checkout, quindi `codex plugin add memory-custodian@memory-custodian-dev`. - Claude Code (plugin): per test locali esegui `claude --plugin-dir .`, o installa nelle skill personali con `./install.sh claude`. - Agenti in stile Gemini: installa con `./install.sh gemini` o `gemini skills link ./skills/memory-custodian`. - CLI/source checkout: esegui dal repository tramite `scripts/memory-custodian ...` o installa in modalità modificabile con `python3 -m pip install -e .` per ottenere il comando `memory-custodian`.

2) Inizializza MemoryCustodian in un progetto (una tantum per repository): Esegui l'inizializzazione una volta per ogni progetto target: - Se installato come script console: `memory-custodian init --project-root /path/to/project --agent all` - Da un checkout del sorgente: `scripts/memory-custodian init --project-root /path/to/project --agent all` Usa `--agent codex`, `--agent claude`, `--agent gemini`, o `--agent all` per generare i file di bootstrap sottili che il tuo agente legge.

3) Comprendi cosa crea l'inizializzazione (dove risiede la memoria): L'inizializzazione crea il set di memoria duratura predefinito sotto `docs/memory/`: - `manifest.md` (instrada cosa caricare) - `brief.md` (forma attuale del progetto) - `decisions.md` (decisioni chiave) - `constraints.md` (requisiti stringenti) - `do-not-use.md` (percorsi rifiutati / lapidi) - `inbox.md` (area di staging) I file di bootstrap della piattaforma (ad esempio, `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`) rimangono sottili e indirizzano gli agenti a `docs/memory/`.

4) Cura il brief generato prima di farvi affidamento: Dopo `init`, `brief.md` inizia come uno scheletro con TODO. Riempilo da fonti autorevoli del progetto (README, codice, documenti) prima di considerare la memoria pronta. Usa `memory-custodian status --project-root /path/to/project` (o `scripts/memory-custodian status ...`) per vedere se il brief è ancora non curato; `status` e `check` segnalano un brief non curato.

5) Carica la memoria giusta per un'attività (lettura manifest-first): Il workflow previsto per gli agenti è: 1) Leggi `docs/memory/manifest.md`. 2) Leggi `docs/memory/brief.md`. 3) Carica solo i file rilevanti per l'attività nominati dal manifest. Per l'ispezione manuale, genera un pacchetto di contesto con: - `memory-custodian read --project-root /path/to/project --task planning` - `memory-custodian read --project-root /path/to/project --task implementation` - `memory-custodian read --project-root /path/to/project --task artifact`

6) Aggiungi memoria duratura quando qualcosa dovrebbe sopravvivere alla chat corrente: Registra decisioni/vincoli/preferenze/approcci rifiutati usando la CLI: - `memory-custodian add "Abbiamo scelto il caricamento manifest-first." --type decision` - `memory-custodian add "Persisti il backoff di ritentativi di sincronizzazione." --type decision --area sync --reason "Mantieni i ritentativi limitati tra i lanci."` Mantieni le voci delle decisioni brevi (lo strumento impone una guida sui token e rifiuta scritture troppo lunghe a meno che tu non consenta esplicitamente voci lunghe).

7) Abilita i moduli di memoria opzionali solo quando diventano rilevanti: I moduli opzionali (ad esempio, regole, profili, aree) sono opt-in e non vengono caricati a meno che non siano abilitati e instradati dal manifest. Abilitali secondo necessità: - `memory-custodian enable preferences` - `memory-custodian enable rules/output` - `memory-custodian enable profile/git` - `memory-custodian enable area/frontend` L'abilitazione non sovrascrive mai un file di modulo esistente.

8) Usa 'do-not-use' per preservare gli approcci rifiutati ed evitare regressioni: Quando rifiuti intenzionalmente un approccio (ad esempio, un backend di archiviazione o un'architettura), registralo in `docs/memory/do-not-use.md` (tramite modifiche o il workflow appropriato di aggiunta/dimenticanza) in modo che le sessioni future non lo ripropongano.

9) Controlla regolarmente la salute e la compatibilità del protocollo: Esegui la validazione deterministica per assicurarti che la struttura, i budget e i metadati del protocollo siano corretti: - `memory-custodian check --project-root /path/to/project` Usa `memory-custodian status` per una rapida panoramica e per rilevare un brief non curato.

10) Compatta e mantieni la memoria (preview-first, mutazioni sicure): Usa i comandi di manutenzione per mantenere la memoria piccola e aggiornata: - `memory-custodian compact --project-root /path/to/project` La compattazione è protetta e preview-first; applica le modifiche solo dopo aver esaminato il piano. La compattazione della posta in arrivo è conservativa (ad esempio, rimozione esatta di unità-punto elenco di primo livello duplicate e filtraggio delle lapidi) e si aspetta che un agente/umano faccia una promozione semantica in decisioni/vincoli.

11) Dimentica le informazioni obsolete in modo sicuro (preview-first): Rimuovi o redigi argomenti obsoleti con la dimenticanza preview-first: - Anteprima: `memory-custodian forget "vecchia nota di distribuzione" --mode soft --project-root /path/to/project` - Applica dopo la revisione: `memory-custodian forget "vecchia nota di distribuzione" --mode soft --apply --project-root /path/to/project` Le corrispondenze ampie richiedono una conferma esplicita (ad esempio, `--allow-broad-match`). Alcuni casi richiedono una riscrittura manuale; lo strumento rifiuterà eliminazioni all'ingrosso non sicure.

12) Ripara o sostituisci una configurazione esistente quando necessario: Se mancano file o i metadati devono essere aggiornati senza sovrascrivere il contenuto curato: - Ripara: `memory-custodian init --project-root /path/to/project --repair` Se desideri intenzionalmente una sostituzione completa, usa la sostituzione preview-first e applica solo quando è corretta: - `memory-custodian init --project-root /path/to/project --replace-existing` - quindi aggiungi `--apply` solo se i file elencati devono essere sostituiti.

13) Migra le versioni del protocollo/memoria del progetto quando lo strumento si aggiorna: Quando `check` segnala metadati del protocollo vecchi o mancanti, migra il manifest del progetto offline: - Anteprima: `memory-custodian migrate --project-root /path/to/project` - Applica dopo la revisione: `memory-custodian migrate --apply --project-root /path/to/project`

14) Usa l'invocazione corretta su Windows vs. source checkout: Su Windows, installa il comando console e usa `memory-custodian ...`. Da un checkout del repository su qualsiasi piattaforma, puoi eseguire `scripts/memory-custodian ...` come wrapper.