Stores and Schema

This page presents the core store abstractions and schema controls used by the Oracle Agent Memory SDK.

Store API

class oracleagentmemory.core.OracleMemoryStore

Bases: IMemoryStore

Common store interface used by OracleAgentMemory.

A store implementation is responsible for persisting text records and performing similarity search over them. Both synchronous and asynchronous entry points are defined so higher-level APIs can expose matching sync/async surfaces without duplicating store-specific logic.

method add

Add records to the store.

• Parameters:
  • contents list[str | None] – Record payloads to persist. Text values are also used for embedding unless index_texts or embeddings are provided. When a text value is None, implementations may fall back to metadata["content"]. Explicit empty strings are preserved.
  • record_type str – Logical record type to create, for example "message", "memory", "guideline", "fact", "preference", "user_profile", or "agent_profile".
  • index_texts list[str] – Optional alternative payloads used only for embedding/indexing. When provided, must align with the text inputs.
  • embeddings list[list[float]] | list[ndarray] – Optional precomputed embedding vectors aligned with the text inputs. When provided, the store must use these vectors directly instead of invoking its embedder. If not provided, the store must have an embedder attached, otherwise an error will be raised.
  • record_ids str | None | list[str | None] – Optional caller-visible identifiers. A single string may be used for one-record inserts, while lists must align with the text inputs. Generated identifiers are returned when this field is omitted.
  • thread_ids str | None | list[str | None] – Optional thread identifiers associated with the inserted records. Scalar values may be broadcast across aligned text inputs.
  • user_ids str | None | list[str | None] – Optional user identifiers associated with the inserted records. Scalar values may be broadcast across aligned text inputs.
  • agent_ids str | None | list[str | None] – Optional agent identifiers associated with the inserted records. Scalar values may be broadcast across aligned text inputs.
  • roles str | None | list[str | None] – Optional message roles such as "user" or "assistant". Scalar values may be broadcast across aligned text inputs. Used only if record_type is "message".
  • timestamps str | None | list[str | None] – Optional event timestamps to persist with the records. Scalar values may be broadcast across aligned text inputs.
  • metadata dict[str, Any] | list[dict[str, Any] | None] | None – Optional caller-provided metadata dictionaries. Metadata may include "content" as fallback source when a text value is omitted rather than explicitly set to "".
  • **store_kwargs (Any) – Implementation-specific write options forwarded to the concrete store.
• Return type: list[str]

Notes

Use add_batches() when the caller already has one or more PendingRecordBatch objects.

• Returns: Identifiers for the inserted records, in the same logical order as the input.
• Return type: List[str]
• Parameters:
  • contents list[str | None]
  • record_type str
  • index_texts list[str]
  • embeddings list[list[float]] | list[ndarray]
  • record_ids str | None | list[str | None]
  • thread_ids str | None | list[str | None]
  • user_ids str | None | list[str | None]
  • agent_ids str | None | list[str | None]
  • roles str | None | list[str | None]
  • timestamps str | None | list[str | None]
  • metadata dict[str, Any] | list[dict[str, Any] | None] | None
  • store_kwargs Any

method add_agent (abstract)

Add an agent profile record.

• Parameters:
  • agent_id str – Stable identifier for the agent profile.
  • information str – Free-form text describing the agent.
• Returns: Identifier of the created agent profile record.
• Return type: str

method add_async (async)

Asynchronously add row-oriented records to the store.

Accepts the same arguments and returns the same identifiers as add().

• Parameters:
  • contents list[str | None]
  • record_type str
  • index_texts list[str]
  • embeddings list[list[float]] | list[ndarray]
  • record_ids str | None | list[str | None]
  • thread_ids str | None | list[str | None]
  • user_ids str | None | list[str | None]
  • agent_ids str | None | list[str | None]
  • roles str | None | list[str | None]
  • timestamps str | None | list[str | None]
  • metadata dict[str, Any] | list[dict[str, Any] | None] | None
  • store_kwargs Any
• Return type: list[str]

method add_batches

Add caller-prepared logical batches to the store.

• Parameters:
  • batches list[PendingRecordBatch] – Fully prepared logical batches to persist. Each batch should carry its own per-record fields such as record_type, scope values, roles, timestamps, and metadata.
  • **store_kwargs (Any) – Implementation-specific write options forwarded to the concrete store.
