Memoria agente

Questa pagina presenta l'implementazione concreta di Oracle AI Agent Memory.

Memoria agente Oracle

classe oracleagentmemory.core.OracleAgentMemory

Basi: IAgentMemory

Client di memoria agente supportato da Oracle DB o da un'area di memorizzazione fornita dal chiamante.

Creare un client di memoria.

• Parametri:
  • store OracleMemoryStore: istanza dell'area di memorizzazione preconfigurata opzionale. Se fornito, il client utilizza direttamente questo negozio invece di creare un'istanza del proprio negozio. Ciò è utile quando i chiamanti necessitano di una configurazione dell'area di memorizzazione superiore alle opzioni del costruttore esposte in OracleAgentMemory.
  • connessione object: connessione/pool Oracle DB opzionale. Se specificato, viene utilizzato l'area di memorizzazione DB. Il passaggio di una connessione raw abilita la modalità a sessione singola per questa istanza client, pertanto le richieste concorrenti devono utilizzare un connection pool. Se omesso, i chiamanti devono passare un store esplicito.
  • embedder IEmbedder | str: istanza di implementazione Embedder o identificativo di modello di incorporamento LiteLLM. Se omesso, non viene collegata alcuna incorporazione e i chiamanti devono fornire vettori precalcolati tramite API di memorizzazione di livello inferiore.
  • LLM ILlm: adattatore LLM opzionale utilizzato dai thread per l'estrazione della memoria e/o il riepilogo del contesto. Per impostazione predefinita, i thread creati o caricati da questo client richiedono un LLM in modo che i messaggi recenti possano essere estratti per le memorie permanenti. Passa un llm qui, forniscilo in un secondo momento in create_thread o esci con extract_memories=False.
  • extract_memories bool: quando si utilizza True, i thread creati o caricati da questo client richiedono un LLM e l'estrazione automatica della memoria rimane abilitata. Impostare su False per disabilitare l'estrazione automatica della memoria e consentire a tali thread di funzionare senza un LLM. Il valore predefinito è True, pertanto gli LLM di estrazione mancanti non riescono velocemente.
  • schema_policy SchemaPolicy | str: criterio di impostazione dello schema DB utilizzato solo durante la creazione di un'area di memorizzazione DB da connection. L'impostazione predefinita è SchemaPolicy.REQUIRE_EXISTING.
  • table_name_prefix str: prefisso facoltativo della tabella DB/indice utilizzato solo durante la creazione di un'area di memorizzazione DB da connection.
• Aumenti: ValueError: se viene fornita una configurazione dell'area di memorizzazione in conflitto, ad esempio passando entrambe le opzioni store e connection, le opzioni specifiche del DB senza una connessione DB o omettendo sia store che connection.

Esempi

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

metodo add_agent

Aggiungere un record profilo agente al negozio.

• Parametri:
  • agent_id str: identificativo dell'agente.
  • informazioni str: informazioni in formato libero sull'agente.
• Restituzioni: identificativo del profilo dell'agente memorizzato.
• Tipo restituito: str

Note

I record profilo agente vengono memorizzati nell'area di memorizzazione a livello di client.

Esempi

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

metodo add_memory

Aggiungere una memoria nel sistema di memoria, attribuita all'utente, all'agente e al thread indicati.

• Parametri:
  • content str: il contenuto della memoria deve essere persistente.
  • user_id str: identificativi di ambito opzionali associati alla memoria memorizzata.
  • agent_id str: identificativi di ambito opzionali associati alla memoria memorizzata.
  • thread_id str: identificativi di ambito opzionali associati alla memoria memorizzata.
  • memory_id str: identificativo stabile fornito dal chiamante opzionale per questa riga di memoria.
  • **store_kwargs (Qualsiasi): opzioni di scrittura specifiche dell'area di memorizzazione inoltrate al backing store.
• Restituzioni: identificativo del record di memoria inserito.
• Tipo restituito: str

Esempi

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'

metodo add_user

Aggiungere un record profilo utente al negozio.

• Parametri:
  • user_id str: identificativo utente.
  • informazioni str: informazioni in formato libero sull'utente.
• Restituzioni: identificativo del profilo utente memorizzato.
• Tipo restituito: str

Note

I record profilo utente vengono memorizzati nell'area di memorizzazione a livello di client (non collegati a un thread specifico).

Esempi

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

metodo create_thread

Creare e registrare un thread.

