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, permitiéndole construir conocimiento a lo largo del tiempo sin mantener todo en la ventana de contexto.

Este es el primitivo clave para la recuperación de contexto justo a tiempo: en lugar de cargar toda la información relevante de antemano, los agentes almacenan lo que aprenden en memoria y lo recuperan bajo demanda. Esto mantiene el contexto activo enfocado en lo que es actualmente relevante, crítico para flujos de trabajo de larga duración donde cargar todo de una vez abrumaría la ventana de contexto. Consulta Effective context engineering para el patrón más amplio.

La herramienta de memoria opera 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 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 tareas. Claude puede crear, leer, actualizar y eliminar archivos en el directorio /memories para almacenar lo que aprende mientras trabaja, 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 herramientas 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, 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 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..."

Para soporte de modelos, consulta la Referencia de herramientas.

Primeros pasos

Para usar la herramienta de memoria:

1. Agrega la herramienta de memoria a tu solicitud
2. Implementa manejadores del lado del cliente para operaciones de memoria

Uso básico

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=2048,
    messages=[
        {
            "role": "user",
            "content": "I'm working on a Python web scraper that keeps crashing with a timeout error. Here's the problematic function:\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\nPlease help me debug this.",
        }
    ],
    tools=[{"type": "memory_20250818", "name": "memory"}],
)

print(message)

Comandos de herramientas

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
• Usa 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, alineado 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: "File {path} exceeds maximum line limit of 999,999 lines."

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: "The path {path} does not exist. Please provide a valid path."

create

Crear un nuevo archivo:

{
  "command": "create",
  "path": "/memories/notes.txt",
  "file_text": "Meeting notes:\n- Discussed project timeline\n- Next steps defined\n"
}

Valores de retorno

• Éxito: "File created successfully at: {path}"

Manejo de errores

• El archivo ya existe: "Error: File {path} already exists"

str_replace

Reemplazar texto en un archivo:

{
  "command": "str_replace",
  "path": "/memories/preferences.txt",
  "old_str": "Favorite color: blue",
  "new_str": "Favorite color: green"
}

Valores de retorno

• Éxito: "The memory file has been edited." seguido de un fragmento del archivo editado con números de línea

Manejo de errores

• El archivo no existe: "Error: The path {path} does not exist. Please provide a valid path."
• Texto no encontrado: "No replacement was performed, old_str `\{old_str}` did not appear verbatim in {path}."
• Texto duplicado: Cuando old_str aparece múltiples veces, devuelve: "No replacement was performed. Multiple occurrences of old_str `\{old_str}` in lines: {line_numbers}. Please ensure it is unique"

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": "- Review memory tool documentation\n"
}

Valores de retorno

• Éxito: "The file {path} has been edited."

Manejo de errores

• El archivo no existe: "Error: The path {path} does not exist"
• Número de línea inválido: "Error: Invalid `insert_line` parameter: {insert_line}. It should be within the range of lines of the file: [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: "Successfully deleted {path}"

Manejo de errores

• El archivo/directorio no existe: "Error: The path {path} does not exist"

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: "Successfully renamed {old_path} to {new_path}"

Manejo de errores

• La fuente no existe: "Error: The path {old_path} does not exist"
• El destino ya existe: Devuelve un error (no sobrescribas): "Error: The destination {new_path} already exists"

Manejo de directorios

Renombra el directorio.

Orientación de indicaciones

Esta instrucción se incluye automáticamente en el indicador del sistema cuando la herramienta de memoria está habilitada:

IMPORTANT: ALWAYS VIEW YOUR MEMORY DIRECTORY BEFORE DOING ANYTHING ELSE.
MEMORY PROTOCOL:
1. Use the `view` command of your `memory` tool to check for earlier progress.
2. ... (work on the task) ...
     - As you make progress, record status / progress / thoughts etc in your memory.
ASSUME INTERRUPTION: Your context window might be reset at any moment, so you risk losing any progress that is not recorded in your memory directory.

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 consideraciones 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 permite 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 rutas

Considera estas salvaguardas:

• Valida que todas las rutas comiencen con /memories
• Resuelve 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 rutas 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 herramientas individuales anteriores para mensajes de error detallados y comportamientos. Los errores comunes incluyen archivo no encontrado, errores de permiso, rutas inválidas y coincidencias de texto duplicadas.

Integración de edición de contexto

La herramienta de memoria se empareja con la edición de contexto para gestionar conversaciones de larga duración. Para obtener más detalles, consulta Context editing.

Usar con Compaction

La herramienta de memoria también se puede emparejar con compaction, que proporciona resumen de contexto de conversación del lado del servidor. Mientras que la edición de contexto borra resultados de herramientas específicas del lado del cliente, la compaction 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 compaction mantiene el contexto activo manejable sin contabilidad del lado del cliente, y la memoria persiste información importante en los límites de compaction para que nada crítico se pierda en el resumen.

Patrón de desarrollo de software de múltiples sesiones

Para proyectos de software de larga duración que abarcan múltiples sesiones de agentes, los archivos de memoria necesitan ser inicializados deliberadamente, no solo escritos ad hoc a medida que avanza el trabajo. El patrón a continuación convierte la memoria en un mecanismo de recuperación estructurado, para que cada nueva sesión pueda continuar exactamente desde donde se quedó la última.

Cómo funciona

1. Sesión inicializadora: La primera sesión configura los artefactos de memoria antes de que comience cualquier trabajo sustancial. Esto incluye un registro de progreso (rastreando qué se ha hecho y qué viene después), una lista de verificación de características (definiendo el alcance del trabajo), y una referencia a cualquier script de inicio o inicialización que el proyecto necesite.

2. Sesiones posteriores: Cada nueva sesión se abre leyendo esos artefactos de memoria. Esto recupera el estado completo del proyecto en segundos, sin necesidad de re-explorar la base de código o retrazar decisiones anteriores.

3. Actualización de fin de sesión: Antes de que una sesión termine, actualiza el registro de progreso con lo que se completó y lo que permanece. Esto asegura que la próxima sesión tenga un punto de partida preciso.

Principio clave

Trabaja en una característica a la vez. Solo marca una característica como completa después de que la verificación de extremo a extremo confirme que funciona, no solo después de que se escriba el código. Esto mantiene el registro de progreso confiable y previene que el scope creep se agrave en sesiones.

Próximos pasos