• Returns: Identifiers for the inserted records, in the same logical order as the input batches and rows.
• Return type: List[str]

Examples

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

method add_batches_async (async)

Asynchronously add caller-prepared logical batches to the store.

Accepts the same arguments and returns the same identifiers as add_batches().

• Parameters:
  • batches list[PendingRecordBatch]
  • store_kwargs Any
• Return type: list[str]

method add_user (abstract)

Add a user profile record.

• Parameters:
  • user_id str – Stable identifier for the user profile.
  • information str – Free-form text describing the user.
• Returns: Identifier of the created user profile record.
• Return type: str

method delete (abstract)

Delete one stored record by identifier.

• Parameters:
  • record_type str – Logical type of the record to remove.
  • record_id str – Identifier of the record to remove.
  • cascade bool – When True, apply any store-supported cascading delete behavior for the requested top-level targets inside the same delete operation. This is primarily used for targets such as actor profiles that own additional scoped records. For example, a user-profile or agent-profile cascade may delete owned threads themselves, the thread-scoped messages and memory-like records removed with those threads, and any remaining directly actor-scoped records such as messages, memories, guidelines, facts, or preferences. For actor-profile deletes, this scoped cleanup may still run when the matching profile row is already absent.
• Returns: Number of requested top-level records deleted, typically 0 or 1. Cascaded child rows are not counted separately, so this may still be 0 when a missing actor profile triggers scoped cleanup.
• Return type: int

method delete_thread (abstract)

Delete a thread and its associated stored data.

• Parameters: thread_id str – Identifier of the thread to remove.
• Returns: Number of deleted thread records, typically 0 or 1.
• Return type: int

Notes

This is the store-level operation for removing a thread and the thread-scoped records managed by the store. Prefer thread deletion when retention requirements call for deleting both source messages and derived thread-scoped memory data, because message-level deletes do not imply that separately persisted derived records are removed.

method get (abstract)

Retrieve one stored record by type and identifier.

• Parameters:
  • record_type str – Logical type of the record to retrieve.
  • record_id str – Identifier of the record to retrieve.
• Returns: The stored record when found, otherwise None.
• Return type: Record | None

method list (abstract)

List stored records for one record type.

• Parameters:
  • record_type str – Logical record type to enumerate.
  • limit int | None – Optional maximum number of most-recent records to return. When omitted, implementations may apply a safe upper bound such as MAX_LIST_LIMIT. Pass None to disable that cap and return every matching record.
  • thread_id str | None – Exact thread-scope filter. When omitted, no filtering is applied. When set to None, only records whose thread_id is None are returned. Unscoped record types ignore this filter.
  • user_id str | None – Exact user-scope filter. When omitted, no filtering is applied. When set to None, only records whose user_id is None are returned. Unscoped record types ignore this filter.
  • agent_id str | None – Exact agent-scope filter. When omitted, no filtering is applied. When set to None, only records whose agent_id is None are returned. Unscoped record types ignore this filter.
• Returns: Records ordered from oldest to newest within the returned window.
• Return type: List[Record]

method list_thread_messages (abstract)

List the message history stored for one thread.

• Parameters:
  • thread_id str – Identifier of the thread whose messages should be returned.
  • last_n int | None – Optional number of most-recent messages to include. When omitted, all stored messages for the thread are returned.
• Returns: Message records ordered from oldest to newest within the returned window.
• Return type: List[MessageRecord]

method search (abstract)

Search records by similarity.

• Parameters:
  • query str | None – Natural language query. Must be provided when query_vector is omitted.
  • query_vector list[float] | None – Optional precomputed query embedding. Exactly one of query and query_vector must be provided.
  • k int – Maximum number of results to return. Explicit values must be at least 1.
  • thread_id str | None – Optional thread scope.
  • user_id str | None – Optional user and agent scope filters.
  • agent_id str | None – Optional user and agent scope filters.
  • exact_user_match bool – Whether each provided scope identifier must be matched exactly.
  • exact_agent_match bool – Whether each provided scope identifier must be matched exactly.
  • exact_thread_match bool – Whether each provided scope identifier must be matched exactly.
  • record_types set[str] | None – Optional set of record types to include.
  • metadata_filter dict[str, Any] | None – Optional partial metadata mapping. A record matches only when its stored metadata contains all requested keys and values. Nested dictionaries are matched recursively. List values are matched by exact equality rather than recursive subset matching, so list order and length must also match.
