Personalizar extracción automática de memoria

La extracción automática de memoria puede capturar detalles útiles sin configuración adicional. Las instrucciones personalizadas permiten a una aplicación agregar orientación al proceso de extracción cuando el comportamiento por defecto se debe adaptar para un caso de uso específico.

En esta guía se explica cómo guiar la extracción de memoria automatizada de Oracle AI Agent Memory con instrucciones personalizadas.

Las instrucciones personalizadas le permiten proporcionar orientación específica del dominio sobre qué detalles vale la pena conservar como memoria duradera. Son útiles cuando su aplicación necesita extracción para reflejar el juicio de los expertos, la política de productos o las prioridades específicas del flujo de trabajo en lugar de tratar cada detalle potencialmente memorable de la misma manera.

Nota: Utilice instrucciones personalizadas cuando la extracción de memoria deba seguir instrucciones específicas de la aplicación. La extracción por defecto es adecuada cuando no se necesita orientación adicional.

Indicación: Consulte Introducción a la memoria del agente para obtener información sobre cómo instalar oracleagentmemory. Si necesita una instancia local de Oracle AI Database para este ejemplo, siga Ejecución local de Oracle AI Database.

Configuración de instrucciones de extracción a nivel de cliente

Cree el componente Memoria de Agente de Oracle con una conexión o pool de Oracle DB, un embebido, un LLM e instrucciones de extracción centradas en el soporte. Estas instrucciones se aplican a los threads creados o cargados a través de este cliente, a menos que un thread proporcione sus propias instrucciones de extracción.

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

Referencia de API: OracleAgentMemory

OracleThread

Extraer recuerdos de soporte de mensajes de thread

Cree un thread de soporte y agregue mensajes de usuario y asistente. En el ejemplo, se define memory_extraction_config=MemoryExtractionConfig(memory_extraction_frequency=1) para que add_messages() ejecute la extracción automática inmediatamente para la vuelta insertada. Las instrucciones personalizadas mantienen la memoria extraída centrada en los ID de pedido, las solicitudes de devolución y los 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.

La salida mostrada anteriormente es ilustrativa. El texto exacto de la memoria depende del LLM de extracción configurado, pero las memorias extraídas deben seguir las instrucciones personalizadas proporcionadas al cliente.

La diferencia es más fácil de ver al comparar el tipo de memoria que se le pide al extractor:

Con instrucciones personalizadas

El extractor mantiene el hecho duradero de soporte al cliente e ignora el saludo y la redacción conversacional.

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

Sin instrucciones personalizadas

El extractor puede mantener una memoria de conversación más amplia porque el campo de extracción por defecto no tiene un ámbito para admitir operaciones.

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

Referencia de API: OracleThread

Resultado de búsqueda de Oracle

Configurar enlace automático de memoria

El enlace automático de memoria conecta una memoria recién extraída a las memorias existentes relevantes. El SDK recupera un juego limitado de memorias candidatas y solicita al LLM de extracción que decida si se debe crear un enlace escrito. Por defecto, POST_EXTRACTION toma esa decisión en una solicitud adicional después de que se hayan extraído las memorias.

El tipo de enlace describe la relación entre la nueva memoria y el candidato existente. supersedes, refines y duplicates conservan la memoria anterior como historial y la marcan como no válida. supports y contradicts mantienen ambas memorias válidas. El enlace automático está limitado a los candidatos recuperados; utilice las API de enlace explícitas cuando se deba registrar siempre una relación.

Utilice MemoryExtractionConfig para personalizar el enlace automático:

memory_link_extraction_mode controla cuándo se resuelven los enlaces. Utilice POST_EXTRACTION para una solicitud de resolución de enlaces independiente, DURING_EXTRACTION para resolver enlaces en la solicitud de extracción o DISABLED para no crear enlaces automáticos.
memory_link_extraction_custom_instructions agrega orientación a la petición de datos de resolución de enlaces, como qué tipos de relación son adecuados para un dominio.
memory_link_extraction_token_limit establece el presupuesto total del token de entrada para la resolución de enlaces posteriores a la extracción. Los valores inferiores a 1 desactivan este límite.

Al igual que con la configuración de extracción descrita anteriormente, proporcione estos campos a nivel de cliente o sustitúyalos para un thread específico. En el siguiente ejemplo, se actualiza el thread de soporte para enlazar solo cambios significativos en los hechos de soporte:

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

La misma configuración se puede transferir a create_thread() o se puede incluir en MemoryExtractionConfig del cliente. Para obtener más información sobre la creación manual de enlaces y la recuperación del contexto enlazado, consulte Crear y buscar gráficos de memoria enlazados.

Referencia de API: MemoryExtractionConfig

OracleThread

Instrucciones de sustitución para un thread

Transfiera memory_extraction_config=MemoryExtractionConfig(memory_extraction_custom_instructions=...) a create_thread() cuando un thread necesite una política de extracción más estrecha que la predeterminada del cliente. El valor de nivel de thread tiene prioridad para ese thread y se mantiene con la configuración del 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.",
        }
    ]
)

Referencia de API: OracleAgentMemory

OracleThread

Actualizar o borrar instrucciones de subproceso

Utilice update_thread() para cambiar las instrucciones de extracción persistentes para un thread existente. Transfiera None para borrar las instrucciones de nivel de thread para que los identificadores de thread futuros utilicen las instrucciones de nivel de cliente o, si no se configura ninguna, el comportamiento de extracción normal del 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
    ),
)

Nota: get_thread(..., memory_extraction_config=MemoryExtractionConfig(memory_extraction_custom_instructions=...)) puede aplicar instrucciones al identificador de thread activo devuelto sin actualizar la configuración de thread persistente.

Referencia de API: OracleAgentMemory

OracleThread

Conclusión

En esta guía hemos aprendido a configurar instrucciones de extracción personalizadas a nivel de cliente, configurar enlaces automáticos de memoria, anular instrucciones de extracción para un thread específico y actualizar o borrar instrucciones de extracción a nivel de thread.

→ Después de haber aprendido a personalizar la extracción automatizada, ahora puede continuar con Uso de API de corto plazo de memoria de Oracle Agent con LangGraph.

Código Completo

Copie el código completo que aparece a continuación.

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