Herramienta de memoria

La herramienta de memoria permite a Claude almacenar y recuperar información a través de conversaciones mediante un directorio de archivos de memoria. Claude puede crear, leer, actualizar y eliminar archivos que persisten entre sesiones, permitiéndole construir conocimiento a lo largo del tiempo sin mantener todo en la ventana de contexto.

La herramienta de memoria opera del lado del cliente—tú controlas dónde y cómo se almacenan los datos a través de tu propia infraestructura.

Casos de uso

• Mantener el contexto del proyecto a través de múltiples ejecuciones de agente
• Aprender de interacciones pasadas, decisiones y retroalimentación
• Construir bases de conocimiento a lo largo del tiempo
• Habilitar el aprendizaje entre conversaciones donde Claude mejora en flujos de trabajo recurrentes

Cómo funciona

Cuando está habilitada, Claude verifica automáticamente su directorio de memoria antes de comenzar las tareas. Claude puede crear, leer, actualizar y eliminar archivos en el directorio /memories para almacenar lo que aprende mientras trabaja, luego referenciar esas memorias en conversaciones futuras para manejar tareas similares de manera más efectiva o continuar donde lo dejó.

Dado que esta es una herramienta del lado del cliente, Claude hace llamadas de herramienta para realizar operaciones de memoria, y tu aplicación ejecuta esas operaciones localmente. Esto te da control completo sobre dónde y cómo se almacena la memoria. Por seguridad, deberías restringir todas las operaciones de memoria al directorio /memories.

Ejemplo: Cómo funcionan las llamadas de herramienta de memoria

Cuando le pides a Claude que ayude con una tarea, Claude verifica automáticamente su directorio de memoria primero. Así es como se ve una interacción típica:

1. Solicitud del usuario:

"Ayúdame a responder a este ticket de servicio al cliente."

2. Claude verifica el directorio de memoria:

"Te ayudaré a responder al ticket de servicio al cliente. Déjame verificar mi memoria para cualquier contexto previo."

Claude llama a la herramienta de memoria:

{
  "type": "tool_use",
  "id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "name": "memory",
  "input": {
    "command": "view",
    "path": "/memories"
  }
}

3. Tu aplicación devuelve el contenido del directorio:

{
  "type": "tool_result",
  "tool_use_id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "content": "Directory: /memories\n- customer_service_guidelines.xml\n- refund_policies.xml"
}

4. Claude lee archivos relevantes:

{
  "type": "tool_use",
  "id": "toolu_01D5E6F7G8H9I0J1K2L3M4N5",
  "name": "memory",
  "input": {
    "command": "view",
    "path": "/memories/customer_service_guidelines.xml"
  }
}

5. Tu aplicación devuelve el contenido del archivo:

{
  "type": "tool_result",
  "tool_use_id": "toolu_01D5E6F7G8H9I0J1K2L3M4N5",
  "content": "<guidelines>\n<addressing_customers>\n- Always address customers by their first name\n- Use empathetic language\n..."
}

6. Claude usa la memoria para ayudar:

"Basándome en tus pautas de servicio al cliente, puedo ayudarte a redactar una respuesta. Por favor comparte los detalles del ticket..."

Modelos compatibles

La herramienta de memoria está disponible en:

• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Claude Sonnet 4 (claude-sonnet-4-20250514)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001)
• Claude Opus 4.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (claude-opus-4-20250514)

Comenzando

Para usar la herramienta de memoria:

1. Incluye el encabezado beta context-management-2025-06-27 en tus solicitudes de API
2. Agrega la herramienta de memoria a tu solicitud
3. Implementa manejadores del lado del cliente para operaciones de memoria

Uso básico

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-sonnet-4-5",
        "max_tokens": 2048,
        "messages": [
            {
                "role": "user",
                "content": "Estoy trabajando en un web scraper de Python que sigue fallando con un error de timeout. Aquí está la función problemática:\n\n```python\ndef fetch_page(url, retries=3):\n    for i in range(retries):\n        try:\n            response = requests.get(url, timeout=5)\n            return response.text\n        except requests.exceptions.Timeout:\n            if i == retries - 1:\n                raise\n            time.sleep(1)\n```\n\nPor favor ayúdame a depurar esto."
            }
        ],
        "tools": [{
            "type": "memory_20250818",
            "name": "memory"
        }]
    }'

Comandos de herramienta

Tu implementación del lado del cliente necesita manejar estos comandos de herramienta de memoria:

view

Muestra el contenido del directorio o el contenido del archivo con rangos de líneas opcionales:

{
  "command": "view",
  "path": "/memories",
  "view_range": [1, 10]  // Opcional: ver líneas específicas
}

create

Crear o sobrescribir un archivo:

{
  "command": "create",
  "path": "/memories/notes.txt",
  "file_text": "Notas de reunión:\n- Se discutió la cronología del proyecto\n- Se definieron los próximos pasos\n"
}

str_replace

Reemplazar texto en un archivo:

{
  "command": "str_replace",
  "path": "/memories/preferences.txt",
  "old_str": "Color favorito: azul",
  "new_str": "Color favorito: verde"
}

insert

Insertar texto en una línea específica:

{
  "command": "insert",
  "path": "/memories/todo.txt",
  "insert_line": 2,
  "insert_text": "- Revisar documentación de herramienta de memoria\n"
}

delete

Eliminar un archivo o directorio:

{
  "command": "delete",
  "path": "/memories/old_file.txt"
}

rename