• Returns: (record, distance) pairs sorted by increasing distance.
• Return type: list[tuple[Record, float]]
• Raises: ValueError – If k is less than 1.

Examples

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'

Filter on a scalar metadata value:

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

Filter on nested metadata:

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

Match a list value exactly, including order:

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

method search_async (async)

Asynchronously search records by vector similarity.

• Parameters:
  • query str | None – Same query text accepted by search.
  • k int – Same maximum result count accepted by search. Explicit values must be at least 1.
  • query_vector list[float] | None – Same optional precomputed query embedding accepted by search.
  • thread_id str | None – Same optional scope filters accepted by search.
  • user_id str | None – Same optional scope filters accepted by search.
  • agent_id str | None – Same optional scope filters accepted by search.
  • exact_user_match bool – Same exact-match flags accepted by search.
  • exact_agent_match bool – Same exact-match flags accepted by search.
  • exact_thread_match bool – Same exact-match flags accepted by search.
  • record_types set[str] | None – Same optional record-type filter accepted by search.
• Returns: (record, distance) pairs returned by the underlying search call.
• Return type: List[tuple[Record, float]]
• Raises: ValueError – If k is less than 1.

method update (abstract)

Update stored record content, embedding data, or metadata.

• Parameters:
  • record_type str – Logical type of the record to update.
  • record_id str – Identifier of the record to update.
  • text str | None – Optional replacement content. Pass None to explicitly clear the stored text when the store supports it. Stores may also clear the associated semantic state and reject conflicting non-null index_text or embedding updates in the same call. Omit the argument to leave content unchanged.
  • index_text str | None – Optional embedding-only payload used to recompute the stored vector without changing the persisted text.
  • embedding list[float] | ndarray | None – Optional precomputed embedding vector. When provided, this is used directly and no embedder call is made. Pass None to explicitly clear the stored embedding when the store supports it.
  • metadata dict[str, Any] | None – Optional replacement metadata mapping. Pass None to clear metadata when the store supports it.
• Returns: Number of updated records, typically 0 or 1. Returns 0 when no stored record matches the requested logical identifier.
• Return type: int
• Raises: ValueError – If the update payload is invalid for the store, such as omitting every optional field or providing conflicting semantic arguments.

Oracle DB Store

class oracleagentmemory.core.OracleDBMemoryStore

Bases: OracleMemoryStore

Database-backed persistence for messages, memories, and actor profiles.

Create an Oracle DB store.

• Parameters:
  • embedder IEmbedder | None – Embedder used for vectorized record types. May be None when callers always provide precomputed vectors in add, update, and search.
  • pool Any – Oracle DB connection or pool. Passing a raw connection enables single-session mode for this store instance: concurrent store calls are serialized locally to preserve the row-lock and transaction assumptions used by write operations. Use a connection pool for concurrent requests.
  • schema_policy SchemaPolicy | str – Schema setup mode. Defaults to requiring an existing, up-to-date managed schema and performing no DDL changes. Use SchemaPolicy.CREATE_IF_NECESSARY to fill missing objects, or SchemaPolicy.RECREATE to drop and recreate managed objects.
  • vector_dim int – Embedding dimension for schema creation when VECTOR columns are created.
  • table_name_prefix str – Optional prefix added to managed table/index names.

method add

Add records to the store.

