Memória do Agente

Esta página apresenta a implementação concreta da Memória do Agente do Oracle AI.

Memória do Agente Oracle

classe oracleagentmemory.core.OracleAgentMemory

Bases: IAgentMemory

Cliente de memória do agente com suporte do Oracle DB ou de um armazenamento fornecido pelo chamador.

Criar um cliente de memória.

• Parâmetros:
  • store OracleMemoryStore – Instância de armazenamento pré-configurada opcional. Quando fornecido, o cliente usa essa loja diretamente em vez de instanciar sua própria loja. Isso é útil quando os chamadores precisam armazenar configurações além das opções do construtor expostas por OracleAgentMemory.
  • connection object – Conexão/pool opcional do Oracle DB. Quando fornecido, o armazenamento do BD é usado. A transmissão de uma conexão bruta ativa o modo de sessão única para esta instância do cliente, portanto, as solicitações simultâneas devem usar um pool de conexões. Quando omitidos, os chamadores devem especificar um store explícito.
  • embedder IEmbedder | str – Instância de implementação do incorporador ou um identificador de modelo de incorporação LiteLLM. Quando omitido, nenhum incorporador é anexado e os chamadores devem fornecer vetores pré-calculados por meio de APIs de armazenamento de nível inferior.
  • LLM ILlm – Adaptador LLM opcional usado por threads para extração de memória e/ou resumo de contexto. Por padrão, os threads criados ou carregados desse cliente exigem um LLM para que mensagens recentes possam ser extraídas para memórias duráveis. Passe uma llm aqui, forneça uma posteriormente em create_thread ou desative-a com a extract_memories=False.
  • extract_memories bool – Quando o True, os threads criados ou carregados por este cliente exigem um LLM e a extração automática de memória permanece ativada. Defina como False para desativar a extração automática de memória e permitir que esses threads operem sem um LLM. O padrão é True, portanto, os LLMs de extração ausentes falham rapidamente.
  • schema_policy SchemaPolicy | str – Política de configuração do esquema do BD usada somente ao construir um armazenamento do BD com base em connection. O padrão é SchemaPolicy.REQUIRE_EXISTING.
  • table_name_prefix str – Prefixo de tabela/índice de BD opcional usado somente ao construir um armazenamento de BD com base em connection.
• Eleva: ValueError – Se for fornecida uma configuração de armazenamento em conflito, como especificar store e connection, opções específicas do BD sem uma conexão de BD ou omitir store e connection.

Exemplos de

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
read_only_client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    extract_memories=False,
)

método add_agent

Adicionar um registro de perfil de agente à loja.

• Parâmetros:
  • agent_id str – Identificador do agente.
  • informações str – Informações de formato livre sobre o agente.
• Retorna: Identificador do perfil do agente armazenado.
• Tipo de retorno: str

Observações

Os registros do perfil do agente são armazenados no armazenamento no nível do cliente.

Exemplos de

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_agent("a1", "Support assistant")
'a1'

método add_memory

Adicione uma memória no sistema de memória, atribuída ao usuário, agente e thread indicados.

• Parâmetros:
  • content str – Conteúdo da memória a ser persistido.
  • user_id str – Identificadores de escopo opcionais associados à memória armazenada.
  • agent_id str – Identificadores de escopo opcionais associados à memória armazenada.
  • thread_id str – Identificadores de escopo opcionais associados à memória armazenada.
  • memory_id str – Identificador estável fornecido pelo chamador opcional para esta linha de memória.
  • **store_kwargs (Qualquer) – Opções de gravação específicas da loja encaminhadas para o armazenamento de apoio.
• Retorna: Identificador do registro de memória inserido.
• Tipo de retorno: str

Exemplos de

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
memory_id = client.add_memory("User likes pizza", memory_id="mem-1")
memory_id
'mem-1'

método add_user

Adicionar um registro de perfil de usuário à loja.

• Parâmetros:
  • user_id str – Identificador do usuário.
  • informações str – Informações de formato livre sobre o usuário.
• Retorna: Identificador do perfil do usuário armazenado.
• Tipo de retorno: str

Observações

Os registros de perfil do usuário são armazenados no armazenamento no nível do cliente (não vinculados a um thread específico).

Exemplos de

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_user("u1", "Prefers concise answers.")
'u1'

método create_thread

Crie e registre um thread.

