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 desde el principio, 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 Ingeniería de contexto efectiva para conocer el patrón más amplio.

La herramienta de memoria opera del lado del cliente: Claude solicita operaciones de archivos 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.

Como 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 tú 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 un almacenamiento real, como un directorio por usuario o claves en una base de datos. La memoria vive completamente en tu aplicación. Una conversación posterior continúa desde la misma memoria cuando envía la misma entrada tools y tu manejador sirve el mismo almacén. Por seguridad, restringe todas las operaciones de memoria al directorio /memories (consulta Protección contra recorrido de rutas).

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

Usar la herramienta de memoria requiere dos pasos:

1. Agrega la herramienta de memoria a tu solicitud. La entrada 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 recorrido de rutas antes de escribirlo.

Uso básico

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-5-5",
    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 SDK proporcionan ayudantes 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 del sistema de archivos local, BetaLocalFilesystemMemoryTool. Las superficies del ayudante y del ejecutor de herramientas viven en el espacio de nombres beta de cada SDK, aunque la herramienta de memoria en sí no requiere un encabezado beta. Los SDK de Go y Ruby no tienen un ayudante de memoria, por lo que esos ejemplos ejecutan el bucle de uso de herramientas por sí mismos, y PHP envuelve el closure de tu manejador en su BetaRunnableTool genérico. Los tres usan un almacén en memoria que reemplazas 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-5-5",
    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 SDK, 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 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 del sistema de archivos local de los SDK (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 propio directorio vacío.

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 los 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 view sobre rutas de imágenes y vistas posteriores por rangos de 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 archivo nuevo:

{
  "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 dice que create "crea o sobrescribe" un archivo, así que espera llamadas 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 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 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 prompts

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 organizado el directorio de memoria, 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: "Only write down information relevant to <topic> in your memory system."

Consideraciones de seguridad

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

Información sensible

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

Tamaño del almacenamiento de archivos

Haz seguimiento del tamaño 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 recorra el resto con view_range.

Expiración de la memoria

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

Protección contra recorrido de rutas

Considera estas protecciones:

• 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 en 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 enumeran 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 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 puede combinarse con la compactación, que resume el contexto más antiguo de la conversación 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 pequeño el contexto activo 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 sustancial. Esto incluye un registro de progreso (que rastrea lo que se ha hecho y lo que sigue), una lista de verificación de funcionalidades (que define el alcance del trabajo) y una referencia a cualquier script de arranque o inicialización que necesite el proyecto.

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 repasar 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 garantiza 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 una verificación de extremo a extremo confirme que funciona, no cuando el código esté escrito. Esto mantiene el registro de progreso preciso de una sesión a otra.

Próximos pasos