Auto Memory y Settings: Lo que Claude Aprende y Cómo lo Configuras

Descripción

Hasta ahora cubrimos la memoria explícita — lo que tú escribes en CLAUDE.md. Pero Claude Code tiene otra forma de memoria: auto memory, donde Claude aprende automáticamente de tus correcciones y preferencias sin que escribas nada en un archivo.

Además, Claude Code tiene un sistema de settings con 3 scopes (global, project, local) que controla permisos, herramientas permitidas, y comportamiento del agente. Los settings no son memoria contextual como CLAUDE.md — son configuración técnica que define qué puede y qué no puede hacer Claude Code en tu entorno.

Esta cápsula cubre ambos sistemas: cómo funciona auto memory, dónde se guarda, cómo gestionarla, y cuándo es mejor que CLAUDE.md. Luego, el sistema de settings: qué configurar en cada scope, cómo hacerlo, y las mejores prácticas para equipos.

Auto Memory: Aprendizaje Automático

Qué es auto memory

Auto memory es la capacidad de Claude Code de recordar correcciones y preferencias entre sesiones sin que las escribas en CLAUDE.md. Cuando corriges a Claude, esa corrección puede guardarse como un "recuerdo" que aplica en futuras sesiones.

Cómo funciona

Sesión 1:
Tú: "Crea un componente Button"
Claude: [crea con function declaration]

Tú: "No uses function declarations. Usa arrow functions 
     con const. Es la convención del proyecto."

Claude: [corrige, usa arrow function]
Claude: [internamente] → Guarda: "Este usuario prefiere 
        arrow functions con const para componentes"

═══════════════════════════════════════════════

Sesión 2 (días después):
Tú: "Crea un componente Card"

Claude: [usa arrow function con const automáticamente]
→ Aplica la corrección aprendida sin que la repitas

Qué tipo de cosas aprende

Auto memory captura patrones de corrección:

Requisito de versión

Auto memory requiere Claude Code v2.1.59 o superior. Verifica con:

claude --version

Si tu versión es menor, actualiza con claude update.

Activar/desactivar auto memory

Auto memory está activo por default. Para desactivarlo:

Opción 1 — Toggle interactivo:

> /memory

Y usa el toggle de auto memory en la interfaz.

Opción 2 — Settings:

{
  "autoMemoryEnabled": false
}

Opción 3 — Variable de entorno:

export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

Dónde se guardan las auto memories

Las auto memories se almacenan en un directorio local dentro de ~/.claude/, organizado por proyecto:

~/.claude/projects/<proyecto>/memory/
├── MEMORY.md              → Índice conciso (primeras 200 líneas o 25KB, lo que ocurra primero, se cargan en cada sesión)
├── debugging.md           → Notas detalladas sobre patrones de debugging
├── api-conventions.md     → Decisiones de diseño de APIs
└── ...                    → Otros archivos temáticos que Claude crea según necesite

MEMORY.md actúa como índice del directorio. Claude lee y escribe archivos en este directorio durante tu sesión. Los archivos temáticos se cargan bajo demanda, no al inicio.

Auto memory es local a tu máquina. Todos los worktrees y subdirectorios dentro del mismo repositorio git comparten un directorio de auto memory.

Cómo ver tus auto memories

Usa el comando /memory dentro de una sesión:

> /memory

/memory lista todos los archivos CLAUDE.md y rules cargados en tu sesión actual, te permite activar/desactivar auto memory, y abre un link para acceder a la carpeta de auto memory. Selecciona cualquier archivo para abrirlo en tu editor.

Cuando le pides a Claude que "recuerde" algo (ej: "siempre usa pnpm, no npm"), Claude lo guarda en auto memory. Para agregar instrucciones a CLAUDE.md en su lugar, pídelo explícitamente: "agrega esto a CLAUDE.md."

Cómo eliminar o editar auto memories

Si Claude aprendió algo incorrecto o desactualizado:

# Desde la interfaz interactiva
> /memory

