Herramienta de memoria

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

La herramienta de memoria funciona del lado del cliente: 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 en múltiples ejecuciones de agentes
• Aprender de interacciones, decisiones y comentarios pasados
• Construir bases de conocimiento con el 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, y luego hacer referencia a esos recuerdos en conversaciones futuras para manejar tareas similares de manera más efectiva o continuar desde donde se quedó.

Como esta es una herramienta del lado del cliente, Claude realiza llamadas de herramienta para realizar operaciones de memoria, y tu aplicación ejecuta esas operaciones localmente. Esto te da control total sobre dónde y cómo se almacena la memoria. Por seguridad, debes 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 este ticket de servicio al cliente."

2. Claude verifica el directorio de memoria:

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

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": "Aquí están los archivos y directorios hasta 2 niveles de profundidad en /memories, excluyendo elementos ocultos y node_modules:\n4.0K\t/memories\n1.5K\t/memories/customer_service_guidelines.xml\n2.0K\t/memories/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": "Aquí está el contenido de /memories/customer_service_guidelines.xml con números de línea:\n     1\t<guidelines>\n     2\t<addressing_customers>\n     3\t- Siempre dirígete a los clientes por su nombre\n     4\t- Usa lenguaje empático\n..."
}

6. Claude usa la memoria para ayudar:

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

Modelos soportados

La herramienta de memoria está disponible en:

• Claude Opus 4.6 (claude-opus-4-6)
• Claude Opus 4.5 (claude-opus-4-5-20251101)
• Claude Opus 4.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (claude-opus-4-20250514)
• 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)

Primeros pasos

Para usar la herramienta de memoria:

