Agent-Speicher

Auf dieser Seite wird die konkrete Implementierung von Oracle AI Agent Memory vorgestellt.

Oracle Agent-Speicher

Klasse oracleagentmemory.core.OracleAgentMemory

Basen: IAgentMemory

Agent-Speicherclient, der von Oracle DB oder einem vom Aufrufer bereitgestellten Speicher gesichert wird.

Erstellen Sie einen Speicherclient.

• Parameter:
  • store OracleMemoryStore – Optionale vorkonfigurierte Speicherinstanz. Wenn angegeben, verwendet der Client diesen Speicher direkt, anstatt seinen eigenen Speicher zu instanziieren. Dies ist nützlich, wenn Aufrufer eine Speicherkonfiguration benötigen, die über die in OracleAgentMemory angegebenen Konstruktoroptionen hinausgeht.
  • Verbindung object – Optionale Oracle DB-Verbindung/Pool. Wenn angegeben, wird der DB-Speicher verwendet. Wenn Sie eine Raw-Verbindung übergeben, wird der Single Session-Modus für diese Clientinstanz aktiviert. Daher sollten gleichzeitige Anforderungen stattdessen einen Connection Pool verwenden. Wenn diese Option ausgelassen wird, müssen Aufrufer eine explizite store übergeben.
  • embedder IEmbedder | str: Embedder-Implementierungsinstanz oder LiteLLM-Einbettungsmodell-ID. Wenn er ausgelassen wird, wird kein Embedder angehängt, und Aufrufer müssen vorab berechnete Vektoren über Speicher-APIs der unteren Ebene bereitstellen.
  • LLM ILlm – Optionaler LLM-Adapter, der von Threads zur Speicherextraktion und/oder Kontextzusammenfassung verwendet wird. Standardmäßig erfordern Threads, die von diesem Client erstellt oder geladen werden, ein LLM, damit aktuelle Nachrichten für dauerhafte Speicher abgebaut werden können. Übergeben Sie hier eine llm, geben Sie eine spätere in create_thread an, oder melden Sie sich bei extract_memories=False ab.
  • extract_memories bool – Wenn True, von diesem Client erstellte oder geladene Threads ein LLM erfordern und die automatische Speicherextraktion aktiviert bleibt. Setzen Sie diesen Wert auf False, um die automatische Speicherextraktion zu deaktivieren und zuzulassen, dass diese Threads ohne LLM ausgeführt werden können. Der Standardwert ist True, sodass fehlende Extraktions-LLMs schnell fehlschlagen.
  • schema_policy SchemaPolicy | str: Die Setup-Policy für das DB-Schema wird nur beim Erstellen eines DB-Speichers aus connection verwendet. Standard ist SchemaPolicy.REQUIRE_EXISTING.
  • table_name_prefix str: Optionales DB-Tabellen-/Indexpräfix, das nur beim Erstellen eines DB-Speichers aus connection verwendet wird.
• Raises: ValueError – Wenn eine widersprüchliche Speicherkonfiguration angegeben wird, wie die Übergabe von store und connection, DB-spezifischen Optionen ohne DB-Verbindung oder das Weglassen von store und connection.

Beispiele

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
read_only_client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    extract_memories=False,
)

Methode add_agent

Fügen Sie dem Shop einen Agent-Profildatensatz hinzu.

• Parameter:
  • agent_id str: Agent-ID.
  • Informationen str – Freiforminformationen zum Agent.
• Rückgaben: ID des gespeicherten Agent-Profils.
• Rückgabetyp: str

Hinweise

Agent-Profildatensätze werden im Speicher auf Client-Ebene gespeichert.

Beispiele

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_agent("a1", "Support assistant")
'a1'

Methode add_memory

Fügen Sie im Speichersystem einen Speicher hinzu, der dem angegebenen Benutzer, Agent und Thread zugewiesen wird.

• Parameter:
  • content str: Zu persistierender Speicherinhalt.
  • user_id str – Optionale Geltungsbereichs-IDs, die mit dem gespeicherten Speicher verknüpft sind.
  • agent_id str – Optionale Geltungsbereichs-IDs, die mit dem gespeicherten Speicher verknüpft sind.
  • thread_id str – Optionale Geltungsbereichs-IDs, die mit dem gespeicherten Speicher verknüpft sind.
  • memory_id str – Optionale vom Aufrufer bereitgestellte stabile ID für diese Speicherzeile.
  • **store_kwargs (Beliebige) – Speicherspezifische Schreiboptionen, die an den zugrunde liegenden Speicher weitergeleitet werden.
