Negozi e schema

Questa pagina presenta le astrazioni dell'area di memorizzazione principale e i controlli dello schema utilizzati dall'SDK di memoria dell'agente Oracle.

API negozio

Semantica scrittura negozio

Le scritture dell'area di memorizzazione mantengono una chiara separazione tra il testo memorizzato da un'applicazione e il payload utilizzato dall'area di memorizzazione per il recupero. La maggior parte delle applicazioni può utilizzare le API a livello di memoria e thread e lasciare che l'area di memorizzazione prepari le righe di ricerca necessarie per il recupero vettoriale, di parole chiave o ibrido. Le API di memorizzazione di livello inferiore espongono index_texts, index_text, embeddings e embedding per integrazioni avanzate che sanno già quale testo o vettori devono essere utilizzati per il recupero.

Pensa a ogni scrittura come a due pezzi correlati:

• contents in add() e content in update() controllano il contenuto del record memorizzato restituito da get(), list() e dai risultati della ricerca.
• index_texts in add() e index_text in update() controllano il testo scritto nelle righe di recupero del negozio. La ricerca utilizza tali righe, quindi restituisce i record logici originali.

update() accetta anche text come parametro di compatibilità non più valido. Utilizzare content nel nuovo codice. Se si specifica text, viene visualizzata un'avvertenza di non validità.

Se non viene fornita alcuna sostituzione di ricerca o incorporamento esplicito, l'area di memorizzazione utilizza il testo memorizzato risolto come testo di recupero. Il testo non vuoto viene messo in chunk dal negozio durante la configurazione del chunk. Testo vuoto memorizza il testo del record, ma non fornisce alcun testo di recupero.

Nella tabella seguente viene descritto come viene scelto il testo di recupero prima di considerare i payload vettoriali espliciti.

Payload di recupero a livello di negozio

Input	add()	update()
index_texts o index_text omesso	Ogni record utilizza il valore contents risolto per il recupero.	Per il recupero viene utilizzato un valore content sostitutivo. Se viene omesso anche content, gli aggiornamenti di solo incorporamento riutilizzano le righe di testo di recupero esistenti del record.
Voce stringa index_texts o stringa index_text	La stringa sostituisce il testo di recupero per il record. Il negozio può eseguire il chunk prima di scrivere le righe di recupero.	La stringa sostituisce il testo di recupero per il record. Il negozio può eseguire il chunk prima di scrivere le righe di recupero.
list[str] index_texts voce o list[str] index_text	L'elenco viene considerato come blocchi di proprietà del chiamante. Ogni stringa non vuota viene scritta come una riga di recupero e il negozio non la raggruppa di nuovo.	L'elenco viene considerato come blocchi di proprietà del chiamante. Ogni stringa non vuota viene scritta come una riga di recupero e il negozio non la raggruppa di nuovo.
None index_texts voce o index_text=None	None nell'elenco esterno index_texts significa "utilizzare il contenuto memorizzato per questo record".	index_text=None cancella le righe di recupero lasciando invariato il contenuto memorizzato, a meno che non venga fornito anche content.
Stringa vuota o elenco chunk vuoto	Memorizza il contenuto del record e non fornisce alcun testo di recupero per tale record.	Aggiorna il contenuto del record quando viene fornito content e cancella il testo di recupero per tale record.

Le integrazioni esplicite sono facoltative. Quando vengono omessi, l'area di memorizzazione ricava vettori locali dal testo di recupero quando è configurata la memorizzazione vettoriale locale; le aree di memorizzazione per parola chiave o ibride possono anche utilizzare righe di recupero solo testo. Quando vengono forniti valori embeddings o embedding espliciti, l'area di memorizzazione scrive tali vettori direttamente e non ne chiama l'incorporatore per tali vettori.

In add(), embeddings=None si comporta come se omettesse embeddings. In update(), embedding=None è esplicito: l'archivio conserva o riscrive il testo di recupero secondo content e index_text, ma memorizza tali righe senza vettori locali. Se content e index_text vengono omessi entrambi, i vettori vengono cancellati dalle righe di recupero esistenti.

La forma vettoriale indica la quantità di proprietà del chunk che il chiamante sta assumendo:

• un vettore significa un vettore per l'intero testo di recupero. L'area di memorizzazione non divide il testo per il vettore esplicito. Se il testo di recupero è vuoto, il vettore può essere memorizzato senza testo di chunk complementare.
• più vettori indicano un vettore per chunk di proprietà del chiamante. Fornire liste di chunk index_texts o index_text corrispondenti oppure utilizzare un update() di sola incorporazione che riutilizza le righe di testo di recupero esistenti del record.
• i conteggi dei vettori devono corrispondere ai conteggi dei chunk e tutti i vettori espliciti in una chiamata add() devono avere la stessa dimensione.
• un payload vettoriale vuoto per record è consentito solo quando non sono presenti righe di testo di recupero da allineare ad esso.

Alcune combinazioni vengono rifiutate in modo che il testo memorizzato, il testo di recupero e i vettori non si separino. Il passaggio di content=None cancella il contenuto memorizzato e le righe di recupero, pertanto non può essere combinato con valori index_text o embedding non nulli. I record del profilo attore non supportano content=None. Il parametro text non più valido ha lo stesso funzionamento. Il passaggio di index_text=None in update() significa "Cancella righe di recupero", pertanto non sono consentite incorporamenti espliciti non vuoti nella stessa chiamata. Più vettori espliciti richiedono testo chunk esplicito, a meno che l'aggiornamento non sia di sola incorporazione e le righe di recupero esistenti non forniscano già il testo chunk.

classe oracleagentmemory.core.OracleMemoryStore

Basi: IMemoryStore

Interfaccia di memorizzazione comune utilizzata da OracleAgentMemory.

Un'implementazione del negozio è responsabile della persistenza dei record di testo e dell'esecuzione di ricerche di somiglianza su di essi. Entrambi i punti di accesso sincrono e asincrono sono definiti in modo che le API di livello superiore possano esporre le superfici di sincronizzazione/asincroni corrispondenti senza duplicare la logica specifica dell'area di memorizzazione.

metodo add

Aggiungere record al negozio.

• Parametri:
  • contents Sequence[str | Mapping[str, object] | Sequence[MessageContent] | bytes | None]: sequenza di payload di record di sola lettura. Le voci di messaggio possono contenere parti MessageContent ordinate, mentre le voci di riepilogo thread possono essere mapping. I valori di testo vengono utilizzati anche per l'indicizzazione semantica, a meno che non vengano forniti index_texts o embeddings. Quando il valore di testo è None, le implementazioni possono tornare a metadata["content"]. Le stringhe vuote esplicite vengono conservate.
  • record_type str: tipo di record logico da creare, ad esempio "message", "memory", "guideline", "fact", "preference", "user_profile", "agent_profile" o "thread_summary".
  • index_texts list[str | list[str] | None]: payload alternativi facoltativi utilizzati solo per l'indicizzazione semantica. Se specificato, l'elenco esterno deve essere allineato agli input di testo. Ogni voce può essere una stringa, che il negozio può chunk internamente, o una lista di stringhe non vuote, che il negozio considera come chunk di proprietà del chiamante e non deve dividere di nuovo.
  • embeddings list[list[float] | ndarray | list[list[float] | ndarray]]: vettori di incorporamento precalcolati facoltativi allineati con gli input di testo. Ogni voce di record può essere un vettore di incorporamento o un elenco di vettori di incorporamento di chunk per quel record. Se fornito, il negozio deve utilizzare questi vettori direttamente invece di invocare il suo embedder. Più vettori per un record richiedono la corrispondenza con gli elenchi di chunk index_texts in modo che i limiti del testo e del chunk vettoriale siano espliciti. Se non viene fornito, le aree di memorizzazione di solito derivano lo stato semantico dall'incorporatore configurato, ma le modalità di indicizzazione basate sul testo specifiche dell'implementazione possono anche consentire scritture di solo testo senza una.
  • record_ids str | None | list[str | None]: identificativi facoltativi visibili al chiamante. È possibile utilizzare una singola stringa per gli inserimenti di un record, mentre gli elenchi devono essere allineati agli input di testo. Gli identificativi generati vengono restituiti quando questo campo viene omesso.
  • thread_ids str | None | list[str | None]: identificativi di thread facoltativi associati ai record inseriti. I valori scalari possono essere trasmessi attraverso input di testo allineati.
  • user_ids str | None | list[str | None]: identificativi utente facoltativi associati ai record inseriti. I valori scalari possono essere trasmessi attraverso input di testo allineati.
  • agent_ids str | None | list[str | None]: identificativi agente facoltativi associati ai record inseriti. I valori scalari possono essere trasmessi attraverso input di testo allineati.
  • roles str | None | list[str | None]: ruoli messaggio facoltativi quali "user" o "assistant". I valori scalari possono essere trasmessi attraverso input di testo allineati. Utilizzato solo se record_type è "message".
  • timestamps str | None | list[str | None]: indicatori orari facoltativi da salvare con i record. Ogni indicatore orario rappresenta un evento associato al record. I valori scalari possono essere trasmessi attraverso input di testo allineati. Le voci omesse o None memorizzano un indicatore orario dell'evento NULL; le letture utilizzano l'ora di creazione del record come indicatore orario effettivo.
  • metadata dict[str, Any] | None | list[dict[str, Any] | None]: dizionari di metadati forniti dal chiamante opzionali. I metadati possono includere "content" come origine di fallback quando un valore di testo viene omesso anziché impostato in modo esplicito su "". Quando si scrive record_type="image", ogni immagine richiede "image_mime_type" con uno dei valori "image/png", "image/jpeg" o "image/webp". L'area di memorizzazione utilizza questo campo per salvare l'immagine, ma non la restituisce come parte dei metadati del record.
  • ttl_days int | None | list[int | None]: durata Time To Live facoltativa in giorni per i record che supportano la scadenza. Omettere questo argomento per utilizzare il valore predefinito dell'area di memorizzazione. Passare None per i record che non devono scadere. I valori scalari possono essere trasmessi attraverso input di testo allineati.
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]: ancoraggio Time To Live opzionale. Utilizzare TimeToLiveAnchor.CREATED_AT per scadere in relazione all'ora di creazione memorizzata oppure TimeToLiveAnchor.TIMESTAMP per scadere in relazione all'indicatore orario dell'evento di ciascun record. Se omesso, le implementazioni utilizzano TimeToLiveAnchor.CREATED_AT.
  • Stati RecordStatus | list[RecordStatus]: stato o stati del ciclo di vita facoltativi per i record. Omettere questa opzione per memorizzare RecordStatus.VALID.
  • **store_kwargs (Qualsiasi): opzioni di scrittura specifiche dell'implementazione inoltrate al negozio concreto.
• Tipo restituito: list[str]

Note

Utilizzare add_batches() quando il chiamante dispone già di uno o più oggetti PendingRecordBatch.

• Restituzioni: identificativi per i record inseriti, nello stesso ordine logico dell'input.
• Tipo restituito: elenco[str]
• Parametri:
  • contenuti Sequence[str | Mapping[str, object] | Sequence[MessageContent] | bytes | None]
  • tipo_record str
  • testi_indice list[str | list[str] | None]
  • embeding list[list[float] | ndarray | list[list[float] | ndarray]]
  • ID_record str | None | list[str | None]
  • id_thread str | None | list[str | None]
  • ID_utente str | None | list[str | None]
  • id_agente str | None | list[str | None]
  • ruoli str | None | list[str | None]
  • Indicatori data/ora str | None | list[str | None]
  • metadati dict[str, Any] | None | list[dict[str, Any] | None]
  • ttl_days int | None | list[int | None]
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]
  • Stati RecordStatus | list[RecordStatus]
  • store_kwargs Any

metodo add_agent (abstract)

Aggiungere un record profilo agente.

• Parametri:
  • agent_id str: identificativo stabile per il profilo dell'agente.
  • information str: testo in formato libero che descrive l'agente.
  • metadati dict[str, Any] | None: mapping dei metadati facoltativo memorizzato nella riga del profilo dell'agente.
• Restituzioni: identificativo del record profilo agente creato.
• Tipo restituito: str

metodo add_agent_async (asincrono)

Aggiungere un record profilo agente in modo asincrono.

• Parametri:
  • agent_id str: identificativo stabile per il profilo dell'agente.
  • information str: testo in formato libero che descrive l'agente.
  • metadati dict[str, Any] | None: mapping dei metadati facoltativo memorizzato nella riga del profilo dell'agente.
• Restituzioni: identificativo del record profilo agente creato.
• Tipo restituito: str

metodo add_async (asincrono)

Aggiungere in modo asincrono record orientati alle righe al negozio.

Accetta gli stessi argomenti e restituisce gli stessi identificativi di add().

• Parametri:
  • contenuti Sequence[str | Mapping[str, object] | Sequence[MessageContent] | bytes | None]
  • tipo_record str
  • testi_indice list[str | list[str] | None]
  • embeding list[list[float] | ndarray | list[list[float] | ndarray]]
  • ID_record str | None | list[str | None]
  • id_thread str | None | list[str | None]
  • ID_utente str | None | list[str | None]
  • id_agente str | None | list[str | None]
  • ruoli str | None | list[str | None]
  • Indicatori data/ora str | None | list[str | None]
  • metadati dict[str, Any] | None | list[dict[str, Any] | None]
  • ttl_days int | None | list[int | None]
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]
  • Stati RecordStatus | list[RecordStatus]
  • store_kwargs Any
• Tipo restituito: list[str]

metodo add_batches

Aggiungere batch logici preparati dal chiamante all'area di memorizzazione.

• Parametri:
  • batches list[PendingRecordBatch]: batch logici completamente preparati da rendere persistenti. Ogni batch deve contenere i propri campi per record, ad esempio record_type, valori di ambito, ruoli, indicatori orari e metadati.
  • **store_kwargs (Qualsiasi): opzioni di scrittura specifiche dell'implementazione inoltrate al negozio concreto.
• Restituzioni: identificativi per i record inseriti, nello stesso ordine logico dei batch e delle righe di input.
• Tipo restituito: elenco[str]

Esempi

store.add_batches(
    [
        PendingRecordBatch(
            contents=["pizza batch"],
            record_type="memory",
            record_ids="mem-batch-docs",
        )
    ]
)
['mem-batch-docs']

metodo add_batches_async (asincrono)

Aggiungere in modo asincrono batch logici preparati dal chiamante all'area di memorizzazione.

Accetta gli stessi argomenti e restituisce gli stessi identificativi di add_batches().

• Parametri:
  • batch list[PendingRecordBatch]
  • store_kwargs Any
• Tipo restituito: list[str]

metodo add_relations (abstract)

Memorizzare una o più relazioni dirette.

I valori scalari vengono trasmessi nel batch dei record di origine. I valori elenco devono avere la stessa lunghezza. È possibile memorizzare un solo orientamento per una coppia di endpoint. Utilizzare opposite_relation_types per descrivere la vista inversa anziché aggiungere una seconda relazione inversa. Le implementazioni possono limitare i tipi di record endpoint e le etichette di relazione che persistono.

• Parametri:
  • source_record_ids str | list[str]: identificativo o identificativi dei record all'estremità di origine di ogni relazione diretta.
  • source_record_types str | list[str]: tipo di record o tipi per source_record_ids. Fornire un valore per tutte le origini o un valore per ogni relazione.
  • target_record_ids str | list[str]: identificativo o identificativi dei record alla fine di ogni relazione diretta.
  • target_record_types str | list[str]: tipo di record o tipi per target_record_ids. Fornire un valore per tutte le destinazioni o un valore per ogni relazione.
  • relation_types str | list[str]: etichetta o etichette di relazione diretta. Fornire un valore per tutte le relazioni o un valore per ogni relazione.
  • opposite_relation_types str | list[str]: etichetta o etichette facoltative per la vista inversa di ciascuna relazione. Per i tipi di relazione di memoria incorporata, l'omissione utilizza l'etichetta inversa predefinita. Per i tipi di relazione personalizzati, l'omissione utilizza la stessa etichetta in entrambe le direzioni.
  • relation_ids str | None | list[str | None]: identificativo o identificativi stabili opzionali. Omettere questa opzione per consentire al negozio di generare identificativi.
  • timestamp str | None | list[str | None]: indicatore orario o indicatori orari facoltativi da memorizzare nelle relazioni.
  • metadati dict[str, Any] | None | list[dict[str, Any] | None]: oggetto o oggetti metadati facoltativi da memorizzare nelle relazioni.
• Restituzioni: identificativi di relazione nell'ordine di input.
• Tipo restituito: list[str]

Esempi

store.add_relations(
    "new", "memory", "old", "memory", "supersedes"
)
['relation-id']

metodo add_relations_async (asincrono)

Memorizza in modo asincrono una o più relazioni dirette.

I valori scalari vengono trasmessi nel batch dei record di origine. I valori elenco devono avere la stessa lunghezza. È possibile memorizzare un solo orientamento per una coppia di endpoint. Utilizzare opposite_relation_types per descrivere la vista inversa anziché aggiungere una seconda relazione inversa.

• Parametri:
  • source_record_ids str | list[str]: identificativo o identificativi dei record all'estremità di origine di ogni relazione diretta.
  • source_record_types str | list[str]: tipo di record o tipi per source_record_ids. Fornire un valore per tutte le origini o un valore per ogni relazione.
  • target_record_ids str | list[str]: identificativo o identificativi dei record alla fine di ogni relazione diretta.
  • target_record_types str | list[str]: tipo di record o tipi per target_record_ids. Fornire un valore per tutte le destinazioni o un valore per ogni relazione.
  • relation_types str | list[str]: etichetta o etichette di relazione diretta. Fornire un valore per tutte le relazioni o un valore per ogni relazione.
  • opposite_relation_types str | list[str]: etichetta o etichette facoltative per la vista inversa di ciascuna relazione. Per i tipi di relazione di memoria incorporata, l'omissione utilizza l'etichetta inversa predefinita. Per i tipi di relazione personalizzati, l'omissione utilizza la stessa etichetta in entrambe le direzioni.
  • relation_ids str | None | list[str | None]: identificativo o identificativi stabili opzionali. Omettere questa opzione per consentire al negozio di generare identificativi.
  • timestamp str | None | list[str | None]: indicatore orario o indicatori orari facoltativi da memorizzare nelle relazioni.
  • metadati dict[str, Any] | None | list[dict[str, Any] | None]: oggetto o oggetti metadati facoltativi da memorizzare nelle relazioni.
