Memory management: 60+ MEMORY.md auto-curated tra sessioni Claude Code

Una sessione Claude Code è effimera per default: la memoria conversazionale finisce quando chiudi la finestra. Per progetti long-running questo è un problema: ogni sessione riparte da zero, ti tocca ricordare al modello "ricordi che avevamo deciso X?". Il sistema memory/ di Claude Code risolve esattamente questo: persiste fatti rilevanti tra sessioni in modo strutturato, auto-curato, lazy-loaded.

Disclaimer di indipendenza: non sono affiliato a qrx né ad Anthropic. La descrizione che segue è basata sulla mia memoria portfolio (60+ fact accumulati in ~12 mesi) e su come la uso operativamente.

Struttura della directory memory/

Location: ~/.claude/projects/<project-slug>/memory/. Schema:

memory/
├── MEMORY.md                   index (max 200 righe)
├── user_role.md                user fact
├── user_workflow.md            user fact
├── feedback_no_dark_mode.md    feedback fact
├── feedback_ollama_only.md     feedback fact
├── project_architecture.md     project fact
├── project_brand.md            project fact
├── reference_wikidata_token.md reference fact
└── reference_buttondown.md     reference fact

MEMORY.md è l'index sempre caricato a inizio sessione. Ogni entry punta a un file specifico (es. - [No dark mode](feedback_no_dark_mode.md) - Sito light only, no toggle). Quando il modello giudica rilevante il fact, legge il file completo (lazy-load).

Le 4 categorie di fact

1. user: chi è l'utente, role, expertise, preferenze cognitive (es. "Senior Java developer, learning React for the first time"). Aiuta a tarare spiegazioni e analogie.
2. feedback: guidance ricevuta su workflow. Do (pattern confermati come buoni) e don't (correzioni applicate). Esempio: "Don't use git stash in worktree" - feedback dopo un disastro di pop tirato dentro WIP da sibling worktree.
3. project: stato corrente del progetto. Decisioni recenti, in-flight blocker, vincoli temporali (es. "P.IVA forfettaria simulata fino a €5K/anno"). Si update spesso, vita più breve dei feedback.
4. reference: pointer a sistemi esterni. URL dashboard, account, repo, doc esterni rilevanti. "Buttondown account federico@federicocalo.dev", "Wikidata Q139562320", ecc.

Quando Claude salva un fact

Default: "anche solo 1% di rilevanza in future sessioni" = salva. Soglia bassa intenzionalmente. Meglio salvare e poi pruning ciclico, che non salvare e perdere context.

Trigger espliciti utente:

• ricorda che X - salva immediatamente.
• dimentica Y - rimuovi fact + entry da MEMORY.md.
• aggiorna che X - sovrascrivi fact esistente.

Trigger automatici (osservati ma senza istruzione esplicita):

• Nuova decisione di design/architettura.
• Correzione utente su workflow ("non così, fai cosà").
• Vincolo scoperto (es. "questa API non funziona in Italia").
• Riferimento a sistema esterno menzionato per la prima volta.

Esempi reali dal mio MEMORY.md

Selezione di entry attuali nel mio MEMORY portfolio (sintesi):

- [Project Architecture](project_portfolio_architecture.md)
  - Monorepo with Angular 21 SSR + Spring Boot 3.4 + FastAPI,
  migrating from Firestore to REST API
- [Brand Positioning](project_brand_positioning.md)
  - "Full-Stack AI Engineer per startup e PMI IT/EU, applicazioni
  enterprise documentate 8-12 settimane" + vincolo pull
- [SSH VPS via public key](feedback_ssh_vps_access.md)
  - Accesso VPS Hetzner solo via alias ssh portfolio-prod
- [No git stash in worktree](feedback_worktree_no_stash.md)
  - Mai usare git stash in worktree (refs/stash condiviso)
- [AI provider OpenRouter (free)](feedback_ai_provider.md)
  - Dal 2026-10-23 i tool AI del sito usano OpenRouter, piano gratuito (prima: Ollama on-prem; voce aggiornata il 2026-10-30)
- [Wikidata API token](reference_wikidata_token.md)
  - Token Federico per Q139562320, .env.prod only
- [Design System GitHub Primer light](project_design_system.md)
  - Sito light theme only, no toggle

Ogni entry è ~100-150 caratteri. Index totale ~180 righe (entro il limit 200). Quando inizio una sessione, Claude legge MEMORY.md e ha tutto il context macro in 1k token. Lazy-load fact specifici on-demand.

Frontmatter dei fact files

---
name: feedback-no-dark-mode
description: Sito light theme only - no dark mode toggle, palette in styles.css
metadata:
  type: feedback
