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 recuperação gerenciados. Isso é mais amplo que OracleThread.delete_message(), que exclui somente a linha de mensagem bruta. Antes de excluir o thread, ele aguarda a extração em segundo plano aceita anteriormente já conhecida por este cliente para esse thread. Ele não serializa todas as operações simultâneas para o mesmo thread enquanto a exclusão está em andamento.

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.

Aviso: SchemaPolicy.CREATE_IF_NECESSARY pode ser mais caro do que a inicialização normal do cliente porque pode aplicar DDL de esquema gerenciado e regravações de dados de melhor esforço antes que a inicialização seja bem-sucedida. Planeje a primeira abertura de um esquema gerenciado mais antigo como uma operação de migração ou manutenção quando esse esquema pode conter muitas linhas.

Se a configuração do esquema precisar criar o job de expurgação de registro expirado gerenciado, mas o usuário do banco de dados não tiver o privilégio scheduler-job, a inicialização avisará e continuará. As mensagens e memórias expiradas permanecem ocultas de leituras e pesquisas, mas elas não são expurgadas fisicamente até que o job seja criado por um usuário com o privilégio CREATE JOB ou um scheduler equivalente.

Quando o SchemaPolicy.CREATE_IF_NECESSARY cria pela primeira vez um índice híbrido gerenciado em um esquema existente, o sistema Oracle verifica o texto de pesquisa armazenado e cria o estado de índice híbrido gerenciado com base no modelo configurado no banco de dados. A inicialização do cliente aguarda a conclusão desse DDL, portanto, planeje o primeiro upgrade híbrido como uma operação de migração ou manutenção para grandes esquemas. SearchIndexSyncMode controla a manutenção contínua após a existência do índice; ele não torna a primeira criação de índice assíncrona.

Exemplos de

from oracleagentmemory.core import (
    MemoryExtractionConfig,
    SearchIndexSyncMode,
    OracleAgentMemory,
    SchemaPolicy,
    SearchStrategy,
)
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
read_only_client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
)

Use um modelo de incorporação no BD para explorar a pesquisa de índice híbrido da Oracle:

from oracleagentmemory.core.embedders import OracleDBEmbedder
db_embedder = OracleDBEmbedder(
    connection=db_pool,
    model="DOC_MODEL",
    embedding_dimension=768,
)
hybrid_client = OracleAgentMemory(
    connection=db_pool,
    embedder=db_embedder,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    search_strategy=SearchStrategy.HYBRID,
    search_index_sync=SearchIndexSyncMode.ON_COMMIT,
)

método add_agent

Adicionar um registro de perfil de agente à loja.

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",
    metadata={"source": "catalog"},
)
'a1'

método add_memory

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

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_memory_async (assíncrono)

Adicione assincronamente um registro de memória ao cliente.

método add_user

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

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.",
    metadata={"source": "crm"},
)
'u1'

método close

Feche o componente de memória do agente.

O fechamento para de aceitar novo trabalho de extração em segundo plano e aguarda a extração de memória em segundo plano pendente para concluir até o timeout configurado. Se esse timeout expirar, o close() retornará mesmo que algum trabalho de extração em segundo plano ainda esteja inacabado. O método é idempotente.

Exemplos de

client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
)
client.close()

método close_async (assíncrono)

Feche assincronamente o componente de memória do agente.

Este método segue o mesmo comportamento de shutdown que close(). Se o tempo limite expirar, ele poderá retornar enquanto o trabalho de extração em segundo plano ainda estiver em execução.

Exemplos de

await client.close_async()

método create_thread

Crie e registre um thread.

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.

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. Antes das execuções de exclusão em cascata, esse método aguarda a extração em segundo plano anterior já aceita para os threads próprios conhecidos nesse momento por meio desse componente de memória do agente. Ele não aguarda o trabalho aceito após o início da espera ou o trabalho iniciado por outro componente ou processo de memória do agente. Não há suporte para o uso simultâneo no escopo do ator enquanto a exclusão está em andamento.

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.

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_memory_async (assíncrono)

Exclua de forma assíncrona um registro semelhante à memória (por exemplo, uma memória, um fato, uma preferência ou uma diretriz) por identificador.

método delete_thread

Exclua todos os registros associados a um identificador de thread.

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 dados de recuperação gerenciados. 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. Antes de excluir o thread, este método aguarda a extração em segundo plano anterior já aceita para esse thread por meio deste componente de memória do agente. Ele não aguarda o trabalho em segundo plano aceito após o início da espera ou o trabalho iniciado por outro componente ou processo de memória do agente. O uso simultâneo do mesmo thread enquanto a exclusão está em andamento não é suportado.

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.

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. Antes das execuções de exclusão em cascata, esse método aguarda a extração em segundo plano anterior já aceita para os threads próprios conhecidos nesse momento por meio desse componente de memória do agente. Ele não aguarda o trabalho aceito após o início da espera ou o trabalho iniciado por outro componente ou processo de memória do agente. Não há suporte para o uso simultâneo no escopo do ator enquanto a exclusão está em andamento.

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.

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'

Pesquise de forma síncrona registros relevantes para uma consulta.

Observações

