Conceitos Básicos da Memória do Agente

Este artigo o orienta na instalação da Memória do Agente e na execução de operações básicas de memória, incluindo armazenamento e recuperação do contexto do usuário.

Pré-requisitos

Certifique-se de ter:

Requisitos do Recurso Oracle AI Database

O armazenamento suportado pelo BD do Oracle Agent Memory requer o Oracle AI Database 23ai ou uma versão mais recente (banco de dados versão 23.4 ou mais recente). Para o Oracle AI Vector Search, defina o parâmetro de inicialização do banco de dados COMPATIBLE como 23.4.0 ou mais recente.

A estratégia de pesquisa selecionada tem estes requisitos adicionais:

Durante a inicialização do esquema gerenciado, a Memória do Agente Oracle valida a versão do banco de dados conectado antes de executar a DDL e reporta uma ação de upgrade quando a estratégia de pesquisa selecionada está indisponível.

Configuração do Banco de Dados Gerenciado

Quando um proprietário de esquema cria ou recria um armazenamento de memória, o pacote Python de Memória do Agente Oracle prepara os objetos de banco de dados gerenciados necessários. O proprietário precisa dos privilégios de sistema CREATE TABLE e CREATE PROCEDURE da Oracle.

Estabeleça conexão como o proprietário do esquema para configuração do esquema. Uma conexão de aplicativo usando schema_owner acessa um armazenamento existente e deve usar SchemaPolicy.REQUIRE_EXISTING; ela não cria nem atualiza os objetos de banco de dados gerenciados do proprietário.

Instalar o SDK

Você pode encontrar todas as versões e plataformas suportadas do oracleagentmemory na página Download de Software.

Para instalar a Memória do Agente, execute:

pip install "oracleagentmemory==26.8.0"

A instalação com pip extrai rodas binárias predefinidas em plataformas suportadas.

Registrando e diagnosticando

O Oracle AI Agent Memory emite mensagens de diagnóstico por meio de log em Python padrão em nomes de logger que começam com oracleagentmemory. O SDK não configura handlers ou níveis de log; os aplicativos podem rotear esses logs para seu console, arquivo ou pipeline de observabilidade existente. Alguns registros de log usam os campos extra do log do Python para diagnóstico estruturado seguro, que pode ser capturado por handlers de log estruturado.

import logging

logging.basicConfig(level=logging.INFO)
logging.getLogger("oracleagentmemory").setLevel(logging.INFO)

Para diagnosticar e solucionar problemas em ambientes controlados, ative os logs DEBUG:

logging.getLogger("oracleagentmemory").setLevel(logging.DEBUG)

Mantenha implantações de produção em um nível que não seja DEBUG. Os logs DEBUG se destinam ao desenvolvimento e ao diagnóstico de suporte, e o texto da mensagem de log não deve ser tratado como uma API pública estável.

Time-to-Live e Expired-Record Purge

As mensagens e memórias apoiadas pelo Oracle DB podem expirar automaticamente por meio de uma combinação de padrões de retenção no nível do esquema e valores ttl_days/ttl_anchor por registro em APIs de gravação e atualização.

Quando o Oracle Agent Memory cria ou faz upgrade de seu esquema gerenciado, ele também cria um job de expurgação DBMS_SCHEDULER diário que remove fisicamente linhas expiradas, seus chunks de recuperação e chunks de recuperação órfãos cuja linha de origem suportada não existe mais. Se a configuração do esquema precisar criar esse job, mas o usuário do banco de dados não tiver CREATE JOB, a configuração será concluída com uma advertência: as linhas expiradas permanecerão filtradas de leituras e pesquisas, mas os chunks expirados e órfãos não serão expurgados fisicamente até que um usuário privilegiado crie o job. Em SchemaPolicy.REQUIRE_EXISTING, um job de expurgação ausente é tolerado e registrado no nível DEBUG.

Os esquemas de memória vinculada também criam um trigger que revalida as memórias sobreviventes após a exclusão de um link, inclusive quando o job de expurgação exclui uma memória expirada e o Oracle coloca seus links em cascata. O proprietário do esquema precisa de CREATE TRIGGER durante a criação ou o upgrade do esquema; os usuários de runtime normais não precisam desse privilégio.

Para obter o modelo de retenção completo, configuração do MemoryRetentionConfig, consultas de verificação de job de expurgação, criação manual de job de DBA e exemplos de Python usando TimeToLiveAnchor, consulte Usar o Tempo de Vida para Mensagens e Memórias.

Permissões do Esquema Linked-Memory

O esquema de memória vinculada inclui um gráfico de propriedades do Oracle SQL e um trigger de banco de dados que mantém o estado do ciclo de vida correto quando os links são excluídos.

Se você definir memory_store_id, o nome do gráfico gerenciado será prefixado da mesma forma que as tabelas. Por exemplo, memory_store_id="SALES" cria SALES_MEMORY_GRAPH.

