Automatische Speicherextraktion anpassen

Die automatische Speicherextraktion kann nützliche Details ohne zusätzliche Konfiguration erfassen. Mit benutzerdefinierten Anweisungen kann eine Anwendung dem Extraktionsprozess Anleitungen hinzufügen, wenn das Standardverhalten für einen bestimmten Anwendungsfall angepasst werden muss.

In diesem Handbuch wird erläutert, wie Sie die automatische Speicherextraktion von Oracle AI Agent Memory mit benutzerdefinierten Anweisungen durchführen.

Mit benutzerdefinierten Anweisungen können Sie domänenspezifische Anweisungen angeben, welche Details als dauerhafter Speicher beibehalten werden sollten. Sie sind nützlich, wenn Ihre Anwendung Extraktion benötigt, um das Expertenurteil, die Produktrichtlinie oder Workflow-spezifische Prioritäten widerzuspiegeln, anstatt jedes potenziell denkbare Detail auf die gleiche Weise zu behandeln.

Hinweis: Verwenden Sie benutzerdefinierte Anweisungen, wenn die Speicherextraktion anwendungsspezifischen Anweisungen folgen soll. Die Standardextraktion ist geeignet, wenn keine zusätzlichen Anweisungen erforderlich sind.

Hinweis: Informationen zur Installation von oracleagentmemory finden Sie unter Erste Schritte mit Agent-Speicher. Wenn Sie für dieses Beispiel eine lokale Oracle AI Database benötigen, folgen Sie Oracle AI Database lokal ausführen.

Extraktionsanweisungen auf Client-Ebene konfigurieren

Erstellen Sie die Oracle Agent Memory-Komponente mit einer Oracle DB-Verbindung oder einem Pool, einem Einbettungsmodul, einem LLM und unterstützungsorientierten Extraktionsanweisungen. Diese Anweisungen gelten für Threads, die über diesen Client erstellt oder geladen wurden, es sei denn, ein Thread stellt seine eigenen Extraktionsanweisungen bereit.

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

API-Referenz: OracleAgentMemory

OracleThread

Support-Memories aus Thread-Nachrichten extrahieren

Erstellen Sie einen Support-Thread, und fügen Sie Benutzer- und Assistentennachrichten hinzu. Im Beispiel wird memory_extraction_config=MemoryExtractionConfig(memory_extraction_frequency=1) festgelegt, sodass add_messages() die automatische Extraktion sofort für den eingefügten Turn ausführt. In den benutzerdefinierten Anweisungen wird der extrahierte Speicher auf Bestell-IDs, Rücksendeanforderungen und Zustellungsprobleme konzentriert.

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.

Die zuvor gezeigte Ausgabe ist illustrativ. Der genaue Speichertext hängt vom konfigurierten Extraktions-LLM ab, die extrahierten Speicher sollten jedoch den benutzerdefinierten Anweisungen folgen, die dem Client bereitgestellt werden.

Der Unterschied ist am einfachsten zu sehen, indem man die Art des Speichers vergleicht, den der Extraktor halten soll:

Mit benutzerdefinierten Anweisungen

Der Extraktor hält die dauerhafte Kundenunterstützung Tatsache und ignoriert die Begrüßung und Konversation Wortlaut.

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

Ohne benutzerdefinierte Anweisungen

Der Extraktor behält möglicherweise einen umfassenderen Konversationsspeicher bei, da die Standardeingabeaufforderung zur Extraktion nicht für die Unterstützung von Vorgängen ausgelegt ist.

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

API-Referenz: OracleThread

OracleSearchResult

Automatische Speicherverknüpfung konfigurieren

Die automatische Speicherverknüpfung verbindet einen neu extrahierten Speicher mit relevanten vorhandenen Speichern. Das SDK ruft eine begrenzte Gruppe von Kandidatenspeichern ab und fragt das Extraktions-LLM, ob ein typisierter Link erstellt werden soll. Standardmäßig trifft POST_EXTRACTION diese Entscheidung in einer zusätzlichen Anforderung, nachdem die Speicher extrahiert wurden.

