Usar memoria de agentes

Usar memoria

Agent Memory es una característica de Research Preview. Solicita acceso para probarla.

Las sesiones de la API de Managed Agents son efímeras por defecto. Cuando una sesión termina, todo lo que el agente aprendió desaparece. Los almacenes de memoria permiten que el agente lleve aprendizajes entre sesiones: preferencias del usuario, convenciones de proyectos, errores anteriores y contexto de dominio.

Todas las solicitudes de la API de Managed Agents requieren el encabezado beta managed-agents-2026-04-01. Se necesita un encabezado beta adicional para características de research preview. El SDK establece estos encabezados beta automáticamente.

Descripción general

Un almacén de memoria es una colección de documentos de texto con alcance de espacio de trabajo optimizada para Claude. Cuando uno o más almacenes de memoria se adjuntan a una sesión, el agente verifica automáticamente los almacenes antes de comenzar una tarea y escribe aprendizajes duraderos cuando termina - no se necesita solicitud o configuración adicional de tu parte.

Cada memoria en un almacén se puede acceder y editar directamente a través de la API o Console, permitiendo ajustes, importación y exportación de memorias.

Cada cambio en una memoria crea una versión de memoria inmutable para soportar auditoría y reversión de cambios de memoria.

Crear un almacén de memoria

Dale al almacén un name y una description. La descripción se pasa al agente, diciéndole qué contiene el almacén.

store = client.beta.memory_stores.create(
    name="User Preferences",
    description="Per-user preferences and project context.",
)
print(store.id)  # memstore_01Hx...

El id del almacén de memoria (memstore_...) es lo que pasas al adjuntar el almacén a una sesión.

Sembrarlo con contenido (opcional)

Precarga un almacén con material de referencia antes de que se ejecute cualquier agente:

Las memorias individuales dentro del almacén están limitadas a 100KB (~25K tokens). Estructura la memoria como muchos archivos pequeños y enfocados, no unos pocos grandes.

Adjuntar un almacén de memoria a una sesión

Los almacenes de memoria se adjuntan en el array resources[] de la sesión.

Opcionalmente incluye un prompt si deseas proporcionar instrucciones específicas de la sesión a Claude sobre cómo usar este almacén de memoria. Se proporciona a Claude además del name y description del almacén de memoria, y está limitado a 4.096 caracteres.

También puedes configurar access. Por defecto es read_write, pero también se soporta read_only (mostrado explícitamente en el ejemplo a continuación).

Se soporta un máximo de 8 almacenes de memoria por sesión. Adjunta múltiples almacenes cuando diferentes partes de la memoria tienen diferentes propietarios o reglas de acceso. Razones comunes:

Material de referencia compartido - un almacén de solo lectura adjunto a muchas sesiones (estándares, convenciones, conocimiento de dominio), mantenido separado de los aprendizajes de lectura-escritura propios de cada sesión.
Mapeo a la estructura de tu producto - un almacén por usuario final, por equipo o por proyecto, mientras se comparte una única configuración de agente.
Ciclos de vida diferentes - un almacén que sobrevive a cualquier sesión individual, o uno que deseas archivar en tu propio cronograma.

Herramientas de memoria

Cuando los almacenes de memoria se adjuntan a una sesión, el agente obtiene automáticamente acceso a herramientas de memoria. Las interacciones del agente con almacenes de memoria se registran como eventos agent.tool_use en el flujo de eventos.

Herramienta	Descripción
`memory_list`	Enumera memorias en un almacén, opcionalmente filtradas por prefijo de ruta.
`memory_search`	Búsqueda de texto completo en contenidos de memoria.
`memory_read`	Lee el contenido de una memoria.
`memory_write`	Crea o sobrescribe una memoria en una ruta.
`memory_edit`	Modifica una memoria existente.
`memory_delete`	Elimina una memoria.

Ver y editar memorias

Los almacenes de memoria se pueden gestionar directamente a través de la API. Úsalo para construir flujos de trabajo de revisión, corregir memorias malas o sembrar almacenes antes de que se ejecute cualquier sesión.

Enumerar memorias

La enumeración no devuelve contenido de memoria, solo metadatos de objeto. Usa path_prefix para listas con alcance de directorio (incluye una barra diagonal final: /notes/ coincide con /notes/a.md pero no con /notes_backup/old.md).

Leer una memoria

Obtener una memoria individual devuelve el contenido completo.

Crear una memoria

Usa memories.write para hacer upsert de una memoria por ruta. Si nada existe en la ruta, se crea; si una memoria ya existe allí, su contenido se reemplaza. Para mutar una memoria existente por mem_... ID (por ejemplo, para renombrar su ruta o aplicar de forma segura una edición de contenido), usa memories.update en su lugar (ver Actualizar una memoria a continuación).