Os valores APP_SCHEMA e APP_USER são placeholders. Substitua-os pelos nomes de usuário do banco de dados. Os exemplos usam letras maiúsculas porque os identificadores Oracle sem aspas são armazenados em letras maiúsculas.

  1. Durante a configuração do esquema, conceda ao proprietário do esquema CREATE PROPERTY GRAPH e CREATE TRIGGER. Eles são necessários com SchemaPolicy.CREATE_IF_NECESSARY ou SchemaPolicy.RECREATE sempre que o trigger de gráfico ou exclusão de link gerenciado deve ser criado. 
    GRANT CREATE PROPERTY GRAPH TO APP_SCHEMA;
GRANT CREATE TRIGGER TO APP_SCHEMA;
-- Run OracleAgentMemory schema setup as APP_SCHEMA.
REVOKE CREATE PROPERTY GRAPH FROM APP_SCHEMA;
REVOKE CREATE TRIGGER FROM APP_SCHEMA;

    Conceda-os novamente antes de uma atualização posterior do SDK se essa atualização precisar criar ou recriar o gráfico gerenciado ou o trigger de exclusão de link.

  2. Durante o runtime normal do aplicativo, decida qual usuário se conecta ao Oracle:
    • Se o usuário de runtime for APP_SCHEMA, nenhuma concessão de gráfico adicional será necessária. O proprietário do gráfico pode acessar seu próprio gráfico.
    • Se o usuário de runtime for diferente, execute o seguinte como APP_SCHEMA após a configuração do esquema. O nome do gráfico padrão é MEMORY_GRAPH; use o nome prefixado quando memory_store_id estiver definido. 
      GRANT SELECT ON PROPERTY GRAPH APP_SCHEMA.MEMORY_GRAPH TO APP_USER;

      O usuário de runtime também precisa do acesso normal ao banco de dados exigido pelo restante da implantação da Memória do Agente Oracle.

SchemaPolicy.REQUIRE_EXISTING ignora a primeira etapa porque espera que o gráfico e o trigger já existam. Um usuário de runtime separado ainda precisa de acesso ao gráfico de propriedades gerenciado.

Inicializar a Instância de Memória

Crie uma instância OracleAgentMemory configurando o incorporador, o LLM e a conexão de banco de dados.

import oracledb

from oracleagentmemory.core import SchemaPolicy
from oracleagentmemory.core.oracleagentmemory import OracleAgentMemory
from oracleagentmemory.apis.searchscope import SearchScope
from oracleagentmemory.core.embedders.embedder import Embedder
from oracleagentmemory.core.llms.llm import Llm

embedder = Embedder(model="YOUR_EMBEDDING_MODEL")
llm = Llm(model="YOUR_LLM")
db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="YOUR DB CONNECT STRING",
)
memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_store_id="T_GET_STARTED",
)

Observação: Por padrão, os esquemas gerenciados do Oracle AI Database não definem um período de retenção para mensagens e memórias. Configure as definições de tempo de vida MemoryRetentionConfig ou por registro para usar outro período de retenção. Para obter mais informações, consulte Usar o Tempo de Vida para Mensagens e Memórias.

Armazenar Entradas de Memória

Comece criando um thread, adicionando mensagens e armazenando uma entrada de memória para o usuário.

messages = [
    {
        "role": "user",
        "content": (
            "Orange juice has become my favorite breakfast drink lately, "
            "what can I pair it with?"
        ),
    },
    {
        "role": "assistant",
        "content": (
            "Nice! Orange juice goes great with something savory. "
            "Try eggs and toast, avocado toast, or a breakfast sandwich."
        ),
    },
]

thread = memory.create_thread(user_id="user_123")
#add_messages will add messages to the DB and extract memories automatically
thread.add_messages(messages)
#add_memory adds memory to the DB
thread.add_memory("The user likes orange juice with breakfast.")

Recuperar Entradas de Memória

Pesquise memórias usando uma consulta no escopo do usuário.

results = memory.search(query="orange juice", scope=SearchScope(user_id="user_123"))
for result in results:
    print(f"- [{result.record.record_type}] {result.content}")

Saída:

- [memory] The user likes orange juice with breakfast.
- [message] Orange juice has become my favorite breakfast drink lately, what can I pair it with?
- [message] Nice! Orange juice goes great with something savory. Try eggs and toast,
            avocado toast, or a breakfast sandwich.

Observação: A saída mostrada é ilustrativa. Versões futuras podem retornar tipos de resultado adicionais, campos ou prescrições.

Compatibilidade do Modelo

Os seguintes Modelos de Linguagem Grande (LLMs) e Modelos de Incorporação são compatíveis com oracleagentmemory.

LMs

Os seguintes Large Language Models (LLMs) foram confirmados como compatíveis.

Modelos hospedados na OCI

OpenAI

LLMs hospedados automaticamente

Antrópico

Gêmeos

Incorporações

Os seguintes Modelos de Incorporação foram confirmados como compatíveis.

Modelos hospedados na OCI

OpenAI

LLMs auto-hospedados

Gêmeos