Herramienta de memoria

La herramienta de memoria permite que Claude almacene y recupere información entre conversaciones en un directorio de archivos de memoria. Claude puede crear, leer, actualizar y eliminar archivos que persisten entre sesiones, acumulando conocimiento con el tiempo sin mantener todo en la "context window" (ventana de contexto).

La memoria admite la recuperación de contexto justo a tiempo. En lugar de cargar toda la información relevante de antemano, un agente registra lo que aprende en archivos de memoria y los vuelve a leer cuando los necesita. Esto mantiene el contexto activo enfocado en la tarea actual, lo cual es importante para sesiones de larga duración que de otro modo saturarían 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: Claude solicita operaciones de archivo y tu aplicación las ejecuta. 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 sesiones de agente
• Aplicar lecciones de interacciones, decisiones y comentarios anteriores a nuevas tareas
• Construir una base de conocimiento con el tiempo



Cómo funciona

Cuando la herramienta de memoria está habilitada, Claude revisa automáticamente su directorio de memoria antes de comenzar una tarea. Mientras trabaja, Claude almacena lo que aprende en archivos bajo /memories y los vuelve a leer en conversaciones posteriores para continuar el trabajo anterior.

Dado que la herramienta de memoria es del lado del cliente, Claude solo solicita operaciones de memoria. Tu aplicación ejecuta cada solicitud contra el almacenamiento que controlas y devuelve el resultado en un bloque tool_result (consulta Manejar llamadas a herramientas). La ruta /memories es un prefijo que tu manejador asigna a almacenamiento real, como un directorio por usuario o claves en una base de datos. La memoria reside completamente en tu aplicación. Una conversación posterior continúa desde la misma memoria cuando envía la misma entrada de tools y tu manejador sirve el mismo almacén. Por seguridad, restringe todas las operaciones de memoria al directorio /memories (consulta Protección contra path traversal).



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

Una interacción típica se ve así:

1. Solicitud del usuario:

"Help me respond to this customer service ticket."

2. Claude revisa 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..."

La herramienta de memoria está disponible en todos los modelos Claude 4 y posteriores. Para ver la lista completa de herramientas proporcionadas por Anthropic, consulta la Referencia de herramientas.



Primeros pasos

La herramienta de memoria está disponible de forma general en la API de Messages: no se requiere ningún encabezado beta. Usarla requiere dos pasos:

1. Agrega la herramienta de memoria a tu solicitud. La entrada de tools {"type": "memory_20250818", "name": "memory"} es toda la configuración: el name debe ser memory, y no defines un esquema de entrada para una herramienta proporcionada por Anthropic.
2. Implementa un manejador del lado del cliente para cada comando de memoria. Tu manejador debe rechazar rutas fuera de /memories, así que lee Protección contra path traversal antes de escribirlo.



Uso básico

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=2048,
    messages=[
        {
            "role": "user",
            "content": "Help me respond to this customer service ticket.",
        }
    ],
    tools=[{"type": "memory_20250818", "name": "memory"}],
)

print(message)



Implementar el manejador de memoria

La respuesta de Claude a una solicitud como la anterior termina con un bloque tool_use que solicita una operación de memoria, como view /memories. Tu aplicación ejecuta la operación y devuelve el resultado en un bloque tool_result, luego envía la conversación de vuelta para que Claude pueda continuar: el bucle de uso de herramientas estándar.

Cuatro SDKs proporcionan helpers para la herramienta de memoria que manejan la interfaz de la herramienta y el bucle. Crea una subclase de BetaAbstractMemoryTool (Python y C#), usa betaMemoryTool (TypeScript) o implementa BetaMemoryToolHandler (Java) para respaldar la memoria con tu propio almacenamiento, como archivos en disco, una base de datos, almacenamiento en la nube o archivos cifrados. Python y TypeScript también incluyen una implementación lista para usar basada en el sistema de archivos local, BetaLocalFilesystemMemoryTool. Las interfaces del helper y del tool-runner residen en el espacio de nombres beta de cada SDK, aunque la herramienta de memoria en sí está disponible de forma general. Los SDKs de Go y Ruby no tienen helper de memoria, por lo que esos ejemplos ejecutan el bucle de uso de herramientas por sí mismos, y PHP envuelve tu closure de manejador en su BetaRunnableTool genérico. Los tres usan un almacén en memoria que debes reemplazar con tu propio almacenamiento.

import anthropic
from anthropic.tools import BetaLocalFilesystemMemoryTool

client = anthropic.Anthropic()
memory = BetaLocalFilesystemMemoryTool(base_path="./memory")

runner = client.beta.messages.tool_runner(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Remember that customer Acme Corp prefers email follow-ups.",
        }
    ],
    tools=[memory],
)

final_message = runner.until_done()
print(final_message.content)

Los almacenes en memoria de los ejemplos de Go, PHP y Ruby los mantienen autocontenidos: cada uno despacha según el campo command en el input del bloque tool_use y devuelve las cadenas descritas en Comandos de la herramienta. Un manejador de producción también necesita la validación de rutas que estos almacenes de demostración omiten. Para ver los ejemplos completos propios de los SDKs, consulta:

• Python: examples/memory/basic.py
• TypeScript: examples/tools-helpers-memory.ts
• C#: MemoryToolExample
• Java: BetaMemoryToolExample.java