• Rückgaben: ID des eingefügten Speicherdatensatzes.
• Rückgabetyp: str

Beispiele

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
memory_id = client.add_memory("User likes pizza", memory_id="mem-1")
memory_id
'mem-1'

Methode add_user

Fügen Sie der Filiale einen Benutzerprofildatensatz hinzu.

• Parameter:
  • user_id str: Benutzer-ID.
  • Informationen str – Freiforminformationen zum Benutzer.
• Rücksendungen: ID des gespeicherten Benutzerprofils.
• Rückgabetyp: str

Hinweise

Benutzerprofildatensätze werden im Speicher auf Client-Ebene gespeichert (nicht an einen bestimmten Thread gebunden).

Beispiele

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_user("u1", "Prefers concise answers.")
'u1'

Methode create_thread

einen Thread erstellen und registrieren

• Parameter:
  • thread_id str: Thread-ID. Wird keine Angabe gemacht, wird eine neue generiert.
  • user_id str: Benutzer-ID, die an diesen Threaddatensatz angehängt ist. Wird keine Angabe gemacht, wird eine neue generiert.
  • agent_id str: Agent-ID, die an diesen Threaddatensatz angehängt ist. Wird keine Angabe gemacht, wird eine neue generiert.
  • LLM ILlm – Optionales LLM-Override für diesen Thread. Wird dieser Wert ausgelassen, wird das zur Bauzeit konfigurierte LLM auf Client-Ebene verwendet. Standardmäßig muss entweder der Client oder der Thread ein LLM bereitstellen, damit die automatische Speicherextraktion ausgeführt werden kann. Legen Sie extract_memories=False hier oder auf dem Client fest, um diese Anforderung abzulehnen.
  • extract_memories bool – Optionale Überschreibung pro Thread für automatische Speicherextraktion. Bei True erfordert dieser Thread ein LLM, damit die automatische Extraktion ausgeführt werden kann. Setzen Sie diesen Wert auf False, um die automatische Extraktion für diesen Thread zu deaktivieren und den Vorgang ohne LLM zuzulassen. Wenn keine Angabe gemacht wird, wird die Einstellung extract_memories auf Clientebene verwendet.
  • max_message_token_length int – Maximale Größe für Prompt-Time-Nachrichten vor dem Abschneiden oder Zusammenfassen während der Speicherextraktion und Aktualisierungen der Kontextzusammenfassung. Der gespeicherte Nachrichteninhalt bleibt unverändert. Wenn diese Option ausgelassen wird, wird standardmäßig 15_000-Token verwendet.
  • message_shortening_input_token_limit int – Maximale Größe in Token des an das LLM gesendeten Nachrichtenauszugs beim Kürzen von übergroßen Prompt-Time-Nachrichtenkopien. Wenn diese Option ausgelassen wird, wird standardmäßig 30_000-Token verwendet.
  • memory_extraction_window int: Anzahl der letzten Nachrichten, die während der Speicherextraktion aufgenommen werden sollen. Setzen Sie diesen Wert auf -1, um eine Extraktion pro add_messages-Aufruf mit dem vollständigen Batch neu hinzugefügter Nachrichten auszuführen. Wenn diese Option ausgelassen wird, wird standardmäßig -1 verwendet.
  • context_summary_update_frequency int – Häufigkeit von Aktualisierungen der Kontextübersicht. Setzen Sie diesen Wert auf -1, um eine Übersichtsaktualisierung pro add_messages-Aufruf mit dem vollständigen Batch neu hinzugefügter Nachrichten auszuführen. Dieselbe Häufigkeit wird für Threadzusammenfassungsmetadaten wiederverwendet, die während der Aktualisierung von add_messages aktualisiert wurden. Wenn diese Option ausgelassen wird, wird standardmäßig 4 verwendet.
  • memory_extraction_frequency int – Häufigkeit von Aktualisierungen der Speicherextraktion. Setzen Sie diesen Wert auf -1, um eine Extraktion pro add_messages-Aufruf mit dem vollständigen Batch neu hinzugefügter Nachrichten auszuführen. Wenn diese Option ausgelassen wird, wird standardmäßig -1 verwendet.
  • memory_extraction_token_limit int – Maximale Extraktions-Prompt-Größe in Token. Wenn diese Option ausgelassen wird, wird standardmäßig 100_000 verwendet.
  • enable_context_summary bool – Gibt an, ob eine laufende Kontextübersicht für diesen Thread beibehalten werden soll.
  • **kwargs (Beliebig) – Zusätzliche implementierungsspezifische Threadoptionen.