Renombrar o mover un archivo/directorio:

{
  "command": "rename",
  "old_path": "/memories/draft.txt",
  "new_path": "/memories/final.txt"
}

Guía de prompting

Incluimos automáticamente esta instrucción al prompt del sistema cuando se incluye la herramienta de memoria:

IMPORTANTE: SIEMPRE VE TU DIRECTORIO DE MEMORIA ANTES DE HACER CUALQUIER OTRA COSA.
PROTOCOLO DE MEMORIA:
1. Usa el comando `view` de tu herramienta `memory` para verificar el progreso anterior.
2. ... (trabajar en la tarea) ...
     - Mientras progresas, registra el estado / progreso / pensamientos etc en tu memoria.
ASUME INTERRUPCIÓN: Tu ventana de contexto podría reiniciarse en cualquier momento, por lo que corres el riesgo de perder cualquier progreso que no esté registrado en tu directorio de memoria.

Si observas que Claude crea archivos de memoria desordenados, puedes incluir esta instrucción:

Nota: al editar tu carpeta de memoria, siempre trata de mantener su contenido actualizado, coherente y organizado. Puedes renombrar o eliminar archivos que ya no sean relevantes. No crees nuevos archivos a menos que sea necesario.

También puedes guiar lo que Claude escribe en la memoria, por ejemplo, "Solo anota información relevante para <tema> en tu sistema de memoria."

Consideraciones de seguridad

Aquí hay preocupaciones importantes de seguridad al implementar tu almacén de memoria:

Información sensible

Claude generalmente se negará a escribir información sensible en archivos de memoria. Sin embargo, es posible que desees implementar una validación más estricta que elimine información potencialmente sensible.

Tamaño de almacenamiento de archivos

Considera rastrear los tamaños de archivos de memoria y prevenir que los archivos crezcan demasiado. Considera agregar un número máximo de caracteres que el comando de lectura de memoria puede devolver, y deja que Claude pagine a través del contenido.

Expiración de memoria

Considera limpiar archivos de memoria periódicamente que no hayan sido accedidos en un tiempo extendido.

Protección contra traversal de rutas

Considera estas salvaguardas:

• Validar que todas las rutas comiencen con /memories
• Resolver rutas a su forma canónica y verificar que permanezcan dentro del directorio de memoria
• Rechazar rutas que contengan secuencias como ../, ..\\, u otros patrones de traversal
• Vigilar secuencias de traversal codificadas en URL (%2e%2e%2f)
• Usar las utilidades de seguridad de ruta integradas de tu lenguaje (por ejemplo, pathlib.Path.resolve() y relative_to() de Python)

Manejo de errores

La herramienta de memoria usa los mismos patrones de manejo de errores que la herramienta de editor de texto. Los errores comunes incluyen archivo no encontrado, errores de permisos y rutas inválidas.

Uso con Edición de Contexto

La herramienta de memoria puede combinarse con edición de contexto, que automáticamente limpia resultados de herramientas antiguos cuando el contexto de conversación crece más allá de un umbral configurado. Esta combinación habilita flujos de trabajo agénticos de larga duración que de otra manera excederían los límites de contexto.

Cómo funcionan juntos

Cuando la edición de contexto está habilitada y tu conversación se acerca al umbral de limpieza, Claude automáticamente recibe una notificación de advertencia. Esto impulsa a Claude a preservar cualquier información importante de los resultados de herramientas en archivos de memoria antes de que esos resultados sean limpiados de la ventana de contexto.

Después de que los resultados de herramientas son limpiados, Claude puede recuperar la información almacenada de archivos de memoria cuando sea necesario, tratando efectivamente la memoria como una extensión de su contexto de trabajo. Esto permite a Claude:

• Continuar flujos de trabajo complejos de múltiples pasos sin perder información crítica
• Referenciar trabajo y decisiones pasadas incluso después de que los resultados de herramientas sean removidos
• Mantener contexto coherente a través de conversaciones que excederían los límites típicos de contexto
• Construir una base de conocimiento a lo largo del tiempo mientras mantiene la ventana de contexto activa manejable

Ejemplo de flujo de trabajo

Considera un proyecto de refactorización de código con muchas operaciones de archivo:

1. Claude hace numerosas ediciones a archivos, generando muchos resultados de herramientas
2. Mientras el contexto crece y se acerca a tu umbral, Claude recibe una advertencia
3. Claude resume los cambios hechos hasta ahora en un archivo de memoria (por ejemplo, /memories/refactoring_progress.xml)
4. La edición de contexto limpia automáticamente los resultados de herramientas más antiguos
5. Claude continúa trabajando, referenciando el archivo de memoria cuando necesita recordar qué cambios ya fueron completados
6. El flujo de trabajo puede continuar indefinidamente, con Claude manejando tanto el contexto activo como la memoria persistente

Configuración

Para usar ambas funciones juntas:

response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=4096,
    messages=[...],
    tools=[
        {
            "type": "memory_20250818",
            "name": "memory"
        },
        # Tus otras herramientas
    ],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {
                    "type": "input_tokens",
                    "value": 100000
                },
                "keep": {
                    "type": "tool_uses",
                    "value": 3
                }
            }
        ]
    }
)

También puedes excluir las llamadas de herramienta de memoria de ser limpiadas para asegurar que Claude siempre tenga acceso a operaciones de memoria recientes:

context_management={
    "edits": [
        {
            "type": "clear_tool_uses_20250919",
            "exclude_tools": ["memory"]
        }
    ]
}