• Restituzioni: identificativi di relazione nell'ordine di input.
• Tipo restituito: list[str]

Esempi

await store.add_relations_async(
    "new", "memory", "old", "memory", "supersedes"
)
['relation-id']

metodo add_user (abstract)

Aggiungere un record profilo utente.

• Parametri:
  • user_id str: identificativo stabile per il profilo utente. Le implementazioni supportate dal database possono derivare questo valore da un contesto di sicurezza dell'utente finale collegato quando viene omesso.
  • information str: testo in formato libero richiesto che descrive l'utente.
  • metadata dict[str, Any] | None: mapping dei metadati facoltativo memorizzato nella riga del profilo utente.
• Restituzioni: identificativo del record profilo utente creato.
• Tipo restituito: str

metodo add_user_async (asincrono)

Aggiungere un record profilo utente in modo asincrono.

• Parametri:
  • user_id str: identificativo stabile per il profilo utente.
  • information str: testo in formato libero che descrive l'utente.
  • metadata dict[str, Any] | None: mapping dei metadati facoltativo memorizzato nella riga del profilo utente.
• Restituzioni: identificativo del record profilo utente creato.
• Tipo restituito: str

metodo delete (abstract)

Eliminare un record memorizzato in base all'identificativo.

• Parametri:
  • record_type str: tipo logico del record da rimuovere.
  • record_id str: identificativo del record da rimuovere.
  • cascade bool: quando si utilizza True, applicare qualsiasi comportamento di eliminazione a catena supportato dall'area di memorizzazione per le destinazioni di livello superiore richieste all'interno della stessa operazione di eliminazione. Viene utilizzato principalmente per destinazioni quali i profili attore che possiedono record con ambito aggiuntivo. Ad esempio, una cascata di profilo utente o di profilo agente può eliminare i thread di proprietà stessi, i messaggi con ambito thread e i record di memoria rimossi con tali thread e qualsiasi record con ambito attore diretto rimanente come messaggi, memorie, linee guida, fatti o preferenze. Per l'eliminazione del profilo attore, questo cleanup con ambito può essere ancora eseguito quando la riga del profilo corrispondente è già assente.
• Restituzioni: numero di record di livello superiore richiesti eliminati, in genere 0 o 1. Le righe figlio a catena non vengono conteggiate separatamente, pertanto è possibile che sia ancora 0 quando un profilo attore mancante attiva il cleanup con ambito.
• Tipo restituito: int.

metodo delete_async (asincrono)

Elimina in modo asincrono un record memorizzato in base all'identificativo.

• Parametri:
  • record_type str: tipo logico del record da rimuovere.
  • record_id str: identificativo del record da rimuovere.
  • cascade bool: quando si utilizza True, applicare qualsiasi comportamento di eliminazione a catena supportato dall'area di memorizzazione per le destinazioni di livello superiore richieste all'interno della stessa operazione di eliminazione. Viene utilizzato principalmente per destinazioni quali i profili attore che possiedono record con ambito aggiuntivo. Ad esempio, una cascata di profilo utente o di profilo agente può eliminare i thread di proprietà stessi, i messaggi con ambito thread e i record di memoria rimossi con tali thread e qualsiasi record con ambito attore diretto rimanente come messaggi, memorie, linee guida, fatti o preferenze. Per l'eliminazione del profilo attore, questo cleanup con ambito può essere ancora eseguito quando la riga del profilo corrispondente è già assente.
• Restituzioni: numero di record di livello superiore richiesti eliminati, in genere 0 o 1. Le righe figlio a catena non vengono conteggiate separatamente, pertanto è possibile che sia ancora 0 quando un profilo attore mancante attiva il cleanup con ambito.
• Tipo restituito: int.

metodo delete_relations (abstract)

Elimina le relazioni in base all'identificativo.

Lo stato del ciclo di vita viene ricalcolato dalle relazioni che rimangono.

• Parametri: relation_ids str | list[str]: identificativo o identificativi delle relazioni da eliminare.
• Restituzioni: numero di relazioni eliminate.
• Tipo restituito: int.

Esempi

store.delete_relations("relation-id")
1

metodo delete_relations_async (asincrono)

Elimina le relazioni in modo asincrono in base all'identificativo.

Lo stato del ciclo di vita viene ricalcolato dalle relazioni che rimangono.

• Parametri: relation_ids str | list[str]: identificativo o identificativi delle relazioni da eliminare.
• Restituzioni: numero di relazioni eliminate.
• Tipo restituito: int.

Esempi

await store.delete_relations_async("relation-id")
1

metodo delete_thread (abstract)

Eliminare un thread e i dati memorizzati associati.

• Parametri: thread_id str: identificativo del thread da rimuovere.
• Restituzioni: numero di record thread eliminati, in genere 0 o 1.
• Tipo restituito: int.

Note

Operazione a livello di negozio per la rimozione di un thread e dei record con ambito thread gestiti dal negozio. Preferire l'eliminazione dei thread quando i requisiti di conservazione richiedono l'eliminazione sia dei messaggi di origine che dei dati di memoria con ambito thread derivato, poiché le eliminazioni a livello di messaggio non implicano la rimozione di record derivati con persistenza separata.

metodo delete_thread_async (asincrono)

Elimina in modo asincrono un thread e i dati memorizzati associati.

• Parametri: thread_id str: identificativo del thread da rimuovere.
• Restituzioni: numero di record thread eliminati, in genere 0 o 1.
• Tipo restituito: int.

Note

Operazione a livello di negozio per la rimozione di un thread e dei record con ambito thread gestiti dal negozio. Preferire l'eliminazione dei thread quando i requisiti di conservazione richiedono l'eliminazione sia dei messaggi di origine che dei dati di memoria con ambito thread derivato, poiché le eliminazioni a livello di messaggio non implicano la rimozione di record derivati con persistenza separata.

metodo get (abstract)

Recupera un record memorizzato per tipo e identificativo.

• Parametri:
  • record_type str: tipo logico del record da recuperare, ad esempio "thread", "message", "memory", "guideline", "fact", "preference", "user_profile", "agent_profile" o "image".
  • record_id str: identificativo del record da recuperare.
  • include_bytes bool: indica se caricare i byte delle immagini memorizzate. Per un record di messaggio, controlla se le immagini allegate includono i relativi byte. Per un record di immagine, controlla se vengono caricati i byte di immagine standalone. Questa opzione non ha effetto su altri tipi di record.
• Restituisce: il record memorizzato, se trovato, altrimenti None. Una ricerca "thread" restituisce un valore ThreadRecord con metadati del thread, configurazione runtime, stato di runtime e indicatore orario di creazione popolato quando l'area di memorizzazione supporta thread persistenti.
• Tipo restituito: Record | Nessuno

metodo get_async (asincrono)

Recupera in modo asincrono un record memorizzato per tipo e identificativo.

• Parametri:
  • record_type str: tipo logico del record da recuperare, ad esempio "thread", "message", "memory", "guideline", "fact", "preference", "user_profile", "agent_profile" o "image".
  • record_id str: identificativo del record da recuperare.
  • include_bytes bool: indica se caricare i byte delle immagini memorizzate. Per un record di messaggio, controlla se le immagini allegate includono i relativi byte. Per un record di immagine, controlla se vengono caricati i byte di immagine standalone. Questa opzione non ha effetto su altri tipi di record.
• Restituisce: il record memorizzato, se trovato, altrimenti None. Una ricerca "thread" restituisce un valore ThreadRecord con metadati del thread, configurazione runtime, stato di runtime e indicatore orario di creazione popolato quando l'area di memorizzazione supporta thread persistenti.
• Tipo restituito: Record | Nessuno

metodo get_relation (abstract)

Restituisce una relazione nel relativo orientamento source-to-target memorizzato.

Fornire relation_id da solo o fornire una tupla completa dell'endpoint source-to-target.

• Parametri:
  • source_record_id str – Identificativo del record di origine. Obbligatorio con gli altri campi endpoint-tuple quando relation_id viene omesso.
  • tipo_record_origine str – Tipo di record di origine. Obbligatorio con gli altri campi endpoint-tuple quando relation_id viene omesso.
  • target_record_id str: identificativo del record di destinazione. Obbligatorio con gli altri campi endpoint-tuple quando relation_id viene omesso.
  • target_record_type str: tipo di record di destinazione. Obbligatorio con gli altri campi endpoint-tuple quando relation_id viene omesso.
  • tipo_relazione str: etichetta della relazione diretta. Obbligatorio con gli altri campi endpoint-tuple quando relation_id viene omesso.
  • relation_id str: identificativo della relazione per la corrispondenza diretta. Fornire questo argomento da solo anziché combinarlo con i campi endpoint-tuple.
• Restituzioni: la relazione corrispondente o None quando non esiste.
• Tipo restituito: RecordRelation | Nessuno

Esempi

store.get_relation(relation_id="relation-id")
RecordRelation(...)
store.get_relation(
    "source-id", "memory", "target-id", "fact", "supports"
)
RecordRelation(...)

metodo get_relation_async (asincrono)

Recupera in modo asincrono una relazione per ID o tupla endpoint.

Fornire relation_id da solo o fornire una tupla completa dell'endpoint source-to-target.

• Parametri:
  • source_record_id str – Identificativo del record di origine. Obbligatorio con gli altri campi endpoint-tuple quando relation_id viene omesso.
  • tipo_record_origine str – Tipo di record di origine. Obbligatorio con gli altri campi endpoint-tuple quando relation_id viene omesso.
  • target_record_id str: identificativo del record di destinazione. Obbligatorio con gli altri campi endpoint-tuple quando relation_id viene omesso.
  • target_record_type str: tipo di record di destinazione. Obbligatorio con gli altri campi endpoint-tuple quando relation_id viene omesso.
  • tipo_relazione str: etichetta della relazione diretta. Obbligatorio con gli altri campi endpoint-tuple quando relation_id viene omesso.
  • relation_id str: identificativo della relazione per la corrispondenza diretta. Fornire questo argomento da solo anziché combinarlo con i campi endpoint-tuple.
• Restituzioni: la relazione corrispondente o None quando non esiste.
• Tipo restituito: RecordRelation | Nessuno

Esempi

await store.get_relation_async(relation_id="relation-id")
RecordRelation(...)

metodo list (abstract)

Elenca i record memorizzati per un tipo di record.

• Parametri:
  • record_type str: tipo di record logico da enumerare, ad esempio "thread", "message", "memory", "guideline", "fact", "preference", "user_profile", "agent_profile" o "thread_summary" o "image".
  • limite int | None: numero massimo facoltativo di record più recenti da restituire. Se omesso, le implementazioni possono applicare un limite superiore sicuro come MAX_LIST_LIMIT. Passare None per disabilitare il limite e restituire ogni record corrispondente.
  • thread_id str | None: filtro thread-ambito esatto. Se omesso, non viene applicato alcun filtro. Se impostato su None, vengono restituiti solo i record il cui thread_id è None. I tipi di record senza ambito ignorano questo filtro. Se record_type è "thread", non è necessario impostare thread_id; utilizzare record_id per selezionare un thread specifico.
  • user_id str | None: filtro esatto dell'ambito utente. Se omesso, non viene applicato alcun filtro. Se impostato su None, vengono restituiti solo i record il cui user_id è None. I tipi di record senza ambito ignorano questo filtro.
  • agent_id str | None: filtro agente-ambito esatto. Se omesso, non viene applicato alcun filtro. Se impostato su None, vengono restituiti solo i record il cui agent_id è None. I tipi di record senza ambito ignorano questo filtro.

  • filtro_metadata dict[str, Any] | None:

    Filtro metadati. Se omesso, non viene applicato alcun filtro. Se impostato su None, vengono restituiti solo i record i cui metadati sono None. Se impostato su un dett, le voci in metadata_filter vengono combinate con la semantica AND. Le voci il cui valore non è un dizionario operatore a livello di campo utilizzano la semantica di corrispondenza esatta: la chiave richiesta deve esistere nei metadati memorizzati. I dizionari nidificati vengono abbinati in modo ricorsivo. I valori scalari e di elenco corrispondono in base all'uguaglianza esatta; anche l'ordine e la lunghezza dell'elenco devono corrispondere. Per eseguire il test dell'appartenenza all'array, utilizzare un dizionario operatore a livello di campo, ad esempio {"tags": {"$array_contains": "prod"}}. Un operando elenco per "$array_contains" indica che devono essere presenti tutti i valori elencati; "$array_contains_any" indica che deve essere presente almeno un valore elencato. Utilizzare "$not" per negare un'altra espressione a livello di campo nello stesso campo, incluso un dizionario operatore o un valore raw di corrispondenza esatta. Le espressioni negative corrispondono quando l'espressione positiva non riesce, inclusi i campi mancanti; l'appartenenza all'array negata corrisponde anche ai campi non array. Ad esempio, metadata_filter={"source": "slack"} per un campo scalare, metadata_filter={"review": {"status": "open"}} per un campo nidificato e metadata_filter={"tags": ["prod", "urgent"]} per una corrispondenza esatta dell'elenco. Combina le condizioni per richiederle tutte:

    metadata_filter={
        "source": "slack",
        "review": {"status": "open"},
        "tags": ["prod", "urgent"],
    }

  • include_bytes bool: indica se i record di immagine o le immagini allegate ai record dei messaggi includono i byte memorizzati. Se omesso o False, le descrizioni delle immagini e i metadati vengono restituiti senza caricare i byte. Per gli elenchi di immagini dirette, impostare questo valore su True solo con un record_id esatto e almeno un filtro utente, agente o ambito thread esatto. Questa opzione non ha effetto su altri tipi di record.
  • record_id str: filtro identificativo record esatto. Se omesso, vengono restituiti i record con qualsiasi identificativo. I filtri di ambito e metadati rimangono vincoli aggiuntivi.
• Restituzioni: record ordinati dal meno recente al più recente all'interno della finestra restituita.
• Tipo restituito: elenco[Record]

metodo list_async (asincrono)

Elenca in modo asincrono i record memorizzati per un tipo di record.

• Parametri:
  • record_type str: tipo di record logico da enumerare, ad esempio "thread", "message", "memory", "guideline", "fact", "preference", "user_profile", "agent_profile" o "image".
  • limite int | None: numero massimo facoltativo di record più recenti da restituire. Se omesso, le implementazioni possono applicare un limite superiore sicuro come MAX_LIST_LIMIT. Passare None per disabilitare il limite e restituire ogni record corrispondente.
  • thread_id str | None: filtro thread-ambito esatto. Se omesso, non viene applicato alcun filtro. Se impostato su None, vengono restituiti solo i record il cui thread_id è None. I tipi di record senza ambito ignorano questo filtro. Se record_type è "thread", non è necessario impostare thread_id; utilizzare record_id per selezionare un thread specifico.
  • user_id str | None: filtro esatto dell'ambito utente. Se omesso, non viene applicato alcun filtro. Se impostato su None, vengono restituiti solo i record il cui user_id è None. I tipi di record senza ambito ignorano questo filtro.
  • agent_id str | None: filtro agente-ambito esatto. Se omesso, non viene applicato alcun filtro. Se impostato su None, vengono restituiti solo i record il cui agent_id è None. I tipi di record senza ambito ignorano questo filtro.

  • filtro_metadata dict[str, Any] | None:

    Filtro metadati. Se omesso, non viene applicato alcun filtro. Se impostato su None, vengono restituiti solo i record i cui metadati sono None. Se impostato su un dett, le voci in metadata_filter vengono combinate con la semantica AND. Le voci il cui valore non è un dizionario operatore a livello di campo utilizzano la semantica di corrispondenza esatta: la chiave richiesta deve esistere nei metadati memorizzati. I dizionari nidificati vengono abbinati in modo ricorsivo. I valori scalari e di elenco corrispondono in base all'uguaglianza esatta; anche l'ordine e la lunghezza dell'elenco devono corrispondere. Per eseguire il test dell'appartenenza all'array, utilizzare un dizionario operatore a livello di campo, ad esempio {"tags": {"$array_contains": "prod"}}. Un operando elenco per "$array_contains" indica che devono essere presenti tutti i valori elencati; "$array_contains_any" indica che deve essere presente almeno un valore elencato. Utilizzare "$not" per negare un'altra espressione a livello di campo nello stesso campo, incluso un dizionario operatore o un valore raw di corrispondenza esatta. Le espressioni negative corrispondono quando l'espressione positiva non riesce, inclusi i campi mancanti; l'appartenenza all'array negata corrisponde anche ai campi non array. Ad esempio, metadata_filter={"source": "slack"} per un campo scalare, metadata_filter={"review": {"status": "open"}} per un campo nidificato e metadata_filter={"tags": ["prod", "urgent"]} per una corrispondenza esatta dell'elenco. Combina le condizioni per richiederle tutte:

    metadata_filter={
        "source": "slack",
        "review": {"status": "open"},
        "tags": ["prod", "urgent"],
    }

  • include_bytes bool: indica se i record di immagine o le immagini allegate ai record dei messaggi includono i byte memorizzati. Se omesso o False, le descrizioni delle immagini e i metadati vengono restituiti senza caricare i byte. Per gli elenchi di immagini dirette, impostare questo valore su True solo con un record_id esatto e almeno un filtro utente, agente o ambito thread esatto. Questa opzione non ha effetto su altri tipi di record.
  • record_id str: filtro identificativo record esatto. Se omesso, vengono restituiti i record con qualsiasi identificativo. I filtri di ambito e metadati rimangono vincoli aggiuntivi.