• Parameters:
  • contents list[str | None] – Record payloads to persist. Text values are also used for embedding unless index_texts or embeddings are provided. When a text value is None, implementations may fall back to metadata["content"]. Explicit empty strings are preserved.
  • record_type str – Logical record type to create, for example "message", "memory", "guideline", "fact", "preference", "user_profile", or "agent_profile".
  • index_texts list[str] – Optional alternative payloads used only for embedding/indexing. When provided, must align with the text inputs.
  • embeddings list[list[float]] | list[ndarray] – Optional precomputed embedding vectors aligned with the text inputs. When provided, the store must use these vectors directly instead of invoking its embedder. If not provided, the store must have an embedder attached, otherwise an error will be raised.
  • record_ids str | None | list[str | None] – Optional caller-visible identifiers. A single string may be used for one-record inserts, while lists must align with the text inputs. Generated identifiers are returned when this field is omitted.
  • thread_ids str | None | list[str | None] – Optional thread identifiers associated with the inserted records. Scalar values may be broadcast across aligned text inputs.
  • user_ids str | None | list[str | None] – Optional user identifiers associated with the inserted records. Scalar values may be broadcast across aligned text inputs.
  • agent_ids str | None | list[str | None] – Optional agent identifiers associated with the inserted records. Scalar values may be broadcast across aligned text inputs.
  • roles str | None | list[str | None] – Optional message roles such as "user" or "assistant". Scalar values may be broadcast across aligned text inputs. Used only if record_type is "message".
  • timestamps str | None | list[str | None] – Optional event timestamps to persist with the records. Scalar values may be broadcast across aligned text inputs.
  • metadata dict[str, Any] | list[dict[str, Any] | None] | None – Optional caller-provided metadata dictionaries. Metadata may include "content" as fallback source when a text value is omitted rather than explicitly set to "".
  • **store_kwargs (Any) – Implementation-specific write options forwarded to the concrete store.
• Return type: list[str]

Notes

Use add_batches() when the caller already has one or more PendingRecordBatch objects.

• Returns: Identifiers for the inserted records, in the same logical order as the input.
• Return type: List[str]
• Parameters:
  • contents list[str | None]
  • record_type str
  • index_texts list[str]
  • embeddings list[list[float]] | list[ndarray]
  • record_ids str | None | list[str | None]
  • thread_ids str | None | list[str | None]
  • user_ids str | None | list[str | None]
  • agent_ids str | None | list[str | None]
  • roles str | None | list[str | None]
  • timestamps str | None | list[str | None]
  • metadata dict[str, Any] | list[dict[str, Any] | None] | None
  • store_kwargs Any

method add_async (async)

Asynchronously add row-oriented records to the store.

Accepts the same arguments and returns the same identifiers as add().

• Parameters:
  • contents list[str | None]
  • record_type str
  • index_texts list[str]
  • embeddings list[list[float]] | list[ndarray]
  • record_ids str | None | list[str | None]
  • thread_ids str | None | list[str | None]
  • user_ids str | None | list[str | None]
  • agent_ids str | None | list[str | None]
  • roles str | None | list[str | None]
  • timestamps str | None | list[str | None]
  • metadata dict[str, Any] | list[dict[str, Any] | None] | None
  • store_kwargs Any
• Return type: list[str]

method add_batches

Add caller-prepared logical batches to the store.

• Parameters:
  • batches list[PendingRecordBatch] – Fully prepared logical batches to persist. Each batch should carry its own per-record fields such as record_type, scope values, roles, timestamps, and metadata.
  • **store_kwargs (Any) – Implementation-specific write options forwarded to the concrete store.
• Returns: Identifiers for the inserted records, in the same logical order as the input batches and rows.
• Return type: List[str]

Examples

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

method add_batches_async (async)

Asynchronously add caller-prepared logical batches to the store.

Accepts the same arguments and returns the same identifiers as add_batches().

• Parameters:
  • batches list[PendingRecordBatch]
  • store_kwargs Any
• Return type: list[str]

method add_agent

Add an agent profile record.

• Parameters:
  • agent_id str – Agent identifier.
  • information str – Free-form information about the agent. This text is stored as the profile content and used to build the profile embedding row in RECORD_CHUNKS.
• Returns: Identifier of the inserted agent profile record.
• Return type: str

Notes

Agent profile records are unscoped. The inserted public record identifier is the same value passed as agent_id.

Examples

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

method add_user

Add a user profile record.

• Parameters:
  • user_id str – User identifier.
  • information str – Free-form information about the user. This text is stored as the profile content and used to build the profile embedding row in RECORD_CHUNKS.
• Returns: Identifier of the inserted user profile record.
• Return type: str

Notes

User profile records are unscoped. The inserted public record identifier is the same value passed as user_id.

Examples

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

method delete

Delete one managed row and its chunk rows by identifier.

