Personalizar extração automática de memória

A extração automática de memória pode capturar detalhes úteis sem configuração adicional. As instruções personalizadas permitem que um aplicativo adicione orientação ao processo de extração quando o comportamento padrão precisar ser adaptado para um caso de uso específico.

Este guia explica como orientar a extração automatizada da memória do Oracle AI Agent Memory com instruções personalizadas.

As instruções personalizadas permitem que você forneça orientação específica do domínio sobre quais detalhes valem a pena preservar como memória durável. Elas são úteis quando seu aplicativo precisa de extração para refletir o julgamento especializado, a política do produto ou as prioridades específicas do fluxo de trabalho, em vez de tratar todos os detalhes potencialmente memoráveis da mesma maneira.

Observação: use instruções personalizadas quando a extração de memória deve seguir a orientação específica do aplicativo. A extração padrão é apropriada quando nenhuma orientação adicional é necessária.

Dica: Consulte Conceitos Básicos da Memória do Agente para saber como instalar o oracleagentmemory. Se você precisar de um Oracle AI Database local para este exemplo, siga Executar o Oracle AI Database localmente.

Configurar instruções de extração no nível do cliente

Crie o componente Memória do Agente Oracle com uma conexão ou pool do Oracle DB, um incorporador, um LLM e instruções de extração com foco no suporte. Essas instruções se aplicam a threads criados ou carregados por meio deste cliente, a menos que um thread forneça suas próprias instruções de extração.

import oracledb

from oracleagentmemory.core import MemoryExtractionConfig, MemoryLinkExtractionMode, SchemaPolicy
from oracleagentmemory.core.embedders.embedder import Embedder
from oracleagentmemory.core.llms.llm import Llm
from oracleagentmemory.core.oracleagentmemory import OracleAgentMemory

embedder = Embedder(model="YOUR_EMBEDDING_MODEL")
llm = Llm(model="YOUR_MEMORY_LLM")
db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="localhost:1521/...",
)
memory_store_id = "T_MEM_EXTRACTION"

support_extraction_instructions = """
Only extract customer support facts:
- order ids
- return requests
- delivery problems
Ignore greetings, small talk, and one-off troubleshooting text.
""".strip()

memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
    memory_extraction_config=MemoryExtractionConfig(
        memory_extraction_custom_instructions=support_extraction_instructions
    ),
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_store_id=memory_store_id,
)

Referência de API: OracleAgentMemory

OracleThread

Extrair Memórias de Suporte de Mensagens de Thread

Crie um thread de suporte e adicione mensagens de usuário e assistente. O exemplo define memory_extraction_config=MemoryExtractionConfig(memory_extraction_frequency=1) para que add_messages() execute a extração automatizada imediatamente para o giro inserido. As instruções personalizadas mantêm a memória extraída focada em IDs de pedidos, solicitações de devolução e problemas de entrega.

support_thread = memory.create_thread(
    thread_id="support_ticket_7421",
    user_id="customer_123",
    memory_extraction_config=MemoryExtractionConfig(memory_extraction_frequency=1),
)

#add_messages persists the turn and runs automated memory extraction because
#MemoryExtractionConfig(memory_extraction_frequency=1) is set for this thread.
support_thread.add_messages(
    [
        {
            "role": "user",
            "content": (
                "Hi, order 7421 arrived damaged. I need a return request "
                "and a replacement delivery."
            ),
        },
        {
            "role": "assistant",
            "content": "I can help start the return request for order 7421.",
        },
    ]
)

results = support_thread.search(
    "return request order 7421",
    max_results=5,
    record_types=["fact"],
)
for result in results:
    print(f"- [{result.record.record_type}] {result.content}")
#- [fact] Customer reported damaged order 7421 and requested a return and replacement delivery.

A saída mostrada anteriormente é ilustrativa. O texto exato da memória depende do LLM de extração configurado, mas as memórias extraídas devem seguir as instruções personalizadas fornecidas ao cliente.

A diferença é mais fácil de ver, comparando o tipo de memória que o extrator é solicitado a manter:

Com instruções personalizadas

O extrator mantém o fato durável de suporte ao cliente e ignora o texto de saudação e conversação.

- [fact] Customer reported damaged order 7421 and requested a return and replacement delivery.

Sem instruções personalizadas