# Claude lista las memorias
# Puedes pedir que elimine una específica:
> "Elimina la memoria sobre usar tabs en vez de spaces. 
   Cambiamos esa convención."

También puedes editar directamente los archivos en .claude/ si prefieres control manual.

Cuándo Auto Memory Ayuda vs Cuándo CLAUDE.md Es Mejor

Auto memory es mejor cuando:

1. Preferencias personales que descubres trabajando:

Tú: "No me gustan las respuestas largas. Sé más conciso."

→ Auto memory: perfecto. Es una preferencia personal que 
  Claude aprende y aplica en futuras sesiones.
→ CLAUDE.md: no encaja. Es una preferencia tuya, no del proyecto.

2. Correcciones menores que no merecen una regla formal:

Tú: "Prefiero if/else sobre ternarios para condiciones complejas"

→ Auto memory: captura la preferencia sin burocracia.
→ CLAUDE.md: demasiado granular para una regla formal.

3. Hábitos que emergen con el uso:

Después de 5 correcciones, Claude nota:
- Este usuario siempre quiere tests después de implementar
- Este usuario prefiere async/await sobre .then()
- Este usuario quiere logs detallados en development

→ Estos patterns se internalizan como auto memory.

CLAUDE.md es mejor cuando:

1. Reglas del proyecto que todo el equipo debe seguir:

"No usar any en TypeScript" → CLAUDE.md
Porque aplica a todo el equipo, no solo a ti.
Auto memory es personal, CLAUDE.md es compartida.

2. Información factual del proyecto:

"Stack: FastAPI, PostgreSQL, Alembic" → CLAUDE.md
Porque es un hecho, no una preferencia.
Auto memory es para correcciones, no para hechos.

3. Convenciones que necesitas documentar:

"Archivos en kebab-case, clases en PascalCase" → CLAUDE.md
Porque necesitas que sea explícito y visible para el equipo.
Auto memory es implícita — nadie más la ve.

Tabla comparativa

Best Practices para Auto Memory

Deja que Claude aprenda naturalmente

No intentes "programar" auto memory. Simplemente trabaja con Claude Code, corrige cuando sea necesario, y deja que las correcciones se acumulen.

# BIEN — corrección natural:
Tú: "Usa const en vez de let aquí, la variable no se reasigna."

# MAL — forzar una "memoria":
Tú: "Recuerda permanentemente: siempre usar const sobre let 
     cuando la variable no se reasigna. Guárdalo."

Revisa periódicamente

Cada pocas semanas, revisa las auto memories acumuladas:

> /memory

Elimina las que ya no aplican (quizás cambiaste de convención) y verifica que no hay contradicciones.

Si algo es importante, ponlo en CLAUDE.md

Si una corrección que hiciste es realmente importante para el proyecto, no confíes solo en auto memory — agrégala a CLAUDE.md:

Tú: "Nunca uses console.log en producción. Usa el logger."

→ Bien: Claude lo recuerda como auto memory.
→ Mejor: Agrega a CLAUDE.md "No usar console.log — usar loguru"
→ Mejor aún: Ambos. Auto memory para ti, CLAUDE.md para el equipo.

Cuidado con memories contradictorias

Si en enero dijiste "usa tabs" y en febrero dijiste "usa spaces", ambas correcciones pueden coexistir como auto memories. Claude tiene que resolver la contradicción — y puede elegir incorrectamente.

Solución: Revisa y limpia memories cuando cambias de convención.

Sistema de Settings

Qué son los settings

Los settings de Claude Code son archivos JSON que configuran el comportamiento técnico del agente: qué herramientas puede usar, qué permisos tiene, y cómo opera. No son contexto sobre tu proyecto — son configuración del agente mismo.

Los 3 scopes