---

# No dark mode

Decisione del 2026-03: il sito federicocalo.dev usa SOLO light theme.
Rimosso ThemeService toggle. Palette completa in
`frontend/src/styles.css` con CSS custom properties var(--color-*).

NON proporre dark mode toggle in nuovi componenti.
NON usare rgba hardcoded per "fall-back dark" - sempre var(--color-*).

Link related: [[project_design_system]]

Frontmatter sempre minimo: name, description, metadata.type. Body 50-300 righe. Link cross-fact via [[name]] syntax (markdown-style internal link).

Pruning ciclico

MEMORY.md cresce ma deve restare sotto 200 righe. Pruning trimestrale tipico:

1. Claude analizza MEMORY.md attuale + ultima sessione activity.
2. Identifica fact stale (es. project fact superseded da decisione più recente).
3. Propone rimozione (con rationale per ognuna).
4. Utente approva/rifiuta caso per caso.
5. Rimozioni approvate: cancella file fact + entry da MEMORY.md.

Tipicamente 5-15 entry rimosse ogni trimestre. Cumulato: stable size intorno a 60-80 entry totali.

Memory cross-progetto

Ogni progetto ha la sua directory memory separata (path con project-slug). Fact in ~/.claude/projects/<project-A>/memory/ non sono visibili in ~/.claude/projects/<project-B>/memory/.

User fact generici (es. "Federico è developer Java/TS") spesso vengono duplicati cross-progetto. Workaround: alcune installazioni Claude Code supportano user-level memory globale in ~/.claude/memory/ (verifica documentazione corrente). Sul mio setup uso memory per-progetto + duplico user fact dove serve.

Anti-pattern: memory come task tracker

Tentazione: salvare TODO o backlog in memory. Errore. Memory è per fatti che persistono, non per task in volo. Per task tracker usa .planning/STATE.md (GSD-managed) o issue tracker esterno.

Sintomo di anti-pattern: project fact che dicono "in corso X, prossimo passo Y, blocker Z". Quelli sono task, non fatti. Salvali altrove, memory resta più pulita.

Anti-pattern: memory come reference docs

Altra tentazione: salvare snippet di documentazione lunga in memory. Errore. Memory è per pointer + decisioni, non per content reference. Reference fact dice "Wikidata API doc URL https://..." non incolla la documentazione intera.

Sintomo di anti-pattern: fact files da 500+ righe. Splitta in pointer-only + content esterno (file in docs/ del progetto).

Sicurezza: cosa NON salvare in memory

• API key, password, token (sempre in .env.prod non in memory).
• Personal data di terzi (GDPR - memory non è classificata per dati personali).
• Decisioni in conflitto con vincoli legali/etici (es. workaround per bypassare licensing).
• Snippet di codice proprietario protetto da NDA.

Memory è file markdown plain text; trattalo come git-tracked (anche se non lo committi, è sul filesystem). Niente cose che non vorresti in un backup.

Memory in workflow GSD

Memory complementa .planning/PROJECT.md:

• PROJECT.md: planning artifacts, formale, in git, condiviso col team se progetto è team.
• memory/: personal context, informale, NON in git (utente personal), tra sessioni Claude Code.

Pattern complementare: una decisione strategica importante va in entrambi. PROJECT.md per audit trail formale; memory per avere il context comodo a portata in ogni sessione futura.

Cosa ho imparato scrivendo questo articolo

La cosa che mi ha sorpreso è quanto il memory abbia ridotto la fatica di "spiegare di nuovo al modello". Prima dell'adozione (sessioni memory-free), ogni inizio sessione era 5-10 minuti di onboarding: "il progetto è X, lo stack è Y, abbiamo deciso Z". Dopo, l'onboarding automatico via MEMORY.md è 30 secondi.

Secondo insight: la disciplina di scrivere fact files in stile ADR (con rationale + Why + How to apply) ha migliorato il content. Memory che cita "Why: incidente del 2026-03 dove abbiamo perso WIP usando git stash in worktree" è più utile di "Memory: don't git stash in worktree". Il why permette al modello di capire edge case quando applica la rule.

Anti-pattern evitati

• Memory come task tracker. STATE.md è per i task; memory per fact persistenti.
• Memory come reference docs. Pointer + decisioni; non content. Splitta in file esterni se cresce.

Una storia ricevuta che vale la pena condividere

Sezione segnaposto. Se hai pattern memory che ti hanno cambiato il workflow, scrivimi a federico@federicocalo.dev.

← Cluster precedente: Ingest-docs synthesizer Prossimo cluster (track Platform): MCP server development →