Personalizza estrazione automatica memoria

L'estrazione automatica della memoria può acquisire dettagli utili senza ulteriori configurazioni. Le istruzioni personalizzate consentono a un'applicazione di aggiungere linee guida al processo di estrazione quando il comportamento predefinito deve essere personalizzato per un caso d'uso specifico.

Questa guida spiega come eseguire l'estrazione automatica della memoria di Oracle AI Agent Memory con istruzioni personalizzate.

Le istruzioni personalizzate consentono di fornire linee guida specifiche del dominio su quali dettagli vale la pena conservare come memoria permanente. Sono utili quando la tua applicazione ha bisogno di estrazione per riflettere il giudizio degli esperti, la politica del prodotto o le priorità specifiche del flusso di lavoro invece di trattare ogni dettaglio potenzialmente memorabile allo stesso modo.

Nota: utilizzare istruzioni personalizzate quando l'estrazione della memoria deve seguire istruzioni specifiche dell'applicazione. L'estrazione predefinita è appropriata quando non sono necessarie ulteriori indicazioni.

Suggerimento: per informazioni sull'installazione di oracleagentmemory, vedere Introduzione alla memoria agente. Se hai bisogno di un Oracle AI Database locale per questo esempio, segui Esegui Oracle AI Database localmente.

Configurare le istruzioni di estrazione a livello di client

Creare il componente Oracle Agent Memory con una connessione o un pool Oracle DB, un programma di incorporazione, un LLM e istruzioni di estrazione incentrate sul supporto. Queste istruzioni si applicano ai thread creati o caricati tramite questo client a meno che un thread non fornisca le proprie istruzioni di estrazione.

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

Riferimento API: OracleAgentMemory

OracleThread

Estrai memorie di supporto da messaggi thread

Creare un thread di supporto e aggiungere messaggi utente e assistente. L'esempio imposta memory_extraction_config=MemoryExtractionConfig(memory_extraction_frequency=1) in modo che add_messages() esegua l'estrazione automatica immediatamente per il turno inserito. Le istruzioni personalizzate mantengono la memoria estratta concentrata sugli ID degli ordini, sulle richieste di reso e sui problemi di consegna.

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.

L'output mostrato in precedenza è illustrativo. Il testo esatto della memoria dipende dal LLM di estrazione configurato, ma le memorie estratte devono seguire le istruzioni personalizzate fornite al client.

La differenza è più facile da vedere confrontando il tipo di memoria che l'estrattore è chiamato a mantenere:

Con istruzioni personalizzate

L'estrattore mantiene il fatto duraturo di supporto del cliente e ignora il saluto e la formulazione conversazionale.

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

Senza istruzioni personalizzate

L'estrattore può mantenere una memoria di conversazione più ampia perché il prompt di estrazione predefinito non è definito per supportare le operazioni.

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

Riferimento API: OracleThread

Risultati ricerca Oracle

Configura collegamento automatico memoria

Il collegamento automatico della memoria collega una memoria appena estratta alle memorie esistenti rilevanti. L'SDK recupera un insieme limitato di memorie candidate e chiede all'LLM di estrazione di decidere se creare un collegamento digitato. Per impostazione predefinita, POST_EXTRACTION prende tale decisione in una richiesta aggiuntiva dopo l'estrazione delle memorie.

Il tipo di collegamento descrive la relazione dalla nuova memoria al candidato esistente. supersedes, refines e duplicates conservano la memoria precedente come cronologia e la contrassegnano come non valida. supports e contradicts mantengono entrambe le memorie valide. Il collegamento automatico è limitato ai candidati recuperati; utilizzare le API di collegamento esplicito quando una relazione deve essere sempre registrata.

Utilizzare MemoryExtractionConfig per personalizzare il collegamento automatico:

memory_link_extraction_mode controlla quando i collegamenti vengono risolti. Utilizzare POST_EXTRACTION per una richiesta di risoluzione dei collegamenti separata, DURING_EXTRACTION per risolvere i collegamenti nella richiesta di estrazione o DISABLED per non creare collegamenti automatici.
memory_link_extraction_custom_instructions aggiunge istruzioni al prompt di risoluzione dei collegamenti, ad esempio i tipi di relazione appropriati per un dominio.
memory_link_extraction_token_limit imposta il budget input-token totale per la risoluzione dei collegamenti post-estrazione. I valori inferiori a 1 disabilitano questo limite.

Come per le impostazioni di estrazione descritte in precedenza, fornire questi campi a livello di client o sostituirli per un thread specifico. L'esempio seguente aggiorna il thread di supporto per collegare solo modifiche significative nei fact di supporto.

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

Le stesse impostazioni possono essere passate a create_thread() o incluse nel file MemoryExtractionConfig del client. Per informazioni dettagliate sulla creazione manuale dei collegamenti e sul recupero del contesto collegato, vedere Creazione e ricerca di grafici di memoria collegati.

Riferimento API: MemoryExtractionConfig

OracleThread

Override istruzioni per un thread

Passare da memory_extraction_config=MemoryExtractionConfig(memory_extraction_custom_instructions=...) a create_thread() quando un thread richiede un criterio di estrazione più ristretto rispetto al valore predefinito del client. Il valore a livello di thread ha la precedenza per quel thread ed è persistente con la configurazione 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.",
        }
    ]
)

Riferimento API: OracleAgentMemory

OracleThread

Aggiorna o cancella istruzioni thread

Utilizzare update_thread() per modificare le istruzioni di estrazione persistenti per un thread esistente. Passare None per cancellare le istruzioni a livello di thread in modo che i futuri handle di thread utilizzino le istruzioni a livello di client o, se non ne sono configurati, il normale funzionamento di estrazione dell'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=...)) può applicare le istruzioni all'handle del thread attivo restituito senza aggiornare la configurazione del thread persistente.

Riferimento API: OracleAgentMemory

OracleThread

Conclusione

In questa guida abbiamo imparato come configurare le istruzioni di estrazione personalizzate a livello di client, configurare il collegamento automatico della memoria, sostituire le istruzioni di estrazione per un thread specifico e aggiornare o cancellare le istruzioni di estrazione a livello di thread.

→ Dopo aver appreso come personalizzare l'estrazione automatizzata, ora è possibile passare a Usa API a breve termine della memoria di Oracle Agent con LangGraph.

Codice completo

Copiare il codice completo che segue.

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