┌──────────────────────────────────────────────┐
│  GLOBAL (~/.claude/settings.json)            │
│  Aplica a TODOS tus proyectos                │
│  Personal, no se comparte                    │
│                                              │
│  ┌──────────────────────────────────────┐    │
│  │  PROJECT (.claude/settings.json)     │    │
│  │  Aplica solo a ESTE proyecto         │    │
│  │  Se commitea al repo (compartido)    │    │
│  │                                      │    │
│  │  ┌──────────────────────────────┐    │    │
│  │  │  LOCAL                       │    │    │
│  │  │  (.claude/settings.local.json)│   │    │
│  │  │  Tus overrides personales    │    │    │
│  │  │  NO se commitea              │    │    │
│  │  └──────────────────────────────┘    │    │
│  └──────────────────────────────────────┘    │
└──────────────────────────────────────────────┘

Precedencia: Local > Project > Global

Scope 1: Global Settings

Ubicación

~/.claude/settings.json

Qué configurar aquí

Preferencias que aplican a todos tus proyectos, en todas tus máquinas:

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "LS"
    ],
    "deny": []
  },
  "preferences": {
    "verbose": false,
    "theme": "dark"
  }
}

Cuándo usar global settings

• Herramientas que siempre quieres permitir (read, grep, ls)
• Preferencias de UI que aplican en todos lados
• Defaults de comportamiento que te gustan

Lo que NO poner aquí

• Herramientas específicas de un proyecto (como un linter particular)
• Permisos que solo aplican en ciertos proyectos
• Configuración que no quieres en todas tus máquinas

Scope 2: Project Settings

Ubicación

my-project/.claude/settings.json

Qué configurar aquí

Configuración compartida con el equipo. Se commitea a git:

{
  "permissions": {
    "allow": [
      "Read",
      "Write",
      "Glob",
      "Grep",
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(npx prisma migrate dev)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(npm publish)"
    ]
  }
}

allowedTools: pre-aprobar herramientas

La configuración más importante de project settings. Define qué comandos puede ejecutar Claude sin pedirte confirmación:

{
  "permissions": {
    "allow": [
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(npm run format)",
      "Bash(npx prisma generate)"
    ]
  }
}

Con esta configuración, cuando Claude quiere ejecutar npm test, lo hace directamente sin preguntarte "Allow? [y/n]". Esto acelera significativamente el workflow.

denyTools: bloquear herramientas peligrosas

{
  "permissions": {
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force)",
      "Bash(npm publish)",
      "Bash(docker rm)"
    ]
  }
}

Estos comandos nunca se ejecutarán, ni siquiera si Claude o tú lo piden. Es una red de seguridad.

Cuándo usar project settings

• Herramientas que todo el equipo debería pre-aprobar (test, lint)
• Herramientas que nadie debería poder ejecutar accidentalmente (rm -rf, force push)
• Configuración que debe ser consistente entre todos los developers del equipo

Commitearlo al repo

Project settings se commitean para que todo el equipo los comparta:

git add .claude/settings.json
git commit -m "chore: configure claude code project settings"

Scope 3: Local Settings

Ubicación

my-project/.claude/settings.local.json

Qué configurar aquí

Tus overrides personales que NO se comparten con el equipo:

{
  "permissions": {
    "allow": [
      "Bash(docker compose up -d)",
      "Bash(psql)"
    ]
  },
  "preferences": {
    "verbose": true
  }
}

Cuándo usar local settings

• Herramientas que solo tú usas (quizás tienes Docker pero tu compañero no)
• Permisos adicionales para tu entorno local
• Overrides de preferencias personales

.gitignore

Local settings no deben commitearse:

echo ".claude/settings.local.json" >> .gitignore

Comparaciones y Decisiones

Auto memory vs CLAUDE.md vs Settings

┌─────────────────────────────────────────────────────────┐
│                                                         │
│  Auto Memory     CLAUDE.md        Settings              │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐          │
│  │ APRENDE  │    │ CONTEXTO │    │ CONFIGURA │          │
│  │          │    │          │    │           │          │
│  │ "No usar │    │ "Stack:  │    │ "Permitir │          │
│  │  var"    │    │  FastAPI" │    │  npm test"│          │
│  │          │    │          │    │           │          │
│  │ Implícito│    │ Explícito│    │ Técnico   │          │
│  │ Personal │    │ Proyecto │    │ Permisos  │          │
│  └──────────┘    └──────────┘    └──────────┘          │
│                                                         │
│  "Lo que          "Lo que         "Lo que                │
│   Claude           tú defines     Claude PUEDE           │
│   aprende de       sobre el       o NO PUEDE             │
│   correcciones"    proyecto"      hacer"                 │
│                                                         │
└─────────────────────────────────────────────────────────┘