• Parameters:
  • record_type str – Record type label to delete. Supported types include "thread", "message", "memory", "guideline", "fact", "preference", "user_profile", and "agent_profile".
  • record_id str – Identifier to delete.
  • cascade bool – When True, expand supported top-level targets such as actor profiles to their scoped child rows inside the same transaction. For a user-profile or agent-profile target, this deletes the owned thread rows first, which removes their thread-scoped message and memory-table rows, then deletes any remaining directly actor-scoped messages and memory-like rows (memory, guideline, fact, preference). This scoped cleanup still runs when the matching profile row is already absent.
• Returns: Number of requested top-level targets removed, typically 0 or 1. Cascaded child rows are not counted separately, so this may still be 0 when a missing actor profile triggers scoped cleanup.
• Return type: int

Notes

The operation runs inside one transaction. When cascade is enabled for a supported top-level target, the profile delete and all scoped child deletes are committed or rolled back together.

Examples

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

method delete_thread

Delete a thread and its associated stored rows.

• Parameters: thread_id str – Thread identifier whose rows should be removed, including the thread row, dependent child rows, and explicit chunk-row cleanup.
• Returns: Number of deleted thread rows (0 or 1).
• Return type: int

Notes

Use this operation when you need thread-scoped cascading cleanup. In the DB-backed store, deleting the thread removes the managed thread row together with associated message and memory rows, plus the record-chunk rows maintained for retrieval. This is broader than a message-level delete, which removes only the raw message row. Thread deletion removes the dependent message and memory rows referenced from THREAD together with the matching RECORD_CHUNKS rows in the same transaction.

Examples

store.delete_thread("c1")
0

method get

Retrieve a stored record by identifier.

• Parameters:
  • record_type str – Record type label resolving to a managed row, such as "message", "memory", "guideline", "fact", "preference", "user_profile", or "agent_profile".
  • record_id str – Identifier to look up.
• Returns: Populated record with decoded metadata when found, otherwise None.
• Return type: Record | None

Examples

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'

method list

Enumerate persisted records for a record type.

• Parameters:
  • record_type str – Record type label (e.g. "message", "memory", "guideline", "fact", "preference", "user_profile", or "agent_profile").
  • limit int | None – Optional maximum number of records to return. When omitted, the store uses its default listing cap. Pass None to disable that cap and return every matching record.
  • thread_id str | None – Exact thread-scope filter. When omitted, no filtering is applied. When set to None, only rows whose thread_id is SQL NULL are returned. Unscoped record types ignore this filter.
  • user_id str | None – Exact user-scope filter. When omitted, no filtering is applied. When set to None, only rows whose user_id is SQL NULL are returned. Unscoped record types ignore this filter.
  • agent_id str | None – Exact agent-scope filter. When omitted, no filtering is applied. When set to None, only rows whose agent_id is SQL NULL are returned. Unscoped record types ignore this filter.
  • metadata_filter dict[str, Any] | None – Metadata filter. When omitted, no filtering is applied. When set to None, only records with no stored metadata are returned. When set to a dict, stored metadata must contain all requested keys and values. Nested dictionaries are matched recursively. List values are matched by exact equality rather than recursive subset matching, so list order and length must also match.
• Returns: Records ordered by insertion order.
• Return type: list[Record]

Notes

"user_profile" and "agent_profile" are unscoped record types. For those record types, thread_id, user_id, and agent_id are ignored and actor identity remains in record.id.

Examples

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

method list_thread_messages

Return persisted messages for a thread.

• Parameters:
  • thread_id str – Thread identifier whose messages should be returned.
  • last_n int | None – Optional number of most-recent messages to return.
• Returns: Message records ordered by insertion order.
• Return type: list[MessageRecord]

Examples

store.list_thread_messages("c1")
[]

method search

Search records by similarity.

