Memoria agente

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

Memoria agente Oracle

Nota: OracleAgentMemory.delete_thread() è il percorso supportato per il cleanup a catena con ambito thread. Rimuove il thread insieme ai messaggi associati, alle memorie permanenti e ai dati di recupero gestiti. Questo valore è più ampio di OracleThread.delete_message(), che elimina solo la riga del messaggio raw. Prima di eliminare il thread, attende l'estrazione in background accettata in precedenza già nota a questo client per tale thread. Non serializza ogni operazione concorrente per lo stesso thread mentre è in corso l'eliminazione.

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.

Avvertenza: SchemaPolicy.CREATE_IF_NECESSARY può essere più costoso del normale avvio del client perché potrebbe applicare DDL dello schema gestito e riscrivere i dati con il massimo sforzo prima che l'inizializzazione abbia esito positivo. Pianificare la prima apertura di uno schema gestito meno recente come operazione di migrazione o manutenzione quando tale schema può contenere più righe.

Se l'impostazione dello schema deve creare il job di rimozione dei record scaduti gestiti, ma l'utente del database non dispone del privilegio scheduler-job, l'inizializzazione avverte e continua. I messaggi e le memorie scaduti rimangono nascosti dalle letture e dalle ricerche, ma non vengono rimossi fisicamente fino a quando il job non viene creato da un utente con CREATE JOB o un privilegio scheduler equivalente.

Quando SchemaPolicy.CREATE_IF_NECESSARY crea per la prima volta un indice ibrido gestito su uno schema esistente, Oracle analizza il testo di ricerca memorizzato e crea lo stato dell'indice ibrido gestito dal modello in-database configurato. L'avvio del client attende il completamento di tale DDL, quindi pianifica il primo aggiornamento ibrido come operazione di migrazione o manutenzione per schemi di grandi dimensioni. SearchIndexSyncMode controlla la manutenzione in corso dopo che l'indice esiste; non rende la prima build dell'indice asincrona.

Esempi

from oracleagentmemory.core import (
    MemoryExtractionConfig,
    SearchIndexSyncMode,
    OracleAgentMemory,
    SchemaPolicy,
    SearchStrategy,
)
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
read_only_client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
)

Utilizzare un modello di incorporamento in DB per sfruttare la ricerca degli indici ibridi Oracle:

from oracleagentmemory.core.embedders import OracleDBEmbedder
db_embedder = OracleDBEmbedder(
    connection=db_pool,
    model="DOC_MODEL",
    embedding_dimension=768,
)
hybrid_client = OracleAgentMemory(
    connection=db_pool,
    embedder=db_embedder,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    search_strategy=SearchStrategy.HYBRID,
    search_index_sync=SearchIndexSyncMode.ON_COMMIT,
)

metodo add_agent

Aggiungere un record profilo agente al negozio.

Note

I record profilo agente vengono memorizzati nell'area di memorizzazione a livello di client e non hanno un ambito intenzionale. L'identificativo del record restituito è lo stesso identificativo pubblico utilizzato dall'applicazione come agent_id.

Esempi

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_agent(
    "a1",
    "Support assistant",
    metadata={"source": "catalog"},
)
'a1'

metodo add_memory

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

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_memory_async (asincrono)

Aggiungere un record di memoria al client in modo asincrono.

metodo add_user

Aggiungere un record profilo utente al negozio.

Note

I record del profilo utente vengono memorizzati nell'area di memorizzazione a livello di client e sono intenzionalmente senza ambito. L'identificativo del record restituito è lo stesso identificativo pubblico utilizzato dall'applicazione come user_id.

Esempi

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_user(
    "u1",
    "Prefers concise answers.",
    metadata={"source": "crm"},
)
'u1'

metodo close

Chiudere il componente di memoria dell'agente.

La chiusura interrompe l'accettazione del nuovo lavoro di estrazione in background e attende il completamento dell'estrazione della memoria in background in sospeso fino al timeout configurato. Se il timeout scade, close() restituisce anche se alcuni lavori di estrazione in background sono ancora incompiuti. Il metodo è idempotente.

Esempi

client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
)
client.close()

metodo close_async (asincrono)

Chiudere in modo asincrono il componente memoria agente.