• Parâmetros:
  • thread_id str – Identificador de thread. Se omitido, um novo é gerado.
  • user_id str – Identificador do usuário anexado a este registro de thread. Se omitido, um novo é gerado.
  • agent_id str – Identificador do agente anexado a este registro de thread. Se omitido, um novo é gerado.
  • LLM ILlm – Substituição de LLM opcional para este thread. Se for omitido, o LLM no nível do cliente configurado no momento da construção será usado. Por padrão, o cliente ou o thread deve fornecer um LLM para que a extração automática de memória possa ser executada. Defina extract_memories=False aqui ou no cliente para não aceitar esse requisito.
  • extract_memories bool – Substituição opcional por thread para extração automática de memória. Quando True, esse thread requer um LLM para que a extração automática possa ser executada. Defina como False para desativar a extração automática deste thread e permitir a operação sem um LLM. Quando omitida, a definição extract_memories no nível do cliente é usada.
  • max_message_token_length int – tamanho máximo da mensagem de tempo de resposta antes do truncamento ou do resumo durante a extração de memória e atualizações de resumo de contexto. O conteúdo da mensagem armazenada permanece inalterado. Quando omitido, o padrão é tokens 15_000.
  • message_shortening_input_token_limit int – Tamanho máximo, em tokens, do trecho de mensagem enviado ao LLM ao encurtar cópias de mensagens de tempo imediato de grande porte. Quando omitido, o padrão é tokens 30_000.
  • memory_extraction_window int - Número de mensagens recentes a serem incluídas durante a extração de memória. Defina como -1 para executar uma extração por chamada add_messages usando o batch completo de mensagens recém-adicionadas. Quando omitido, o padrão é -1.
  • context_summary_update_frequency int – Frequência de atualizações do resumo de contexto. Defina como -1 para executar uma atualização de resumo por chamada add_messages usando o batch completo de mensagens recém-adicionadas. A mesma cadência é reutilizada para metadados de consolidação de thread atualizados durante add_messages. Quando omitido, o padrão é 4.
  • memory_extraction_frequency int – Frequência de atualizações de extração de memória. Defina como -1 para executar uma extração por chamada add_messages usando o batch completo de mensagens recém-adicionadas. Quando omitido, o padrão é -1.
  • memory_extraction_token_limit int – Tamanho máximo do prompt de extração em tokens. Quando omitido, o padrão é 100_000.
  • enable_context_summary bool – Se deve manter um resumo de contexto em execução para este thread.
  • **kwargs (Qualquer um) – Opções de threads adicionais específicas da implementação.
• Retorna: um OracleThread.
• Tipo da devolução: OracleThread
• Gera: ValueError – Se nenhum LLM estiver disponível para extração automática de memória e o thread e o cliente não tiverem sido configurados com extract_memories=False.

Exemplos de

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
thread = client.create_thread(thread_id="c1", user_id="u1")
thread.thread_id
'c1'

método delete_memory

Excluir um registro de memória por identificador.

• Parâmetros: memory_id str – Identificador de memória.
• Retorna: Número de linhas de memória excluídas (0 ou 1).
• Tipo de retorno: int

Exemplos de

client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
memory_id = client.add_memory("Temporary memory", memory_id="mem-delete")
client.delete_memory(memory_id)
1

método delete_thread

Exclua todos os registros associados a um identificador de thread.

• Parâmetros:
  • thread_id str – Identificador do thread a ser excluído.
  • allow_non_existing bool – Quando True, a exclusão de um thread ausente é tratada como um no-op.
• Retorna: Número de linhas de thread excluídas (0 ou 1).
• Tipo de retorno: int

Exemplos de

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
thread = client.create_thread(thread_id="c-delete")
client.delete_thread(thread.thread_id)
1

método get_thread

Recupera um thread criado anteriormente.

• Parâmetros:
  • thread_id str – Identificador usado ao criar o thread.
  • LLM ILlm – Substituição de LLM opcional para o thread reaberto. Quando omitido, o LLM no nível do cliente configurado no momento da construção é usado.
  • extract_memories bool – Substituição opcional para extração automática de memória no thread reaberto. Quando omitida, a definição extract_memories no nível do cliente é usada.
  • max_message_token_length int – Substituição opcional para o tamanho máximo da mensagem de tempo de resposta antes do truncamento ou resumo durante a extração de memória e atualizações de resumo de contexto. O conteúdo da mensagem armazenada permanece inalterado.
  • message_shortening_input_token_limit int – Substituição opcional para o tamanho máximo, em tokens, do trecho de mensagem enviado ao LLM ao encurtar cópias de mensagens de tempo imediato de grande porte.
  • memory_extraction_window int – Substituição opcional do número de mensagens recentes usadas durante a extração de memória.
  • context_summary_update_frequency int – Substituição opcional para a frequência de atualizações do resumo de contexto.
  • memory_extraction_frequency int – Substituição opcional para a frequência de atualizações de extração de memória.
  • memory_extraction_token_limit int – Substituição opcional para o tamanho máximo do prompt de extração em tokens.
  • enable_context_summary bool – Substituição opcional para saber se o thread reaberto deve manter um resumo de contexto em execução.
• Retorna: Um handle de thread reconstruído a partir de metadados de armazenamento.
• Tipo da devolução: OracleThread
• Aumenta:
  • KeyError – Se o id do thread for desconhecido para esta instância do cliente.
  • ValueError – Se nenhum LLM estiver disponível para extração automática de memória e o cliente não tiver sido configurado com extract_memories=False.

Observações

As substituições explícitas por chamada têm precedência. Quando as substituições de runtime são omitidas, os threads reabertos usam a configuração de runtime persistente quando disponível antes de voltar aos padrões do SDK.

Exemplos de

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
created = client.create_thread(thread_id="c1", user_id="u1")
loaded = client.get_thread("c1")
loaded.user_id
'u1'