• Parametri:
  • thread_id str: identificativo del thread. Se omesso, ne viene generato uno nuovo.
  • user_id str: identificativo utente associato a questo record thread. Se omesso, ne viene generato uno nuovo.
  • agent_id str: identificativo dell'agente associato a questo record thread. Se omesso, ne viene generato uno nuovo.
  • LLM ILlm: sostituzione LLM opzionale per questo thread. Se omesso, viene utilizzato l'LLM a livello di client configurato al momento della costruzione. Per impostazione predefinita, il client o il thread devono fornire un LLM in modo che l'estrazione automatica della memoria possa essere eseguita. Impostare extract_memories=False qui o sul client per rinunciare a tale requisito.
  • extract_memories bool: sostituzione opzionale per thread per l'estrazione automatica della memoria. Quando si utilizza True, questo thread richiede un LLM in modo che l'estrazione automatica possa essere eseguita. Impostare su False per disabilitare l'estrazione automatica per questo thread e consentire il funzionamento senza un LLM. Se omesso, viene utilizzata l'impostazione extract_memories a livello di client.
  • max_message_token_length int: dimensione massima dei messaggi in fase di prompt prima del troncamento o del riepilogo durante l'estrazione della memoria e gli aggiornamenti di riepilogo del contesto. Il contenuto del messaggio memorizzato rimane invariato. Se omesso, per impostazione predefinita vengono utilizzati i token 15_000.
  • message_shortening_input_token_limit int: la dimensione massima, nei token, dell'estratto del messaggio inviato all'LLM quando si accorciano le copie dei messaggi di prompt time di grandi dimensioni. Se omesso, per impostazione predefinita vengono utilizzati i token 30_000.
  • memory_extraction_window int: numero di messaggi recenti da includere durante l'estrazione della memoria. Impostare su -1 per eseguire un'estrazione per ogni chiamata add_messages utilizzando il batch completo dei nuovi messaggi aggiunti. Se omesso, il valore predefinito è -1.
  • context_summary_update_frequency int: frequenza degli aggiornamenti di summary di contesto. Impostare su -1 per eseguire un aggiornamento di riepilogo per ogni chiamata add_messages utilizzando il batch completo dei nuovi messaggi aggiunti. La stessa cadenza viene riutilizzata per i metadati di riepilogo dei thread aggiornati durante add_messages. Se omesso, il valore predefinito è 4.
  • memory_extraction_frequency int: frequenza degli aggiornamenti dell'estrazione della memoria. Impostare su -1 per eseguire un'estrazione per ogni chiamata add_messages utilizzando il batch completo dei nuovi messaggi aggiunti. Se omesso, il valore predefinito è -1.
  • memory_extraction_token_limit int: dimensione massima del prompt di estrazione nei token. Se omesso, il valore predefinito è 100_000.
  • enable_context_summary bool – Indica se mantenere un riepilogo del contesto di esecuzione per questo thread.
  • **kwarg (Qualsiasi): opzioni di thread aggiuntive specifiche dell'implementazione.
• Restituzioni: A OracleThread.
• Tipo restituito: OracleThread
• Aumenti: ValueError: se non è disponibile alcun LLM per l'estrazione automatica della memoria e il thread e il client non sono stati configurati con extract_memories=False.

Esempi

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'

metodo delete_memory

Eliminare un record di memoria in base all'identificativo.

• Parametri: memory_id str – identificativo della memoria.
• Restituzioni: numero di righe di memoria eliminate (0 o 1).
• Tipo restituito: int.

Esempi

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

metodo delete_thread

Elimina tutti i record associati a un identificativo thread.

• Parametri:
  • thread_id str: identificativo del thread da eliminare.
  • allow_non_existing bool: quando si elimina True, l'eliminazione di un thread mancante viene considerata non operativo.
• Restituzioni: numero di righe di thread eliminate (0 o 1).
• Tipo restituito: int.

Esempi

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

metodo get_thread

Recupera un thread creato in precedenza.

• Parametri:
  • thread_id str: identificativo utilizzato per la creazione del thread.
  • LLM ILlm: sostituzione LLM opzionale per il thread riaperto. Se omesso, viene utilizzato l'LLM a livello di client configurato al momento della costruzione.
  • extract_memories bool: override facoltativo per l'estrazione automatica della memoria nel thread riaperto. Se omesso, viene utilizzata l'impostazione extract_memories a livello di client.
  • max_message_token_length int: override facoltativo per la dimensione massima dei messaggi in fase di prompt prima del troncamento o del riepilogo durante l'estrazione della memoria e gli aggiornamenti di riepilogo del contesto. Il contenuto del messaggio memorizzato rimane invariato.
  • message_shortening_input_token_limit int: override facoltativo per la dimensione massima, nei token, dell'estratto del messaggio inviato all'LLM quando si accorciano le copie dei messaggi di prompt time di grandi dimensioni.
  • memory_extraction_window int: override facoltativo per il numero di messaggi recenti utilizzati durante l'estrazione della memoria.
  • context_summary_update_frequency int: sostituzione facoltativa per la frequenza degli aggiornamenti di context-summary.
  • memory_extraction_frequency int: sostituzione facoltativa per la frequenza degli aggiornamenti di estrazione della memoria.
  • memory_extraction_token_limit int: sostituzione facoltativa per la dimensione massima del prompt di estrazione nei token.
  • enable_context_summary bool: override facoltativo per determinare se il thread riaperto deve mantenere un riepilogo del contesto in esecuzione.
• Restituzioni: un handle di thread ricostruito dai metadati dell'area di memorizzazione.
• Tipo restituito: OracleThread
• Solleva:
  • KeyError: se l'ID thread è sconosciuto a questa istanza client.
  • ValueError: se non è disponibile alcun LLM per l'estrazione automatica della memoria e il client non è stato configurato con extract_memories=False.

Note

Le sostituzioni esplicite per chiamata hanno la precedenza. Quando gli override runtime vengono omessi, i thread riaperti utilizzano la configurazione runtime persistente quando disponibile prima di tornare ai valori predefiniti dell'SDK.

Esempi

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'