• Restituzioni: record ordinati dal meno recente al più recente all'interno della finestra restituita.
• Tipo restituito: elenco[Record]

metodo list_relations (abstract)

Elenca le relazioni memorizzate nell'orientamento source-to-target.

• Parametri:
  • tipo_relazione str: etichetta della relazione diretta opzionale da abbinare, ad esempio "supports" o "supersedes". Omettere di includere ogni tipo di relazione.
  • source_record_id str: identificativo del record di origine facoltativo per la corrispondenza.
  • source_record_type str: tipo di record di origine facoltativo di cui trovare la corrispondenza.
  • target_record_id str: identificativo del record di destinazione facoltativo per la corrispondenza.
  • target_record_type str: tipo di record di destinazione facoltativo per la corrispondenza.
  • limite int | None: numero massimo facoltativo di relazioni create per la prima volta da restituire. Se omesso, le implementazioni possono applicare un limite superiore sicuro come MAX_LIST_LIMIT. Passare None per restituire ogni relazione memorizzata corrispondente.
  • metadata_filter dict[str, Any] | None: filtro dei metadati. Se omesso, non viene applicato alcun filtro. Se impostato su None, vengono restituite solo le relazioni i cui metadati sono None. Se impostato su un dett, le voci vengono combinate con la semantica AND. I dizionari nidificati utilizzano la corrispondenza esatta ricorsiva. I valori scalari e di lista richiedono l'uguaglianza esatta; utilizzare {"tags": {"$array_contains": "prod"}} per corrispondere all'appartenenza all'array, "$array_contains_any" per corrispondere a qualsiasi valore elencato oppure "$not" per negare un'altra espressione di campo.
  • relation_id str: filtro identificativo relazione esatto. Se omesso, vengono restituite le relazioni con qualsiasi identificativo. Altri filtri rimangono vincoli aggiuntivi.
• Restituzioni: relazioni ordinate in base all'ora e all'identificativo di creazione.
• Tipo restituito: list[RecordRelation]

Esempi

store.list_relations(
    source_record_id="current-memory",
    relation_type="supports",
    metadata_filter={"source": "manual"},
)
[RecordRelation(...)]

metodo list_relations_async (asincrono)

Elenca in modo asincrono le relazioni nell'orientamento da origine a destinazione.

• Parametri:
  • tipo_relazione str: etichetta della relazione diretta opzionale da abbinare, ad esempio "supports" o "supersedes". Omettere di includere ogni tipo di relazione.
  • source_record_id str: identificativo del record di origine facoltativo per la corrispondenza.
  • source_record_type str: tipo di record di origine facoltativo di cui trovare la corrispondenza.
  • target_record_id str: identificativo del record di destinazione facoltativo per la corrispondenza.
  • target_record_type str: tipo di record di destinazione facoltativo per la corrispondenza.
  • limite int | None: numero massimo facoltativo di relazioni create per la prima volta da restituire. Se omesso, le implementazioni possono applicare un limite superiore sicuro come MAX_LIST_LIMIT. Passare None per restituire ogni relazione memorizzata corrispondente.
  • metadata_filter dict[str, Any] | None: filtro dei metadati. Se omesso, non viene applicato alcun filtro. Se impostato su None, vengono restituite solo le relazioni i cui metadati sono None. Se impostato su un dett, le voci vengono combinate con la semantica AND. I dizionari nidificati utilizzano la corrispondenza esatta ricorsiva. I valori scalari e di lista richiedono l'uguaglianza esatta; utilizzare {"tags": {"$array_contains": "prod"}} per corrispondere all'appartenenza all'array, "$array_contains_any" per corrispondere a qualsiasi valore elencato oppure "$not" per negare un'altra espressione di campo.
  • relation_id str: identificativo di relazione facoltativo che consente la corrispondenza diretta.
• Restituzioni: relazioni ordinate in base all'ora e all'identificativo di creazione.
• Tipo restituito: list[RecordRelation]

Esempi

await store.list_relations_async(
    source_record_id="current-memory", relation_type="supports"
)
[RecordRelation(...)]

metodo list_thread_messages (abstract)

Elenca la cronologia dei messaggi memorizzata per una discussione.

• Parametri:
  • thread_id str: identificativo del thread in cui devono essere restituiti i messaggi.
  • last_n int | None: numero facoltativo di messaggi più recenti da includere. Se omesso, vengono restituiti tutti i messaggi memorizzati per il thread. Se combinato con un intervallo di sequenze, il limite viene applicato all'interno di tale intervallo.
  • range_start_seq_no int | None: limite della sequenza inferiore incluso facoltativo. Vengono restituiti solo i messaggi il cui valore seq_no è almeno questo.
  • range_end_seq_no int | None: limite della sequenza superiore esclusivo opzionale. Vengono restituiti solo i messaggi con seq_no inferiore a questo valore.
  • include_bytes bool: indica se le parti immagine allegate ai messaggi restituiti includono i byte memorizzati. Se omesso o False, le descrizioni delle immagini e i metadati vengono restituiti senza caricare i byte.
• Restituzioni: i record dei messaggi ordinati dal meno recente al più recente all'interno della finestra restituita.
• Tipo restituito: List[MessageRecord]

metodo list_thread_messages_async (asincrono)

Elenca in modo asincrono la cronologia dei messaggi memorizzata per un thread.

• Parametri:
  • thread_id str: identificativo del thread in cui devono essere restituiti i messaggi.
  • last_n int | None: numero facoltativo di messaggi più recenti da includere. Se omesso, vengono restituiti tutti i messaggi memorizzati per il thread. Se combinato con un intervallo di sequenze, il limite viene applicato all'interno di tale intervallo.
  • range_start_seq_no int | None: limite della sequenza inferiore incluso facoltativo. Vengono restituiti solo i messaggi il cui valore seq_no è almeno questo.
  • range_end_seq_no int | None: limite della sequenza superiore esclusivo opzionale. Vengono restituiti solo i messaggi con seq_no inferiore a questo valore.
  • include_bytes bool: indica se le parti immagine allegate ai messaggi restituiti includono i byte memorizzati. Se omesso o False, le descrizioni delle immagini e i metadati vengono restituiti senza caricare i byte.
• Restituzioni: i record dei messaggi ordinati dal meno recente al più recente all'interno della finestra restituita.
• Tipo restituito: List[MessageRecord]

metodo search (abstract)

Cerca i record per somiglianza.

• Parametri:
  • query str | None: query in linguaggio naturale. Deve essere fornito quando query_vector viene omesso.
  • query_vector list[float] | None: incorporamento facoltativo di query precalcolate. Specificare esattamente uno dei valori query e query_vector.
  • k int: numero massimo di risultati da restituire. I valori espliciti devono essere almeno 1. Questo è un limite superiore: la chiamata può restituire meno di k risultati quando i filtri sono troppo restrittivi, quando esistono meno record di corrispondenza non scaduti o a causa di un funzionamento di ricerca specifico dell'implementazione.
  • thread_id str | None: ambito del thread facoltativo.
  • user_id str | None: filtri facoltativi per l'ambito di utente e agente.
  • agent_id str | None: filtri facoltativi per l'ambito dell'utente e dell'agente.
  • exact_user_match bool: indica se ogni identificativo di ambito specificato deve avere una corrispondenza esatta.
  • exact_agent_match bool: indica se ogni identificativo di ambito fornito deve avere una corrispondenza esatta.
  • exact_thread_match bool: indica se ogni identificativo di ambito fornito deve avere una corrispondenza esatta.
  • record_types set[str] | None: set facoltativo di tipi di record da includere.
  • metadata_filter dict[str, Any] | None: mapping facoltativo del filtro dei metadati. Le voci in metadata_filter sono combinate con la semantica AND. Le voci il cui valore non è un dizionario operatore a livello di campo utilizzano la semantica di corrispondenza esatta: la chiave richiesta deve esistere nei metadati memorizzati. I dizionari nidificati vengono abbinati in modo ricorsivo. I valori scalari e di elenco corrispondono in base all'uguaglianza esatta; anche l'ordine e la lunghezza dell'elenco devono corrispondere. Per eseguire il test dell'appartenenza all'array, utilizzare un dizionario operatore a livello di campo, ad esempio {"tags": {"$array_contains": "prod"}}. Un operando elenco per "$array_contains" indica che devono essere presenti tutti i valori elencati; "$array_contains_any" indica che deve essere presente almeno un valore elencato. Utilizzare "$not" per negare un'altra espressione a livello di campo nello stesso campo, incluso un dizionario operatore o un valore raw di corrispondenza esatta. Le espressioni negative corrispondono quando l'espressione positiva non riesce, inclusi i campi mancanti; l'appartenenza all'array negata corrisponde anche ai campi non array.
  • include_invalid_results bool: indica se i risultati includono record di tipo memoria con stato non valido. L'impostazione predefinita è True. Passare False per escluderli.
  • num_hops int: numero di bordi dei collegamenti di memoria da seguire per ogni risultato della memoria diretta. Sono supportati i valori da 0 a 5; 0 disabilita l'espansione del grafico.
  • max_linked_results int: numero massimo di memorie collegate tra tutti gli hop collegati a ciascun risultato diretto. 0 mantiene i risultati diretti senza contesto collegato. L'impostazione predefinita è 100.
• Restituzioni: coppie (record, distance) ordinate in base alla distanza crescente. L'elenco può contenere meno di k voci.
• Tipo restituito: list[tuple[Record, float]]
• Raise: ValueError: se k è minore di 1.

Esempi

store.add(
    ["Searchable abstract memory"],
    record_type="memory",
    record_ids="mem-search-abstract-docs",
)
['mem-search-abstract-docs']
store.search("Searchable", 1, record_types={"memory"})[0][0].id
'mem-search-abstract-docs'

Filtra in base a un valore di metadati scalare:

store.add(
    ["pizza release"],
    record_type="memory",
    record_ids="mem-search-meta-source-docs2",
    metadata={"source": "slack"},
)
['mem-search-meta-source-docs2']
any(
    record.id == "mem-search-meta-source-docs2"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"source": "slack"},
    )
)
True

Filtra in base ai metadati nidificati:

store.add(
    ["pizza review"],
    record_type="memory",
    record_ids="mem-search-meta-review-docs2",
    metadata={"review": {"status": "open"}},
)
['mem-search-meta-review-docs2']
any(
    record.id == "mem-search-meta-review-docs2"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"review": {"status": "open"}},
    )
)
True

Corrisponde esattamente a un valore di elenco, incluso l'ordine:

store.add(
    ["pizza tags"],
    record_type="memory",
    record_ids="mem-search-meta-tags-docs2",
    metadata={"tags": ["prod", "urgent"]},
)
['mem-search-meta-tags-docs2']
any(
    record.id == "mem-search-meta-tags-docs2"
    for record, _ in store.search(
        "pizza",
        k=5,
        metadata_filter={"tags": ["prod", "urgent"]},
    )
)
True

Filtra quando un array di metadati contiene un valore:

any(
    record.id == "mem-search-meta-tags-docs2"
    for record, _ in store.search(
        "pizza",
        k=5,
        metadata_filter={"tags": {"$array_contains": "prod"}},
    )
)
True

Combina più condizioni metadati. Un record deve soddisfare ogni chiave:

store.add(
    ["pizza rollout"],
    record_type="memory",
    record_ids="mem-search-meta-combined-docs2",
    metadata={
        "source": "slack",
        "review": {"status": "open"},
        "tags": ["prod", "urgent"],
    },
)
['mem-search-meta-combined-docs2']
any(
    record.id == "mem-search-meta-combined-docs2"
    for record, _ in store.search(
        "pizza",
        k=5,
        metadata_filter={
            "source": "slack",
            "review": {"status": "open"},
            "tags": ["prod", "urgent"],
        },
    )
)
True

metodo search_async (asincrono)

Cercare i record in modo asincrono in base alla somiglianza semantica.

• Parametri:
  • query str | None: lo stesso testo di query accettato da search.
  • k int: conteggio massimo dei risultati accettato da search. I valori espliciti devono essere almeno 1.
  • query_vector list[float] | None: incorporamento facoltativo della stessa query precalcolata accettato da search.
  • thread_id str | None: gli stessi filtri di ambito opzionali accettati da search.
  • user_id str | None: gli stessi filtri di ambito opzionali accettati da search.
  • agent_id str | None: filtri di ambito opzionali uguali accettati da search.
  • exact_user_match bool: flag della stessa corrispondenza esatta accettati da search.
  • exact_agent_match bool: flag della stessa corrispondenza esatta accettati da search.
  • exact_thread_match bool: flag della stessa corrispondenza esatta accettati da search.
  • record_types set[str] | None: filtro del tipo di record opzionale accettato da search.
  • metadata_filter dict[str, Any] | None: lo stesso filtro di metadati facoltativo accettato da search, tra cui scalare, nidificato, lista esatta, appartenenza ad array e condizioni combinate come {"source": "slack"}, {"review": {"status": "open"}}, {"tags": ["prod", "urgent"]} e {"tags": {"$array_contains": "prod"}}.
  • include_invalid_results bool: opzione dei risultati dello stesso stato del ciclo di vita accettata da search.
  • num_hops int: profondità di espansione del grafico identica accettata da search.
  • max_linked_results int: lo stesso limite di memoria collegata per ogni singolo risultato accettato dall'indirizzo search.
• Restituzioni: coppie (record, distance) restituite dalla chiamata search sottostante.
• Tipo restituito: List[tuple[Record, float]]
• Raise: ValueError: se k è minore di 1.

metodo update (abstract)

Aggiorna il contenuto dei record memorizzati, incorporando dati, metadati, indicatore orario o scadenza.

• Parametri:
  • record_type str: tipo logico di record da aggiornare.
  • record_id str: identificativo del record da aggiornare.
  • content str | Mapping[str, object] | Sequence[MessageContent] | bytes | None: contenuto sostitutivo canonico. Per i record message, passare una stringa o una sequenza ordinata di parti di contenuto di testo e immagine; utilizzare "" per sostituire il messaggio con testo vuoto. Per i record simili alla memoria, le aree di memorizzazione possono accettare None per cancellare il testo memorizzato e lo stato semantico associato. Omettere l'argomento per non modificare il contenuto. Non fornire questo insieme a text.
  • index_text str | list[str] | None: payload semantico alternativo facoltativo utilizzato per ricalcolare o sostituire lo stato di ricerca memorizzato senza modificare il testo persistente. Una stringa può essere messa a chunking internamente dal negozio. Una lista di stringhe non vuote viene considerata come chunk di proprietà del chiamante e non deve essere divisa di nuovo. Alcune implementazioni possono anche persistere separatamente come testo di ricerca ibrida. Per un record image, questo campo sostituisce la descrizione dell'immagine persistente.
  • incorporamento list[float] | ndarray | list[list[float] | ndarray] | None: vettore di incorporamento precalcolato opzionale o elenco di vettori di incorporamento dei chunk. Se fornito, questo viene utilizzato direttamente e non viene effettuata alcuna chiamata di incorporamento. Più vettori richiedono liste di chunk index_text corrispondenti o righe di testo chunk memorizzate esistenti. Passare None per cancellare in modo esplicito l'incorporamento memorizzato quando l'area di memorizzazione lo supporta. I negozi con indicizzazione text-aware possono anche consentire aggiornamenti semantici senza incorporamento o incorporamento esplicito.
  • metadata dict[str, Any] | None: mapping dei metadati di sostituzione facoltativo. Passare None per cancellare i metadati quando l'area di memorizzazione li supporta. La sostituzione dell'immagine content richiede "image_mime_type" in questo mapping. L'area di memorizzazione utilizza questo campo per salvare l'immagine, ma non la restituisce come parte dei metadati del record.
  • timestamp str | None: nuovo indicatore orario facoltativo da salvare con il record. Rappresenta la data di creazione del record. Omettere questo argomento per non modificare l'indicatore orario memorizzato. Passare None per cancellare l'indicatore orario salvato e utilizzare l'ora di aggiunta del record al negozio quando il negozio lo supporta.
  • ttl_days int | None: aggiornamento della scadenza facoltativo in giorni. Omettere questo argomento insieme a ttl_anchor per conservare l'indicatore orario di scadenza corrente. Passare None per cancellare la scadenza.
  • ttl_anchor TimeToLiveAnchor: ancoraggio Time To Live opzionale per un aggiornamento della scadenza. Utilizzare TimeToLiveAnchor.CREATED_AT per l'ora di creazione del record o TimeToLiveAnchor.TIMESTAMP per la sostituzione timestamp fornita nello stesso aggiornamento oppure l'indicatore orario dell'evento memorizzato quando timestamp viene omesso. Se si specifica ttl_anchor senza ttl_days, viene utilizzata la durata Time To Live predefinita dell'area di memorizzazione o dello schema. Quando ttl_anchor viene omesso durante un aggiornamento, le implementazioni utilizzano TimeToLiveAnchor.CREATED_AT.
  • stato RecordStatus: stato del ciclo di vita di sostituzione facoltativo per i record.

  • testo str | None –

    Alias non più valido per content. Passare None per cancellare in modo esplicito il testo memorizzato quando è supportato dall'area di memorizzazione. Non fornire questo insieme a content.

    Non più valido

    Deprecato dalla versione 26.8.0: questo parametro è deprecato nella versione 26.8.0 e verrà rimosso nella versione 27.1. Utilizzare invece content.

• Restituzioni: numero di record aggiornati (0 o 1). Un valore restituito pari a 0 indica che nessun record è stato aggiornato.
• Tipo restituito: int.
• Aumenti: ValueError: se il payload di aggiornamento non è valido per l'area di memorizzazione, ad esempio omettendo ogni campo facoltativo o fornendo argomenti semantici in conflitto.

metodo update_async (asincrono)

Aggiorna in modo asincrono il contenuto dei record memorizzati, incorporando dati, metadati, indicatore orario o scadenza.

