Saltar al contenido principal

Memoria y edición de contexto

Avanzado

Un agente de larga duración tiene dos enemigos: olvida lo que aprendió en el momento en que termina la conversación, y su ventana de contexto se llena de salida de herramientas obsoleta hasta que desborda. Anthropic ofrece una primitiva para cada uno — la memory tool (persistencia) y la edición de contexto (poda) — y están diseñadas para usarse juntas.

What you'll learn
  • Qué es la memory tool: un almacén de archivos del lado del cliente en /memories que implementas tú, no Anthropic
  • Los seis comandos que tu handler debe responder: view, create, str_replace, insert, delete, rename
  • Por qué la validación de path-traversal es innegociable cuando lo conectas
  • Cómo la edición de contexto limpia automáticamente resultados de herramientas antiguos una vez que el contexto cruza un umbral de tokens
  • Cómo combinar ambos bajo un único encabezado beta, y los detalles a vigilar con el cacheo y el orden

Dos problemas, dos herramientas​

Mantén las dos ideas separadas en tu cabeza:

  • Memory tool = persistencia entre sesiones. Claude lee y escribe archivos; tú los almacenas.
  • Edición de contexto = poda dentro de una sesión. La API descarta resultados de herramientas obsoletos del prompt antes de que lleguen a Claude.

Esta página se complementa con Prompt Caching y la economía de tokens para el lado de los costes, y con Context Engineering y los harnesses de agentes de larga duración para el porqué.

Vocabulario de memoria y contexto
Pulsa Intro o Espacio para girar la tarjeta. Usa las flechas izquierda y derecha para moverte entre las tarjetas.Término mostrado.
1 / 5

La memory tool es una herramienta que implementas tú​

Esto confunde a la gente: habilitar la memory tool no te da almacenamiento alojado por Anthropic. Es una herramienta del lado del cliente. Claude emite llamadas de herramienta como view o create; tu aplicación las ejecuta contra el backend que elijas — archivos locales, una base de datos, blobs cifrados, almacenamiento en la nube — y devuelve el resultado. Tú controlas dónde viven los bytes (que es también por qué es apta para Zero-Data-Retention).

Cuando la herramienta está habilitada, Anthropic inyecta una instrucción de sistema que le indica a Claude que revise su directorio de memoria antes de hacer cualquier otra cosa, y que registre el progreso a medida que trabaja para que nada se pierda si el contexto se reinicia.

Paso 1 — habilitar la herramienta​

Añade la herramienta a tu solicitud. La cadena de tipo es la versión fechada memory_20250818.

import anthropic

client = anthropic.Anthropic()

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

print(message)

Los SDK oficiales incluyen helpers de memoria para que no tengas que armar a mano la interfaz de la herramienta — extiende BetaAbstractMemoryTool (Python, C#), usa betaMemoryTool (TypeScript), o implementa BetaMemoryToolHandler (Java). Te dan un hook limpio donde conectas tu almacenamiento.

Paso 2 — responder a los seis comandos​

Tu handler debe implementar estos. Las cadenas que Claude espera de vuelta son específicas: hazlas coincidir para que el modelo interprete los resultados correctamente.

Guided walkthrough1 of 6
  1. Lista un directorio (archivos hasta 2 niveles de profundidad, con tamaños legibles por humanos) o devuelve el contenido de un archivo con números de línea indexados desde 1. view_range opcional para leer un fragmento.

Un view real del directorio devuelve algo como esto — fíjate en el encabezado literal y los tamaños separados por tabulaciones, que el modelo está entrenado para analizar:

Here're the files and directories up to 2 levels deep in /memories, excluding hidden items and node_modules:
4.0K	/memories
1.5K	/memories/customer_service_guidelines.xml
2.0K	/memories/refund_policies.xml

Paso 3 — bloquear las rutas (no te saltes esto)​

La memory tool permite que un modelo emita cadenas de ruta arbitrarias. Una conversación envenenada o un payload de inyección de prompts puede intentar escapar de /memories y leer o sobrescribir archivos en otra parte de tu máquina. Trata cada ruta entrante como hostil.

Watch out
  • Rechaza cualquier ruta que no resuelva a un punto dentro de /memories.
  • Canonicaliza antes de comprobar: en Python, Path(p).resolve() y luego verifica que .relative_to(memories_root) no lance una excepción.
  • Bloquea ../, ..\ y traversal codificado en URL como %2e%2e%2f.
  • Limita los tamaños de archivo y la longitud de lectura para que un agente descontrolado no pueda agotar el disco ni inflar el siguiente prompt.

Este validador es lo que decide la partida: fíjalo y pruébalo antes de desplegar cualquier otra cosa:

Guard contra path-traversal (Python)

from pathlib import Path

MEMORY_ROOT = Path("/srv/agent/memories").resolve()

def safe_path(requested: str) -> Path:
  # Map the model's /memories/... onto your real root, then prove containment.
  rel = requested.removeprefix("/memories").lstrip("/")
  candidate = (MEMORY_ROOT / rel).resolve()
  candidate.relative_to(MEMORY_ROOT)  # raises ValueError if it escaped
  return candidate

La edición de contexto evita que la ventana desborde​

La memoria resuelve el olvido. El problema opuesto — una ventana de contexto atiborrada de bloques tool_result antiguos de hace 40 búsquedas web — es lo que resuelve la edición de contexto. Una vez que el prompt cruza un umbral de tokens, la API limpia los resultados de herramientas más antiguos (reemplazándolos con un breve marcador para que Claude sepa que se eliminaron) antes de que el prompt se envíe al modelo. Tu cliente conserva el historial completo y sin editar; solo se recorta lo que llega al modelo.

Funciona sobre un encabezado beta:

anthropic-beta: context-management-2025-06-27

Lo configuras con un array context_management.edits. La estrategia principal es clear_tool_uses_20250919:

message = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=2048,
    betas=["context-management-2025-06-27"],
    messages=[...],
    tools=[{"type": "memory_20250818", "name": "memory"}],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 30000},  # start clearing past 30k
                "keep": {"type": "tool_uses", "value": 3},            # always keep the last 3
                "clear_at_least": {"type": "input_tokens", "value": 5000},
                "exclude_tools": ["memory"],                          # never clear memory calls
                "clear_tool_inputs": False,                           # keep the call args, drop results
            }
        ]
    },
)

