Criar um agente com memory stores

Use memory stores quando você precisar de contexto durável que possa ser usado entre usuários, sessões e agentes, e que seja acessível por aplicações externas. Memory stores são úteis para armazenar notas de contas, playbooks de suporte, relatórios de bugs ou qualquer conteúdo que você queira reutilizar em muitas execuções de agentes. Referência da API:

1. Crie o memory store

Crie um store para um corpo durável de conhecimento. Use instructions para descrever como as entradas devem ser escritas e mantidas.

mka1 llm memory-stores create --body '{
  "name": "Acme support memory",
  "description": "Durable support notes for Acme Corp.",
  "instructions": "Keep entries concise. Use one file per durable fact, customer preference, or open issue.",
  "visibility": "workspace",
  "metadata": {
    "account_id": "acct_acme"
  }
}' \
  -H 'X-On-Behalf-Of: <end-user-id>'

A resposta inclui um ID como mem_store_.... visibility determina se este memory store pode ser usado apenas por um X-On-Behalf-Of específico (private) ou se qualquer usuário pode acessá-lo, independentemente do X-On-Behalf-Of (workspace). Veja a referência para criar memory store.

2. Adicione entradas de memória

As entradas são endereçadas por path. Use caminhos previsíveis para que o agente encontre arquivos no store montado.

mka1 llm memory-stores create-entry \
  --memory-store-id mem_store_123 \
  --body '{
    "path": "accounts/acme/preferences.md",
    "content": "# Acme preferences\n\n- Prefer concise weekly status summaries.\n- Escalate production incidents to the on-call channel before creating a ticket.",
    "metadata": {
      "kind": "customer-preferences"
    }
  }' \
  -H 'X-On-Behalf-Of: <end-user-id>'

A resposta inclui um ID de entrada e content_hash.

3. Crie o agente salvo

Crie um agente com uma ferramenta shell e monte o memory store no ambiente shell. Use read_only para memória de referência. Use read_write quando o agente deve atualizar memória escrevendo arquivos em /mnt/memory/<label>. Quando o agente escreve, edita ou exclui arquivos dentro de uma montagem read_write, o sandbox sincroniza essas mudanças de volta para o memory store quando o comando shell termina.

mka1 agents create --body '{
  "name": "account-support-agent",
  "description": "Answers support questions with durable account context.",
  "model": "auto",
  "instructions": "Use the mounted Acme support memory for durable account context. Read files under /mnt/memory/acme_support before answering account-specific questions. When you learn a durable Acme fact, write or update the relevant markdown file under /mnt/memory/acme_support. Do not invent account facts that are not present in memory.",
  "tools": [
    {
      "type": "shell",
      "environment": {
        "type": "container_auto",
        "memory_stores": [
          {
            "store_id": "mem_store_123",
            "label": "acme_support",
            "access": "read_write",
            "description": "Durable support notes for Acme Corp.",
            "instructions": "Use these files as account context. Prefer specific files under accounts/acme/. Write durable account learnings back as concise markdown."
          }
        ]
      }
    }
  ],
  "tool_choice": "auto",
  "metadata": {
    "memory_store_id": "mem_store_123",
    "account_id": "acct_acme"
  }
}' \
  -H 'X-On-Behalf-Of: <end-user-id>'

Veja a referência para criar um agente.

4. Execute o agente e atualize memória

O agente pode ler arquivos montados com a ferramenta shell. Se o store montado for read_write, ele também pode atualizar memória escrevendo arquivos em /mnt/memory/<label>. O sandbox restaura os arquivos montados antes do comando, cria uma snapshot e sincroniza os arquivos alterados ao final.

mka1 agent-runs create \
  --agent-id agt_123 \
  --body '{
    "input": "Draft a support update for Acme about the production incident response plan. Use the mounted Acme memory before answering. Also remember that Acme now wants customer-facing incident summaries by 4 PM Central.",
    "metadata": {
      "memory_store_id": "mem_store_123",
      "source": "docs-recipe"
    }
  }' \
  -H 'X-On-Behalf-Of: <end-user-id>'

Use recuperar uma execução de agente para consultar o status. Use transmitir eventos de execução para mostrar progresso ao vivo.

5. Inspecione a memória depois

Depois que a execução termina, use a Memory Stores API para revisar o que mudou. Os mesmos arquivos que o agente escreve em /mnt/memory/acme_support ficam disponíveis como entradas de memória.

mka1 llm memory-stores list-entries \
  --memory-store-id mem_store_123 \
  --limit 20 \
  -H 'X-On-Behalf-Of: <end-user-id>'

Veja a referência para listar entradas de memória.

Notas operacionais

Use montagens read_only para memória de referência e read_write para agentes que podem editar memória durável.
Deixe agentes atualizarem memória escrevendo arquivos em montagens read_write com a ferramenta shell.
Use atualizações diretas da Memory Stores API para sementes iniciais, revisões, correções administrativas ou importações.
Mantenha entradas pequenas para que o agente inspecione apenas arquivos relevantes durante a execução.

Documentation Index

​1. Crie o memory store

​2. Adicione entradas de memória

​3. Crie o agente salvo

​4. Execute o agente e atualize memória

​5. Inspecione a memória depois

​Notas operacionais