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.

La herramienta de memoria funciona 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 contexto del proyecto entre múltiples ejecuciones de agentes
• Aprender de interacciones, decisiones y retroalimentación pasadas
• Construir bases de conocimiento a lo largo del tiempo
• Habilitar 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, y luego hacer referencia a esos recuerdos en futuras conversaciones para manejar tareas similares de manera más efectiva o continuar donde lo dejó.

Dado que esta es una herramienta del lado del cliente, Claude realiza llamadas de herramienta para realizar operaciones de memoria, y tu aplicación ejecuta esas operaciones localmente. Esto te da control total 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 obtener contexto previo."

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": "Directory: /memories\n- customer_service_guidelines.xml\n- 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": "<guidelines>\n<addressing_customers>\n- Always address customers by their first name\n- Use empathetic language\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..."

Modelos compatibles

La herramienta de memoria está disponible en:

• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Claude Sonnet 4 (claude-sonnet-4-20250514)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001)
• Claude Opus 4.5 (claude-opus-4-5-20251101)
• Claude Opus 4.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (claude-opus-4-20250514)

Primeros pasos

Para usar la herramienta de memoria:

1. Incluye el encabezado beta context-management-2025-06-27 en tus solicitudes de API
2. Agrega la herramienta de memoria a tu solicitud
3. Implementa manejadores del lado del cliente para operaciones de memoria

Uso básico

Comandos de herramienta

Tu implementación del lado del cliente necesita manejar estos comandos de herramienta de memoria:

view

Muestra el contenido del directorio o contenido del archivo con rangos de línea opcionales:

{
  "command": "view",
  "path": "/memories",
  "view_range": [1, 10]  // Opcional: ver líneas específicas
}

create

Crear o sobrescribir un archivo:

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

str_replace

Reemplazar texto en un archivo:

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

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

delete

Eliminar un archivo o directorio:

{
  "command": "delete",
  "path": "/memories/old_file.txt"
}

rename

Renombrar o mover un archivo/directorio:

{
  "command": "rename",
  "old_path": "/memories/draft.txt",
  "new_path": "/memories/final.txt"
}

Orientación de indicaciones

Incluimos automáticamente esta instrucción en el indicador del sistema cuando se incluye la herramienta de memoria:

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 preocupaciones 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 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 permitir que Claude pagine a través del contenido.

Expiración de memoria

Considera limpiar periódicamente archivos de memoria que no hayan 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 los mismos patrones de manejo de errores que la herramienta de editor de texto. Los errores comunes incluyen archivo no encontrado, errores de permisos y rutas inválidas.

Usar con Edición de Contexto

La herramienta de memoria se puede combinar con edición de contexto, que automáticamente borra resultados de herramientas antiguos cuando el contexto de conversación crece más allá de un umbral configurado. Esta combinación permite flujos de trabajo agentes de larga duración que de otro modo excederían los límites de contexto.

Cómo funcionan juntos

Cuando la edición de contexto está habilitada y tu conversación se acerca al umbral de limpieza, Claude recibe automáticamente una notificación de advertencia. Esto le indica a Claude que preserve cualquier información importante de los resultados de herramientas en archivos de memoria antes de que esos resultados se borren de la ventana de contexto.

Después de que los resultados de herramientas se borren, Claude puede recuperar la información almacenada de archivos de memoria siempre que sea necesario, tratando efectivamente la memoria como una extensión de su contexto de trabajo. Esto permite a Claude:

• Continuar flujos de trabajo complejos de múltiples pasos sin perder información crítica
• Hacer referencia a trabajo pasado y decisiones incluso después de que los resultados de herramientas se eliminen
• Mantener contexto coherente entre conversaciones que excederían los límites de contexto típicos
• Construir una base de conocimiento a lo largo del tiempo mientras se mantiene la ventana de contexto activo manejable

Flujo de trabajo de ejemplo

Considera un proyecto de refactorización de código con muchas operaciones de archivo:

1. Claude realiza numerosas ediciones a archivos, generando muchos resultados de herramientas
2. A medida que el contexto crece y se acerca a tu umbral, Claude recibe una advertencia
3. Claude resume los cambios realizados hasta ahora en un archivo de memoria (por ejemplo, /memories/refactoring_progress.xml)
4. La edición de contexto borra automáticamente los resultados de herramientas más antiguos
5. Claude continúa trabajando, haciendo referencia al archivo de memoria cuando necesita recordar qué cambios ya se completaron
6. El flujo de trabajo puede continuar indefinidamente, con Claude administrando tanto el contexto activo como la memoria persistente

Configuración

Para usar ambas características juntas:

También puedes excluir llamadas de herramienta de memoria de ser borradas para asegurar que Claude siempre tenga acceso a operaciones de memoria recientes:

context_management={
    "edits": [
        {
            "type": "clear_tool_uses_20250919",
            "exclude_tools": ["memory"]
        }
    ]
}