Qué significan los parámetros:

ParámetroPredeterminadoQué controla
trigger100.000 tokens de entradaCuándo se activa la limpieza
keep3 usos de herramientaCuántos pares recientes de uso/resultado de herramienta se preservan siempre
clear_at_leastningunoTokens mínimos liberados por activación: úsalo para que una invalidación de caché realmente valga la pena
exclude_toolsningunoHerramientas que nunca se limpian (p. ej. memory, web_search)
clear_tool_inputsfalseSi también descartar los argumentos de la llamada de la herramienta, no solo el resultado

La respuesta te dice lo que hizo, bajo context_management.applied_edits — p. ej. cleared_tool_uses y cleared_input_tokens — para que puedas registrar cuánto se recuperó.

Existe una estrategia hermana, clear_thinking_20251015, que poda bloques antiguos de extended-thinking. Si usas ambas, lista clear_thinking_20251015 primero en el array edits.

Pro tip
  • Limpiar resultados de herramientas invalida cualquier prefijo de prompt-cache en el punto de limpieza: combínalo con clear_at_least para pagar esa invalidación solo cuando estés liberando un fragmento significativo.
  • exclude_tools: ["memory"] es la jugada habitual: quieres que las notas propias del agente persistan, no que se barran junto con resultados de búsqueda obsoletos.
  • La edición de contexto (recorte del lado del cliente) y la compactación (resumen del lado del servidor) son funciones distintas: para ejecuciones muy largas puedes combinar ambas.

Por qué combinarlas — los números​

Usadas juntas, las dos funciones permiten que un agente se ejecute mucho más allá de una sola ventana de contexto: la edición de contexto mantiene la ventana viva ligera, y todo lo que importa se escribe en memoria antes de que se limpiara. Anthropic reporta que combinar memoria con edición de contexto dio una mejora del 39% en una evaluación de búsqueda agéntica, y que la edición de contexto por sí sola redujo el uso de tokens en un 84% en una prueba de búsqueda web de 100 turnos.

Un patrón que funciona: el registro de proyecto multisesión​

El uso más limpio de la memoria es inicializarla de forma deliberada en lugar de escribir archivos sobre la marcha:

Guided walkthrough1 of 4
  1. Antes de cualquier trabajo real, escribe un registro de progreso, una lista de verificación de funciones y una nota que apunte a cualquier script de arranque que el proyecto necesite.

Pon a prueba tu comprensión​

Check yourself

0/3
  1. ¿Dónde se almacenan realmente los datos de la memory tool?
  2. ¿Qué elimina la estrategia clear_tool_uses_20250919 de la edición de contexto?
  3. ¿Por qué debes validar cada ruta que recibe la memory tool?

Fuentes y lecturas adicionales​