1. Incluye el encabezado beta context-management-2025-06-27 en tus solicitudes de API
2. Añade 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-opus-4-6",
        "max_tokens": 2048,
        "messages": [
            {
                "role": "user",
                "content": "Estoy trabajando en un web scraper de Python que sigue fallando con un error de tiempo de espera. 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. Aunque estas especificaciones describen los comportamientos recomendados con los que Claude está más familiarizado, puedes modificar tu implementación y devolver cadenas según sea necesario para tu caso de uso.

view

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

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

Valores de retorno

Para directorios: Devuelve un listado que muestra archivos y directorios con sus tamaños:

Aquí están los archivos y directorios hasta 2 niveles de profundidad en {path}, excluyendo elementos ocultos y node_modules:
{size}    {path}
{size}    {path}/{filename1}
{size}    {path}/{filename2}

• Lista archivos hasta 2 niveles de profundidad
• Muestra tamaños legibles por humanos (por ejemplo, 5.5K, 1.2M)
• Excluye elementos ocultos (archivos que comienzan con .) y node_modules
• Utiliza carácter de tabulación entre tamaño y ruta

Para archivos: Devuelve el contenido del archivo con un encabezado y números de línea:

Aquí está el contenido de {path} con números de línea:
{line_numbers}{tab}{content}

Formato de número de línea:

• Ancho: 6 caracteres, alineados a la derecha con relleno de espacios
• Separador: Carácter de tabulación entre número de línea y contenido
• Indexación: Indexada en 1 (la primera línea es la línea 1)
• Límite de línea: Los archivos con más de 999,999 líneas deben devolver un error: "El archivo {path} excede el límite máximo de 999,999 líneas."

Ejemplo de salida:

Aquí está el contenido de /memories/notes.txt con números de línea:
     1	Hello World
     2	This is line two
    10	Line ten
   100	Line one hundred

Manejo de errores

• El archivo/directorio no existe: "La ruta {path} no existe. Por favor, proporciona una ruta válida."

create

Crear un nuevo archivo:

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

Valores de retorno

• Éxito: "Archivo creado exitosamente en: {path}"

Manejo de errores

• El archivo ya existe: "Error: El archivo {path} ya existe"

str_replace

Reemplazar texto en un archivo:

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

Valores de retorno

• Éxito: "El archivo de memoria ha sido editado." seguido de un fragmento del archivo editado con números de línea

Manejo de errores

• El archivo no existe: "Error: La ruta {path} no existe. Por favor, proporciona una ruta válida."
• Texto no encontrado: "No se realizó ningún reemplazo, old_str `\{old_str}` no apareció textualmente en {path}."
• Texto duplicado: Cuando old_str aparece varias veces, devuelve: "No se realizó ningún reemplazo. Múltiples ocurrencias de old_str `\{old_str}` en líneas: {line_numbers}. Por favor, asegúrate de que sea único"

Manejo de directorios

Si la ruta es un directorio, devuelve un error de "archivo no existe".

insert

Insertar texto en una línea específica:

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

Valores de retorno

• Éxito: "El archivo {path} ha sido editado."

Manejo de errores

• El archivo no existe: "Error: La ruta {path} no existe"
• Número de línea inválido: "Error: Parámetro `insert_line` inválido: {insert_line}. Debe estar dentro del rango de líneas del archivo: [0, {n_lines}]"

Manejo de directorios

Si la ruta es un directorio, devuelve un error de "archivo no existe".

delete

Eliminar un archivo o directorio:

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

Valores de retorno

• Éxito: "Se eliminó exitosamente {path}"

Manejo de errores

• El archivo/directorio no existe: "Error: La ruta {path} no existe"

Manejo de directorios

Elimina el directorio y todo su contenido de forma recursiva.

rename

Renombrar o mover un archivo/directorio:

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

Valores de retorno

• Éxito: "Se renombró exitosamente {old_path} a {new_path}"

Manejo de errores

• El origen no existe: "Error: La ruta {old_path} no existe"
• El destino ya existe: Devuelve un error (no sobrescribas): "Error: El destino {new_path} ya existe"

Manejo de directorios

Renombra el directorio.

Orientación de indicaciones

Incluimos automáticamente esta instrucción en el indicador 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. ... (trabaja en la tarea) ...
     - A medida que avances, registra el estado / progreso / pensamientos, etc. en tu memoria.
ASUME INTERRUPCIÓN: Tu ventana de contexto podría restablecerse 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 intenta 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 escribe información relevante para <topic> en tu sistema de memoria."

Consideraciones de seguridad

Aquí hay preocupaciones de seguridad importantes 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 los archivos de memoria e impedir que los archivos crezcan demasiado. Considera agregar un número máximo de caracteres que el comando de lectura de memoria puede devolver, y permitir que Claude pagine a través del contenido.

Expiración de memoria

Considera limpiar periódicamente los archivos de memoria que no han sido accedidos durante un tiempo prolongado.

Protección contra traversal de ruta

Considera estas salvaguardas:

• Valida que todas las rutas comiencen con /memories
• Resuelve las rutas a su forma canónica y verifica que permanezcan dentro del directorio de memoria
• Rechaza rutas que contengan secuencias como ../, ..\\, u otros patrones de traversal
• Vigila secuencias de traversal codificadas en URL (%2e%2e%2f)
• Usa 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 utiliza patrones de manejo de errores similares a la herramienta de editor de texto. Consulta las secciones de comandos de herramienta individuales anteriores para obtener mensajes de error detallados y comportamientos. Los errores comunes incluyen archivo no encontrado, errores de permiso, rutas inválidas y coincidencias de texto duplicadas.

Usar con Edición de Contexto

La herramienta de memoria se puede combinar con edición de contexto, que borra automáticamente los resultados de herramientas antiguas cuando el contexto de la conversación crece más allá de un umbral configurado. Esta combinación permite flujos de trabajo de agentes de larga duración que de otro modo 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 borrado, Claude recibe automáticamente una notificación de advertencia. Esto le indica a Claude que preserve cualquier información importante de los resultados de herramientas en archivos de memoria antes de que esos resultados se borren de la ventana de contexto.

Después de que se borren los resultados de herramientas, 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
• Hacer referencia al trabajo y decisiones pasadas incluso después de que se eliminen los resultados de herramientas
• Mantener contexto coherente en conversaciones que excederían los límites de contexto típicos
• Construir una base de conocimiento con el tiempo mientras se mantiene la ventana de contexto activa manejable

Flujo de trabajo de ejemplo

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

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

Configuración

Para usar ambas características juntas:

response = client.beta.messages.create(
    model="claude-opus-4-6",
    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 borradas para asegurar que Claude siempre tenga acceso a operaciones de memoria recientes:

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

Usar con Compactación

La herramienta de memoria también se puede emparejar con compactación, que proporciona resumen del lado del servidor del contexto de conversación más antiguo. Mientras que la edición de contexto borra resultados de herramientas específicas del lado del cliente, la compactación resume automáticamente toda la conversación del lado del servidor cuando se acerca al límite de la ventana de contexto.

Para flujos de trabajo de agentes de larga duración, considera usar ambos: la compactación mantiene el contexto activo manejable sin contabilidad del lado del cliente, y la memoria persiste información importante en los límites de compactación para que nada crítico se pierda en el resumen.