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 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 la memoria y lo recuperan bajo demanda. Esto mantiene el contexto activo enfocado en lo que es relevante en ese momento, algo crítico para flujos de trabajo de larga duración donde cargar todo de una vez saturaría la ventana de contexto. Consulta Effective context engineering para conocer el patrón más amplio.

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 lo largo de múltiples ejecuciones del agente
• Aprender de interacciones, decisiones y comentarios anteriores
• 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, y luego referenciar esas memorias en conversaciones futuras para manejar tareas similares de manera más efectiva o retomar donde lo dejó.

Dado que esta es una herramienta del lado del cliente, Claude realiza llamadas a la herramienta para ejecutar 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 a la herramienta de memoria

Cuando le pides a Claude que te 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:

"Help me respond to this customer service ticket."

2. Claude verifica el directorio de memoria:

"I'll help you respond to the customer service ticket. Let me check my memory for any previous context."

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": "Here're the files and directories up to 2 levels deep in /memories, excluding hidden items and node_modules:\n4.0K\t/memories\n1.5K\t/memories/customer_service_guidelines.xml\n2.0K\t/memories/refund_policies.xml"
}

4. Claude lee los 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": "Here's the content of /memories/customer_service_guidelines.xml with line numbers:\n     1\t<guidelines>\n     2\t<addressing_customers>\n     3\t- Always address customers by their first name\n     4\t- Use empathetic language\n..."
}

6. Claude usa la memoria para ayudar:

"Based on your customer service guidelines, I can help you craft a response. Please share the ticket details..."

Para conocer la compatibilidad 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 las operaciones de memoria



Uso básico

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-4-8",
    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 la herramienta

Tu implementación del lado del cliente necesita manejar estos comandos de la 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 de un directorio o el contenido de un archivo con rangos de líneas opcionales:

{
  "command": "view",
  "path": "/memories",
  "view_range": [1, 10] // Optional: view specific lines
}



Valores de retorno

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

Here're the files and directories up to 2 levels deep in {path}, excluding hidden items and node_modules:
{size}    {path}
{size}    {path}/{filename1}
{size}    {path}/{filename2}

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

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

Here's the content of {path} with line numbers:
{line_numbers}{tab}{content}

Formato de números de línea:

• Ancho: 6 caracteres, alineado a la derecha con relleno de espacios
• Separador: Carácter de tabulación entre el número de línea y el contenido
• Indexación: Indexado desde 1 (la primera línea es la línea 1)
• Límite de líneas: 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:

Here's the content of /memories/notes.txt with line numbers:
     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

Crea 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

Reemplaza 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 varias 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 "el archivo no existe".



insert

Inserta 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 "el archivo no existe".



delete

Elimina 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

Renombra o mueve 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

• El origen 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.



Guía de prompting

Esta instrucción se incluye automáticamente en la indicación 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:

Note: when editing your memory folder, always try to keep its content up-to-date, coherent and organized. You can rename or delete files that are no longer relevant. Do not create new files unless necessary.

También puedes guiar lo que Claude escribe en la memoria. Por ejemplo: "Only write down information relevant to <topic> in your memory system."



Consideraciones de seguridad

Estas son preocupaciones de seguridad importantes al implementar tu almacén de memoria:



Información sensible

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



Tamaño del almacenamiento de archivos

Considera hacer seguimiento de los tamaños de los archivos de memoria y evitar 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 la memoria

Considera limpiar periódicamente los archivos de memoria que no se hayan accedido durante un tiempo prolongado.



Protección contra path traversal

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 recorrido
• Presta atención a secuencias de recorrido 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 usa patrones de manejo de errores similares a los de la herramienta de editor de texto. Consulta las secciones individuales de comandos de herramienta anteriores para ver mensajes de error y comportamientos detallados. Los errores comunes incluyen archivo no encontrado, errores de permisos, rutas inválidas y coincidencias de texto duplicadas.



Integración con la edición de contexto

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



Uso con Compactación

La herramienta de memoria también se puede combinar con la 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íficos 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 agénticos 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 a través de los límites de compactación para que nada crítico se pierda en el resumen.



Patrón de desarrollo de software multisesión

Para proyectos de software de larga duración que abarcan múltiples sesiones de agente, los archivos de memoria deben inicializarse deliberadamente, no solo escribirse de manera ad hoc a medida que avanza el trabajo. El patrón a continuación convierte la memoria en un mecanismo de recuperación estructurado, de modo que cada nueva sesión pueda retomar exactamente donde la anterior lo dejó.



Cómo funciona

1. Sesión inicializadora: La primera sesión configura los artefactos de memoria antes de que comience cualquier trabajo sustantivo. Esto incluye un registro de progreso (que rastrea lo que se ha hecho y lo que viene después), una lista de verificación de funcionalidades (que define 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 comienza leyendo esos artefactos de memoria. Esto recupera el estado completo del proyecto en segundos, sin necesidad de volver a explorar la base de código ni retrazar decisiones anteriores.

3. Actualización al final de la sesión: Antes de que termine una sesión, actualiza el registro de progreso con lo que se completó y lo que queda pendiente. Esto asegura que la siguiente sesión tenga un punto de partida preciso.



Principio clave

Trabaja en una funcionalidad a la vez. Solo marca una funcionalidad como completa después de que la verificación de extremo a extremo confirme que funciona, no solo después de que el código esté escrito. Esto mantiene el registro de progreso confiable y evita que la expansión del alcance se acumule a lo largo de las sesiones.



Próximos pasos