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

Observação: OracleAgentMemory.delete_thread() é o caminho suportado para limpeza em cascata com escopo de thread. Ele remove o thread junto com mensagens associadas, memórias duráveis e dados de vetores ou partes gerenciados. Isso é mais amplo que OracleThread.delete_message(), que exclui somente a linha de mensagem bruta.

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 de perfil do agente são armazenados no armazenamento no nível do cliente e não têm escopo intencional. O identificador de registro retornado é o mesmo identificador público que o aplicativo usa como agent_id.

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 e não têm escopo intencional. O identificador de registro retornado é o mesmo identificador público que o aplicativo usa como user_id.

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.
- metadata dict[str, Any] | None – Metadados opcionais semelhantes a JSON persistidos na linha do thread.
- 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. Quando omitido, o padrão é -1.
- 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, em tokens, dos prompts do LLM usados para extração de memória e execução de atualizações resumidas. Quando omitido, o padrão é 100_000.
- context_card_token_limit int – Tamanho máximo, em tokens, dos prompts do LLM usados para resumir o cartão de contexto. 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_agent`

Excluir um registro de perfil do agente por identificador.

Parâmetros:
- agent_id str – Identificador do agente cujo perfil deve ser removido.
- cascade bool – Quando True (padrão), também exclua registros com escopo para esse agente. Isso inclui a exclusão de threads próprios, as mensagens e registros semelhantes à memória removidos com esses threads e quaisquer registros diretamente no escopo do agente, como mensagens, memórias, diretrizes, fatos ou preferências. Essa limpeza com escopo ainda é executada quando a linha agente-perfil correspondente já está ausente. Defina como False para remover somente o registro do perfil.
Retorna: Número de linhas de perfil do agente excluídas (0 ou 1). Ainda pode ser 0 quando linhas com escopo foram removidas durante a limpeza em cascata.
Tipo de retorno: int

Observações

As exclusões em cascata são planejadas e executadas dentro do armazenamento de apoio para que a exclusão do perfil e todas as exclusões filho com escopo ocorram em uma operação de armazenamento.

Exemplos de

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_agent("a-delete", "Support assistant")
'a-delete'
client.delete_agent("a-delete")
1

método `delete_memory`

Excluir um registro semelhante à memória (por exemplo, uma memória, um fato, uma preferência ou uma diretriz) por identificador.

Parâmetros: memory_id str – Identificador de memória. O identificador pode se referir a um registro memory, guideline, fact ou preference armazenado.
Retorna: Número de linhas semelhantes à 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 de thread a ser excluído.
Retorna: Número de linhas de thread excluídas (0 ou 1).
Tipo de retorno: int

Observações

Use esta operação quando precisar de remoção completa de retenção de um thread. O armazenamento de suporte exclui o thread junto com mensagens com escopo de thread associadas, memórias duráveis e linhas de vetor ou bloco gerenciadas. Isso difere de OracleThread.delete_message(), que remove apenas o registro de mensagem bruta e não faz cascata para memórias derivadas criadas a partir dessa mensagem.

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 `delete_user`

Excluir um registro de perfil de usuário por identificador.

Parâmetros:
- user_id str – Identificador do usuário cujo perfil deve ser removido.
- cascade bool – Quando True (padrão), também exclui registros com escopo para esse usuário. Isso inclui a exclusão de threads próprios, as mensagens e registros semelhantes à memória removidos com esses threads e quaisquer registros diretamente no escopo do usuário restantes, como mensagens, memórias, diretrizes, fatos ou preferências. Essa limpeza com escopo ainda é executada quando a linha de perfil do usuário correspondente já está ausente. Defina como False para remover somente o registro do perfil.
Retorna: Número de linhas de perfil do usuário excluídas (0 ou 1). Ainda pode ser 0 quando linhas com escopo foram removidas durante a limpeza em cascata.
Tipo de retorno: int

Observações

Exemplos de

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_user("u-delete", "Prefers concise answers.")
'u-delete'
client.delete_user("u-delete")
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, em tokens, dos prompts do LLM usados para extração de memória e execução de atualizações resumidas.
- context_card_token_limit int – Substituição opcional para o tamanho máximo, em tokens, dos prompts do LLM usados para resumo do cartão de contexto.
- 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'

Memória do Agente