• Parametri:
  • record_type str: tipo logico di record da aggiornare.
  • record_id str: identificativo del record da aggiornare.
  • content str | Mapping[str, object] | Sequence[MessageContent] | bytes | None: contenuto sostitutivo canonico. Per i record message, passare una stringa o una sequenza ordinata di parti di contenuto di testo e immagine; utilizzare "" per sostituire il messaggio con testo vuoto. Per i record simili alla memoria, le aree di memorizzazione possono accettare None per cancellare il testo memorizzato e lo stato semantico associato. Omettere l'argomento per non modificare il contenuto. Non fornire questo insieme a text.
  • index_text str | list[str] | None: payload semantico alternativo facoltativo utilizzato per ricalcolare o sostituire lo stato di ricerca memorizzato senza modificare il testo persistente. Una stringa può essere messa a chunking internamente dal negozio. Una lista di stringhe non vuote viene considerata come chunk di proprietà del chiamante e non deve essere divisa di nuovo. Alcune implementazioni possono anche persistere separatamente come testo di ricerca ibrida. Per un record image, questo campo sostituisce la descrizione dell'immagine persistente.
  • incorporamento list[float] | ndarray | list[list[float] | ndarray] | None: vettore di incorporamento precalcolato opzionale o elenco di vettori di incorporamento dei chunk. Se fornito, questo viene utilizzato direttamente e non viene effettuata alcuna chiamata di incorporamento. Più vettori richiedono liste di chunk index_text corrispondenti o righe di testo chunk memorizzate esistenti. Passare None per cancellare in modo esplicito l'incorporamento memorizzato quando l'area di memorizzazione lo supporta. I negozi con indicizzazione text-aware possono anche consentire aggiornamenti semantici senza incorporamento o incorporamento esplicito.
  • metadata dict[str, Any] | None: mapping dei metadati di sostituzione facoltativo. Passare None per cancellare i metadati quando l'area di memorizzazione li supporta. La sostituzione dell'immagine content richiede "image_mime_type" in questo mapping. L'area di memorizzazione utilizza questo campo per salvare l'immagine, ma non la restituisce come parte dei metadati del record.
  • timestamp str | None: nuovo indicatore orario facoltativo da salvare con il record. Rappresenta la data di creazione del record. Omettere questo argomento per non modificare l'indicatore orario memorizzato. Passare None per cancellare l'indicatore orario salvato e utilizzare l'ora di aggiunta del record al negozio quando il negozio lo supporta.
  • ttl_days int | None: aggiornamento della scadenza facoltativo in giorni. Omettere questo argomento insieme a ttl_anchor per conservare l'indicatore orario di scadenza corrente. Passare None per cancellare la scadenza.
  • ttl_anchor TimeToLiveAnchor: ancoraggio Time To Live opzionale per un aggiornamento della scadenza. Utilizzare TimeToLiveAnchor.CREATED_AT per l'ora di creazione del record o TimeToLiveAnchor.TIMESTAMP per la sostituzione timestamp fornita nello stesso aggiornamento oppure l'indicatore orario dell'evento memorizzato quando timestamp viene omesso. Se si specifica ttl_anchor senza ttl_days, viene utilizzata la durata Time To Live predefinita dell'area di memorizzazione o dello schema. Quando ttl_anchor viene omesso durante un aggiornamento, le implementazioni utilizzano TimeToLiveAnchor.CREATED_AT.
  • stato RecordStatus: stato del ciclo di vita di sostituzione facoltativo per i record. Ometterlo per mantenere lo stato corrente.

  • testo str | None –

    Alias non più valido per content. Passare None per cancellare in modo esplicito il testo memorizzato quando è supportato dall'area di memorizzazione. Non fornire questo insieme a content.

    Non più valido

    Deprecato dalla versione 26.8.0: questo parametro è deprecato nella versione 26.8.0 e verrà rimosso nella versione 27.1. Utilizzare invece content.

• Restituzioni: numero di record aggiornati (0 o 1). Un valore restituito pari a 0 indica che nessun record è stato aggiornato.
• Tipo restituito: int.
• Aumenti: ValueError: se il payload di aggiornamento non è valido per l'area di memorizzazione, ad esempio omettendo ogni campo facoltativo o fornendo argomenti semantici in conflitto.

metodo update_relations (abstract)

Aggiorna valori modificabili nelle relazioni memorizzate.

I campi omessi rimangono invariati, ad eccezione del fatto che la modifica a un tipo di relazione di memoria incorporata sostituisce l'etichetta inversa con l'inversa fissa. Un'area di memorizzazione di memoria supportata dal database ricalcola anche gli stati del ciclo di vita degli endpoint dopo una modifica del tipo di relazione.

• Parametri:
  • relation_ids str | list[str]: identificativo o identificativi delle relazioni da aggiornare.
  • relation_types str | list[str]: etichetta o etichette opzionali per la relazione diretta sostitutiva. Omettere questa opzione per conservare le etichette memorizzate.
  • opposite_relation_types str | list[str]: etichetta o etichette di relazione inversa sostitutiva opzionale. Passare un'etichetta per sostituirla o omettere questo argomento per conservarla.
  • timestamps str | None | list[str | None]: indicatore orario o indicatori orari di sostituzione facoltativi. Passare None per cancellare un indicatore orario memorizzato.
  • metadata dict[str, Any] | None | list[dict[str, Any] | None]: oggetto o oggetti metadati di sostituzione facoltativi. I metadati forniti sostituiscono l'oggetto memorizzato e non vengono uniti.
• Restituzioni: identificativi delle relazioni aggiornate.
• Tipo restituito: list[str]

Esempi

store.update_relations(
    "relation-id", relation_types="supports"
)
['relation-id']

metodo update_relations_async (asincrono)

Aggiorna in modo asincrono valori modificabili nelle relazioni memorizzate.

I campi omessi rimangono invariati, ad eccezione del fatto che la modifica a un tipo di relazione di memoria incorporata sostituisce l'etichetta inversa con l'inversa fissa. Un'area di memorizzazione di memoria supportata dal database ricalcola anche gli stati del ciclo di vita degli endpoint dopo una modifica del tipo di relazione.

• Parametri:
  • relation_ids str | list[str]: identificativo o identificativi delle relazioni da aggiornare.
  • relation_types str | list[str]: etichetta o etichette opzionali per la relazione diretta sostitutiva. Omettere questa opzione per conservare le etichette memorizzate.
  • opposite_relation_types str | list[str]: etichetta o etichette di relazione inversa sostitutiva opzionale. Passare un'etichetta per sostituirla o omettere questo argomento per conservarla.
  • timestamps str | None | list[str | None]: indicatore orario o indicatori orari di sostituzione facoltativi. Passare None per cancellare un indicatore orario memorizzato.
  • metadata dict[str, Any] | None | list[dict[str, Any] | None]: oggetto o oggetti metadati di sostituzione facoltativi. I metadati forniti sostituiscono l'oggetto memorizzato e non vengono uniti.
• Restituzioni: identificativi delle relazioni aggiornate.
• Tipo restituito: list[str]

Esempi

await store.update_relations_async(
    "relation-id", relation_types="supports"
)
['relation-id']

Area di memorizzazione Oracle DB

classe oracleagentmemory.core.OracleDBMemoryStore

Basi: OracleMemoryStore

Persistenza supportata dal database per messaggi, documenti, memorie e profili degli attori.

Creare un'area di memorizzazione Oracle DB.

• Parametri:
  • embedder IEmbedder | None: incorporamento utilizzato quando l'area di memorizzazione richiede incorporamenti vettoriali locali. Può essere None quando i chiamanti forniscono sempre vettori precalcolati o quando la ricerca per parola chiave viene utilizzata con scritture di solo testo e query di testo. SearchStrategy.HYBRID richiede un OracleDBEmbedder qui in modo che l'indice ibrido gestito possa utilizzare il modello in-database di questo incorporante.
  • pool Any: connessione o pool Oracle DB. Il passaggio di una connessione raw abilita la modalità a sessione singola per questa istanza dell'area di memorizzazione: le chiamate dell'area di memorizzazione concorrente vengono serializzate localmente per conservare le ipotesi di blocco delle righe e delle transazioni utilizzate dalle operazioni di scrittura. Utilizzare un connection pool per le richieste concorrenti.
  • schema_policy SchemaPolicy | str: controlla la modalità di apertura o preparazione dello schema gestito. L'impostazione predefinita richiede uno schema esistente e aggiornato e non apporta modifiche DDL. Per un negozio identificato da memory_store_id, SchemaPolicy.CREATE_IF_NECESSARY crea o ripara lo schema quando necessario; SchemaPolicy.RECREATE lo elimina e lo ricostruisce. Le versioni precedenti dello schema richiedono un aggiornamento dello schema del pacchetto prima di poter essere riparate. Quando schema_owner è impostato, utilizzare SchemaPolicy.REQUIRE_EXISTING per l'accesso cross-schema ordinario o SchemaPolicy.NO_CHECK per l'accesso runtime Deep Data Security. Entrambi impediscono la DDL dello schema gestito, inclusa la creazione, la riparazione, la ricreazione e la creazione del primo indice ibrido; eseguono tali azioni mentre sono connessi come utente del database proprietario senza schema_owner. Nessuna delle due modalità rende l'area di memorizzazione di sola lettura: le normali letture e scritture della memoria utilizzano l'autorizzazione effettiva del database dell'utente della connessione. Per l'accesso runtime a Deep Data Security, utilizzare SchemaPolicy.NO_CHECK e creare l'area di memorizzazione mentre è attivo un OracleMemoryEndUserSecurityContext. L'area di memorizzazione risultante richiede un contesto utente finale attivo per ogni operazione successiva del database. I criteri dello schema diversi da NO_CHECK rifiutano i contesti utente finale attivi, pertanto il lavoro del ciclo di vita dello schema non può essere eseguito accidentalmente come utente finale.
  • vector_dim int | None: dimensione di incorporamento facoltativa per la memorizzazione vettoriale locale. Passare un numero intero positivo per creare la colonna di incorporamento gestita e l'indice vettoriale e per convalidare i metadati dello schema esistenti rispetto a tale dimensione. Passare None o omettere l'argomento quando questa memoria di memorizzazione non richiede memoria vettoriale locale. La parola chiave e la ricerca ibrida possono funzionare dal testo di ricerca memorizzato senza la colonna di incorporamento locale. La ricerca vettoriale richiede la memorizzazione vettoriale locale. Quando questo argomento viene omesso e il backend di ricerca efficace è la ricerca vettoriale, l'area di memorizzazione utilizza embedder.embedding_dimension quando è disponibile un incorporamento.

  • nome_tabellaprefisso str –

    Prefisso facoltativo aggiunto ai nomi di tabella/indice gestiti. Passare questo o memory_store_id, non entrambi.

    Non più valido

    Deprecato dalla versione 26.6.0: questo parametro è deprecato nella versione 26.6.0 e verrà rimosso nella versione 27.1. Utilizzare invece memory_store_id.

  • memory_store_id str: ID stabile per l'area di memorizzazione della memoria DB gestita. Riutilizzare lo stesso ID per riaprire lo stesso negozio gestito. L'ID viene unito tramite join ai nomi degli oggetti DB gestiti con un carattere di sottolineatura, pertanto deve iniziare con una lettera, contenere solo lettere, numeri e caratteri di sottolineatura e contenere al massimo 16 caratteri. Passare questo o table_name_prefix, non entrambi. Se omesso, l'area di memorizzazione utilizza table_name_prefix o il valore predefinito non prefisso quando viene omesso anche table_name_prefix. La creazione, la riparazione o la ricreazione di un'area di memorizzazione nello schema dell'utente della connessione richiede un package DBMS_AGENT_MEMORY_STORE compatibile in tale schema.
  • schema_owner str: proprietario dello schema facoltativo per un'area di memorizzazione della memoria gestita esistente. Omettere questa opzione per utilizzare lo schema dell'utente di connessione. L'argomento pool può essere una connessione al database raw o un connection pool. Utilizzare questa opzione quando appartiene a un utente DB dell'applicazione che dispone di privilegi sulle tabelle di proprietà di un altro utente. Questa opzione è solo per l'accesso runtime a un'area di memorizzazione della memoria gestita già creata. Utilizzare SchemaPolicy.REQUIRE_EXISTING per l'accesso cross-schema ordinario o SchemaPolicy.NO_CHECK con un contesto di sicurezza utente finale attivo per un'area di memorizzazione protetta da Deep Data Security. Creare, aggiornare o ricreare l'area di memorizzazione della memoria gestita durante la connessione come proprietario dello schema e omettere questa opzione. Passare un identificativo senza virgolette; l'input minuscolo viene normalizzato in maiuscolo e i proprietari dello schema con distinzione tra maiuscole e minuscole quotati non sono supportati. Concedere CREATE SESSION e i privilegi oggetto richiesti all'utente DB dell'applicazione; vedere la sezione Database Users and Privileges della guida alla risoluzione dei problemi per i privilegi esatti. In alternativa, esporre le viste con oggetto gestito identico nome nello schema di runtime e omettere schema_owner; questo valore è supportato solo per SchemaPolicy.REQUIRE_EXISTING.
  • search_strategy SearchStrategy: valore SearchStrategy che seleziona il backend per search(). Utilizzare SearchStrategy.VECTOR (impostazione predefinita) per il recupero solo vettoriale, SearchStrategy.HYBRID per eseguire una query su un indice vettoriale ibrido Oracle gestito nel testo di ricerca memorizzato o SearchStrategy.KEYWORD per classificare in base alla corrispondenza parola chiave/testo nel testo di ricerca memorizzato senza fusione vettoriale. KEYWORD non richiede l'embedder. HYBRID richiede che embedder sia un valore OracleDBEmbedder, pertanto l'indice ibrido gestito utilizza lo stesso modello in-database dell'embedder dell'area di memorizzazione principale. Se un client per parole chiave apre uno schema ibrido esistente, l'area di memorizzazione può utilizzare il ramo di testo di tale indice ibrido. L'avvio non riesce quando viene utilizzata una strategia incompatibile con uno schema esistente perché tale schema potrebbe non contenere lo stato della ricerca memorizzata richiesto dalla strategia. Quando schema_policy=SchemaPolicy.REQUIRE_EXISTING e questo argomento vengono omessi, il miglior sforzo dell'area di memorizzazione rileva la modalità di ricerca memorizzata dello schema dai metadati gestiti e la utilizza quando disponibile.
  • search_index_sync SearchIndexSyncMode: valore SearchIndexSyncMode che seleziona il funzionamento di aggiornamento dell'indice di ricerca gestito per SearchStrategy.HYBRID e SearchStrategy.KEYWORD. SearchIndexSyncMode.ON_COMMIT è l'impostazione predefinita e rende i record ricercabili non appena viene eseguito il commit della transazione di scrittura. SearchIndexSyncMode.MANUAL lascia l'aggiornamento a un'operazione di sincronizzazione esplicita lato database. SearchIndexSyncMode.AUTO consente a Oracle di aggiornare l'indice ibrido gestito in modo asincrono ed è supportato solo con SearchStrategy.HYBRID; la ricerca per parola chiave rifiuta AUTO.
  • memory_retention_config MemoryRetentionConfig: configurazione di conservazione della memoria facoltativa per i messaggi e le memorie supportate dal database. MemoryRetentionConfig.default_ttl_days viene utilizzato quando una nuova scrittura omette ttl_days. MemoryRetentionConfig.max_ttl_days blocca le durate esplicite per record al di sopra del massimo configurato con un avviso e, se impostato, fa in modo che ttl_days=None utilizzi tale massimo invece di creare righe non in scadenza. Con SchemaPolicy.CREATE_IF_NECESSARY, una configurazione esplicita aggiorna i metadati memorizzati in uno schema gestito aggiornato esistente, ma non aggiorna le date di scadenza esistenti; omettendo mantiene l'impostazione esistente. Se una configurazione esplicita lascia default_ttl_days o max_ttl_days in NOT_SET_MARKER, l'SDK risolve l'attributo al relativo valore predefinito (None) prima di confrontare o memorizzare i metadati dello schema. Scegliere questa configurazione in base alle informazioni previste memorizzate nei record, al motivo per cui l'applicazione la conserva e a qualsiasi impegno di conservazione delle applicazioni o delle normative.
• Aumenti: RuntimeError: se un contesto di sicurezza dell'utente finale è attivo con un criterio di schema diverso da SchemaPolicy.NO_CHECK o se un'area di memorizzazione runtime NO_CHECK viene aperta o utilizzata senza un contesto di sicurezza dell'utente finale attivo.

Avvertenza: SchemaPolicy.CREATE_IF_NECESSARY può essere più costoso del normale avvio del negozio perché potrebbe riparare gli oggetti dello schema gestito prima che l'inizializzazione abbia esito positivo. Pianificare il lavoro di riparazione come operazione di manutenzione quando uno schema può contenere più righe. Un'area di memorizzazione in una versione precedente dello schema richiede un aggiornamento dello schema del pacchetto prima dell'inizializzazione.

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'inizializzazione dell'area di memorizzazione attende il completamento di tale DDL, pertanto pianifica il primo upgrade 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.

La creazione di tale indice ibrido gestito crea anche una preferenza vectorizer DBMS_VECTOR_CHAIN denominata dallo schema gestito. La preferenza memorizza i metadati di configurazione del vectorizer leggero dal modello OracleDBEmbedder configurato. Può essere ispezionato con viste delle preferenze di Oracle Text, ad esempio CTX_USER_PREFERENCES e CTX_USER_PREFERENCE_VALUES.

metodo add

Aggiungere record all'area di memorizzazione di Oracle DB.