Escrituras seguras (concurrencia optimista)

Pasa precondition={"type": "not_exists"} a memories.write para hacerlo una protección de solo creación. Si una memoria ya existe en la ruta, la escritura devuelve 409 memory_precondition_failed en lugar de reemplazarla. Úsalo cuando estés sembrando un almacén y desees evitar sobrescribir contenido existente.

Para editar de forma segura una memoria existente (leer, modificar, escribir de vuelta sin sobrescribir un cambio concurrente), usa memories.update con una precondición content_sha256 en su lugar. Ver Actualizar una memoria a continuación.

Actualizar una memoria

memories.update() modifica una memoria existente por su mem_... ID. Puedes cambiar content, path (un renombre), o ambos en una sola llamada.

Renombrar a una ruta ocupada devuelve 409 conflict. El llamador debe eliminar o renombrar el bloqueador primero, o pasar precondition={"type": "not_exists"} para hacer que el renombre sea una no-op si algo ya existe en el destino.

El ejemplo a continuación renombra una memoria a una ruta de archivo:

Ediciones de contenido seguras (concurrencia optimista)

Para editar el contenido de una memoria sin sobrescribir una escritura concurrente, pasa una precondición content_sha256. La actualización solo se aplica si el hash almacenado aún coincide con el que leíste; en caso de desajuste devuelve 409 memory_precondition_failed, en cuyo punto relees la memoria e intentas de nuevo contra el estado fresco.

Eliminar una memoria

Opcionalmente pasa expected_content_sha256 para una eliminación condicional.

Auditar cambios de memoria

Cada mutación a una memoria crea una versión de memoria inmutable (memver_...). Las versiones se acumulan durante la vida útil de la memoria padre y forman la superficie de auditoría y reversión debajo de ella. La llamada memories.retrieve en vivo siempre devuelve el head actual; los puntos finales de versión te dan el historial completo.

Se escribe una nueva versión en cada mutación:

El primer memories.write a una ruta crea una versión con operation: "created".
memories.update que cambia content, path, o ambos crea una versión con operation: "modified".
memories.delete crea una versión con operation: "deleted".

Usa los puntos finales de versión para auditar qué usuario o agente cambió qué y cuándo, para inspeccionar o restaurar una instantánea anterior, y para eliminar contenido sensible del historial con redact.

Listar versiones

Listar metadatos de versión paginados para una tienda, más reciente primero. Filtrar por memory_id, operation (created, modified, o deleted), session_id, api_key_id, o un rango de tiempo created_at_gte/created_at_lte. La respuesta de lista no incluye el cuerpo content; obtén versiones individuales con retrieve cuando necesites el contenido completo.

Recuperar una versión

Obtener una versión individual devuelve los mismos campos que la respuesta de lista más el cuerpo content completo.

Redactar una versión

Redactar limpia el contenido de una versión histórica mientras se preserva el rastro de auditoría (quién hizo qué, cuándo). Úsalo para flujos de trabajo de cumplimiento normativo, como eliminar secretos filtrados, información de identificación personal (PII), o solicitudes de eliminación de usuarios. Redactar borra completamente content, content_sha256, content_size_bytes, y path; todos los demás campos, incluido el actor y las marcas de tiempo, se preservan.

client.beta.memory_stores.memories.write(
    memory_store_id=store.id,
    path="/formatting_standards.md",
    content="All reports use GAAP formatting. Dates are ISO-8601...",
)

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    resources=[
        {
            "type": "memory_store",
            "memory_store_id": store.id,
            "access": "read_write",
            "prompt": "User preferences and project context. Check before starting any task.",
        }
    ],
)

page = client.beta.memory_stores.memories.list(
    store.id,
    path_prefix="/",
)
for memory in page.data:
    print(
        f"{memory.path}  ({memory.size_bytes} bytes, sha={memory.content_sha256[:8]})"
    )

mem = client.beta.memory_stores.memories.write(
    memory_store_id=store.id,
    path="/preferences/formatting.md",
    content="Always use tabs, not spaces.",
)

client.beta.memory_stores.memories.write(
    memory_store_id=store.id,
    path="/preferences/formatting.md",
    content="Always use 2-space indentation.",
    precondition={"type": "not_exists"},
)

client.beta.memory_stores.memories.update(
    memory_id=mem.id,
    memory_store_id=store.id,
    content="CORRECTED: Always use 2-space indentation.",
    precondition={"type": "content_sha256", "content_sha256": mem.content_sha256},
)