Cuándo usar cada uno

Patterns Comunes

Pattern 1: "Settings de equipo estandarizados"

Todos los projects del equipo comparten settings consistentes:

{
  "permissions": {
    "allow": [
      "Read",
      "Write",
      "Glob",
      "Grep",
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(npm run format)",
      "Bash(npm run build)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force)",
      "Bash(npm publish)"
    ]
  }
}

Pattern 2: "Auto memory + CLAUDE.md = redundancia intencional"

Las correcciones importantes van en ambos lugares:

Sesión: "No uses console.log, usa el logger"
→ Claude lo guarda como auto memory
→ Tú lo agregas a CLAUDE.md

¿Redundante? Sí. ¿Malo? No.
- Auto memory: te cubre si olvidas actualizar CLAUDE.md
- CLAUDE.md: cubre al equipo que no tiene tu auto memory

Pattern 3: "Local settings para desarrollo"

Tu local settings agrega permisos para tu entorno de desarrollo:

{
  "permissions": {
    "allow": [
      "Bash(docker compose up -d)",
      "Bash(docker compose down)",
      "Bash(psql -h localhost)",
      "Bash(redis-cli)"
    ]
  }
}

Tu compañero que usa SQLite no necesita permisos de Docker.

Pattern 4: "Limpieza periódica de auto memory"

Cada mes, revisa y limpia:

> /memory

Claude: "Memorias actuales:
1. Prefiere arrow functions para componentes
2. Usa tabs con 2 espacios [NOTA: cambiaste a 4 hace 2 semanas]
3. No usar moment.js, usar date-fns
4. Tests con describe/it pattern
5. Respuestas en español"

Tú: "Elimina la #2, ahora uso 4 espacios. Y actualiza la #1: 
     ya no uso arrow functions para componentes, uso function 
     declarations (cambiamos la convención)."

Pattern 5: "Settings progresivos"

Empieza permisivo, restringe según necesites:

// Semana 1 — solo lo básico
{
  "permissions": {
    "allow": ["Read", "Write", "Glob", "Grep"]
  }
}

// Semana 2 — agregas comandos seguros
{
  "permissions": {
    "allow": [
      "Read", "Write", "Glob", "Grep",
      "Bash(npm test)",
      "Bash(npm run lint)"
    ]
  }
}

// Semana 3 — bloqueas lo peligroso
{
  "permissions": {
    "allow": [...],
    "deny": ["Bash(rm -rf *)", "Bash(git push --force)"]
  }
}

Pitfalls y Edge Cases

Pitfall 1: Confiar solo en auto memory para reglas críticas

# Peligroso:
Tú le dices a Claude "nunca modifiques la tabla payments directamente"
Claude lo guarda como auto memory
Tu compañero usa Claude Code → no tiene esa memory → rompe payments

# Solución: Las reglas críticas van en CLAUDE.md (compartido)

Pitfall 2: Auto memories contradictorias acumuladas

Enero: "Usa Express para APIs"
Marzo: "Usa Fastify en vez de Express"
Junio: "Vamos a probar Hono"

→ Tres auto memories sobre frameworks que se contradicen
→ Claude puede confundirse sobre cuál seguir

Solución: Limpia memories cuando cambias de stack o convención

Pitfall 3: Settings demasiado permisivos

{
  "permissions": {
    "allow": ["Bash(*)"]
  }
}

Esto permite que Claude ejecute CUALQUIER comando sin pedir confirmación. Incluyendo rm -rf /, git push --force, npm publish. No hagas esto.

Pitfall 4: Olvidar el .gitignore para settings.local.json

# Si commiteas settings.local.json:
# - Tu compañero hereda tus permisos personales
# - Puede causar conflictos si tienen entornos diferentes
# - Pierde el propósito de "local"