Os valores explícitos do escopo None ainda seguem as regras de correspondência exata resolvidas: exact_*_match=False deixa essa dimensão sem restrições, enquanto exact_*_match=True corresponde apenas a registros sem escopo nessa dimensão.

método search_async (assíncrono)

Pesquise registros relevantes para uma consulta de forma assíncrona.

Observações

Os valores explícitos do escopo None ainda seguem as regras de correspondência exata resolvidas: exact_*_match=False deixa essa dimensão sem restrições, enquanto exact_*_match=True corresponde apenas a registros sem escopo nessa dimensão.

método update_memory

Atualizar um registro de memória armazenada por identificador.

Observações

Os campos omitidos são preservados do registro armazenado. O escopo armazenado permanece inalterado. A substituição de metadados é uma substituição de objeto inteiro, não uma mesclagem JSON recursiva.

método update_memory_async (assíncrono)

Atualizar de forma assíncrona um registro semelhante a memória armazenada por identificador.

Observações

Os campos omitidos permanecem inalterados. As atualizações de escopo não são suportadas por esta API. A substituição de metadados é uma substituição de objeto inteiro, não uma mesclagem JSON recursiva.

método update_thread

Persistir metadados de thread e atualizações duráveis de configuração de runtime.

Observações

A configuração de runtime é resolvida do thread de conversa armazenado mais as substituições explícitas especificadas para esta chamada, correspondendo à semântica get_thread antes de persistir o resultado. Os metadados omitidos e as atualizações de configuração de runtime são resolvidos com base em dados armazenados, não de qualquer instância OracleThread carregada anteriormente, e somente as atualizações de metadados fornecidas explicitamente ou as substituições duráveis de configuração de runtime são gravadas de volta. A substituição de metadados é uma substituição de objeto inteiro, não uma mesclagem JSON recursiva. A propriedade do thread não pode ser alterada por meio dessa API; portanto, user_id e agent_id permanecem inalterados. O estado de tempo de execução mutável, como contadores de extração, é deixado intocado.

Exemplos de

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
updated = client.update_thread(
    "c1",
    metadata={"flags": {"vip": True}},
    message_shortening_input_token_limit=12_000,
)
updated.message_shortening_input_token_limit
12000

método wait_for_memory_extraction

Aguarde a extração anterior da memória em segundo plano iniciada por este cliente.

Este método aguarda a extração em segundo plano já iniciada por meio desta instância do OracleAgentMemory, em todos os threads pertencentes a este componente de memória do agente. Ele não aguarda o início da extração após o início dessa espera, a extração iniciada por outro componente de memória do agente ou a extração em execução em outro processo. As falhas de extração contam como concluídas para esta espera.

Exemplos de

client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
)
client.wait_for_memory_extraction(timeout=10)

método wait_for_memory_extraction_async (assíncrono)

Aguarde assincronamente a extração de memória em segundo plano anterior.

Este método segue o mesmo comportamento de wait_for_memory_extraction().

Exemplos de

await client.wait_for_memory_extraction_async(timeout=10)

Extração de memória

classe oracleagentmemory.core.MemoryExtractionConfig

Bases: object

Configurações agrupadas para extração automática de memória.

Informe este objeto para OracleAgentMemory, create_thread, get_thread ou update_thread para configurar a extração automática. Os campos omitidos herdam da próxima configuração mais ampla. Por exemplo, um thread criado sem memory_extraction_frequency usa o padrão do componente de memória do agente, e o padrão do componente retorna ao padrão do SDK.

Exemplos de

from oracleagentmemory.core import MemoryExtractionConfig, MemoryExtractionMode
config = MemoryExtractionConfig(
    extract_memories=True,
    extraction_mode=MemoryExtractionMode.BACKGROUND,
)

classe oracleagentmemory.core.MemoryExtractionMode

Bases: str, Enum

Controla quando o trabalho de extração automática de memória é executado.

INLINE executa a extração automática antes que o método de gravação seja retornado. BACKGROUND retorna depois que a gravação bruta é bem-sucedida e o trabalho de extração devido é tentado em segundo plano. A extração em segundo plano é o melhor esforço: as memórias derivadas podem aparecer mais tarde ou podem nunca ser escritas se o trabalho em segundo plano não puder ser concluído.

PLANO DE FUNDO = 'CONTEXTO'

Retorne após a persistência de mensagem bruta e execute a extração de melhor esforço no trabalho em segundo plano.

EM LINHA = 'EM LINHA'

Execute a extração antes de o método de gravação retornar.

classe oracleagentmemory.core.BackgroundExtractionQueueFullBehavior

Bases: str, Enum

Controla o que acontece quando a extração em segundo plano não pode ser enfileirada no tempo.

ELIMINAR = 'ELIMINAR'

Registre um aviso e continue imediatamente quando a capacidade da fila estiver indisponível.

WAIT_THEN_DROP = 'WAIT_THEN_DROP'

Aguarde a capacidade da fila até o timeout configurado, registre um aviso e continue.

WAIT_THEN_RAISE = 'WAIT_THEN_RAISE'

Aguarde a capacidade da fila até o timeout configurado e, em seguida, gere TimeoutError.