Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
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 ventana de contexto.
La memoria admite la recuperación de contexto justo a tiempo. En lugar de cargar toda la información relevante por adelantado, un agente registra lo que aprende en archivos de memoria y los vuelve a leer bajo demanda. 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.
Cuando la herramienta de memoria está habilitada, Claude verifica automáticamente su directorio de memoria antes de comenzar una tarea. A medida que trabaja, Claude almacena lo que aprende en archivos bajo /memories y los vuelve a leer en conversaciones posteriores para continuar el trabajo anterior.
Debido a 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 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 path traversal).
Una interacción típica se ve así:
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..."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.
La herramienta de memoria está disponible de forma general en la Messages API: no se requiere ningún encabezado beta. Usarla requiere dos pasos:
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./memories, así que lee Protección contra path traversal antes de escribirlo.client = anthropic.Anthropic()
message = client.messages.create(
model="claude-opus-5",
max_tokens=2048,
messages=[
{
"role": "user",
"content": "Help me respond to this customer service ticket.",
}
],
tools=[{"type": "memory_20250818", "name": "memory"}],
)
print(message)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 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 de 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í está disponible de forma general. Los SDKs de Go y Ruby no tienen ayudante 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 tú 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",
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 de los propios SDKs, consulta:
Tu implementación del lado del cliente debe manejar los siguientes comandos. Estas especificaciones describen los comportamientos recomendados y las cadenas de retorno: Claude lee cualquier texto que contenga el resultado de tu herramienta, por lo que puedes devolver cadenas diferentes si tu aplicación lo necesita.
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.
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}5.5K, 1.2M).) y node_modulesEl 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 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:
"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 hundredLa descripción de la herramienta de Claude también dice 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 en rutas de imágenes y vistas posteriores con rangos de archivos largos.
"The path {path} does not exist. Please provide a valid path."Crea un archivo nuevo:
{
"command": "create",
"path": "/memories/notes.txt",
"file_text": "Meeting notes:\n- Discussed project timeline\n- Next steps defined\n"
}"File created successfully at: {path}""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 en 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.
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.
"The memory file has been edited." seguido de un fragmento del archivo editado con números de línea"Error: The path {path} does not exist. Please provide a valid path.""No replacement was performed, old_str `\{old_str}` did not appear verbatim in {path}."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"Si la ruta es un directorio, devuelve un error de "el archivo no existe".
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.
"The file {path} has been edited.""Error: The path {path} does not exist""Error: Invalid `insert_line` parameter: {insert_line}. It should be within the range of lines of the file: [0, {n_lines}]"Si la ruta es un directorio, devuelve un error de "el archivo no existe".
Elimina un archivo o directorio:
{
"command": "delete",
"path": "/memories/old_file.txt"
}"Successfully deleted {path}""Error: The path {path} does not exist"Elimina el directorio y todo su contenido de forma recursiva. La descripción de la herramienta le dice a Claude que no puede eliminar el propio directorio /memories, así que rechaza un delete cuya ruta sea la raíz de memoria.
Renombra o mueve un archivo o directorio:
{
"command": "rename",
"old_path": "/memories/draft.txt",
"new_path": "/memories/final.txt"
}"Successfully renamed {old_path} to {new_path}""Error: The path {old_path} does not exist""Error: The destination {new_path} already exists"Renombra el directorio. La descripción de la herramienta le dice a Claude que no puede renombrar el propio directorio /memories, así que rechaza un rename cuyo old_path sea la raíz de memoria.
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 escribe información relevante a <topic> en tu sistema de memoria."
Tu aplicación ejecuta cada operación de archivo que Claude solicita, por lo que estas salvaguardas son tu responsabilidad:
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 los datos sensibles antes de que tu manejador escriba el archivo.
Haz 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.
Elimina periódicamente los archivos de memoria a los que no se ha accedido en mucho tiempo.
Considera estas salvaguardas:
/memories../, ..\\ u otros patrones de traversal%2e%2e%2f)pathlib.Path.resolve() y relative_to() de Python)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
}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.
La herramienta de memoria también se puede combinar 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 ambos: 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 a la sumarización.
Para proyectos de software que abarcan múltiples sesiones de agente, configura los archivos de memoria deliberadamente en lugar de escribirlos ad hoc 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.
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 sigue), 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.
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.
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. Esto garantiza que la siguiente sesión tenga un punto de partida preciso.
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.
Ejecuta comandos de shell en una sesión bash persistente.
Gestiona automáticamente el contexto de la conversación a medida que crece con la edición de contexto.
Compactación de contexto del lado del servidor para gestionar conversaciones largas que se acercan a los límites de la ventana de contexto.
Directorio de herramientas proporcionadas por Anthropic y referencia de propiedades opcionales de definición de herramientas.
Was this page helpful?