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` (abstract)

Embed and persist text records.

Parameters:
- contents list[str | None] – Text payloads to store. These values are also used as embedding payloads when index_texts is not provided. When an item is omitted (None), stores resolve it from metadata key "content" when available; otherwise empty content is kept.
- record_type str – Record type label for stored records (for example "message" or "memory").
- index_texts list[str] – Optional embedding-only payloads aligned with contents.
- embeddings list[list[float]] | list[ndarray] – Optional precomputed embedding vectors aligned with contents. When provided, stores use these vectors directly and do not call the embedder.
- record_ids str | None | list[str] | list[None] – Optional caller-visible record IDs. Must be either fully provided (one per text) or omitted for all texts. Returned IDs match these values when provided.
- thread_ids str | None | list[str | None] – Optional scope identifiers stored with the records.
- user_ids str | None | list[str | None] – Optional scope identifiers stored with the records.
- agent_ids str | None | list[str | None] – Optional scope identifiers stored with the records.
- roles str | None | list[str | None] – Optional chat role for message records.
- timestamps str | None | list[str | None] – Optional timestamp or per-record timestamps.
- metadata dict[str, Any] | list[dict[str, Any] | None] | None – Optional metadata mapping or per-record metadata mappings. Metadata may include "content" as fallback source for omitted text values.
- **store_kwargs (Any) – Store-specific write options forwarded by higher-level APIs.
Returns: Insert identifiers for each input content item. These match record_ids when provided; otherwise stores generate identifiers.
Return type: list[str]

Examples

store.add(["Abstract memory"], record_type="memory", record_ids="mem-abstract-docs")
['mem-abstract-docs']

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

Oracle DB Store

class `oracleagentmemory.core.OracleDBMemoryStore`

Bases: OracleMemoryStore

Database-backed persistence for messages and typed memory records.

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 memory store.

Parameters:
- contents list[str | None] – Text payloads to store. These values are also used to compute embedding unless index_texts or embeddings are provided. When an item is omitted (None), stores resolve it from metadata key "content" when available; otherwise empty content is kept.
- record_type str – Record type label for stored records (for example "message", "memory", guideline, fact, or preference).
- index_texts list[str] – Optional alternative payloads used only for embedding/indexing. When provided, must have the same length as contents.
- embeddings list[list[float]] | list[ndarray] – Optional precomputed embedding vectors aligned with contents. When provided, stores must use these vectors directly and must not invoke the embedder. When omitted, the store uses the embedder only for non-empty indexing payloads; explicit empty strings are stored without chunk embeddings.
- record_ids str | None | list[str] | list[None] – Optional caller-visible record IDs. Must be either fully provided (one per text) or omitted for all texts. Returned IDs match these values when provided. When omitted, the store generates IDs client-side.
- thread_ids str | None | list[str | None] – Optional scope identifiers stored with the records.
- user_ids str | None | list[str | None] – Optional scope identifiers stored with the records.
- agent_ids str | None | list[str | None] – Optional scope identifiers stored with the records.
- roles str | None | list[str | None] – Optional chat role for message records.
- timestamps str | None | list[str | None] – Optional caller-provided event timestamps.
- metadata dict[str, Any] | list[dict[str, Any] | None] | None – Optional caller-provided metadata dictionaries. Metadata may include "content" as fallback source for omitted text values.
- **store_kwargs (Any) – Store-specific write options. Supported keys currently include batch_size for Oracle executemany batching.
Returns: Insert identifiers for each input content item. These match record_ids when provided; otherwise stores return generated IDs.
Return type: list[str]

Examples

store.add(
    ["Hello from docs"],
    record_type="message",
    record_ids="msg-docs-add",
    thread_ids="c-docs-add",
    roles="user",
)
['msg-docs-add']

method `add_agent`

Add an agent profile record.

Parameters:
- agent_id str – Agent identifier.
- information str – Free-form information about the agent.
Returns: Identifier of the inserted agent profile record.
Return type: str

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.
Returns: Identifier of the inserted user profile record.
Return type: str

Examples

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

method `delete`

Delete a managed vector-record row and its chunk rows by identifier.

Parameters:
- record_type str – Record type label whose managed table should be targeted, such as "message", "memory", "guideline", "fact", or "preference"
- record_id str – Identifier of the row to remove.
Returns: Number of rows removed (0 when the identifier was not found).
Return type: int

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 vector-record and chunk rows.

Parameters: thread_id str – Thread identifier whose rows should be removed (including cascade-deleted child rows).
Returns: Number of deleted thread rows (0 or 1).
Return type: int

Examples

store.delete_thread("c1")
0

method `get`

Retrieve a stored message or memory by identifier.

Parameters:
- record_type str – Record type label resolving to a managed vector-record row, such as "message", "memory", "guideline", "fact", or "preference".
- 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", or "preference").
- limit int – Maximum number of records to return.
- thread_id str | None – Exact thread-scope filter. When omitted, no filtering is applied. When set to None, only records unscoped on the thread dimension are returned.
- user_id str | None – Exact user-scope filter. When omitted, no filtering is applied. When set to None, only records unscoped on the user dimension are returned.
- agent_id str | None – Exact agent-scope filter. When omitted, no filtering is applied. When set to None, only records unscoped on the agent dimension are returned.
- 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]

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']

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 record types to include. When omitted, the search covers any record type.
- 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 `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, or preference)
- record_id str – Identifier of the message or memory 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.

Stores and Schema

Store API

class oracleagentmemory.core.OracleMemoryStore

method add (abstract)

method search (abstract)

Oracle DB Store

class oracleagentmemory.core.OracleDBMemoryStore

method add

method add_agent

method add_user

method delete

method delete_thread

method get

method list

method list_thread_messages

method search

method update

Schema Policy

class oracleagentmemory.core.SchemaPolicy

REQUIRE_EXISTING

CREATE_IF_EMPTY

CREATE_IF_NECESSARY

RECREATE

class `oracleagentmemory.core.OracleMemoryStore`

method `add` (abstract)

method `search` (abstract)

class `oracleagentmemory.core.OracleDBMemoryStore`

method `add`

method `add_agent`

method `add_user`

method `delete`

method `delete_thread`

method `get`

method `list`

method `list_thread_messages`

method `search`

method `update`

class `oracleagentmemory.core.SchemaPolicy`