• Rückgaben: Eine OracleThread.
• Rückgabetyp: OracleThread
• Raises: ValueError – Wenn kein LLM für die automatische Speicherextraktion verfügbar ist und Thread und Client nicht mit extract_memories=False konfiguriert wurden.

Beispiele

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
thread = client.create_thread(thread_id="c1", user_id="u1")
thread.thread_id
'c1'

Methode delete_memory

Speicherdatensatz nach Kennung löschen.

• Parameter: memory_id str – Speicher-ID.
• Rückgaben: Anzahl der gelöschten Speicherzeilen (0 oder 1).
• Rückgabetyp: int

Beispiele

client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
memory_id = client.add_memory("Temporary memory", memory_id="mem-delete")
client.delete_memory(memory_id)
1

Methode delete_thread

Löschen Sie alle Datensätze, die mit einer Thread-ID verknüpft sind.

• Parameter:
  • thread_id str: Zu löschende Thread-ID.
  • allow_non_existing bool – Wenn True gelöscht wird, wird ein fehlender Thread als "no-op" behandelt.
• Rückgaben: Anzahl der gelöschten Threadzeilen (0 oder 1).
• Rückgabetyp: int

Beispiele

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
thread = client.create_thread(thread_id="c-delete")
client.delete_thread(thread.thread_id)
1

Methode get_thread

Ruft einen zuvor erstellten Thread ab.

• Parameter:
  • thread_id str: ID, die beim Erstellen des Threads verwendet wird.
  • LLM ILlm – Optionales LLM-Override für den erneut geöffneten Thread. Wird das LLM auf Client-Ebene ausgelassen, das zur Bauzeit konfiguriert wurde, wird verwendet.
  • extract_memories bool – Optionales Override für die automatische Speicherextraktion im erneut geöffneten Thread. Wenn diese Option ausgelassen wird, wird die Einstellung extract_memories auf Clientebene verwendet.
  • max_message_token_length int – Optionales Override für die maximale Größe von Prompt-Time-Nachrichten vor dem Abschneiden oder Zusammenfassen während der Speicherextraktion und Aktualisierungen der Kontextzusammenfassung. Der gespeicherte Nachrichteninhalt bleibt unverändert.
  • message_shortening_input_token_limit int – Optionale Überschreibung für die maximale Größe des Nachrichtenauszugs in Token, der an das LLM gesendet wird, wenn übergroße Nachrichtenkopien zur Eingabeaufforderung gekürzt werden.
  • memory_extraction_window int – Optionales Override für die Anzahl der letzten Nachrichten, die während der Speicherextraktion verwendet wurden.
  • context_summary_update_frequency int – Optionale Überschreibung für die Häufigkeit von Aktualisierungen der Kontextübersicht.
  • memory_extraction_frequency int – Optionales Override für die Häufigkeit von Aktualisierungen der Speicherextraktion.
  • memory_extraction_token_limit int – Optionales Override für die maximale Extraktions-Prompt-Größe in Token.
  • enable_context_summary bool – Optionales Override, wenn der erneut geöffnete Thread eine laufende Kontextzusammenfassung beibehalten soll.
• Rückgaben: Ein Thread-Handle, das aus Speichermetadaten rekonstruiert wurde.
• Rückgabetyp: OracleThread
• Erhöht:
  • KeyError – Wenn die Thread-ID dieser Clientinstanz unbekannt ist.
  • ValueError – Wenn kein LLM für die automatische Speicherextraktion verfügbar ist und der Client nicht mit extract_memories=False konfiguriert wurde.

Hinweise

Explizite Overrides pro Aufruf haben Vorrang. Wenn Laufzeit-Overrides ausgelassen werden, verwenden erneut geöffnete Threads eine persistente Laufzeitkonfiguration, sofern verfügbar, bevor sie auf SDK-Standardwerte zurückgreifen.

Beispiele

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
created = client.create_thread(thread_id="c1", user_id="u1")
loaded = client.get_thread("c1")
loaded.user_id
'u1'