Comandos de la herramienta

Tu implementación del lado del cliente debe manejar los siguientes comandos. Estas especificaciones describen los comportamientos y cadenas de retorno recomendados: Claude lee cualquier texto que contenga el resultado de tu herramienta, por lo que puedes devolver cadenas diferentes si tu aplicación lo necesita.



view

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

{
  "command": "view",
  "path": "/memories/notes.txt",
  "view_range": [1, 10]
}

view_range es opcional y se aplica a las vistas de archivos de texto: [start_line, end_line] devuelve esas líneas, y [start_line, -1] devuelve todo desde start_line hasta el final del archivo.



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}\t{path}
{size}\t{path}/{filename1}
{size}\t{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

El primer view de /memories en un almacén vacío no es un error. Las herramientas de memoria de sistema de archivos local de los SDKs (BetaLocalFilesystemMemoryTool) crean la raíz de memoria antes de la primera llamada de Claude y devuelven el encabezado del listado seguido de una sola línea de tamaño y ruta para el directorio vacío en sí.

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, alineados 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: Basada en 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

La descripción de la herramienta de Claude también indica que view muestra archivos de imagen (.jpg, .jpeg y .png) y trunca la vista de texto de archivos de más de 16,000 caracteres. Espera llamadas a view sobre rutas de imágenes y vistas de seguimiento con rangos para archivos largos.



Manejo de errores

• El archivo o 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"

La descripción de la herramienta de Claude indica que create "crea o sobrescribe" un archivo, así que espera llamadas a create sobre rutas que ya existen. Devolver el error es el comportamiento de referencia, y sobrescribir en su lugar es una opción de implementación válida.



str_replace

Reemplaza texto en un archivo:

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

new_str es opcional para str_replace: cuando se omite, old_str se elimina sin reemplazo.



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"
}

insert_text se inserta después de la línea insert_line, y 0 inserta al principio del archivo.



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 no vá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 o directorio no existe: "Error: The path {path} does not exist"



Manejo de directorios

Elimina el directorio y todo su contenido de forma recursiva. La descripción de la herramienta le indica a Claude que no puede eliminar el directorio /memories en sí, así que rechaza un delete cuya ruta sea la raíz de memoria.



rename

Renombra o mueve un archivo o 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. La descripción de la herramienta le indica a Claude que no puede renombrar el directorio /memories en sí, así que rechaza un rename cuyo old_path sea la raíz de memoria.



Guía de prompting

Cuando la herramienta de memoria está presente en los tools de tu solicitud, la API agrega automáticamente esta instrucción a la indicación del sistema. No necesitas enviarla tú mismo:

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.

La descripción de la herramienta de Claude ya le indica que mantenga el directorio de memoria organizado, por lo que no necesitas repetir esa instrucción. Si Claude aún crea archivos de memoria desordenados, puedes reforzarlo en tu prompt:

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: "Solo anota información relevante para <topic> en tu sistema de memoria."



Consideraciones de seguridad

Tu aplicación ejecuta cada operación de archivo que Claude solicita, por lo que estas salvaguardas son tu responsabilidad:



Información sensible

Claude generalmente se niega a escribir información sensible en archivos de memoria. Para garantías más sólidas, agrega validación que elimine datos sensibles antes de que tu manejador escriba el archivo.



Tamaño de almacenamiento de archivos

Realiza un seguimiento de los tamaños de los archivos de memoria y limita cuánto puede crecer un archivo. Considera limitar cuántos caracteres devuelve el comando view y deja que Claude pagine el resto con view_range.



Expiración de memoria

Elimina periódicamente los archivos de memoria a los que no se ha accedido en mucho tiempo.



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
• Vigila las 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. Los mensajes de error de cada comando se listan en Comandos de la herramienta. Para devolver un error a Claude, establece is_error en true en el resultado de la herramienta y coloca el mensaje en content:

{
  "type": "tool_result",
  "tool_use_id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "content": "Error: The path /memories/notes.txt does not exist",
  "is_error": true
}



Integración con 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 puede combinarse con la compactación, que resume el contexto de conversación más antiguo del lado del servidor. La edición de contexto borra resultados de herramientas específicos en el cliente. La compactación resume automáticamente toda la conversación en el servidor cuando la conversación se acerca al límite de la ventana de contexto.

Para agentes de larga duración, considera usar ambas: la compactación mantiene el contexto activo pequeño sin contabilidad del lado del cliente, y la memoria preserva la información que debe sobrevivir al resumen.



Patrón de desarrollo de software multisesión

Para proyectos de software que abarcan múltiples sesiones de agente, configura los archivos de memoria deliberadamente en lugar de escribirlos de forma improvisada a medida que avanza el trabajo. El siguiente patrón convierte la memoria en un mecanismo de recuperación: cada nueva sesión se reanuda desde el estado que registró la anterior.



Cómo funciona el patrón

1. Sesión inicializadora: La primera sesión configura los archivos 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 archivos de memoria. Esto restaura el estado del proyecto sin 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. Marca una funcionalidad como completa solo después de que la verificación de extremo a extremo confirme que funciona, no cuando el código esté escrito. Esto mantiene el registro de progreso preciso de sesión a sesión.



Próximos pasos