O extrator pode manter uma memória de conversa mais ampla porque o prompt de extração padrão não tem escopo para suportar operações.

- [memory] The user contacted support about order 7421 and discussed a damaged delivery.

Referência de API: OracleThread

Resultado do OracleSearch

Configurar vinculação automática de memória

A ligação automática de memória conecta uma memória recém-extraída a memórias existentes relevantes. O SDK recupera um conjunto limitado de memórias candidatas e solicita ao LLM de extração que decida se um link digitado deve ser criado. Por padrão, o POST_EXTRACTION toma essa decisão em uma solicitação adicional depois que as memórias são extraídas.

O tipo de link descreve o relacionamento da nova memória com o candidato existente. supersedes, refines e duplicates preservam a memória antiga como histórico e a marcam como inválida. supports e contradicts mantêm ambas as memórias válidas. A vinculação automática é limitada aos candidatos recuperados; use as APIs de vinculação explícitas quando um relacionamento deve ser sempre registrado.

Use MemoryExtractionConfig para personalizar a vinculação automática:

memory_link_extraction_mode controla quando os links são resolvidos. Use POST_EXTRACTION para uma solicitação de resolução de link separada, DURING_EXTRACTION para resolver links na solicitação de extração ou DISABLED para não criar links automáticos.
memory_link_extraction_custom_instructions adiciona orientação ao prompt de resolução de link, como quais tipos de relacionamento são apropriados para um domínio.
memory_link_extraction_token_limit define o orçamento total do token de entrada para resolução de link pós-extração. Valores menores que 1 desativam esse limite.

Como com as configurações de extração descritas anteriormente, forneça esses campos no nível do cliente ou substitua-os por um thread específico. O exemplo a seguir atualiza o thread de suporte para vincular apenas alterações significativas nos fatos de suporte:

memory.update_thread(
    "support_ticket_7421",
    memory_extraction_config=MemoryExtractionConfig(
        memory_link_extraction_mode=MemoryLinkExtractionMode.POST_EXTRACTION,
        memory_link_extraction_custom_instructions=(
            "Only link a new support fact when it supersedes or refines "
            "an existing support fact. Do not create supports or contradicts links."
        ),
        memory_link_extraction_token_limit=8_000,
    ),
)

As mesmas definições podem ser especificadas para create_thread() ou incluídas na MemoryExtractionConfig do cliente. Para obter detalhes sobre como criar links manualmente e recuperar contexto vinculado, consulte Criar e Pesquisar Gráficos de Memória Vinculados.

Referência de API: MemoryExtractionConfig

OracleThread

Substituir Instruções para um Thread

Informe memory_extraction_config=MemoryExtractionConfig(memory_extraction_custom_instructions=...) para create_thread() quando um thread precisar de uma política de extração mais restrita do que o padrão do cliente. O valor no nível do thread tem precedência para esse thread e é persistido com a configuração do thread.

billing_thread = memory.create_thread(
    thread_id="billing_ticket_9310",
    user_id="customer_123",
    memory_extraction_config=MemoryExtractionConfig(
        memory_extraction_frequency=1,
        memory_extraction_custom_instructions=(
            "Only extract billing facts, invoice identifiers, and payment issues."
        ),
    ),
)

billing_thread.add_messages(
    [
        {
            "role": "user",
            "content": "Invoice INV-9310 was paid twice and needs a refund.",
        }
    ]
)

Referência de API: OracleAgentMemory

OracleThread

Atualizar ou Limpar Instruções de Thread

Use update_thread() para alterar instruções de extração persistidas para um thread existente. Passe None para limpar as instruções no nível do thread para que os handles futuros do thread usem as instruções no nível do cliente ou, se nenhuma estiver configurada, o comportamento normal de extração do SDK.

memory.update_thread(
    "support_ticket_7421",
    memory_extraction_config=MemoryExtractionConfig(
        memory_extraction_custom_instructions=(
            "Only extract product defects and replacement requests."
        )
    ),
)

memory.update_thread(
    "support_ticket_7421",
    memory_extraction_config=MemoryExtractionConfig(
        memory_extraction_custom_instructions=None
    ),
)

Observação: get_thread(..., memory_extraction_config=MemoryExtractionConfig(memory_extraction_custom_instructions=...)) pode aplicar instruções ao handle de thread ativo retornado sem atualizar a configuração de thread persistente.