Questo metodo segue lo stesso funzionamento di spegnimento di close(). Se il timeout scade, può essere restituito mentre il lavoro di estrazione in background è ancora in esecuzione.

Esempi

await client.close_async()

metodo create_thread

Creare e registrare un thread.

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_agent

Eliminare un record profilo agente in base all'identificativo.

Note

Le eliminazioni a catena vengono pianificate ed eseguite all'interno del backing store, pertanto l'eliminazione del profilo e tutte le eliminazioni figlio con ambito vengono eseguite in un'unica operazione negozio. Prima dell'esecuzione dell'eliminazione a catena, questo metodo attende l'estrazione in background precedente già accettata per i thread di proprietà noti in quel momento tramite questo componente di memoria dell'agente. Non attende l'accettazione del lavoro dopo l'inizio dell'attesa o l'avvio del lavoro da parte di un altro componente o processo di memoria agente. L'uso con ambito attore concorrente durante l'eliminazione non è supportato.

Esempi

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

metodo delete_memory

Eliminare un record simile alla memoria (ad esempio, una memoria, un fatto, una preferenza o una linea guida) in base all'identificativo.

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_memory_async (asincrono)

Elimina in modo asincrono un record simile alla memoria (ad esempio, una memoria, un fatto, una preferenza o una linea guida) per identificativo.

metodo delete_thread

Elimina tutti i record associati a un identificativo thread.

Note

Utilizzare questa operazione quando è necessaria la rimozione completa della conservazione di un thread. L'area di memorizzazione di backup elimina il thread insieme ai messaggi con ambito thread associato, alle memorie permanenti e ai dati di recupero gestiti. Ciò è diverso da OracleThread.delete_message(), che rimuove solo il record di messaggio raw e non si applica alle memorie derivate create da tale messaggio. Prima di eliminare il thread, questo metodo attende l'estrazione in background precedente già accettata per tale thread tramite questo componente di memoria dell'agente. Non attende l'accettazione del lavoro in background dopo l'inizio dell'attesa o l'avvio del lavoro da parte di un altro componente o processo di memoria agente. L'uso concorrente dello stesso thread durante l'eliminazione non è supportato.

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 delete_user

Eliminare un record profilo utente in base all'identificativo.

Note

Le eliminazioni a catena vengono pianificate ed eseguite all'interno del backing store, pertanto l'eliminazione del profilo e tutte le eliminazioni figlio con ambito vengono eseguite in un'unica operazione negozio. Prima dell'esecuzione dell'eliminazione a catena, questo metodo attende l'estrazione in background precedente già accettata per i thread di proprietà noti in quel momento tramite questo componente di memoria dell'agente. Non attende l'accettazione del lavoro dopo l'inizio dell'attesa o l'avvio del lavoro da parte di un altro componente o processo di memoria agente. L'uso con ambito attore concorrente durante l'eliminazione non è supportato.

Esempi

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

metodo get_thread

Recupera un thread creato in precedenza.

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'

Cercare in modo sincrono i record pertinenti a un'interrogazione.

Note

I valori espliciti dell'ambito None seguono ancora le regole di corrispondenza esatta risolte: exact_*_match=False lascia la dimensione non vincolata, mentre exact_*_match=True corrisponde solo ai record senza ambito su tale dimensione.

metodo search_async (asincrono)

Cercare in modo asincrono i record pertinenti a un'interrogazione.

Note

I valori espliciti dell'ambito None seguono ancora le regole di corrispondenza esatta risolte: exact_*_match=False lascia la dimensione non vincolata, mentre exact_*_match=True corrisponde solo ai record senza ambito su tale dimensione.

metodo update_memory

Aggiorna un record memorizzato come memoria in base all'identificativo.

Note

I campi omessi vengono conservati dal record memorizzato. L'ambito memorizzato rimane invariato. La sostituzione dei metadati è una sostituzione dell'intero oggetto, non un'unione JSON ricorsiva.

metodo update_memory_async (asincrono)

Aggiorna in modo asincrono un record memorizzato simile alla memoria in base all'identificativo.

Note

I campi omessi rimangono invariati. Aggiornamenti dell'ambito non supportati da questa API. La sostituzione dei metadati è una sostituzione dell'intero oggetto, non un'unione JSON ricorsiva.

metodo update_thread