• Parametri:
  • contents Sequence[str | Mapping[str, object] | Sequence[MessageContent] | bytes | None]: sequenza di payload di record di sola lettura. Le voci del messaggio possono contenere parti MessageContent ordinate. Le voci di riepilogo thread possono essere mapping, stringhe che diventano oggetti {"text": value} o None memorizzati come JSON null. I valori di testo vengono utilizzati anche per la ricerca, a meno che non venga specificato index_texts. Per gli altri tipi di record, None può tornare a metadata["content"]. Le stringhe vuote esplicite vengono conservate.
  • record_type str: tipo di record logico da creare, ad esempio "message", "memory", "guideline", "fact", "preference", "user_profile", "agent_profile" o "thread_summary".
  • index_texts list[str | list[str] | None]: payload alternativi facoltativi utilizzati come testo di ricerca. Utilizzare questa opzione per controllare quali indici di ricerca basati su DB o ibridi. Ogni voce dell'elenco esterno è allineata a un record. Una voce stringa può essere messa a chunk dal negozio. Una voce di elenco viene considerata come blocchi di proprietà del chiamante e scritta così com'è a RECORD_CHUNKS.chunk_text. Quando vengono forniti anche embeddings, le voci dell'elenco richiedono esattamente un vettore per chunk; le voci stringa accettano solo un singolo vettore per quel record.

  • embeding list[list[float] | ndarray | list[list[float] | ndarray]] –

    Vettori di incorporamento precompilati opzionali allineati a contents. Ogni voce di record può essere un vettore o un elenco di vettori chunk. Quando la memoria vettoriale locale è configurata, questi vettori vengono memorizzati direttamente come rappresentazione vettoriale del record invece di chiamare l'incorporatore del negozio per creare vettori locali per la scrittura. Un singolo vettore rappresenta l'intero testo semantico, anche quando il chunker configurato altrimenti lo dividerebbe. Più vettori di chunk richiedono liste di chunk index_texts corrispondenti.

    In SearchStrategy.VECTOR, la ricerca vettoriale si posiziona rispetto ai vettori memorizzati. In SearchStrategy.HYBRID o SearchStrategy.KEYWORD, la ricerca basata su DB si classifica attraverso il testo di ricerca memorizzato e il testo gestito da Oracle o lo stato dell'indice ibrido, quindi le integrazioni del tempo aggiuntivo influiscono solo su qualsiasi storage vettoriale locale configurato, non su quella strategia di ricerca attiva. Se questa area di memorizzazione è stata configurata senza memoria vettoriale locale, fornire index_texts anziché embeddings per sostituire il testo visibile a tali indici con riconoscimento testo.

  • record_ids str | None | list[str | None]: identificativi facoltativi visibili al chiamante. È possibile utilizzare una singola stringa per gli inserimenti di un record, mentre gli elenchi devono essere allineati a contents. Gli identificativi generati vengono restituiti quando questo campo viene omesso.
  • thread_ids str | None | list[str | None]: identificativi di thread facoltativi associati ai record inseriti. I valori scalari possono essere trasmessi attraverso gli input allineati.
  • user_ids str | None | list[str | None]: identificativi utente facoltativi associati ai record inseriti. I valori scalari possono essere trasmessi attraverso gli input allineati. Se omesso in un'area di memorizzazione runtime SchemaPolicy.NO_CHECK, l'area di memorizzazione utilizza il nome utente del contesto di sicurezza dell'utente finale attivo. Passare None in modo esplicito per preservare un ID utente con ambito non definito.
  • agent_ids str | None | list[str | None]: identificativi agente facoltativi associati ai record inseriti. I valori scalari possono essere trasmessi attraverso gli input allineati.
  • roles str | None | list[str | None]: ruoli messaggio facoltativi quali "user" o "assistant". Utilizzato solo se record_type è "message".
  • timestamps str | None | list[str | None]: indicatori orari facoltativi da salvare con i record. Ogni indicatore orario rappresenta la data di creazione del record. I valori scalari possono essere trasmessi attraverso gli input allineati. Le voci omesse o None lasciano l'indicatore orario dell'evento non impostato. Se ttl_anchor è TimeToLiveAnchor.TIMESTAMP, ogni record interessato deve avere un valore di indicatore orario ISO-8601 concreto. Gli indicatori orari ISO-8601 senza un fuso orario vengono trattati come UTC.
  • metadata dict[str, Any] | None | list[dict[str, Any] | None]: dizionari di metadati opzionali. I metadati possono includere "content" come origine di fallback quando un valore di testo viene omesso anziché impostato su "". Le scritture delle immagini richiedono "image_mime_type" con "image/png", "image/jpeg" o "image/webp". L'area di memorizzazione utilizza questo campo per salvare l'immagine, ma non la restituisce come parte dei metadati del record.
  • ttl_days int | None | list[int | None]: durata Time To Live opzionale in giorni per i record di tipo messaggio e memoria. Omettere questo argomento per utilizzare MemoryRetentionConfig.default_ttl_days dallo schema gestito. Passare None per utilizzare MemoryRetentionConfig.max_ttl_days quando la configurazione di conservazione ne imposta uno o per creare un record non in scadenza quando non lo è. I valori superiori a MemoryRetentionConfig.max_ttl_days vengono bloccati al massimo con un'avvertenza. I valori scalari possono essere trasmessi attraverso gli input allineati.
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]: ancoraggio Time To Live opzionale. Utilizzare TimeToLiveAnchor.CREATED_AT per scadere in relazione all'ora di creazione del database oppure TimeToLiveAnchor.TIMESTAMP per scadere in relazione all'indicatore orario dell'evento fornito. Se omesso, la scadenza utilizza TimeToLiveAnchor.CREATED_AT. La scadenza ancorata all'indicatore orario richiede un indicatore orario ISO-8601 concreto per ogni record inserito. Gli indicatori orari ISO-8601 senza un fuso orario vengono trattati come UTC.
  • Stati RecordStatus | list[RecordStatus]: stato del ciclo di vita facoltativo per i record che lo supportano. Fornire un valore RecordStatus da applicare a ogni record di input o un elenco di stati allineati a contents. Omettere questo argomento per utilizzare RecordStatus.VALID.
  • **store_kwargs (Qualsiasi): opzioni di scrittura DB. batch_size controlla la dimensione del batch executemany e per impostazione predefinita è 256.
• Restituzioni: identificativi per i record inseriti, nello stesso ordine logico dell'input.
• Tipo restituito: list[str]

Esempi

store.add(
    ["Index this stored text"],
    record_type="memory",
    record_ids="mem-db-add-docs",
)
['mem-db-add-docs']
store.add(
    ["Stored text"],
    record_type="memory",
    index_texts=["Search this text"],
    record_ids="mem-db-index-text-docs",
)
['mem-db-index-text-docs']
store.add(
    ["Short-lived event"],
    record_type="memory",
    record_ids="mem-db-ttl-docs",
    timestamps="2026-01-01T12:00:00+00:00",
    ttl_days=7,
    ttl_anchor=TimeToLiveAnchor.TIMESTAMP,
)
['mem-db-ttl-docs']

metodo add_agent

Aggiungere un record profilo agente.

• Parametri:
  • agent_id str: identificativo dell'agente.
  • informazioni str: informazioni in formato libero sull'agente. Questo testo viene memorizzato come contenuto del profilo e utilizzato per creare la rappresentazione ricercabile del profilo.
  • metadati dict[str, Any] | None: mapping dei metadati facoltativo memorizzato nella riga del profilo dell'agente.
• Restituzioni: identificativo del record profilo agente inserito.
• Tipo restituito: str

Note

I record profilo agente non hanno ambito. L'identificativo di record pubblico inserito è lo stesso valore passato come agent_id.

Esempi

store.add_agent("a-docs-agent", "Support assistant")
'a-docs-agent'

metodo add_agent_async (asincrono)

Aggiungere un record profilo agente in modo asincrono.

• Parametri:
  • agent_id str: identificativo stabile per il profilo dell'agente.
  • information str: testo in formato libero che descrive l'agente.
  • metadati dict[str, Any] | None: mapping dei metadati facoltativo memorizzato nella riga del profilo dell'agente.
• Restituzioni: identificativo del record profilo agente creato.
• Tipo restituito: str

metodo add_async (asincrono)

Aggiungere in modo asincrono record orientati alle righe al negozio.

Accetta gli stessi argomenti e restituisce gli stessi identificativi di add().

• Parametri:
  • contenuti Sequence[str | Mapping[str, object] | Sequence[MessageContent] | bytes | None]
  • tipo_record str
  • testi_indice list[str | list[str] | None]
  • embeding list[list[float] | ndarray | list[list[float] | ndarray]]
  • ID_record str | None | list[str | None]
  • id_thread str | None | list[str | None]
  • ID_utente str | None | list[str | None]
  • id_agente str | None | list[str | None]
  • ruoli str | None | list[str | None]
  • Indicatori data/ora str | None | list[str | None]
  • metadati dict[str, Any] | None | list[dict[str, Any] | None]
  • ttl_days int | None | list[int | None]
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]
  • Stati RecordStatus | list[RecordStatus]
  • store_kwargs Any
• Tipo restituito: list[str]

metodo add_batches

Aggiungere batch logici preparati dal chiamante all'area di memorizzazione.

• Parametri:
  • batches list[PendingRecordBatch]: batch logici completamente preparati da rendere persistenti. Ogni batch deve contenere i propri campi per record, ad esempio record_type, valori di ambito, ruoli, indicatori orari e metadati.
  • **store_kwargs (Qualsiasi): opzioni di scrittura specifiche dell'implementazione inoltrate al negozio concreto.
• Restituzioni: identificativi per i record inseriti, nello stesso ordine logico dei batch e delle righe di input.
• Tipo restituito: elenco[str]

Esempi

store.add_batches(
    [
        PendingRecordBatch(
            contents=["pizza batch"],
            record_type="memory",
            record_ids="mem-batch-docs",
        )
    ]
)
['mem-batch-docs']

metodo add_batches_async (asincrono)

Aggiungere in modo asincrono batch logici preparati dal chiamante all'area di memorizzazione.

Accetta gli stessi argomenti e restituisce gli stessi identificativi di add_batches().

• Parametri:
  • batch list[PendingRecordBatch]
  • store_kwargs Any
• Tipo restituito: list[str]

metodo add_relations

Memorizzare una o più relazioni memoria-memoria atomicamente.

I valori scalari vengono trasmessi attraverso il batch source-ID; gli elenchi devono essere allineati. È possibile memorizzare un solo orientamento di relazione per una coppia di endpoint. Le etichette dei collegamenti di memoria integrati ricevono l'etichetta inversa fissa e le etichette del ciclo di vita aggiornano lo stato dell'endpoint nella stessa transazione.

• Parametri:
  • source_record_ids str | list[str]: identificativi di memoria di origine, come scalare o un elenco allineato.
  • source_record_types str | list[str] – Tipi simili alla memoria per i record di origine.
  • target_record_ids str | list[str]: identificativi di memoria di destinazione, come una lista scalare o allineata.
  • target_record_types str | list[str]: tipi simili alla memoria per i record di destinazione.
  • relation_types str | list[str]: etichette delle relazioni dirette.
  • opposite_relation_types str | list[str]: etichette inverse opzionali per i tipi di relazione personalizzati. Questo descrive la vista inversa della relazione memorizzata; non crea una seconda relazione nella direzione inversa.
  • relation_ids str | None | list[str | None]: identificativi di relazione stabili opzionali. Ometti per generare identificativi.
  • timestamp str | None | list[str | None]: indicatori orari facoltativi memorizzati con le relazioni.
  • metadata dict[str, Any] | None | list[dict[str, Any] | None]: metadati facoltativi memorizzati con le relazioni.
• Restituzioni: gli identificativi di relazione creati nell'ordine di input.
• Tipo restituito: list[str]

Esempi

store.add_relations(
    "new-memory", "memory", "old-memory", "memory", "supersedes"
)
['relation-id']

metodo add_relations_async (asincrono)

Memorizza in modo asincrono una o più relazioni dirette.

I valori scalari vengono trasmessi nel batch dei record di origine. I valori elenco devono avere la stessa lunghezza. È possibile memorizzare un solo orientamento per una coppia di endpoint. Utilizzare opposite_relation_types per descrivere la vista inversa anziché aggiungere una seconda relazione inversa.

• Parametri:
  • source_record_ids str | list[str]: identificativo o identificativi dei record all'estremità di origine di ogni relazione diretta.
  • source_record_types str | list[str]: tipo di record o tipi per source_record_ids. Fornire un valore per tutte le origini o un valore per ogni relazione.
  • target_record_ids str | list[str]: identificativo o identificativi dei record alla fine di ogni relazione diretta.
  • target_record_types str | list[str]: tipo di record o tipi per target_record_ids. Fornire un valore per tutte le destinazioni o un valore per ogni relazione.
  • relation_types str | list[str]: etichetta o etichette di relazione diretta. Fornire un valore per tutte le relazioni o un valore per ogni relazione.
  • opposite_relation_types str | list[str]: etichetta o etichette facoltative per la vista inversa di ciascuna relazione. Per i tipi di relazione di memoria incorporata, l'omissione utilizza l'etichetta inversa predefinita. Per i tipi di relazione personalizzati, l'omissione utilizza la stessa etichetta in entrambe le direzioni.
  • relation_ids str | None | list[str | None]: identificativo o identificativi stabili opzionali. Omettere questa opzione per consentire al negozio di generare identificativi.
  • timestamp str | None | list[str | None]: indicatore orario o indicatori orari facoltativi da memorizzare nelle relazioni.
  • metadati dict[str, Any] | None | list[dict[str, Any] | None]: oggetto o oggetti metadati facoltativi da memorizzare nelle relazioni.
• Restituzioni: identificativi di relazione nell'ordine di input.
• Tipo restituito: list[str]

Esempi

await store.add_relations_async(
    "new", "memory", "old", "memory", "supersedes"
)
['relation-id']

metodo add_user

Aggiungere un record profilo utente.

• Parametri:
  • user_id str: identificativo utente. Se omesso in un'area di memorizzazione runtime SchemaPolicy.NO_CHECK, l'area di memorizzazione utilizza il nome utente del contesto di sicurezza dell'utente finale attivo. In caso contrario, specificare esplicitamente questo argomento.
  • informazioni str: informazioni in formato libero richieste per l'utente. Questo testo viene memorizzato come contenuto del profilo e utilizzato per creare la rappresentazione ricercabile del profilo.
  • metadata dict[str, Any] | None: mapping dei metadati facoltativo memorizzato nella riga del profilo utente.
• Restituzioni: identificativo del record del profilo utente inserito.
• Tipo restituito: str

Note

I record profilo utente non hanno ambito. L'identificativo di record pubblico inserito è il valore user_id esplicito o derivato.

Esempi

store.add_user("u-docs-profile", "Prefers concise answers.")
'u-docs-profile'

metodo add_user_async (asincrono)

Aggiungere un record profilo utente in modo asincrono.

• Parametri:
  • user_id str: identificativo stabile per il profilo utente.
  • information str: testo in formato libero che descrive l'utente.
  • metadata dict[str, Any] | None: mapping dei metadati facoltativo memorizzato nella riga del profilo utente.
• Restituzioni: identificativo del record profilo utente creato.
• Tipo restituito: str

metodo delete

Eliminare una riga gestita e le relative righe chunk in base all'identificativo.

• Parametri:
  • record_type str: etichetta del tipo di record da eliminare. I tipi supportati includono "thread", "message", "memory", "guideline", "fact", "preference", "user_profile" e "agent_profile" e "thread_summary".
  • record_id str: identificativo da eliminare.
  • a cascata bool: quando si utilizza True, espandere le destinazioni di livello superiore supportate, ad esempio i profili attore, nelle righe figlio con ambito all'interno della stessa transazione. Per una destinazione di profilo utente o di profilo agente, vengono eliminate prima le righe di thread di proprietà, che rimuovono i messaggi con ambito thread e le righe della tabella di memoria, quindi i messaggi con ambito attore e le righe simili alla memoria rimanenti (memory, guideline, fact, preference). Il cleanup con ambito viene ancora eseguito quando la riga del profilo corrispondente è già assente.
• Restituzioni: numero di destinazioni di livello superiore richieste rimosse, in genere 0 o 1. Le righe figlio a catena non vengono conteggiate separatamente, pertanto è possibile che sia ancora 0 quando un profilo attore mancante attiva il cleanup con ambito.
• Tipo restituito: int.

Note

L'operazione viene eseguita all'interno di una transazione. Quando cascade è abilitato per una destinazione di livello superiore supportata, l'eliminazione del profilo e tutte le eliminazioni figlio con ambito vengono sottoposte a commit o sottoposte a rollback insieme.

Esempi

store.add(["Delete me"], record_type="memory", record_ids="mem-delete-docs")
['mem-delete-docs']
store.delete("memory", "mem-delete-docs")
1

metodo delete_async (asincrono)

Elimina in modo asincrono un record memorizzato in base all'identificativo.

• Parametri:
  • record_type str: tipo logico del record da rimuovere.
  • record_id str: identificativo del record da rimuovere.
  • cascade bool: quando si utilizza True, applicare qualsiasi comportamento di eliminazione a catena supportato dall'area di memorizzazione per le destinazioni di livello superiore richieste all'interno della stessa operazione di eliminazione. Viene utilizzato principalmente per destinazioni quali i profili attore che possiedono record con ambito aggiuntivo. Ad esempio, una cascata di profilo utente o di profilo agente può eliminare i thread di proprietà stessi, i messaggi con ambito thread e i record di memoria rimossi con tali thread e qualsiasi record con ambito attore diretto rimanente come messaggi, memorie, linee guida, fatti o preferenze. Per l'eliminazione del profilo attore, questo cleanup con ambito può essere ancora eseguito quando la riga del profilo corrispondente è già assente.
• Restituzioni: numero di record di livello superiore richiesti eliminati, in genere 0 o 1. Le righe figlio a catena non vengono conteggiate separatamente, pertanto è possibile che sia ancora 0 quando un profilo attore mancante attiva il cleanup con ambito.
• Tipo restituito: int.

metodo delete_relations

Elimina le relazioni per identificativo e ricalcola lo stato del ciclo di vita.

