Agent-Speicher

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

Oracle Agent-Speicher

Hinweis: OracleAgentMemory.delete_thread() ist der unterstützte Pfad für die Thread-bezogene kaskadierende Bereinigung. Es entfernt den Thread zusammen mit zugehörigen Nachrichten, dauerhaften Speichern und verwalteten Vektor- oder Chunk-Daten. Dies ist breiter als OracleThread.delete_message(), wodurch nur die Raw-Nachrichtenzeile gelöscht wird.

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 und absichtlich nicht kopiert. Die zurückgegebene Datensatz-ID ist dieselbe öffentliche ID, die von der Anwendung verwendet wird wie agent_id.

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 Kundenspeicher gespeichert und absichtlich unkopiert. Die zurückgegebene Datensatz-ID ist dieselbe öffentliche ID, die von der Anwendung verwendet wird wie user_id.

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.
  • metadata dict[str, Any] | None – Optionale JSON-ähnliche Metadaten werden in der Threadzeile persistiert.
  • 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. Wenn diese Option ausgelassen wird, wird standardmäßig -1 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 Größe der LLM-Prompts, die für die Speicherextraktion und die Ausführung von Zusammenfassungsaktualisierungen verwendet werden, in Token. Wenn diese Option ausgelassen wird, wird standardmäßig 100_000 verwendet.
  • context_card_token_limit int – Maximale Größe in Token der LLM-Eingabeaufforderungen, die für die Kontextkartenzusammenfassung verwendet werden. 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_agent

Agent-Profildatensatz nach ID löschen.

• Parameter:
  • agent_id str: Agent-ID, deren Profil entfernt werden soll.
  • kaskadieren bool – Wenn True (Standard) gilt, löschen Sie auch Datensätze, die für diesen Agent gelten. Dazu gehören das Löschen eigener Threads selbst, der Nachrichten und speicherähnlicher Datensätze, die mit diesen Threads entfernt wurden, sowie aller verbleibenden direkt auf Agents bezogenen Datensätze, wie Nachrichten, Speicher, Richtlinien, Fakten oder Vorlieben. Diese Bereichsbereinigung wird noch ausgeführt, wenn die entsprechende Agent-Profilzeile bereits fehlt. Setzen Sie diesen Wert auf False, um nur den Profildatensatz zu entfernen.
• Rückgaben: Anzahl der gelöschten Agent-Profilzeilen (0 oder 1). Dies kann immer noch 0 sein, wenn Bereichszeilen während der Kaskadenbereinigung entfernt wurden.
• Rückgabetyp: int

Hinweise

Kaskadierende Löschvorgänge werden im zugrunde liegenden Speicher geplant und ausgeführt, sodass das Löschen des Profils und alle untergeordneten Löschvorgänge mit Geltungsbereich in einem Speichervorgang erfolgen.

Beispiele

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_agent("a-delete", "Support assistant")
'a-delete'
client.delete_agent("a-delete")
1

Methode delete_memory

Löschen Sie einen speicherähnlichen Datensatz (z. B. Speicher, Fakt, Voreinstellung oder Richtlinie) nach Kennung.

• Parameter: memory_id str – Speicher-ID. Die ID kann sich auf einen gespeicherten memory-, guideline-, fact- oder preference-Datensatz beziehen.
• Rückgaben: Anzahl der gelöschten speicherähnlichen Zeilen (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.
• Rückgaben: Anzahl der gelöschten Threadzeilen (0 oder 1).
• Rückgabetyp: int

Hinweise

Verwenden Sie diesen Vorgang, wenn ein Thread vollständig entfernt werden muss. Der Backing Store löscht den Thread zusammen mit zugehörigen Thread-bezogenen Nachrichten, dauerhaften Speichern und verwalteten Vektor- oder Chunk-Zeilen. Dies unterscheidet sich von OracleThread.delete_message(), das nur den Raw-Nachrichtendatensatz entfernt und nicht auf abgeleitete Speicher kaskadiert, die aus dieser Nachricht erstellt wurden.

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 delete_user

Benutzerprofildatensatz nach ID löschen.

• Parameter:
  • user_id str: Benutzer-ID, deren Profil entfernt werden soll.
  • kaskadieren bool – Wenn True (Standard) gilt, löschen Sie auch Datensätze, die für diesen Benutzer gelten. Dazu gehören das Löschen eigener Threads selbst, der Nachrichten und speicherähnlicher Datensätze, die mit diesen Threads entfernt wurden, sowie aller verbleibenden direkt benutzerbezogenen Datensätze, wie Nachrichten, Speicher, Richtlinien, Fakten oder Vorlieben. Diese Bereichsbereinigung wird noch ausgeführt, wenn die übereinstimmende Benutzerprofilzeile bereits fehlt. Setzen Sie diesen Wert auf False, um nur den Profildatensatz zu entfernen.
• Rückgaben: Anzahl der gelöschten Benutzerprofilzeilen (0 oder 1). Dies kann immer noch 0 sein, wenn Bereichszeilen während der Kaskadenbereinigung entfernt wurden.
• Rückgabetyp: int

Hinweise

Kaskadierende Löschvorgänge werden im zugrunde liegenden Speicher geplant und ausgeführt, sodass das Löschen des Profils und alle untergeordneten Löschvorgänge mit Geltungsbereich in einem Speichervorgang erfolgen.

Beispiele

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_user("u-delete", "Prefers concise answers.")
'u-delete'
client.delete_user("u-delete")
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 Größe der LLM-Prompts, die für die Speicherextraktion und die Ausführung von Zusammenfassungsupdates verwendet werden, in Token.
  • context_card_token_limit int – Optionales Override für die maximale Größe in Token der LLM-Prompts, die für die Kontextkartenzusammenfassung verwendet werden.
  • 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'