Usar memoria

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 sus aprendizajes entre sesiones: preferencias del usuario, convenciones de proyectos, errores anteriores y contexto del dominio.

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 puede ser accedida y editada directamente a través de la API o Console, permitiendo ajustes, importación y exportación de memorias.

Cada cambio a una memoria crea una memory_version 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=$(curl -fsS https://api.anthropic.com/v1/memory_stores \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<EOF
{
  "name": "User Preferences",
  "description": "Per-user preferences and project context."
}
EOF
)
store_id=$(jq -r '.id' <<< "$store")
echo "$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:

Adjuntar 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 del 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.

Inspeccionar y corregir memoria

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

Listar memorias

List no devuelve contenido de memoria, solo metadatos de objetos. 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 del documento.

Escribir un documento

Usa memories.write para hacer upsert de un documento por ruta. Si nada existe en la ruta, se crea; si un documento ya existe allí, su contenido se reemplaza. Para mutar un documento 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 Update a continuación).

Crear solo si la ruta está libre

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

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

Actualizar

memories.update() modifica un documento 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 un documento a una ruta de archivo:

Ediciones de contenido seguras (concurrencia optimista)

Para editar el contenido de un documento 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 el documento e intentas de nuevo contra el estado fresco.

Eliminar un documento

Opcionalmente pasa expected_content_sha256 para una eliminación condicional.

Versiones de memoria

Cada mutación a una memoria crea una memory version 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 endpoints 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 endpoints 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 recientes 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 registro 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, o solicitudes de eliminación de usuarios. Redactar borra completamente content, content_sha256, content_size_bytes, y path; todos los demás campos, incluyendo el actor y las marcas de tiempo, se preservan.