Der Linktyp beschreibt die Beziehung zwischen dem neuen Speicher und dem vorhandenen Kandidaten. supersedes, refines und duplicates behalten den älteren Speicher als Historie bei und markieren ihn als ungültig. supports und contradicts behalten beide Speicher gültig bei. Die automatische Verknüpfung ist auf die abgerufenen Kandidaten beschränkt. Verwenden Sie die expliziten Verknüpfungs-APIs, wenn eine Beziehung immer aufgezeichnet werden muss.

Verwenden Sie MemoryExtractionConfig, um die automatische Verknüpfung anzupassen:

memory_link_extraction_mode steuert, wann Links aufgelöst werden. Verwenden Sie POST_EXTRACTION für eine separate Anforderung zur Linkauflösung, DURING_EXTRACTION für das Auflösen von Links in der Extraktionsanforderung oder DISABLED, um keine automatischen Links zu erstellen.
memory_link_extraction_custom_instructions fügt dem Prompt für die Linkauflösung Anweisungen hinzu, z.B. welche Beziehungstypen für eine Domain geeignet sind.
memory_link_extraction_token_limit legt das gesamte Input-Token-Budget für die Auflösung von Post-Extraction-Links fest. Werte unter 1 deaktivieren diesen Grenzwert.

Wie bei den zuvor beschriebenen Extraktionseinstellungen stellen Sie diese Felder auf Client-Ebene bereit oder überschreiben sie für einen bestimmten Thread. Im folgenden Beispiel wird der Support-Thread so aktualisiert, dass nur sinnvolle Änderungen an Support-Fakten verknüpft werden:

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

Dieselben Einstellungen können an create_thread() übergeben oder in der MemoryExtractionConfig des Clients enthalten sein. Weitere Informationen zum manuellen Erstellen von Links und Abrufen des verknüpften Kontexts finden Sie unter Verknüpfte Speicherdiagramme erstellen und suchen.

API-Referenz: MemoryExtractionConfig

OracleThread

Anweisungen für einen Thread überschreiben

Übergeben Sie memory_extraction_config=MemoryExtractionConfig(memory_extraction_custom_instructions=...) an create_thread(), wenn ein Thread eine engere Extraktions-Policy benötigt als der Clientstandard. Der Wert auf Thread-Ebene hat Vorrang für diesen Thread und wird mit der Thread-Konfiguration beibehalten.

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.",
        }
    ]
)

API-Referenz: OracleAgentMemory

OracleThread

Anleitung zum Aktualisieren oder Löschen des Threads

Verwenden Sie update_thread(), um persistente Extraktionsanweisungen für einen vorhandenen Thread zu ändern. Übergeben Sie None, um die Anweisungen auf Threadebene zu löschen, sodass zukünftige Thread-Handles die Anweisungen auf Client-Ebene verwenden oder, wenn keine konfiguriert sind, das normale Extraktionsverhalten des 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
    ),
)

Hinweis: get_thread(..., memory_extraction_config=MemoryExtractionConfig(memory_extraction_custom_instructions=...)) kann Anweisungen auf das zurückgegebene Live-Thread-Handle anwenden, ohne die Konfiguration des persistenten Threads zu aktualisieren.

API-Referenz: OracleAgentMemory

OracleThread

Abschluss

In dieser Anleitung haben wir gelernt, wie Sie benutzerdefinierte Extraktionsanweisungen auf Client-Ebene konfigurieren, automatische Speicherverknüpfungen konfigurieren, Extraktionsanweisungen für einen bestimmten Thread außer Kraft setzen und Extraktionsanweisungen auf Thread-Ebene aktualisieren oder löschen.

→ Nachdem Sie gelernt haben, wie Sie die automatisierte Extraktion anpassen, können Sie jetzt mit Oracle Agent Memory Short-Term APIs mit LangGraph verwenden fortfahren.

Vollständiger Code

Kopieren Sie den folgenden vollständigen Code.

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