• Parametri: relation_ids str | list[str]: identificativo o identificativi delle relazioni da eliminare.
• Restituzioni: numero di relazioni eliminate.
• Tipo restituito: int.

Esempi

store.delete_relations("relation-id")
1

metodo delete_relations_async (asincrono)

Elimina le relazioni in modo asincrono in base all'identificativo.

Lo stato del ciclo di vita viene ricalcolato dalle relazioni che rimangono.

• Parametri: relation_ids str | list[str]: identificativo o identificativi delle relazioni da eliminare.
• Restituzioni: numero di relazioni eliminate.
• Tipo restituito: int.

Esempi

await store.delete_relations_async("relation-id")
1

metodo delete_thread

Eliminare un thread e le relative righe memorizzate associate.

• Parametri: thread_id str: identificativo del thread le cui righe devono essere rimosse, incluse la riga del thread, le righe figlio dipendenti e il cleanup esplicito della riga chunk.
• Restituzioni: numero di righe di thread eliminate (0 o 1).
• Tipo restituito: int.

Note

Utilizzare questa operazione quando è necessario eseguire il cleanup a cascata con ambito thread. Nell'area di memorizzazione supportata dal database, l'eliminazione del thread rimuove la riga del thread gestito insieme alle righe di messaggio e memoria associate, oltre ai dati di ricerca gestiti per il recupero. Questa operazione è più ampia di un'eliminazione a livello di messaggio, che rimuove solo la riga del messaggio raw. L'eliminazione dei thread rimuove le righe di messaggi e memoria dipendenti insieme ai dati di recupero associati nella stessa transazione.

Esempi

store.delete_thread("c1")
0

metodo delete_thread_async (asincrono)

Elimina in modo asincrono un thread e i dati memorizzati associati.

• Parametri: thread_id str: identificativo del thread da rimuovere.
• Restituzioni: numero di record thread eliminati, in genere 0 o 1.
• Tipo restituito: int.

Note

Operazione a livello di negozio per la rimozione di un thread e dei record con ambito thread gestiti dal negozio. Preferire l'eliminazione dei thread quando i requisiti di conservazione richiedono l'eliminazione sia dei messaggi di origine che dei dati di memoria con ambito thread derivato, poiché le eliminazioni a livello di messaggio non implicano la rimozione di record derivati con persistenza separata.

metodo get

Recupera un record memorizzato in base all'identificativo.

• Parametri:
  • record_type str: etichetta del tipo di record che viene risolta in una riga gestita, ad esempio "message", "memory", "guideline", "fact", "preference", "thread", "user_profile", o "agent_profile" o "thread_summary".
  • record_id str: identificativo di cui eseguire la ricerca.
  • include_bytes bool: indica se caricare i byte di immagine per i record di immagine o le immagini allegate per i record di messaggio. L'impostazione predefinita è False.
• Restituzioni: record popolato con metadati decodificati se trovati, altrimenti None.
• Tipo restituito: Record | Nessuno

Esempi

store.add(["Remember this"], record_type="memory", record_ids="mem-get-docs")
['mem-get-docs']
store.get("memory", "mem-get-docs").id
'mem-get-docs'

metodo get_async (asincrono)

Recupera in modo asincrono un record memorizzato per tipo e identificativo.

• Parametri:
  • record_type str: tipo logico del record da recuperare, ad esempio "thread", "message", "memory", "guideline", "fact", "preference", "user_profile", "agent_profile" o "image".
  • record_id str: identificativo del record da recuperare.
  • include_bytes bool: indica se caricare i byte delle immagini memorizzate. Per un record di messaggio, controlla se le immagini allegate includono i relativi byte. Per un record di immagine, controlla se vengono caricati i byte di immagine standalone. Questa opzione non ha effetto su altri tipi di record.
• Restituisce: il record memorizzato, se trovato, altrimenti None. Una ricerca "thread" restituisce un valore ThreadRecord con metadati del thread, configurazione runtime, stato di runtime e indicatore orario di creazione popolato quando l'area di memorizzazione supporta thread persistenti.
• Tipo restituito: Record | Nessuno

metodo get_relation

Restituisce una relazione identificata dall'ID o una tupla completa dell'endpoint.

Fornire relation_id da solo o fornire una tupla completa dell'endpoint source-to-target.

• Parametri:
  • source_record_id str – Identificativo del record di origine. Obbligatorio con gli altri campi endpoint-tuple quando relation_id viene omesso.
  • tipo_record_origine str – Tipo di record di origine. Obbligatorio con gli altri campi endpoint-tuple quando relation_id viene omesso.
  • target_record_id str: identificativo del record di destinazione. Obbligatorio con gli altri campi endpoint-tuple quando relation_id viene omesso.
  • target_record_type str: tipo di record di destinazione. Obbligatorio con gli altri campi endpoint-tuple quando relation_id viene omesso.
  • tipo_relazione str: etichetta della relazione diretta. Obbligatorio con gli altri campi endpoint-tuple quando relation_id viene omesso.
  • relation_id str: identificativo della relazione per la corrispondenza diretta. Fornire questo argomento da solo anziché combinarlo con i campi endpoint-tuple.
• Restituzioni: la relazione memorizzata corrispondente o None quando non esiste.
• Tipo restituito: RecordRelation | Nessuno

Esempi

store.get_relation(relation_id="relation-id")
RecordRelation(...)
store.get_relation(
    "source-id", "memory", "target-id", "fact", "supports"
)
RecordRelation(...)

metodo get_relation_async (asincrono)

Recupera in modo asincrono una relazione per ID o tupla endpoint.

Fornire relation_id da solo o fornire una tupla completa dell'endpoint source-to-target.

• Parametri:
  • source_record_id str – Identificativo del record di origine. Obbligatorio con gli altri campi endpoint-tuple quando relation_id viene omesso.
  • tipo_record_origine str – Tipo di record di origine. Obbligatorio con gli altri campi endpoint-tuple quando relation_id viene omesso.
  • target_record_id str: identificativo del record di destinazione. Obbligatorio con gli altri campi endpoint-tuple quando relation_id viene omesso.
  • target_record_type str: tipo di record di destinazione. Obbligatorio con gli altri campi endpoint-tuple quando relation_id viene omesso.
  • tipo_relazione str: etichetta della relazione diretta. Obbligatorio con gli altri campi endpoint-tuple quando relation_id viene omesso.
  • relation_id str: identificativo della relazione per la corrispondenza diretta. Fornire questo argomento da solo anziché combinarlo con i campi endpoint-tuple.
• Restituzioni: la relazione corrispondente o None quando non esiste.
• Tipo restituito: RecordRelation | Nessuno

Esempi

await store.get_relation_async(relation_id="relation-id")
RecordRelation(...)

metodo list

Enumerare i record persistenti per un tipo di record.

• Parametri:
  • record_type str: etichetta del tipo di record (ad esempio "thread", "message", "memory", "guideline", "fact", "preference", "thread", "user_profile" o "agent_profile").
  • limite int | None: numero massimo facoltativo di record da restituire. Se omesso, il negozio utilizza il suo limite predefinito. Passare None per disabilitare il limite e restituire ogni record corrispondente.
  • thread_id str | None: filtro thread-ambito esatto. Se omesso, non viene applicato alcun filtro. Se impostato su None, vengono restituite solo le righe il cui thread_id è SQL NULL. I tipi di record senza ambito ignorano questo filtro. Se record_type è "thread", non è necessario impostare thread_id; utilizzare record_id per selezionare un thread specifico.
  • user_id str | None: filtro esatto dell'ambito utente. Se omesso, non viene applicato alcun filtro. Se impostato su None, vengono restituite solo le righe il cui user_id è SQL NULL. I tipi di record senza ambito ignorano questo filtro.
  • agent_id str | None: filtro agente-ambito esatto. Se omesso, non viene applicato alcun filtro. Se impostato su None, vengono restituite solo le righe il cui agent_id è SQL NULL. I tipi di record senza ambito ignorano questo filtro.

  • filtro_metadata dict[str, Any] | None:

    Filtro metadati. Se omesso, non viene applicato alcun filtro. Se impostato su None, vengono restituiti solo i record senza metadati memorizzati. Se impostato su un dett, le voci in metadata_filter vengono combinate con la semantica AND. Le voci il cui valore non è un dizionario operatore a livello di campo utilizzano la semantica di corrispondenza esatta: la chiave richiesta deve esistere nei metadati memorizzati. I dizionari nidificati vengono abbinati in modo ricorsivo. I valori scalari e di elenco corrispondono in base all'uguaglianza esatta; anche l'ordine e la lunghezza dell'elenco devono corrispondere. Per eseguire il test dell'appartenenza all'array, utilizzare un dizionario operatore a livello di campo, ad esempio {"tags": {"$array_contains": "prod"}}. Un operando elenco per "$array_contains" indica che devono essere presenti tutti i valori elencati; "$array_contains_any" indica che deve essere presente almeno un valore elencato. Utilizzare "$not" per negare un'altra espressione a livello di campo nello stesso campo, incluso un dizionario operatore o un valore raw di corrispondenza esatta. Le espressioni negative corrispondono quando l'espressione positiva non riesce, inclusi i campi mancanti; l'appartenenza all'array negata corrisponde anche ai campi non array. Ad esempio, metadata_filter={"source": "slack"} per un campo scalare, metadata_filter={"review": {"status": "open"}} per un campo nidificato e metadata_filter={"tags": ["prod", "urgent"]} per una corrispondenza esatta dell'elenco. Combina le condizioni per richiederle tutte:

    metadata_filter={
        "source": "slack",
        "review": {"status": "open"},
        "tags": ["prod", "urgent"],
    }

  • include_bytes bool: indica se i record di immagine o le immagini allegate ai record dei messaggi includono i byte memorizzati. L'impostazione predefinita è False. Gli elenchi di immagini dirette richiedono un record_id e almeno un filtro di ambito utente, agente o thread esatto quando si tratta di True.
  • record_id str: filtro identificativo record esatto. Se omesso, vengono restituiti i record con qualsiasi identificativo. I filtri di ambito e metadati rimangono vincoli aggiuntivi.
• Restituzioni: record ordinati in base all'ordine di inserimento.
• Tipo restituito: list[Record]

Note

"user_profile" e "agent_profile" sono tipi di record senza ambito. Per questi tipi di record, thread_id, user_id e agent_id vengono ignorati e l'identità dell'attore rimane in record.id. I record "thread" espongono l'identificativo del thread sia come record.id che come record.thread_id.

Esempi

store.add(
    ["First listed", "Second listed"],
    record_type="memory",
    record_ids=["mem-list-docs-1", "mem-list-docs-2"],
)
['mem-list-docs-1', 'mem-list-docs-2']
[record.id for record in store.list("memory", limit=2)]
['mem-list-docs-1', 'mem-list-docs-2']
store.add_user("u-list-docs", "Prefers concise answers.")
'u-list-docs'
any(
    record.id == "u-list-docs"
    for record in store.list("user_profile", user_id=None, limit=10)
)
True

metodo list_async (asincrono)

Elenca in modo asincrono i record memorizzati per un tipo di record.

• Parametri:
  • record_type str: tipo di record logico da enumerare, ad esempio "thread", "message", "memory", "guideline", "fact", "preference", "user_profile", "agent_profile" o "image".
  • limite int | None: numero massimo facoltativo di record più recenti da restituire. Se omesso, le implementazioni possono applicare un limite superiore sicuro come MAX_LIST_LIMIT. Passare None per disabilitare il limite e restituire ogni record corrispondente.
  • thread_id str | None: filtro thread-ambito esatto. Se omesso, non viene applicato alcun filtro. Se impostato su None, vengono restituiti solo i record il cui thread_id è None. I tipi di record senza ambito ignorano questo filtro. Se record_type è "thread", non è necessario impostare thread_id; utilizzare record_id per selezionare un thread specifico.
  • user_id str | None: filtro esatto dell'ambito utente. Se omesso, non viene applicato alcun filtro. Se impostato su None, vengono restituiti solo i record il cui user_id è None. I tipi di record senza ambito ignorano questo filtro.
  • agent_id str | None: filtro agente-ambito esatto. Se omesso, non viene applicato alcun filtro. Se impostato su None, vengono restituiti solo i record il cui agent_id è None. I tipi di record senza ambito ignorano questo filtro.

  • filtro_metadata dict[str, Any] | None:

    Filtro metadati. Se omesso, non viene applicato alcun filtro. Se impostato su None, vengono restituiti solo i record i cui metadati sono None. Se impostato su un dett, le voci in metadata_filter vengono combinate con la semantica AND. Le voci il cui valore non è un dizionario operatore a livello di campo utilizzano la semantica di corrispondenza esatta: la chiave richiesta deve esistere nei metadati memorizzati. I dizionari nidificati vengono abbinati in modo ricorsivo. I valori scalari e di elenco corrispondono in base all'uguaglianza esatta; anche l'ordine e la lunghezza dell'elenco devono corrispondere. Per eseguire il test dell'appartenenza all'array, utilizzare un dizionario operatore a livello di campo, ad esempio {"tags": {"$array_contains": "prod"}}. Un operando elenco per "$array_contains" indica che devono essere presenti tutti i valori elencati; "$array_contains_any" indica che deve essere presente almeno un valore elencato. Utilizzare "$not" per negare un'altra espressione a livello di campo nello stesso campo, incluso un dizionario operatore o un valore raw di corrispondenza esatta. Le espressioni negative corrispondono quando l'espressione positiva non riesce, inclusi i campi mancanti; l'appartenenza all'array negata corrisponde anche ai campi non array. Ad esempio, metadata_filter={"source": "slack"} per un campo scalare, metadata_filter={"review": {"status": "open"}} per un campo nidificato e metadata_filter={"tags": ["prod", "urgent"]} per una corrispondenza esatta dell'elenco. Combina le condizioni per richiederle tutte:

    metadata_filter={
        "source": "slack",
        "review": {"status": "open"},
        "tags": ["prod", "urgent"],
    }

  • include_bytes bool: indica se i record di immagine o le immagini allegate ai record dei messaggi includono i byte memorizzati. Se omesso o False, le descrizioni delle immagini e i metadati vengono restituiti senza caricare i byte. Per gli elenchi di immagini dirette, impostare questo valore su True solo con un record_id esatto e almeno un filtro utente, agente o ambito thread esatto. Questa opzione non ha effetto su altri tipi di record.
  • record_id str: filtro identificativo record esatto. Se omesso, vengono restituiti i record con qualsiasi identificativo. I filtri di ambito e metadati rimangono vincoli aggiuntivi.
• Restituzioni: record ordinati dal meno recente al più recente all'interno della finestra restituita.
• Tipo restituito: elenco[Record]

metodo list_relations

Elenca le relazioni nel loro orientamento source-to-target.

• Parametri:
  • tipo_relazione str: etichetta della relazione diretta opzionale da abbinare, ad esempio "supports" o "supersedes". Omettere di includere ogni tipo di relazione.
  • source_record_id str: identificativo del record di origine facoltativo per la corrispondenza.
  • source_record_type str: tipo di record di origine facoltativo di cui trovare la corrispondenza.
  • target_record_id str: identificativo del record di destinazione facoltativo per la corrispondenza.
  • target_record_type str: tipo di record di destinazione facoltativo per la corrispondenza.
  • limite int | None: numero massimo facoltativo di relazioni create per la prima volta da restituire. Se omesso, l'area di memorizzazione utilizza MAX_LIST_LIMIT. Passare None per restituire ogni relazione memorizzata corrispondente.
  • metadata_filter dict[str, Any] | None: filtro dei metadati. Se omesso, non viene applicato alcun filtro. Se impostato su None, vengono restituite solo le relazioni i cui metadati sono None. Se impostato su un dett, le voci vengono combinate con la semantica AND. I dizionari nidificati utilizzano la corrispondenza esatta ricorsiva. I valori scalari e di lista richiedono l'uguaglianza esatta; utilizzare {"tags": {"$array_contains": "prod"}} per corrispondere all'appartenenza all'array, "$array_contains_any" per corrispondere a qualsiasi valore elencato oppure "$not" per negare un'altra espressione di campo.
  • relation_id str: filtro identificativo relazione esatto. Se omesso, vengono restituite le relazioni con qualsiasi identificativo. Altri filtri rimangono vincoli aggiuntivi.
• Restituzioni: relazioni ordinate in base all'ora e all'identificativo di creazione.
• Tipo restituito: list[RecordRelation]

Esempi

store.list_relations(
    source_record_id="current-memory",
    relation_type="supports",
    metadata_filter={"source": "manual"},
)
[RecordRelation(...)]

metodo list_relations_async (asincrono)

Elenca in modo asincrono le relazioni nell'orientamento da origine a destinazione.

• Parametri:
  • tipo_relazione str: etichetta della relazione diretta opzionale da abbinare, ad esempio "supports" o "supersedes". Omettere di includere ogni tipo di relazione.
  • source_record_id str: identificativo del record di origine facoltativo per la corrispondenza.
  • source_record_type str: tipo di record di origine facoltativo di cui trovare la corrispondenza.
  • target_record_id str: identificativo del record di destinazione facoltativo per la corrispondenza.
  • target_record_type str: tipo di record di destinazione facoltativo per la corrispondenza.
  • limite int | None: numero massimo facoltativo di relazioni create per la prima volta da restituire. Se omesso, le implementazioni possono applicare un limite superiore sicuro come MAX_LIST_LIMIT. Passare None per restituire ogni relazione memorizzata corrispondente.
  • metadata_filter dict[str, Any] | None: filtro dei metadati. Se omesso, non viene applicato alcun filtro. Se impostato su None, vengono restituite solo le relazioni i cui metadati sono None. Se impostato su un dett, le voci vengono combinate con la semantica AND. I dizionari nidificati utilizzano la corrispondenza esatta ricorsiva. I valori scalari e di lista richiedono l'uguaglianza esatta; utilizzare {"tags": {"$array_contains": "prod"}} per corrispondere all'appartenenza all'array, "$array_contains_any" per corrispondere a qualsiasi valore elencato oppure "$not" per negare un'altra espressione di campo.
  • relation_id str: identificativo di relazione facoltativo che consente la corrispondenza diretta.