# Solución:
echo ".claude/settings.local.json" >> .gitignore

Pitfall 5: No usar settings cuando deberías

# Si cada vez Claude te pregunta:
"Claude wants to run: npm test. Allow? [y/n]"
"Claude wants to run: npm test. Allow? [y/n]"
"Claude wants to run: npm test. Allow? [y/n]"

# ...y siempre dices "y", deberías agregar a settings:
{
  "permissions": {
    "allow": ["Bash(npm test)"]
  }
}

# Ahora npm test se ejecuta sin confirmación

Edge Case: Auto memory vs CLAUDE.md en conflicto

CLAUDE.md: "Usar tabs para indentación"
Auto memory: "Este usuario prefiere spaces"

¿Cuál gana?

Depende de la implementación, pero generalmente:
- CLAUDE.md tiene más peso como fuente explícita
- Pero si la corrección fue reciente, puede prevalecer

Solución: Cuando detectes un conflicto, resuelve uno:
- Actualiza CLAUDE.md para que coincida con tu preferencia
- O elimina la auto memory que contradice CLAUDE.md

Ejemplo Completo Integrado

Escenario: Configurar un proyecto completo con los 3 sistemas

Un proyecto FastAPI con un equipo de 3 developers. Setup completo:

1. CLAUDE.md (contexto del proyecto):

# Invoice API

API de facturación electrónica. Python 3.12, FastAPI, PostgreSQL.

## Stack
- FastAPI 0.109, SQLAlchemy 2.0, Alembic
- Pytest + httpx, Pydantic v2
- Redis para caché, Celery para background tasks

## Convenciones
- snake_case, type hints obligatorias
- Schemas: InvoiceCreate, InvoiceUpdate, InvoiceResponse
- No usar print(), usar loguru

## Comandos
- Dev: `uvicorn src.main:app --reload`
- Test: `pytest -v`
- Lint: `ruff check src/`
- Migrate: `alembic upgrade head`

## Reglas
- NO modificar alembic/versions/ manualmente
- NO hacer queries SQL directas (usar SQLAlchemy)
- Ejecutar tests después de cambios en services/

2. Project settings (.claude/settings.json):

{
  "permissions": {
    "allow": [
      "Read",
      "Write",
      "Glob",
      "Grep",
      "Bash(pytest -v)",
      "Bash(pytest)",
      "Bash(ruff check src/)",
      "Bash(ruff format src/)",
      "Bash(alembic upgrade head)",
      "Bash(uvicorn src.main:app --reload)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force)",
      "Bash(pip install * --break-system-packages)",
      "Bash(alembic downgrade *)"
    ]
  }
}

3. Local settings (.claude/settings.local.json) — solo para ti:

{
  "permissions": {
    "allow": [
      "Bash(docker compose up -d)",
      "Bash(docker compose down)",
      "Bash(pgcli)",
      "Bash(redis-cli)"
    ]
  }
}

4. Auto memory (se acumula con el uso):

Después de 2 semanas de uso, Claude aprendió:

• Prefieres ver output verbose de tests
• No quieres explicaciones largas, solo el código
• Siempre quieres el schema Pydantic antes del endpoint
• Prefieres async generators sobre listas para responses grandes

Resultado: Un sistema completo donde:

• CLAUDE.md da el contexto del proyecto (compartido)
• Project settings define permisos del equipo (compartido)
• Local settings agrega tus herramientas (personal)
• Auto memory refina la experiencia con el tiempo (personal)

Ejercicios Prácticos

Ejercicio 1: Genera auto memories intencionalmente

Abre Claude Code y trabaja en una tarea. Durante la sesión, haz 3 correcciones explícitas:

1. Corrige una convención de naming
2. Corrige una preferencia de estilo (e.g., "no uses ternarios complejos")
3. Corrige una preferencia de output (e.g., "sé más conciso")

En una sesión posterior, verifica si Claude aplica las correcciones automáticamente.

Ejercicio 2: Configura project settings