Referência de API: OracleAgentMemory

OracleThread

Conclusão

Neste guia, aprendemos a configurar instruções de extração personalizadas no nível do cliente, configurar vinculação automática de memória, substituir instruções de extração para um thread específico e atualizar ou limpar instruções de extração no nível do thread.

→ Depois de aprender a personalizar a extração automatizada, agora você pode prosseguir para Usar APIs de Curto Prazo de Memória do Agente Oracle com LangGraph.

Código Inteiro

Copie o código completo a seguir.

#Copyright © 2026 Oracle and/or its affiliates.
#This software is under the Apache License 2.0
#(LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0) or Universal Permissive License
#(UPL) 1.0 (LICENSE-UPL or https://oss.oracle.com/licenses/upl), at your option.

#Oracle Agent Memory Code Example - Customize Automatic Memory Extraction
#------------------------------------------------------------------------

##Configure custom memory extraction instructions

import oracledb

from oracleagentmemory.core import MemoryExtractionConfig, MemoryLinkExtractionMode, SchemaPolicy
from oracleagentmemory.core.embedders.embedder import Embedder
from oracleagentmemory.core.llms.llm import Llm
from oracleagentmemory.core.oracleagentmemory import OracleAgentMemory

embedder = Embedder(model="YOUR_EMBEDDING_MODEL")
llm = Llm(model="YOUR_MEMORY_LLM")
db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="localhost:1521/...",
)
memory_store_id = "T_MEM_EXTRACTION"

support_extraction_instructions = """
Only extract customer support facts:
- order ids
- return requests
- delivery problems
Ignore greetings, small talk, and one-off troubleshooting text.
""".strip()

memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
    memory_extraction_config=MemoryExtractionConfig(
        memory_extraction_custom_instructions=support_extraction_instructions
    ),
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_store_id=memory_store_id,
)

##Extract support memories from thread messages

support_thread = memory.create_thread(
    thread_id="support_ticket_7421",
    user_id="customer_123",
    memory_extraction_config=MemoryExtractionConfig(memory_extraction_frequency=1),
)

#add_messages persists the turn and runs automated memory extraction because
#MemoryExtractionConfig(memory_extraction_frequency=1) is set for this thread.
support_thread.add_messages(
    [
        {
            "role": "user",
            "content": (
                "Hi, order 7421 arrived damaged. I need a return request "
                "and a replacement delivery."
            ),
        },
        {
            "role": "assistant",
            "content": "I can help start the return request for order 7421.",
        },
    ]
)

results = support_thread.search(
    "return request order 7421",
    max_results=5,
    record_types=["fact"],
)
for result in results:
    print(f"- [{result.record.record_type}] {result.content}")
#- [fact] Customer reported damaged order 7421 and requested a return and replacement delivery.

##Configure automatic memory linking

memory.update_thread(
    "support_ticket_7421",
    memory_extraction_config=MemoryExtractionConfig(
        memory_link_extraction_mode=MemoryLinkExtractionMode.POST_EXTRACTION,
        memory_link_extraction_custom_instructions=(
            "Only link a new support fact when it supersedes or refines "
            "an existing support fact. Do not create supports or contradicts links."
        ),
        memory_link_extraction_token_limit=8_000,
    ),
)

##Override custom instructions for one thread

billing_thread = memory.create_thread(
    thread_id="billing_ticket_9310",
    user_id="customer_123",
    memory_extraction_config=MemoryExtractionConfig(
        memory_extraction_frequency=1,
        memory_extraction_custom_instructions=(
            "Only extract billing facts, invoice identifiers, and payment issues."
        ),
    ),
)

billing_thread.add_messages(
    [
        {
            "role": "user",
            "content": "Invoice INV-9310 was paid twice and needs a refund.",
        }
    ]
)

##Update or clear thread custom instructions

memory.update_thread(
    "support_ticket_7421",
    memory_extraction_config=MemoryExtractionConfig(
        memory_extraction_custom_instructions=(
            "Only extract product defects and replacement requests."
        )
    ),
)

memory.update_thread(
    "support_ticket_7421",
    memory_extraction_config=MemoryExtractionConfig(
        memory_extraction_custom_instructions=None
    ),
)