• Parameters:
  • query str | None – Natural language query. Must be provided when query_vector is omitted.
  • query_vector list[float] | None – Optional precomputed query embedding. Exactly one of query and query_vector must be provided.
  • k int – Maximum number of results to return. Explicit values must be at least 1.
  • thread_id str | None – Optional thread-scope identifier. exact_thread_match=False leaves the thread dimension unconstrained. exact_thread_match=True matches the provided thread_id exactly. If thread_id=None, it matches only records unscoped on the thread dimension.
  • user_id str | None – Optional user and agent scope identifiers. The corresponding exact_*_match=False flag leaves that dimension unconstrained. exact_*_match=True matches the provided ID exactly. If the ID is None, it matches only records unscoped on that dimension.
  • agent_id str | None – Optional user and agent scope identifiers. The corresponding exact_*_match=False flag leaves that dimension unconstrained. exact_*_match=True matches the provided ID exactly. If the ID is None, it matches only records unscoped on that dimension.
  • exact_user_match bool – Whether each scope identifier must be matched exactly. False leaves that dimension unconstrained. True matches the provided value exactly. If that value is None, it matches only unscoped records on that dimension.
  • exact_agent_match bool – Whether each scope identifier must be matched exactly. False leaves that dimension unconstrained. True matches the provided value exactly. If that value is None, it matches only unscoped records on that dimension.
  • exact_thread_match bool – Whether each scope identifier must be matched exactly. False leaves that dimension unconstrained. True matches the provided value exactly. If that value is None, it matches only unscoped records on that dimension.
  • record_types set[str] | None – Optional set of searchable record types to include. When omitted, the DB search covers messages, memory-table rows, and actor profiles. Actor profiles contribute their information payload, while message and memory rows contribute their content payload. During search, profile record types use their actor identifier for the applicable scope dimension while the remaining scope dimensions behave as None.
  • metadata_filter dict[str, Any] | None – Optional partial metadata mapping. A record matches only when its stored metadata contains all requested keys and values. Nested dictionaries are matched recursively. List values are matched by exact equality rather than recursive subset matching, so list order and length must also match.
• Returns: (record, distance) pairs sorted by increasing distance.
• Return type: list[tuple[Record, float]]
• Raises: ValueError – If k is less than 1.

Examples

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'

Filter on a scalar metadata value:

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

Filter on nested metadata:

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

Match a list value exactly, including order:

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

method search_async (async)

Asynchronously search records by vector similarity.

• Parameters:
  • query str | None – Same query text accepted by search.
  • k int – Same maximum result count accepted by search. Explicit values must be at least 1.
  • query_vector list[float] | None – Same optional precomputed query embedding accepted by search.
  • thread_id str | None – Same optional scope filters accepted by search.
  • user_id str | None – Same optional scope filters accepted by search.
  • agent_id str | None – Same optional scope filters accepted by search.
  • exact_user_match bool – Same exact-match flags accepted by search.
  • exact_agent_match bool – Same exact-match flags accepted by search.
  • exact_thread_match bool – Same exact-match flags accepted by search.
  • record_types set[str] | None – Same optional record-type filter accepted by search.
• Returns: (record, distance) pairs returned by the underlying search call.
• Return type: List[tuple[Record, float]]
• Raises: ValueError – If k is less than 1.

method update

Update stored record content, chunk embeddings, and metadata values.

• Parameters:
  • record_type str – Record type label of the row being modified (for example "message", "memory", "guideline", "fact", "preference", "user_profile", or "agent_profile")
  • record_id str – Identifier of the stored row to update.
  • text str | None – Optional replacement text persisted in the content column. Pass None to clear the stored text and clear the stored embedding. Pass only None or omitted semantic arguments in the same call. Pass "" to preserve explicit empty content while clearing any chunk embedding for that record. When omitted, the existing content is left unchanged.
  • index_text str | None – Optional embedding-only payload. When omitted, text is embedded.
  • embedding list[float] | ndarray | None – Optional precomputed embedding vector. When provided, this is used directly and no embedder call is made. Pass None to clear the stored embedding.
  • metadata dict[str, Any] | None – Optional metadata mapping serialized to JSON and stored in metadata.
• Returns: Number of updated rows (0 or 1). Returns 0 when no logical record matches record_type and record_id.
• Return type: int
• Raises: ValueError – If record_type is unsupported, if no update payload is provided, or if the semantic update arguments are incompatible.

Examples

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

Schema Policy

class oracleagentmemory.core.SchemaPolicy

Bases: str, Enum

Schema creation policy for Oracle DB stores.

REQUIRE_EXISTING

Validate that the full managed schema already exists and is up-to-date. Do not create or modify DB objects.

CREATE_IF_EMPTY

If no managed objects exist, bootstrap schema. If objects already exist, require a complete and up-to-date managed schema.

CREATE_IF_NECESSARY

Create only missing managed objects, including metadata.

RECREATE

Drop and recreate all managed schema objects. This is destructive.