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 artigo explica como orientar a extração automatizada da memória do Oracle AI Agent Memory com instruções personalizadas.

Instruções personalizadas fornecem orientação adicional específica do aplicativo para extração de memória. Eles são úteis quando seu aplicativo precisa de extração para refletir o conhecimento do domínio, a política do produto ou as prioridades específicas da conversa.

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 banco de dados Oracle 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
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")
memory_llm = Llm(model="YOUR_MEMORY_LLM")
db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="YOUR DB CONNECT STRING",
)

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=memory_llm,
    memory_extraction_config=MemoryExtractionConfig(
        memory_extraction_custom_instructions=support_extraction_instructions
    ),
)

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}")

Saída:

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

A saída mostrada acima é 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

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, substituí-las 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 com LangGraph.

Código Inteiro

#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
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")
memory_llm = Llm(model="YOUR_MEMORY_LLM")
db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="YOUR DB CONNECT STRING",
)

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=memory_llm,
    memory_extraction_config=MemoryExtractionConfig(
        memory_extraction_custom_instructions=support_extraction_instructions
    ),
)



##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.



##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
    ),
)