Crea .claude/settings.json en tu proyecto con:

• 4-5 comandos pre-aprobados (test, lint, build)
• 2-3 comandos bloqueados (rm -rf, force push)

Verifica que funciona: pide a Claude que ejecute npm test y observa si pide confirmación o no.

{
  "permissions": {
    "allow": [
      "Read",
      "Write",
      "Glob",
      "Grep",
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(npm run build)",
      "Bash(npx prisma generate)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force)",
      "Bash(npm publish)"
    ]
  }
}

Ejercicio 3: Compara auto memory vs CLAUDE.md

1. Inicia una sesión nueva
2. Haz una corrección a Claude (e.g., "no uses semicolons")
3. En la siguiente sesión, verifica si lo recuerda (auto memory)
4. Agrega la misma regla a CLAUDE.md
5. Elimina la auto memory
6. Verifica que la regla sigue aplicando (ahora desde CLAUDE.md)

Esto demuestra que ambas fuentes producen el mismo resultado, pero CLAUDE.md es visible y compartible.

Ejercicio 4: Configura los 3 scopes de settings

Crea los 3 archivos de settings:

1. Global (~/.claude/settings.json): Permisos básicos que quieres en todos los proyectos
2. Project (.claude/settings.json): Permisos específicos de este proyecto
3. Local (.claude/settings.local.json): Tus overrides personales

Verifica que el local override funciona: agrega un permiso en local que no está en project.

# 1. Global settings
mkdir -p ~/.claude
cat > ~/.claude/settings.json << 'EOF'
{
  "permissions": {
    "allow": ["Read", "Glob", "Grep"]
  }
}
EOF

# 2. Project settings
mkdir -p .claude
cat > .claude/settings.json << 'EOF'
{
  "permissions": {
    "allow": [
      "Bash(npm test)",
      "Bash(npm run lint)"
    ]
  }
}
EOF

# 3. Local settings
cat > .claude/settings.local.json << 'EOF'
{
  "permissions": {
    "allow": [
      "Bash(docker compose up -d)"
    ]
  }
}
EOF

# 4. Agregar local a .gitignore
echo ".claude/settings.local.json" >> .gitignore

Ejercicio 5: Limpieza de auto memory

Revisa tus auto memories actuales y haz limpieza:

> /memory

1. Identifica memories que ya no aplican
2. Identifica memories que contradicen CLAUDE.md
3. Elimina las obsoletas
4. Migra las importantes a CLAUDE.md si aún no están ahí

Resumen

• Auto memory es aprendizaje implícito: Claude recuerda correcciones y preferencias entre sesiones.
• Se activa naturalmente cuando corriges a Claude. No necesitas forzarla.
• Auto memory es personal, no se comparte. Para reglas del equipo, usa CLAUDE.md.
• Revisa periódicamente con /memory y limpia memories obsoletas o contradictorias.
• Settings tiene 3 scopes: Global (todas tus máquinas), Project (compartido con el equipo), Local (solo tú).
• allowedTools pre-aprueba comandos para acelerar el workflow.
• denyTools bloquea comandos peligrosos como red de seguridad.
• Project settings se commitean a git. Local settings van en .gitignore.
• Auto memory + CLAUDE.md + Settings = sistema completo de memoria y configuración.
• Cuando algo es importante: ponlo en CLAUDE.md (explícito, compartido). Cuando es personal: deja que auto memory lo maneje o usa CLAUDE.local.md.

Siguiente cápsula: 05 - CLAUDE.local.md — preferencias personales que no se comparten con el equipo.

Recursos Adicionales

1. Claude Code Memory — Anthropic Docs — Documentación oficial de auto memory y CLAUDE.md
2. Claude Code Settings — Configuración de scopes: global, project, local
3. Claude Code Best Practices — Recomendaciones para gestionar auto memory y permisos
4. Claude Code CLI Reference — Comandos para gestionar memoria y settings
5. Claude Code Interactive Mode — Gestión de permisos en sesiones interactivas
6. Claude Code Overview — Arquitectura general de Claude Code