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 el contexto del proyecto en múltiples ejecuciones de agentes
• Aprender de interacciones, decisiones y comentarios pasados
• 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 hacer referencia a esos recuerdos en conversaciones futuras 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 herramientas 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 herramientas 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 cualquier contexto anterior."

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:

"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 Opus 4.6 (claude-opus-4-6)
• 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)
• Claude Sonnet 4.6 (claude-sonnet-4-6)
• 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)

Primeros pasos

Para usar la herramienta de memoria:

1. Añade la herramienta de memoria a tu solicitud
2. Implementa manejadores del lado del cliente para operaciones de memoria

Uso básico

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "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"
        }]
    }'

Comandos de herramientas

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

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

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 por humanos (por ejemplo, 5.5K, 1.2M)
• Excluye elementos ocultos (archivos que comienzan con .) y node_modules
• Usa carácter de tabulación entre tamaño y 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, alineados a la derecha con relleno de espacios
• Separador: Carácter de tabulación entre número de línea y contenido
• Indexación: Indexada en 1 (la primera línea es la línea 1)
• Límite de línea: 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

Crear 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

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

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

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

delete

Eliminar 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

Renombrar o mover 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.

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 consideraciones 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 y evitar que los archivos crezcan demasiado. Considera añadir 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 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 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 patrones de manejo de errores similares a la herramienta de editor de texto. Consulta las secciones de comandos de herramientas individuales anteriores para mensajes de error detallados y comportamientos. Los errores comunes incluyen archivo no encontrado, errores de permisos, rutas inválidas y coincidencias de texto duplicadas.

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 la conversación crece más allá de un umbral configurado. Esta combinación permite flujos de trabajo de 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 solicita 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 se borren los resultados de herramientas, Claude puede recuperar la información almacenada de archivos de memoria cuando 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 y decisiones pasadas incluso después de que los resultados de herramientas se hayan eliminado
• Mantener contexto coherente en 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

Ejemplo de flujo de trabajo

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

1. Claude realiza numerosas ediciones en 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 gestionando tanto el contexto activo como la memoria persistente

Configuración

Para usar ambas funciones juntas:

response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=4096,
    messages=[...],
    tools=[
        {"type": "memory_20250818", "name": "memory"},
        # Your other tools
    ],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 100000},
                "keep": {"type": "tool_uses", "value": 3},
            }
        ]
    },
)

También puedes excluir llamadas de herramientas 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"]}]
}

Usar con Compactación

La herramienta de memoria también se puede emparejar con compactación, que proporciona resumen del contexto de conversación anterior del lado del servidor. Mientras que la edición de contexto borra resultados de herramientas específicos del lado del cliente, la compactación automáticamente resume toda la conversación del lado del servidor cuando se acerca al límite de la ventana de contexto.

Para flujos de trabajo de agentes 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 en los límites de compactación para que nada crítico se pierda en el resumen.