Rendi persistenti i metadati del thread e gli aggiornamenti della configurazione di runtime permanente.

Note

La configurazione runtime viene risolta dal thread di conversazione memorizzato più le sostituzioni esplicite passate a questa chiamata, facendo corrispondere la semantica get_thread prima di rendere persistente il risultato. I metadati omessi e gli aggiornamenti di configurazione runtime vengono risolti dai dati memorizzati, non da alcuna istanza OracleThread caricata in precedenza e vengono riscritti solo gli aggiornamenti dei metadati forniti in modo esplicito o le sostituzioni durature di configurazione runtime. La sostituzione dei metadati è una sostituzione dell'intero oggetto, non un'unione JSON ricorsiva. La proprietà del thread non è modificabile tramite questa API, pertanto user_id e agent_id rimangono invariati. Lo stato di runtime modificabile, ad esempio i contatori di estrazione, non viene modificato.

Esempi

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
updated = client.update_thread(
    "c1",
    metadata={"flags": {"vip": True}},
    message_shortening_input_token_limit=12_000,
)
updated.message_shortening_input_token_limit
12000

metodo wait_for_memory_extraction

Attendere l'avvio dell'estrazione della memoria di background precedente da parte di questo client.

Questo metodo attende l'estrazione in background già avviata tramite questa istanza OracleAgentMemory, in tutti i thread di proprietà di questo componente di memoria dell'agente. Non attende l'avvio dell'estrazione dopo l'inizio di questa attesa, l'estrazione avviata da un altro componente di memoria agente o l'esecuzione dell'estrazione in un altro processo. Conteggio degli errori di estrazione completati per questa attesa.

Esempi

client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
)
client.wait_for_memory_extraction(timeout=10)

metodo wait_for_memory_extraction_async (asincrono)

Attendere in modo asincrono l'estrazione della memoria in background precedente.

Questo metodo segue lo stesso funzionamento di wait_for_memory_extraction().

Esempi

await client.wait_for_memory_extraction_async(timeout=10)

Estrazione memoria

classe oracleagentmemory.core.MemoryExtractionConfig

Basi: object

Impostazioni raggruppate per l'estrazione automatica della memoria.

Passare questo oggetto a OracleAgentMemory, create_thread, get_thread o update_thread per configurare l'estrazione automatica. I campi omessi ereditano dall'impostazione più ampia successiva. Ad esempio, un thread creato senza memory_extraction_frequency utilizza il componente di memoria dell'agente predefinito e il valore predefinito del componente torna al valore predefinito dell'SDK.

Esempi

from oracleagentmemory.core import MemoryExtractionConfig, MemoryExtractionMode
config = MemoryExtractionConfig(
    extract_memories=True,
    extraction_mode=MemoryExtractionMode.BACKGROUND,
)

classe oracleagentmemory.core.MemoryExtractionMode

Basi: str, Enum

Controlla quando viene eseguito il lavoro di estrazione automatica della memoria.

INLINE esegue l'estrazione automatica prima che venga restituito il metodo di scrittura. BACKGROUND restituisce dopo l'esito positivo della scrittura raw e il lavoro di estrazione dovuto viene tentato in background. L'estrazione dello sfondo è lo sforzo migliore: i ricordi derivati possono apparire più tardi o non possono mai essere scritti se il lavoro in background non può essere completato.

SFONDO = 'SFONDO'

Torna dopo la persistenza del messaggio raw ed esegui l'estrazione con il massimo sforzo nel lavoro in background.

IN LINEA = "IN LINEA"

Eseguire l'estrazione prima che venga restituito il metodo di scrittura.

classe oracleagentmemory.core.BackgroundExtractionQueueFullBehavior

Basi: str, Enum

Controlla cosa accade quando l'estrazione in background non può fare la coda in tempo.

ELIMINA = 'ELIMINA'

Registrare un avviso e continuare immediatamente quando la capacità della coda non è disponibile.

WAIT_THEN_DROP = 'WAIT_THEN_DROP'

Attendere la capacità della coda fino al timeout configurato, quindi registrare un'avvertenza e continuare.

WAIT_THEN_RAISE = 'WAIT_THEN_RAISE'

Attendere la capacità della coda fino al timeout configurato, quindi attivare TimeoutError.