• Restituzioni: relazioni ordinate in base all'ora e all'identificativo di creazione.
• Tipo restituito: list[RecordRelation]

Esempi

await store.list_relations_async(
    source_record_id="current-memory", relation_type="supports"
)
[RecordRelation(...)]

metodo list_thread_messages

Restituisci messaggi persistenti per un thread.

• Parametri:
  • thread_id str: identificativo del thread i cui messaggi devono essere restituiti.
  • last_n int | None: numero facoltativo di messaggi più recenti da restituire.
  • range_start_seq_no int | None: limite della sequenza inferiore incluso facoltativo.
  • range_end_seq_no int | None: limite della sequenza superiore esclusivo opzionale.
  • include_bytes bool: indica se le parti immagine allegate ai messaggi restituiti includono i byte memorizzati. L'impostazione predefinita è False.
• Restituzioni: record di messaggi ordinati in base all'ordine di inserimento.
• Tipo restituito: list[MessageRecord]

Esempi

store.list_thread_messages("c1")
[]

metodo list_thread_messages_async (asincrono)

Elenca in modo asincrono la cronologia dei messaggi memorizzata per un thread.

• Parametri:
  • thread_id str: identificativo del thread in cui devono essere restituiti i messaggi.
  • last_n int | None: numero facoltativo di messaggi più recenti da includere. Se omesso, vengono restituiti tutti i messaggi memorizzati per il thread. Se combinato con un intervallo di sequenze, il limite viene applicato all'interno di tale intervallo.
  • range_start_seq_no int | None: limite della sequenza inferiore incluso facoltativo. Vengono restituiti solo i messaggi il cui valore seq_no è almeno questo.
  • range_end_seq_no int | None: limite della sequenza superiore esclusivo opzionale. Vengono restituiti solo i messaggi con seq_no inferiore a questo valore.
  • include_bytes bool: indica se le parti immagine allegate ai messaggi restituiti includono i byte memorizzati. Se omesso o False, le descrizioni delle immagini e i metadati vengono restituiti senza caricare i byte.
• Restituzioni: i record dei messaggi ordinati dal meno recente al più recente all'interno della finestra restituita.
• Tipo restituito: List[MessageRecord]

metodo search

Cerca i record per somiglianza.

Il backend di ricerca attivo dipende dal valore SearchStrategy configurato dell'area di memorizzazione. SearchStrategy.VECTOR classifica il vettore di query rispetto ai vettori di record memorizzati. SearchStrategy.HYBRID esegue query sull'indice ibrido gestito di Oracle sul testo di ricerca memorizzato e sul relativo stato dell'indice gestito. SearchStrategy.KEYWORD si classifica solo in base al testo corrispondente sul testo di ricerca memorizzato.

• Parametri:
  • query str | None: testo in lingua naturale opzionale utilizzato per trovare record corrispondenti o simili. Fornire almeno un carattere che non sia uno spazio quando query_vector viene omesso. La ricerca vettoriale incorpora questo testo; la ricerca per parola chiave lo confronta con il testo di ricerca memorizzato; la ricerca ibrida lo utilizza sia per il testo che per il recupero vettoriale. Quando il testo supera la dimensione chunk configurata, l'area di memorizzazione ricerca ogni chunk di query separatamente e unisce i risultati classificati con la fusione di classificazione reciproca.
  • query_vector list[float] | None: incorporamento facoltativo di query precalcolate. Specificare esattamente uno dei valori query e query_vector. Nella ricerca vettoriale, questo viene confrontato con i vettori di record memorizzati. Nella ricerca ibrida, viene inviata all'indice ibrido gestito di Oracle come input vettoriale lato query e non causa il confronto diretto tra l'area di memorizzazione DB e i vettori memorizzati in fase di aggiunta o aggiornamento. La ricerca per parola chiave non accetta query_vector. Il vettore deve essere non vuoto, un dimensionale e contenere solo valori numerici finiti. Nella ricerca ibrida, la relativa dimensione deve corrispondere al modello OracleDBEmbedder configurato.
  • k int: numero massimo di risultati da restituire. I valori espliciti devono essere almeno 1. Questo è un limite superiore: la chiamata può restituire meno di k risultati quando i filtri sono troppo restrittivi, quando esistono meno record di corrispondenza non scaduti o a causa di un funzionamento di ricerca specifico dell'implementazione.
  • thread_id str | None: identificativo di ambito thread facoltativo. exact_thread_match=False lascia la dimensione thread non vincolata. exact_thread_match=True corrisponde esattamente al valore thread_id fornito. Se thread_id=None, corrisponde solo ai record senza ambito nella dimensione thread.
  • user_id str | None: identificativi facoltativi dell'ambito utente e agente. Il flag exact_*_match=False corrispondente lascia la dimensione non vincolata. exact_*_match=True corrisponde esattamente all'ID fornito. Se l'ID è None, corrisponde solo ai record senza ambito su tale dimensione.
  • agent_id str | None: identificativi facoltativi di ambito utente e agente. Il flag exact_*_match=False corrispondente lascia la dimensione non vincolata. exact_*_match=True corrisponde esattamente all'ID fornito. Se l'ID è None, corrisponde solo ai record senza ambito su tale dimensione.
  • exact_user_match bool: indica se ogni identificativo di ambito deve avere una corrispondenza esatta. False lascia la dimensione non vincolata. True corrisponde esattamente al valore fornito. Se il valore è None, corrisponde solo ai record con ambito non definito della dimensione.
  • exact_agent_match bool: indica se ogni identificativo di ambito deve avere una corrispondenza esatta. False lascia la dimensione non vincolata. True corrisponde esattamente al valore fornito. Se il valore è None, corrisponde solo ai record con ambito non definito della dimensione.
  • exact_thread_match bool: indica se ogni identificativo di ambito deve avere una corrispondenza esatta. False lascia la dimensione non vincolata. True corrisponde esattamente al valore fornito. Se il valore è None, corrisponde solo ai record con ambito non definito della dimensione.
  • record_types set[str] | None: set facoltativo di tipi di record ricercabili da includere. Se omessa, la ricerca DB copre messaggi, documenti come immagini, righe della tabella di memoria e profili degli attori. I record immagine forniscono una descrizione, i profili attore contribuiscono al payload information e le righe di messaggio e memoria contribuiscono al payload content. Durante la ricerca, i tipi di record profilo utilizzano il relativo identificativo attore per la dimensione ambito applicabile mentre le restanti dimensioni ambito funzionano come None.
  • metadata_filter dict[str, Any] | None: mapping facoltativo del filtro dei metadati. Le voci in metadata_filter sono combinate con la semantica AND. Le voci il cui valore non è un dizionario operatore a livello di campo utilizzano la semantica di corrispondenza esatta: la chiave richiesta deve esistere nei metadati memorizzati. I dizionari nidificati vengono abbinati in modo ricorsivo. I valori scalari e di elenco corrispondono in base all'uguaglianza esatta; anche l'ordine e la lunghezza dell'elenco devono corrispondere. Per eseguire il test dell'appartenenza all'array, utilizzare un dizionario operatore a livello di campo, ad esempio {"tags": {"$array_contains": "prod"}}. Un operando elenco per "$array_contains" indica che devono essere presenti tutti i valori elencati; "$array_contains_any" indica che deve essere presente almeno un valore elencato. Utilizzare "$not" per negare un'altra espressione a livello di campo nello stesso campo, incluso un dizionario operatore o un valore raw di corrispondenza esatta. Le espressioni negative corrispondono quando l'espressione positiva non riesce, inclusi i campi mancanti; l'appartenenza all'array negata corrisponde anche ai campi non array.
  • include_invalid_results bool: indica se i risultati includono record di tipo memoria con stato non valido. L'impostazione predefinita è True. Passare False per escluderli.
  • num_hops int: numero di bordi dei collegamenti di memoria da seguire per ogni risultato della memoria diretta. Sono supportati i valori da 0 a 5; 0 disabilita l'espansione del grafico. L'espansione segue i collegamenti in entrambe le direzioni. I record collegati continuano a rispettare l'ambito, i metadati, il tipo di record e i filtri di scadenza richiesti. I risultati dei messaggi diretti, dei documenti e dei profili rimangono nel set di risultati, ma non sono espansi nel grafico.
  • max_linked_results int: numero massimo di memorie collegate tra tutti gli hop collegati a ciascun risultato diretto. 0 mantiene i risultati diretti senza contesto collegato. L'impostazione predefinita è 100.
• Restituzioni: coppie (record, distance) ordinate in base alla distanza crescente. L'elenco può contenere meno di k voci. Per un'interrogazione a chunk, la distanza viene derivata dal punteggio di fusione a rango reciproco.
• Tipo restituito: list[tuple[Record, float]]
• Solleva:
  • ValueError: se k è minore di 1, se vengono forniti entrambi i valori query e query_vector, se query è vuoto, se la modalità vettoriale non è in grado di risolvere l'incorporamento di una query, se query_vector non è valido o se metadata_filter non è valido.
  • TimeoutError: se l'espansione del grafico richiede più tempo del tempo massimo consentito.

Esempi

store.add(
    ["pizza preference"],
    record_type="memory",
    record_ids="mem-search-docs",
    thread_ids="c-search-docs",
)
['mem-search-docs']
results = store.search(
    "pizza",
    1,
    thread_id="c-search-docs",
    exact_thread_match=True,
    record_types={"memory"},
)
results[0][0].id
'mem-search-docs'

Filtra in base a un valore di metadati scalare:

store.add(
    ["pizza release"],
    record_type="memory",
    record_ids="mem-search-meta-source-docs",
    metadata={"source": "slack"},
)
['mem-search-meta-source-docs']
any(
    record.id == "mem-search-meta-source-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"source": "slack"},
    )
)
True

Filtra in base ai metadati nidificati:

store.add(
    ["pizza review"],
    record_type="memory",
    record_ids="mem-search-meta-review-docs",
    metadata={"review": {"status": "open"}},
)
['mem-search-meta-review-docs']
any(
    record.id == "mem-search-meta-review-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"review": {"status": "open"}},
    )
)
True

Corrisponde esattamente a un valore di elenco, incluso l'ordine:

store.add(
    ["pizza tags"],
    record_type="memory",
    record_ids="mem-search-meta-tags-docs",
    metadata={"tags": ["prod", "urgent"]},
)
['mem-search-meta-tags-docs']
any(
    record.id == "mem-search-meta-tags-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"tags": ["prod", "urgent"]},
    )
)
True

Filtra quando un array di metadati contiene un valore:

any(
    record.id == "mem-search-meta-tags-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"tags": {"$array_contains": "prod"}},
    )
)
True

Combina più condizioni metadati. Un record deve soddisfare ogni chiave:

store.add(
    ["pizza rollout"],
    record_type="memory",
    record_ids="mem-search-meta-combined-docs",
    metadata={
        "source": "slack",
        "review": {"status": "open"},
        "tags": ["prod", "urgent"],
    },
)
['mem-search-meta-combined-docs']
any(
    record.id == "mem-search-meta-combined-docs"
    for record, _ in store.search(
        "pizza",
        k=5,
        metadata_filter={
            "source": "slack",
            "review": {"status": "open"},
            "tags": ["prod", "urgent"],
        },
    )
)
True

metodo search_async (asincrono)

Cercare i record in modo asincrono in base alla somiglianza semantica.

• Parametri:
  • query str | None: lo stesso testo di query accettato da search.
  • k int: conteggio massimo dei risultati accettato da search. I valori espliciti devono essere almeno 1.
  • query_vector list[float] | None: incorporamento facoltativo della stessa query precalcolata accettato da search.
  • thread_id str | None: gli stessi filtri di ambito opzionali accettati da search.
  • user_id str | None: gli stessi filtri di ambito opzionali accettati da search.
  • agent_id str | None: filtri di ambito opzionali uguali accettati da search.
  • exact_user_match bool: flag della stessa corrispondenza esatta accettati da search.
  • exact_agent_match bool: flag della stessa corrispondenza esatta accettati da search.
  • exact_thread_match bool: flag della stessa corrispondenza esatta accettati da search.
  • record_types set[str] | None: filtro del tipo di record opzionale accettato da search.
  • metadata_filter dict[str, Any] | None: lo stesso filtro di metadati facoltativo accettato da search, tra cui scalare, nidificato, lista esatta, appartenenza ad array e condizioni combinate come {"source": "slack"}, {"review": {"status": "open"}}, {"tags": ["prod", "urgent"]} e {"tags": {"$array_contains": "prod"}}.
  • include_invalid_results bool: opzione dei risultati dello stesso stato del ciclo di vita accettata da search.
  • num_hops int: profondità di espansione del grafico identica accettata da search.
  • max_linked_results int: lo stesso limite di memoria collegata per ogni singolo risultato accettato dall'indirizzo search.
• Restituzioni: coppie (record, distance) restituite dalla chiamata search sottostante.
• Tipo restituito: List[tuple[Record, float]]
• Raise: ValueError: se k è minore di 1.

metodo update

Aggiorna il contenuto del record memorizzato, lo stato della ricerca, i metadati e i valori dell'indicatore orario.

• Parametri:
  • record_type str: etichetta del tipo di record della riga da modificare, ad esempio "message", "memory", "guideline", "fact", "preference", "user_profile" o "agent_profile".
  • record_id str: identificativo della riga memorizzata da aggiornare.
  • content str | Mapping[str, object] | Sequence[MessageContent] | bytes | None: il contenuto di sostituzione canonica è persistente nella colonna content. Per i record dei messaggi, passare "" per cancellare il contenuto durante la cancellazione di qualsiasi rappresentazione vettoriale memorizzata; None esplicito viene rifiutato. Per i record simili alla memoria, passare None per cancellare il testo memorizzato e incorporare e passare solo None o argomenti semantici omessi nella stessa chiamata. Se omesso, il contenuto esistente rimane invariato. Non fornire questo insieme a text.
  • index_text str | list[str] | None: payload facoltativo solo semantico. Se omesso, per l'indicizzazione semantica viene utilizzato content. Negli schemi con capacità ibrida questo diventa anche il testo di ricerca memorizzato utilizzato dal componente di testo di Oracle. Un valore stringa può essere chunk dal negozio; un valore elenco viene considerato come chunk di proprietà del chiamante e scritto così com'è a RECORD_CHUNKS. Se viene fornito solo embedding, il testo di ricerca esistente viene riutilizzato.

  • incorporamento list[float] | ndarray | list[list[float] | ndarray] | None:

    Vettore di incorporamento precomputato opzionale o elenco di vettori di incorporamento chunk. Quando la memoria vettoriale locale è configurata, questo viene utilizzato direttamente e non viene effettuata alcuna chiamata di incorporamento. Passare None per cancellare l'incorporamento memorizzato. Un singolo vettore rappresenta l'intero testo di sostituzione quando viene fornito content, anche quando il chunker configurato divide tale testo. Quando si sostituisce il testo, vengono rifiutati più vettori chunk a meno che index_text non sia un elenco chunk. Quando viene fornito solo embedding, il conteggio di incorporamento deve corrispondere alle righe chunk esistenti del record.

    In SearchStrategy.VECTOR, la ricerca vettoriale si posiziona rispetto all'incorporamento memorizzato. In SearchStrategy.HYBRID o SearchStrategy.KEYWORD, la ricerca basata su DB si classifica attraverso il testo di ricerca memorizzato e il testo gestito da Oracle o lo stato dell'indice ibrido, quindi le integrazioni del tempo di aggiornamento influiscono solo su qualsiasi storage vettoriale locale configurato, non su quella strategia di ricerca attiva. Se questa area di memorizzazione è stata configurata senza memoria vettoriale locale, fornire index_text anziché embedding per aggiornare il testo visibile a tali indici con riconoscimento testo. Gli aggiornamenti semantici di solo testo possono omettere completamente embedding in tali modalità.

  • metadata dict[str, Any] | None: mapping dei metadati facoltativo serializzato in JSON e memorizzato in metadata. La sostituzione dell'immagine content richiede "image_mime_type" con "image/png", "image/jpeg" o "image/webp". L'area di memorizzazione utilizza questo campo per salvare l'immagine, ma non la restituisce come parte dei metadati del record.
  • timestamp str | None: nuovo indicatore orario facoltativo da salvare con il record. Rappresenta la data di creazione del record. Se omesso, l'indicatore orario esistente viene conservato. Passare None per cancellare l'indicatore orario salvato e utilizzare l'ora di creazione del database per i futuri aggiornamenti della scadenza TimeToLiveAnchor.CREATED_AT. Quando ttl_anchor è TimeToLiveAnchor.TIMESTAMP, gli indicatori orari ISO-8601 senza un fuso orario vengono considerati come UTC.
  • ttl_days int | None: aggiornamento della scadenza facoltativo in giorni. Omettere questo argomento insieme a ttl_anchor per conservare l'indicatore orario di scadenza corrente. Passare None per utilizzare MemoryRetentionConfig.max_ttl_days quando la configurazione di conservazione ne imposta una o per cancellare la scadenza quando non è impostata. I valori superiori a MemoryRetentionConfig.max_ttl_days vengono bloccati al massimo con un'avvertenza. L'aggiornamento della scadenza può rendere nuovamente visibile un record scaduto se non è stato ancora rimosso.
  • ttl_anchor TimeToLiveAnchor: ancoraggio Time To Live opzionale per un aggiornamento della scadenza. Utilizzare TimeToLiveAnchor.CREATED_AT per eseguire il conteggio dall'ora di creazione memorizzata oppure TimeToLiveAnchor.TIMESTAMP per eseguire il conteggio dalla sostituzione timestamp fornita nello stesso aggiornamento oppure dall'indicatore orario dell'evento memorizzato quando timestamp viene omesso. Se si specifica ttl_anchor senza ttl_days, la scadenza viene aggiornata utilizzando MemoryRetentionConfig.default_ttl_days dello schema. Quando ttl_anchor viene omesso durante un aggiornamento, l'area di memorizzazione utilizza TimeToLiveAnchor.CREATED_AT. Gli aggiornamenti con indicatore orario basato su indicatore orario richiedono un indicatore orario ISO-8601 sostitutivo nella stessa chiamata o un indicatore orario evento memorizzato esistente in tale formato. Gli indicatori orari ISO-8601 senza un fuso orario vengono trattati come UTC.
  • stato RecordStatus: stato del ciclo di vita di sostituzione facoltativo per i record. Ometterlo per mantenere lo stato corrente.

  • testo str | None –

    Alias non più valido per content. Passare None per cancellare il testo memorizzato e cancellare l'incorporamento memorizzato. Non fornire questo insieme a content.

    Non più valido

    Deprecato dalla versione 26.8.0: questo parametro è deprecato nella versione 26.8.0 e verrà rimosso nella versione 27.1. Utilizzare invece content.

• Restituzioni: numero di record aggiornati (0 o 1). Un valore restituito pari a 0 indica che nessun record è stato aggiornato.
• Tipo restituito: int.
• Aumenti: ValueError: se record_type non è supportato, se non viene fornito alcun payload di aggiornamento o se gli argomenti di aggiornamento semantico sono incompatibili.

Esempi

store.add(["Original note"], record_type="memory", record_ids="mem-update-docs")
['mem-update-docs']
store.update("memory", "mem-update-docs", content="Updated note")
1
store.get("memory", "mem-update-docs").content
'Updated note'

metodo update_async (asincrono)

Aggiorna in modo asincrono il contenuto dei record memorizzati, incorporando dati, metadati, indicatore orario o scadenza.

• Parametri:
  • record_type str: tipo logico di record da aggiornare.
  • record_id str: identificativo del record da aggiornare.
  • content str | Mapping[str, object] | Sequence[MessageContent] | bytes | None: contenuto sostitutivo canonico. Per i record message, passare una stringa o una sequenza ordinata di parti di contenuto di testo e immagine; utilizzare "" per sostituire il messaggio con testo vuoto. Per i record simili alla memoria, le aree di memorizzazione possono accettare None per cancellare il testo memorizzato e lo stato semantico associato. Omettere l'argomento per non modificare il contenuto. Non fornire questo insieme a text.
  • index_text str | list[str] | None: payload semantico alternativo facoltativo utilizzato per ricalcolare o sostituire lo stato di ricerca memorizzato senza modificare il testo persistente. Una stringa può essere messa a chunking internamente dal negozio. Una lista di stringhe non vuote viene considerata come chunk di proprietà del chiamante e non deve essere divisa di nuovo. Alcune implementazioni possono anche persistere separatamente come testo di ricerca ibrida. Per un record image, questo campo sostituisce la descrizione dell'immagine persistente.
  • incorporamento list[float] | ndarray | list[list[float] | ndarray] | None: vettore di incorporamento precalcolato opzionale o elenco di vettori di incorporamento dei chunk. Se fornito, questo viene utilizzato direttamente e non viene effettuata alcuna chiamata di incorporamento. Più vettori richiedono liste di chunk index_text corrispondenti o righe di testo chunk memorizzate esistenti. Passare None per cancellare in modo esplicito l'incorporamento memorizzato quando l'area di memorizzazione lo supporta. I negozi con indicizzazione text-aware possono anche consentire aggiornamenti semantici senza incorporamento o incorporamento esplicito.
  • metadata dict[str, Any] | None: mapping dei metadati di sostituzione facoltativo. Passare None per cancellare i metadati quando l'area di memorizzazione li supporta. La sostituzione dell'immagine content richiede "image_mime_type" in questo mapping. L'area di memorizzazione utilizza questo campo per salvare l'immagine, ma non la restituisce come parte dei metadati del record.
  • timestamp str | None: nuovo indicatore orario facoltativo da salvare con il record. Rappresenta la data di creazione del record. Omettere questo argomento per non modificare l'indicatore orario memorizzato. Passare None per cancellare l'indicatore orario salvato e utilizzare l'ora di aggiunta del record al negozio quando il negozio lo supporta.
  • ttl_days int | None: aggiornamento della scadenza facoltativo in giorni. Omettere questo argomento insieme a ttl_anchor per conservare l'indicatore orario di scadenza corrente. Passare None per cancellare la scadenza.
  • ttl_anchor TimeToLiveAnchor: ancoraggio Time To Live opzionale per un aggiornamento della scadenza. Utilizzare TimeToLiveAnchor.CREATED_AT per l'ora di creazione del record o TimeToLiveAnchor.TIMESTAMP per la sostituzione timestamp fornita nello stesso aggiornamento oppure l'indicatore orario dell'evento memorizzato quando timestamp viene omesso. Se si specifica ttl_anchor senza ttl_days, viene utilizzata la durata Time To Live predefinita dell'area di memorizzazione o dello schema. Quando ttl_anchor viene omesso durante un aggiornamento, le implementazioni utilizzano TimeToLiveAnchor.CREATED_AT.
  • stato RecordStatus: stato del ciclo di vita di sostituzione facoltativo per i record. Ometterlo per mantenere lo stato corrente.

  • testo str | None –

    Alias non più valido per content. Passare None per cancellare in modo esplicito il testo memorizzato quando è supportato dall'area di memorizzazione. Non fornire questo insieme a content.

    Non più valido

    Deprecato dalla versione 26.8.0: questo parametro è deprecato nella versione 26.8.0 e verrà rimosso nella versione 27.1. Utilizzare invece content.

• Restituzioni: numero di record aggiornati (0 o 1). Un valore restituito pari a 0 indica che nessun record è stato aggiornato.
• Tipo restituito: int.
• Aumenti: ValueError: se il payload di aggiornamento non è valido per l'area di memorizzazione, ad esempio omettendo ogni campo facoltativo o fornendo argomenti semantici in conflitto.

metodo update_relations

Aggiorna i campi di relazione modificabili e ricalcola lo stato del ciclo di vita dell'endpoint.

I campi omessi rimangono invariati. Le etichette dei collegamenti di memoria incorporati conservano sempre l'etichetta inversa derivata.

• Parametri:
  • relation_ids str | list[str]: identificativo o identificativi delle relazioni da aggiornare.
  • relation_types str | list[str]: etichetta o etichette opzionali per la relazione diretta sostitutiva.
  • opposite_relation_types str | list[str]: etichetta inversa di sostituzione opzionale o etichette per tipi personalizzati.
  • timestamps str | None | list[str | None]: indicatori orari di sostituzione facoltativi. Passare None per cancellare uno.
  • metadata dict[str, Any] | None | list[dict[str, Any] | None]: metadati di sostituzione facoltativi. Sostituisce i metadati esistenti.
• Restituzioni: identificativi delle relazioni aggiornate.
• Tipo restituito: list[str]

Esempi

store.update_relations("relation-id", relation_types="supports")
['relation-id']

metodo update_relations_async (asincrono)

Aggiorna in modo asincrono valori modificabili nelle relazioni memorizzate.

I campi omessi rimangono invariati, ad eccezione del fatto che la modifica a un tipo di relazione di memoria incorporata sostituisce l'etichetta inversa con l'inversa fissa. Un'area di memorizzazione di memoria supportata dal database ricalcola anche gli stati del ciclo di vita degli endpoint dopo una modifica del tipo di relazione.

• Parametri:
  • relation_ids str | list[str]: identificativo o identificativi delle relazioni da aggiornare.
  • relation_types str | list[str]: etichetta o etichette opzionali per la relazione diretta sostitutiva. Omettere questa opzione per conservare le etichette memorizzate.
  • opposite_relation_types str | list[str]: etichetta o etichette di relazione inversa sostitutiva opzionale. Passare un'etichetta per sostituirla o omettere questo argomento per conservarla.
  • timestamps str | None | list[str | None]: indicatore orario o indicatori orari di sostituzione facoltativi. Passare None per cancellare un indicatore orario memorizzato.
  • metadata dict[str, Any] | None | list[dict[str, Any] | None]: oggetto o oggetti metadati di sostituzione facoltativi. I metadati forniti sostituiscono l'oggetto memorizzato e non vengono uniti.
• Restituzioni: identificativi delle relazioni aggiornate.
• Tipo restituito: list[str]

Esempi

await store.update_relations_async(
    "relation-id", relation_types="supports"
)
['relation-id']

Relazioni

OracleDBMemoryStore può memorizzare le relazioni dirette tra record simili alla memoria (memory, fact, guideline e preference). Utilizzare add_relations(), get_relation(), list_relations(), update_relations() e delete_relations() quando un'integrazione richiede l'API di relazione di livello inferiore. Le API client e thread forniscono link_records(), update_record_link() e delete_record_link() per i tipi di relazione di memoria supportati.

Per recuperare una relazione, fornire relation_id da solo o la tupla dell'endpoint completamente memorizzata: ID e tipo del record di origine, ID e tipo del record di destinazione e tipo di relazione. Una tupla parziale e un ID relazione combinati con qualsiasi campo tupla non sono validi perché nessuno dei due identifica in modo univoco la relazione richiesta.

Utilizzare list_relations() per enumerare le relazioni nell'ordine di creazione. Filtra per ID e tipo di record di origine o di destinazione o per etichetta di relazione diretta. Utilizza il normale limite di safe list del negozio a meno che non si superi limit=None. Il suo metadata_filter utilizza la stessa semantica di corrispondenza esatta, oggetto nidificato, array-membership e negazione di list(); passare metadata_filter=None per restituire solo le relazioni senza metadati.

I tipi di relazione ciclo di vita, supersedes, refines e duplicates, contrassegnano la memoria di destinazione come non valida mentre il collegamento esiste. La rimozione o la modifica dell'ultimo collegamento consente di ripristinare lo stato valido della destinazione. Le API di ricerca possono escludere record non validi con include_invalid_results=False.

classe oracleagentmemory.apis.relations.RecordRelation

Basi: object

Descrivere una relazione memorizzata e diretta tra due record.

• Parametri:
  • id str: identificativo stabile della relazione.
  • source_record_id str: identificativo del record nell'origine memorizzata della relazione.
  • source_record_type str: tipo logico del record di origine.
  • target_record_id str: identificativo del record nella destinazione memorizzata della relazione.
  • target_record_type str: tipo logico del record di destinazione.
  • relation_type str: etichetta il cui significato segue la direzione source-to-target memorizzata.
  • opposite_relation_type str: etichetta utilizzata quando si esegue lo spostamento dalla destinazione all'origine.
  • timestamp str | None: indicatore orario del chiamante facoltativo associato alla relazione.
  • metadati dict[str, Any] | None: metadati facoltativi simili a JSON memorizzati con la relazione.
  • created_at str: indicatore orario di creazione del database per la relazione.

Strategia di ricerca

classe oracleagentmemory.core.dbsearch.SearchStrategy

Basi: Enum

Funzionamento della ricerca per le aree di memorizzazione di Oracle DB.

L'inizializzazione dell'area di memorizzazione DB utilizza la strategia selezionata per scegliere la funzionalità di ricerca dello schema gestito. La ricerca VECTOR memorizza gli incorporamenti locali. La ricerca KEYWORD memorizza il testo ricercabile e un indice di testo. HYBRID memorizza il testo ricercabile più lo stato dell'indice vettoriale ibrido gestito da Oracle. L'area di memorizzazione DB convalida questa funzionalità di schema all'avvio in modo che una strategia incompatibile non restituisca in silenzio risultati incompleti.

VECTOR

Cerca solo per somiglianza vettoriale. L'area di memorizzazione incorpora la query con l'incorporatore configurato oppure utilizza un query_vector fornito dal chiamante e classifica i record in base alla distanza dai vettori memorizzati. Utilizzare questa opzione con uno schema DB configurato per la ricerca vettoriale.

HYBRID

Cerca con l'indice ibrido gestito di Oracle. Oracle combina la corrispondenza di testo rispetto al testo di ricerca memorizzato con la classificazione vettoriale dell'indice ibrido nel database. Utilizzare questa opzione quando gli utenti possono eseguire ricerche in base al linguaggio naturale, nonché agli identificatori esatti, agli alias o ai nomi dei prodotti. Questa strategia richiede che l'embedder principale dell'area di memorizzazione sia un OracleDBEmbedder in modo che l'indice gestito e l'area di memorizzazione condividano un modello nel database.

KEYWORD

Cerca solo per parola chiave/testo corrispondente rispetto al testo di ricerca memorizzato. Questa modalità non crea incorporamenti di query locali e non richiede un incorporamento di Oracle DB. Se aperto rispetto a uno schema ibrido esistente, può utilizzare il ramo di testo di tale indice ibrido senza creare un nuovo indice ibrido. Utilizzare questa opzione quando identificatori esatti, alias, nomi di prodotti o frasi brevi devono guidare il recupero senza fusione vettoriale.

IBRIDO = "ibrido"

KEYWORD = parola chiave

VECTOR = 'vettore'

Modalità di sincronizzazione indice di ricerca

classe oracleagentmemory.core.dbsearch.SearchIndexSyncMode

Basi: Enum

Funzionamento di aggiornamento per gli indici di ricerca DB gestiti.

Questa impostazione controlla quando Oracle rende visibile il testo di ricerca nuovo o modificato per la ricerca basata sul testo supportata dal database. SearchStrategy.HYBRID utilizza l'indice vettoriale ibrido gestito di Oracle. SearchStrategy.KEYWORD utilizza un indice Oracle Text. SearchStrategy.VECTOR non utilizza questa impostazione.

ON_COMMIT

Aggiornare l'indice quando viene eseguito il commit della transazione di scrittura. Questa è la scelta predefinita e più semplice per la maggior parte delle applicazioni perché i record possono essere cercati immediatamente dopo una scrittura riuscita. Può aggiungere lavoro per scrivere transazioni perché l'indice viene mantenuto aggiornato immediatamente.

MANUAL

Non aggiornare l'indice automaticamente. È possibile che i record nuovi o aggiornati non vengano visualizzati nella ricerca per parola chiave o ibrida finché non si esegue l'operazione di sincronizzazione dell'indice lato database. Ciò è utile per i caricamenti di massa o le finestre di manutenzione in cui si desidera controllare quando vengono eseguiti i lavori di aggiornamento.

AUTO

Consenti a Oracle di aggiornare l'indice ibrido gestito in modo asincrono. Le scritture possono evitare il costo di aggiornamento immediato, ma i risultati della ricerca potrebbero rimanere in ritardo rispetto alle scritture recenti fino al completamento dell'aggiornamento in background da parte di Oracle. Questa modalità è supportata solo con SearchStrategy.HYBRID.

Avvertenza: questa impostazione controlla la manutenzione continua dopo l'esistenza dell'indice di ricerca gestito. Non rende la prima build dell'indice asincrona. La creazione di un indice ibrido gestito sul testo di ricerca memorizzata esistente può essere a esecuzione prolungata perché Oracle crea lo stato dell'indice ibrido gestito da tale testo.

AUTO = 'AUTO'

MANUAL = 'manuale'

ON_COMMIT = 'ON_COMMIT'

Time To Live

classe oracleagentmemory.core.retention.MemoryRetentionConfig

Basi: object

Impostazioni di conservazione a livello di schema per i record supportati da Oracle DB.

• Parametri:
  • default_ttl_days int | None: durata Time To Live predefinita, in giorni. Lasciare il valore NOT_SET_MARKER per utilizzare il valore predefinito None (nessun valore massimo).
  • max_ttl_days int | None: durata massima opzionale del tempo reale, in giorni. Lasciare il segno NOT_SET_MARKER per utilizzare il valore predefinito None. Passare None per nessun massimo. Quando è impostato, questo è un hard cap: le scritture che tentano di utilizzare un valore ttl_days più grande vengono bloccate a questo massimo con un avviso e le API di scrittura che passano ttl_days=None utilizzano questo massimo invece di creare record non in scadenza.

classe oracleagentmemory.apis.ttl.TimeToLiveAnchor

Basi: Enum

Ancoraggio utilizzato per calcolare un indicatore orario di scadenza da una durata Time To Live.

CREATED_AT

Scadenza del calcolo dall'indicatore orario di creazione del database del record. Questa è l'impostazione predefinita quando i chiamanti omettono ttl_anchor.

TIMESTAMP

Calcola la scadenza dall'indicatore orario dell'evento memorizzato del record. Utilizzare questa opzione quando un messaggio o una memoria rappresenta un evento meno recente e deve scadere in relazione all'ora dell'evento anziché all'ora di inserimento.

CREATED_AT = 'CREATED_AT'

TIMESTAMP = 'Indicatore orario'

Criterio schema

classe oracleagentmemory.core.SchemaPolicy

Basi: str, Enum

Criterio di creazione schema per le aree di memorizzazione di Oracle DB.

RICHIEDI_ESISTENTE

Verificare che lo schema gestito completo esista già e sia aggiornato. Non creare o modificare oggetti DB.

CREA_SE_EMPTY

Se non esistono oggetti gestiti, lo schema di bootstrap. Se gli oggetti esistono già, è necessario uno schema gestito completo e aggiornato.

CREA_SE_NECESSARIO

Creare gli oggetti gestiti mancanti e applicare gli aggiornamenti dello schema gestito supportati.

RICREA

Eliminare e ricreare tutti gli oggetti schema gestiti. Questo è distruttivo.

NESSUN_CONTROLLO

Salta la convalida e la creazione dello schema gestito. Utilizzare questo criterio per un'area di memorizzazione protetta da Deep Data Security esistente mentre è attivo un contesto di sicurezza dell'utente finale. Un negozio aperto in un contesto utente finale richiede un contesto attivo per ogni operazione di database successiva. Altri criteri dello schema rifiutano i contesti dell'utente finale perché il lavoro del ciclo di vita dello schema deve essere eseguito tramite un'identità del database amministrativo.