Threads

This page presents the concrete Oracle thread handle together with the developer-facing message helper type.

Oracle Thread

class oracleagentmemory.core.OracleThread

Bases: IThread

Thread backed by an Oracle store.

This implementation embeds and stores both thread messages and manually added memories, then supports similarity search over all stored records.

Notes

• Messages are stored as individual records (one record per message).
• Search can be restricted to the current thread, or allowed to return results from any thread (client-controlled).

Create a new OracleThread instance.

• Parameters:
  • store OracleMemoryStore – Shared store backend used to persist embedded records.
  • thread_id str – Thread identifier. If not provided, a UUID is generated.
  • user_id str – User identifier associated with the thread. If omitted, a UUID is generated.
  • agent_id str – Agent identifier associated with the thread. If omitted, a UUID is generated.
  • metadata dict[str, Any] | None – Optional JSON-like metadata associated with the thread.
  • persist_messages_in_config bool – Whether _to_config should include recent raw message snapshots. Automatically set to False for threads using the DB store to avoid exporting message-table contents through thread config.
  • llm ILlm | None – Optional LLM adapter used for memory extraction and context summary updates. When provided, add_messages will extract relevant memories from each added message and store them as typed memory records ("memory", "guideline", "fact", or "preference").
  • memory_extraction_config MemoryExtractionConfig – Optional thread-level memory extraction configuration. Use it to control automatic extraction settings such as extraction mode, summary behavior, extraction limits, and whether automatic extraction is enabled at all. Pass either this grouped config or the deprecated inline extraction parameters, not both. When omitted, standalone OracleThread() uses SDK defaults for the extraction fields and keeps context summaries enabled.

  • memory_extraction_window int –

    Number of most recent messages (including the newly added one) to provide as context to the LLM during extraction. Set to -1 to extract only once per add_messages call using the full batch of newly added messages. Defaults to -1.

    Deprecated

    Deprecated since version 26.6.0: This parameter was deprecated in 26.6.0 and will be removed in 27.1. Please use memory_extraction_config instead.

  • context_summary_update_frequency int –

    Number of messages after which the extraction context summary should be updated. Set to -1 to summarize only once per add_messages call using the full batch of newly added messages. Defaults to -1.

    Info: Deprecated since version 26.6.0: This parameter was deprecated in 26.6.0 and will be removed in 27.1. Please use memory_extraction_config instead.

  • memory_extraction_frequency int –

    Number of messages after which the memory extraction is triggered. Set to -1 to extract only once per add_messages call using the full batch of newly added messages.

    Info: Deprecated since version 26.6.0: This parameter was deprecated in 26.6.0 and will be removed in 27.1. Please use memory_extraction_config instead.

  • memory_extraction_token_limit int –

    Maximum size, in tokens, of the LLM prompts used for memory extraction and running summary updates. Longer prompts are truncated. If negative or 0, prompt truncation is disabled.

    Info: Deprecated since version 26.6.0: This parameter was deprecated in 26.6.0 and will be removed in 27.1. Please use memory_extraction_config instead.

  • context_card_token_limit int – Maximum input token budget for the LLM prompt used to build the summary and topic list included in the context card. Defaults to 100_000; values less than or equal to 0 disable prompt truncation.
  • context_card_type_search_concurrency int – Maximum number of memory-like record searches to run concurrently when building a context card with min_relevant_results_by_type. Defaults to 5.
  • max_message_token_length int – Maximum size, in tokens, of the prompt-time copy of each message used during LLM-backed memory extraction and context-summary updates. Stored message content remains unchanged. If negative or 0, no prompt-time shortening is performed. If an LLM is provided, oversized prompt copies are summarized instead of truncated.
  • message_shortening_input_token_limit int – Maximum size, in tokens, of the message excerpt sent to the LLM when shortening oversized prompt copies. Defaults to 30_000 tokens. If negative or 0, no outbound bound is applied during LLM-based shortening.

  • enable_context_summary bool –

    Whether to keep a compact running summary of the thread. When enabled and an llm is provided, the summary is updated according to context_summary_update_frequency. The current summary is provided as context when extracting memories. Defaults to True for standalone OracleThread().

    Info: Deprecated since version 26.6.0: This parameter was deprecated in 26.6.0 and will be removed in 27.1. Please use memory_extraction_config instead.

  • memory_extraction_custom_instructions str | None –

    Optional custom instructions appended to the automatic memory extraction system prompt for this thread.

    Info: Deprecated since version 26.6.0: This parameter was deprecated in 26.6.0 and will be removed in 27.1. Please use memory_extraction_config instead.

  • memory_extraction_inherit_message_metadata bool | Sequence[str] –

    Whether automatically extracted memories inherit metadata from source messages. Pass True to inherit all message metadata, a non-string sequence of top-level message metadata keys to inherit only those keys, or False to disable inheritance. Defaults to True. If one extraction pass uses multiple source messages, the selected metadata must match across those messages.

    Info: Deprecated since version 26.6.0: This parameter was deprecated in 26.6.0 and will be removed in 27.1. Please use memory_extraction_config instead.

  • client OracleAgentMemory | None

Examples

from oracleagentmemory.core import OracleAgentMemory
import oracledb
db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="YOUR DB CONNECT STRING",
)
client = OracleAgentMemory(connection=db_pool, embedder=embedder)
thread = client.create_thread(
    thread_id="c1",
    llm=llm,
    memory_extraction_config=MemoryExtractionConfig(enable_context_summary=True),
)
len(thread.add_messages([{"role": "user", "content": "I love pizza."}]))
1

method add_memory

Add a manual memory entry and index it.

• Parameters:
  • content str – Text content to store as a memory.
  • memory_type Literal['memory', 'guideline', 'fact', 'preference'] | ~oracleagentmemory._notset._NotSetMarker – Memory category to store. Supported values are "memory", "fact", "guideline", and "preference". When omitted, the content is stored as a general "memory".
  • user_id str – Optional user identifier override.
  • agent_id str – Optional agent identifier override.
  • thread_id str – Optional thread identifier override.
  • memory_id str – Optional caller-provided stable identifier for this memory row.
  • metadata dict[str, Any] | None – Optional metadata to persist with the stored memory.
  • timestamp str | None – Optional timestamp to save for this memory. It represents when the memory was created. When omitted or None, the store uses the current time. When ttl_anchor is TimeToLiveAnchor.TIMESTAMP, provide a concrete ISO-8601 timestamp value. ISO-8601 timestamps without a timezone are treated as UTC.
  • ttl_days int | None – Optional time-to-live duration in days. Omit this argument to use the schema default time-to-live duration. Pass None to use MemoryRetentionConfig.max_ttl_days when the retention configuration sets one, or to store a non-expiring memory when it does not. Values above MemoryRetentionConfig.max_ttl_days are clamped to that maximum with a warning.
  • ttl_anchor TimeToLiveAnchor – Optional time-to-live anchor. Use TimeToLiveAnchor.CREATED_AT for the database creation time or TimeToLiveAnchor.TIMESTAMP for the memory timestamp. Timestamp-anchored expiration requires a concrete ISO-8601 timestamp for this memory. ISO-8601 timestamps without a timezone are treated as UTC.
  • **store_kwargs (Any) – Store-specific write options forwarded to the backing store.
• Returns: Identifier of the inserted memory record.
• Return type: str

Examples

thread.add_memory("Remember this preference", memory_id="mem-thread-docs")
'mem-thread-docs'

method add_memory_async (async)

Add a memory asynchronously.

• Parameters:
  • content str – Memory content to store.
  • memory_type Literal['memory', 'guideline', 'fact', 'preference'] | ~oracleagentmemory._notset._NotSetMarker – Memory category to store. Supported values are "memory", "fact", "guideline", and "preference". When omitted, the content is stored as a general "memory".
  • user_id str – Optional user scope override.
  • agent_id str – Optional agent scope override.
  • thread_id str – Optional thread scope override.
  • memory_id str – Optional caller-provided memory identifier. When omitted, stores generate an ID.
  • metadata dict[str, Any] | None – Optional metadata to persist with the stored memory.
  • timestamp str | None – Optional timestamp to save for this memory. It represents when the memory was created. When omitted or None, the store uses the current time.
  • ttl_days int | None – Optional time-to-live duration in days. Omit this argument to use the schema default time-to-live duration, or pass None for a memory that does not expire.
  • ttl_anchor TimeToLiveAnchor – Optional time-to-live anchor. Use TimeToLiveAnchor.CREATED_AT or TimeToLiveAnchor.TIMESTAMP.
  • **store_kwargs (Any) – Implementation-specific write options forwarded to the backing store.
• Return type: str

method add_messages

Add messages to the thread and index them.

In background extraction mode, this method returns after raw messages are inserted and due background extraction is attempted in the background.

• Parameters:
  • messages list[Message | MessageT] – List of messages to append. Messages can be Message objects or dictionaries with role and content (and optional id).
  • metadata dict[str, Any] | None | list[dict[str, Any] | None] – Optional shared or per-message metadata to persist. When omitted, metadata embedded in each message is used.
  • ttl_days int | None | list[int | None] – Optional time-to-live duration in days for appended messages. Omit this argument to use the schema default time-to-live duration. Pass None to use MemoryRetentionConfig.max_ttl_days when the retention configuration sets one, or to create non-expiring messages when it does not. Values above MemoryRetentionConfig.max_ttl_days are clamped to that maximum with a warning. Scalar values apply to the full batch.
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor] – Optional time-to-live anchor. Use TimeToLiveAnchor.CREATED_AT for database creation time or TimeToLiveAnchor.TIMESTAMP for each message timestamp. Timestamp-anchored expiration requires a concrete ISO-8601 timestamp for each affected message. When omitted, messages expire relative to TimeToLiveAnchor.CREATED_AT. ISO-8601 timestamps without a timezone are treated as UTC.
  • **store_kwargs (Any) – Store-specific write options forwarded to the backing store.
• Returns: Identifiers of inserted message records. In background extraction mode, automatic extraction work may still be running when these identifiers are returned.
• Return type: list[str]

Notes

In MemoryExtractionMode.BACKGROUND, raw messages are persisted before extracted memories are stored. If background extraction does not queue, or if a configured queue-capacity wait reaches its timeout, the inserted raw messages remain stored and the call either continues without extracted memories or raises TimeoutError, depending on background_extraction_queue_full_behavior.

Examples

len(thread.add_messages([{"role": "user", "content": "Thread message from docs"}]))
1

method add_messages_async (async)

Asynchronously add messages to the thread and index them.

In background extraction mode, this method returns after raw messages are inserted and due background extraction is attempted in the background.

In MemoryExtractionMode.BACKGROUND, raw messages are persisted before extracted memories are stored. If background extraction does not queue, or if a configured queue-capacity wait reaches its timeout, the inserted raw messages remain stored and the call either continues without extracted memories or raises TimeoutError, depending on background_extraction_queue_full_behavior.

• Parameters:
  • messages list[Message | MessageT]
  • metadata dict[str, Any] | None | list[dict[str, Any] | None]
  • ttl_days int | None | list[int | None]
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]
  • store_kwargs Any
• Return type: list[str]

method delete_memory

Delete a memory-like record (e.g., a memory, fact, preference, or guideline) from this exact thread by identifier.

• Parameters: memory_id str – Memory identifier. Only memory-like records (memory, guideline, fact, preference) whose stored thread_id exactly matches this thread are deleted.
• Returns: Number of deleted records (0 or 1). Returns 0 when the identifier does not exist or belongs to a different thread.
• Return type: int

Examples

thread.delete_memory("456")
0

method delete_message

Delete a message record from this exact thread by identifier.

• Parameters: message_id str – Message identifier. Only messages whose stored thread_id exactly matches this thread are deleted.
• Returns: Number of deleted message records (0 or 1). Returns 0 when the identifier does not exist or belongs to a different thread.
• Return type: int

Notes

Deleting a message removes only the raw message record. Derived memories are not deleted because we do not yet track which extracted memories came from which message, so they may remain searchable or still affect context-card output. Use OracleAgentMemory.delete_thread() to delete the thread together with its associated messages and memories.

Examples

thread.delete_message("123")
0

method get_context_card

Return a context-card object for the thread.

Prefer get_context_card_async when an LLM-backed implementation may perform remote network I/O.

• Parameters:
  • fallback_message_count int – Number of recent messages to use when deriving the fallback summary text for retrieval and rendering. When omitted, this resolves to 5.
  • max_relevant_results int – Maximum number of retrieved durable records to include. When omitted, this resolves to 5 unless min_relevant_results_by_type is provided; in that case it resolves to the larger of 5 and the sum of the requested per-type minimums.
  • max_recent_messages int – Maximum number of trailing raw messages to embed verbatim. When omitted, this resolves to 5.
  • min_relevant_results_by_type Mapping[Literal['memory', 'guideline', 'fact', 'preference'], int] | None | ~oracleagentmemory._notset._NotSetMarker – Optional per-type minimums for relevant memory-like records included in the context card. Requested types are searched first, and remaining max_relevant_results slots are filled from all supported memory-like record types. Supported keys are "memory", "fact", "guideline", and "preference".
  • **kwargs (Any) – Reserved for future context-card options. Unexpected keyword arguments raise TypeError.
• Returns: A context-card object containing a thread context summary based on the most recent messages. Use OracleContextCard.content to access the rendered XML-like text.
• Return type: OracleContextCard

Notes

This uses the thread’s default search scope with exact_thread_match=False, so relevant memories from other threads for the same user/agent may be included.

Examples

thread.add_memory("User likes pizza", memory_id="mem-context-docs")
'mem-context-docs'
len(thread.add_messages([{"role": "user", "content": "Tell me about pizza"}]))
1
"User likes pizza" in thread.get_context_card().content
True
card = thread.get_context_card(
    max_relevant_results=4,
    min_relevant_results_by_type={"memory": 1},
)
len(card.relevant_results or []) <= 4
True

method get_context_card_async (async)

Asynchronously return a context-card object for the thread.

• Parameters:
  • fallback_message_count int – Number of recent messages to use when deriving the fallback summary text for retrieval and rendering. When omitted, this resolves to 5.
  • max_relevant_results int – Maximum number of retrieved durable records to include. When omitted, this resolves to 5 unless min_relevant_results_by_type is provided; in that case it resolves to the larger of 5 and the sum of the requested per-type minimums.
  • max_recent_messages int – Maximum number of trailing raw messages to embed verbatim. When omitted, this resolves to 5.
  • min_relevant_results_by_type Mapping[Literal['memory', 'guideline', 'fact', 'preference'], int] | None | ~oracleagentmemory._notset._NotSetMarker – Optional per-type minimums for relevant memory-like records included in the context card. Requested types are searched first, and remaining max_relevant_results slots are filled from all supported memory-like record types. Supported keys are "memory", "fact", "guideline", and "preference".
  • **kwargs (Any) – Reserved for future context-card options. Unexpected keyword arguments raise TypeError.
• Returns: A context-card object for the thread.
• Return type: OracleContextCard

Examples

card = await thread.get_context_card_async(
    min_relevant_results_by_type={"preference": 1, "guideline": 1},
)
len(card.relevant_results or []) <= 5
True

method get_messages

Return stored messages for this thread.

• Parameters:
  • start int | None – Start index (0-based). When omitted together with end, the most recent bounded window is returned.
  • end int | None – End index (exclusive). When omitted, a bounded window of most recent messages is returned. Pass None or -1 to explicitly request all messages from start onward.
• Returns: Messages in chronological order.
• Return type: list[Message]

Examples

len(thread.add_messages([{"role": "user", "content": "Stored message example"}]))
1
messages = thread.get_messages()
messages[-1].content
'Stored message example'

method get_messages_async (async)

Return raw thread messages asynchronously.

• Parameters:
  • start int | None – Optional start index.
  • end int | None – Optional end index.
• Returns: Raw message objects.
• Return type: list[Message]

method get_summary

Return a best-effort summary of the thread.

Prefer get_summary_async when an LLM-backed implementation may perform remote network I/O.

• Parameters:
  • except_last int – Number of most recent messages to exclude from the summary.
  • token_budget int – Soft token budget. When omitted, a bounded default is applied. Positive values truncate only when the formatted summary exceeds the budget as estimated by _estimate_tokens(); the returned text is then capped to int(token_budget * 3.5) characters. Non-positive values disable the output bound.
  • **kwargs (Any) – Reserved for future summary options. Unexpected keyword arguments raise TypeError.
• Returns: Summary object containing the synthesized thread summary text.
• Return type: OracleSummary

Examples

len(thread.add_messages([{"role": "assistant", "content": "Summary source message"}]))
1
summary = thread.get_summary()
bool(summary.content)
True

method get_summary_async (async)

Asynchronously return a best-effort summary of the thread.

• Parameters:
  • except_last int – Number of most recent messages to exclude from the summary.
  • token_budget int – Soft token budget. When omitted, a bounded default is applied. Positive values truncate only when the formatted summary exceeds the budget as estimated by _estimate_tokens(); the returned text is then capped to int(token_budget * 3.5) characters. Non-positive values disable the output bound.
  • **kwargs (Any) – Reserved for future summary options. Unexpected keyword arguments raise TypeError.
• Returns: Summary object containing the synthesized thread summary text.
• Return type: OracleSummary

method search

Search synchronously for records relevant to a query.

• Parameters:
  • query str – Natural-language query string.
  • user_id str | None – Optional user scope override. Omitted values inherit the thread’s default user scope.
  • agent_id str | None – Optional agent scope override. Omitted values inherit the thread’s default agent scope.
  • thread_id str | None – Optional thread scope override. Omitted values inherit the thread’s current thread identifier.
  • exact_user_match bool – Whether user matching should be strict.
  • exact_agent_match bool – Whether agent matching should be strict.
  • exact_thread_match bool – Whether thread matching should be strict.
  • max_results int – Optional maximum number of results to return. When provided, it must be at least 1. Omitting this argument uses the default value of 10. The call may return fewer than max_results when fewer non-expired matching records exist.
  • record_types list[str] – Optional list of record types to include, such as "memory" or "message".

  • metadata_filter dict[str, Any] | None –

    Optional metadata filter mapping used as an additional filter after scope and record-type filtering. Entries in metadata_filter are combined with AND semantics. Entries whose value is not a field-level operator dictionary use exact-match semantics: the requested key must exist in the stored record metadata. Nested dictionaries match nested metadata objects recursively. Scalar and list values must match exactly; list order and length must also match. Omit this argument, or pass None, to search without metadata filtering. Examples include metadata_filter={"source": "chat"} for a scalar field, metadata_filter={"travel": {"need": "transit"}} for a nested field, and metadata_filter={"tags": ["trip", "urgent"]} for an exact list match. Combine conditions to require all of them:

    metadata_filter={
        "source": "chat",
        "travel": {"need": "transit"},
        "tags": ["trip", "urgent"],
    }

    To test array membership, use a field-level operator dictionary. "$array_contains" matches one value, or all values in a list. "$array_contains_any" matches at least one value from a list. "$not" negates another field-level expression at the same field, including an operator dictionary or raw exact-match value. Negated expressions match when the positive expression would fail, including missing fields; negated array membership also matches non-array fields:

    metadata_filter={
        "source": "chat",
        "tags": {
            "$array_contains": "trip",
            "$not": {"$array_contains": "archived"},
        },
    }

  • scope SearchScope – Optional prebuilt search scope. Provide either scope or the explicit identifier and exact-match arguments, not both.
• Returns: Search results ordered by decreasing relevance.
• Return type: list[SearchResult]
• Raises: ValueError – If scope is combined with explicit identifier or exact-match arguments, if max_results is less than 1, or if metadata_filter is neither a dictionary nor None.

Notes

Omitted scope fields inherit this thread’s default search scope: exact user and agent matching plus this thread’s current user_id, agent_id, and thread_id. The default thread search intentionally leaves exact_thread_match=False, so it may return relevant records from other threads for the same user/agent. Pass exact_thread_match=True to restrict results to the current thread. Explicit None scope values still follow the resolved exact-match rules: exact_*_match=False leaves that dimension unconstrained, while exact_*_match=True matches only stored None values.

Explicit max_results values must be at least 1; omitting the argument uses the default value of 10. This is an upper bound: the call may return fewer than max_results results when filters are too restrictive, when fewer matching records exist, or because of implementation-specific search behavior.

method search_async (async)

Search asynchronously for records relevant to a query.

• Parameters:
  • query str – Natural-language query string.
  • user_id str | None – Optional user scope override. Omitted values inherit the thread’s default user scope.
  • agent_id str | None – Optional agent scope override. Omitted values inherit the thread’s default agent scope.
  • thread_id str | None – Optional thread scope override. Omitted values inherit the thread’s current thread identifier.
  • exact_user_match bool – Whether user matching should be strict.
  • exact_agent_match bool – Whether agent matching should be strict.
  • exact_thread_match bool – Whether thread matching should be strict.
  • max_results int – Optional maximum number of results to return. When provided, it must be at least 1. Omitting this argument uses the default value of 10.
  • record_types list[str] – Optional list of record types to include, such as "memory" or "message".

  • metadata_filter dict[str, Any] | None –

    Optional metadata filter mapping used as an additional filter after scope and record-type filtering. Entries in metadata_filter are combined with AND semantics. Entries whose value is not a field-level operator dictionary use exact-match semantics: the requested key must exist in the stored record metadata. Nested dictionaries match nested metadata objects recursively. Scalar and list values must match exactly; list order and length must also match. Omit this argument, or pass None, to search without metadata filtering. Examples include metadata_filter={"source": "chat"} for a scalar field, metadata_filter={"travel": {"need": "transit"}} for a nested field, and metadata_filter={"tags": ["trip", "urgent"]} for an exact list match. Combine conditions to require all of them:

    metadata_filter={
        "source": "chat",
        "travel": {"need": "transit"},
        "tags": ["trip", "urgent"],
    }

    To test array membership, use a field-level operator dictionary. "$array_contains" matches one value, or all values in a list. "$array_contains_any" matches at least one value from a list. "$not" negates another field-level expression at the same field, including an operator dictionary or raw exact-match value. Negated expressions match when the positive expression would fail, including missing fields; negated array membership also matches non-array fields:

    metadata_filter={
        "source": "chat",
        "tags": {
            "$array_contains": "trip",
            "$not": {"$array_contains": "archived"},
        },
    }

  • scope SearchScope – Optional prebuilt search scope. Provide either scope or the explicit identifier and exact-match arguments, not both.
• Returns: Search results ordered by decreasing relevance.
• Return type: list[SearchResult]
• Raises: ValueError – If scope is combined with explicit identifier or exact-match arguments, if max_results is less than 1, or if metadata_filter is neither a dictionary nor None.

Notes

Omitted scope fields inherit this thread’s default search scope: exact user and agent matching plus this thread’s current user_id, agent_id, and thread_id. The default thread search intentionally leaves exact_thread_match=False, so it may return relevant records from other threads for the same user/agent. Pass exact_thread_match=True to restrict results to the current thread. Explicit None scope values still follow the resolved exact-match rules: exact_*_match=False leaves that dimension unconstrained, while exact_*_match=True matches only stored None values.

Explicit max_results values must be at least 1; omitting the argument uses the default value of 10. This is an upper bound: the call may return fewer than max_results results when filters are too restrictive, when fewer matching records exist, or because of implementation-specific search behavior.

method update_memory

Update a memory-like record owned by this exact thread.

• Parameters:
  • memory_id str – Memory identifier. Only memory-like records (memory, guideline, fact, preference) whose stored thread_id exactly matches this thread are updated.
  • content str – Optional replacement content. Provide a string to replace the stored content. When omitted, the stored content is preserved. Passing None is not supported; omit content to keep the current value, or use delete_memory() to remove the record.
  • metadata dict[str, Any] | None – Optional replacement metadata mapping. When omitted, the stored metadata is preserved. When provided, it replaces the stored metadata object; this API does not deep-merge metadata.
  • timestamp str | None – Optional new timestamp for this memory. It represents when the memory was created. When omitted, the stored timestamp is preserved. Pass None to clear the saved timestamp and use the time the record was created in the store. When ttl_anchor is TimeToLiveAnchor.TIMESTAMP, replacement timestamps must be ISO-8601 strings. ISO-8601 timestamps without a timezone are treated as UTC.
  • ttl_days int | None – Optional expiration refresh in days. Omit this argument to leave the current expiration unchanged unless ttl_anchor is provided. Pass None to use MemoryRetentionConfig.max_ttl_days when the retention configuration sets one, or to clear expiration when it does not. Values above MemoryRetentionConfig.max_ttl_days are clamped to that maximum with a warning. Expired memories are unavailable to this thread API and cannot be refreshed.
  • ttl_anchor TimeToLiveAnchor – Optional time-to-live anchor for an expiration refresh. Use TimeToLiveAnchor.CREATED_AT for the memory creation time or TimeToLiveAnchor.TIMESTAMP for the replacement timestamp supplied in the same update, or the stored event timestamp when timestamp is omitted. Providing ttl_anchor without ttl_days uses the schema default time-to-live duration. When ttl_anchor is omitted during a refresh, the thread uses TimeToLiveAnchor.CREATED_AT. Timestamp-anchored refreshes require either a replacement ISO-8601 timestamp in the same call or an existing stored event timestamp in that format. ISO-8601 timestamps without a timezone are treated as UTC.
  • **kwargs (Any) – Unexpected keyword arguments are rejected.
• Returns: Identifier of the updated memory-like record.
• Return type: str

method update_memory_async (async)

Update a memory-like record asynchronously.

• Parameters:
  • memory_id str – Identifier of the memory-like record to update.
  • content str – Optional replacement content. Provide a string to replace the stored content. When omitted, the stored content is preserved. Passing None is not supported; omit content to keep the current value, or use delete_memory() to remove the record.
  • metadata dict[str, Any] | None – Optional replacement metadata mapping. When omitted, the stored metadata is preserved. When provided, it replaces the stored metadata object; this API does not deep-merge metadata.
  • timestamp str | None – Optional new timestamp for this memory. It represents when the memory was created. When omitted, the stored timestamp is preserved. Pass None to clear the saved timestamp and use the time the record was created in the store.
  • ttl_days int | None – Optional expiration refresh in days. Omit this argument together with ttl_anchor to preserve the current expiration timestamp. Pass None to clear expiration.
  • ttl_anchor TimeToLiveAnchor – Optional time-to-live anchor for an expiration refresh. Providing ttl_anchor without ttl_days uses the schema default time-to-live duration.
  • **kwargs (Any) – Unexpected keyword arguments are rejected.
• Returns: Identifier of the updated memory-like record.
• Return type: str

Examples

from functools import partial
from oracleagentmemory._async_helpers import run_async_in_sync
memory_id = thread.add_memory("Original memory")
run_async_in_sync(
    partial(thread.update_memory_async, memory_id, content="Updated memory")
) == memory_id
True

method update_message

Update a raw message record owned by this exact thread.

• Parameters:
  • message_id str – Message identifier. Only messages whose stored thread_id exactly matches this thread are updated.
  • content str – Optional replacement message content. Provide a string to replace the stored content. When omitted, the stored content is preserved. Passing None is not supported.
  • metadata dict[str, Any] | None – Optional replacement metadata mapping. When omitted, the stored metadata is preserved. When provided, it replaces the stored metadata object; this API does not deep-merge metadata.
  • ttl_days int | None – Optional expiration refresh in days. Omit this argument to leave the current expiration unchanged unless ttl_anchor is provided. Pass None to use MemoryRetentionConfig.max_ttl_days when the retention configuration sets one, or to clear expiration when it does not. Values above MemoryRetentionConfig.max_ttl_days are clamped to that maximum with a warning. Expired messages are unavailable to this thread API and cannot be refreshed.
  • ttl_anchor TimeToLiveAnchor – Optional time-to-live anchor for an expiration refresh. Use TimeToLiveAnchor.CREATED_AT for the message creation time or TimeToLiveAnchor.TIMESTAMP for the stored event timestamp. Providing ttl_anchor without ttl_days uses the schema default time-to-live duration. When ttl_anchor is omitted during a refresh, the thread uses TimeToLiveAnchor.CREATED_AT. Timestamp-anchored refreshes require an existing stored ISO-8601 message timestamp. ISO-8601 timestamps without a timezone are treated as UTC.
  • **kwargs (Any) – Unexpected keyword arguments are rejected.
• Returns: Identifier of the updated message record.
• Return type: str

Notes

Omitted fields are preserved from the stored record. Stored role and timestamp remain unchanged. Editing content updates the raw message history and, when automatic extraction is enabled, can cause the SDK to re-extract memories from the edited message and earlier history. In INLINE mode, that extraction completes before this method returns. In BACKGROUND mode, this method returns after the raw message update succeeds and background extraction is attempted. This follow-up work does not affect the normal extraction frequency used by later add_messages() calls. Existing extracted memories remain in place while newly extracted memories from the edited content may be added. Because the raw message update and any later extracted-memory writes do not happen atomically, extracted memories can still reflect the earlier message content if the background work does not queue, if a configured queue-capacity wait reaches its timeout, or if later extraction work fails. Also, note that existing extracted memories keep their original expiration when a source message’s TTL changes.

Examples

message_id = thread.add_messages([{"role": "user", "content": "Draft message"}])[0]
thread.update_message(message_id, content="Edited message") == message_id
True

method update_message_async (async)

Update a raw message record owned by this exact thread asynchronously.

• Parameters:
  • message_id str – Message identifier. Only messages whose stored thread_id exactly matches this thread are updated.
  • content str – Optional replacement message content. Provide a string to replace the stored content. When omitted, the stored content is preserved. Passing None is not supported.
  • metadata dict[str, Any] | None – Optional replacement metadata mapping. When omitted, the stored metadata is preserved. When provided, it replaces the stored metadata object; this API does not deep-merge metadata.
  • ttl_days int | None – Optional expiration refresh in days. Omit this argument to leave the current expiration unchanged unless ttl_anchor is provided. Pass None to use MemoryRetentionConfig.max_ttl_days when the retention configuration sets one, or to clear expiration when it does not. Values above MemoryRetentionConfig.max_ttl_days are clamped to that maximum with a warning. Expired messages are unavailable to this thread API and cannot be refreshed.
  • ttl_anchor TimeToLiveAnchor – Optional time-to-live anchor for an expiration refresh. Use TimeToLiveAnchor.CREATED_AT for the message creation time or TimeToLiveAnchor.TIMESTAMP for the stored event timestamp. Providing ttl_anchor without ttl_days uses the schema default time-to-live duration. Timestamp-anchored refreshes require an existing stored ISO-8601 message timestamp. ISO-8601 timestamps without a timezone are treated as UTC.
  • **kwargs (Any) – Unexpected keyword arguments are rejected.
• Returns: Identifier of the updated message record.
• Return type: str

Notes

Omitted fields are preserved from the stored record. Stored role and timestamp remain unchanged. Editing content updates the raw message history and, when automatic extraction is enabled, can cause the SDK to re-extract memories from the edited message and earlier history. In INLINE mode, that extraction completes before this method returns. In BACKGROUND mode, this method returns after the raw message update succeeds and background extraction is attempted. This follow-up work does not affect the normal extraction frequency used by later add_messages() calls. Existing extracted memories remain in place while newly extracted memories from the edited content may be added. Because the raw message update and any later extracted-memory writes do not happen atomically, extracted memories can still reflect the earlier message content if the background work does not queue, if a configured queue-capacity wait reaches its timeout, or if later extraction work fails. Also, note that existing extracted memories keep their original expiration when a source message’s TTL changes.

Examples

message_id = thread.add_messages([{"role": "user", "content": "Draft message"}])[0]
run_async_in_sync(
    partial(thread.update_message_async, message_id, content="Edited message")
) == message_id
True

method wait_for_memory_extraction

Wait for earlier background memory extraction for this thread.

This method waits for background extraction started by earlier add_messages(), add_messages_async(), update_message(), or update_message_async() calls on this thread through the same agent memory component. If one of those calls is already finishing, this method includes the extraction it starts before waiting.

The method does not wait for extraction started after this wait begins, for extraction started by a different agent memory component, or for extraction running in another process. Extraction failures count as finished for this wait.

• Parameters: timeout float | None – Optional maximum number of seconds to wait. Defaults to 300. Pass None to wait until pending extraction for this thread has finished.
• Raises: TimeoutError – Raised when the timeout expires before the earlier background extraction finishes.
• Return type: None

Examples

thread.wait_for_memory_extraction(timeout=10)

method wait_for_memory_extraction_async (async)

Asynchronously wait for earlier background memory extraction.

This method follows the same behavior as wait_for_memory_extraction().

• Parameters: timeout float | None – Optional maximum number of seconds to wait. Defaults to 300. Pass None to wait indefinitely.
• Raises: TimeoutError – Raised when the timeout expires before the earlier background extraction finishes.
• Return type: None

Examples

await thread.wait_for_memory_extraction_async(timeout=10)

Note: delete_message() deletes only the raw message row. Derived memories may still be searchable or appear in context cards. Use OracleAgentMemory.delete_thread() to delete the thread together with its associated messages and memories. The client-level thread delete waits for earlier accepted background extraction already known for that thread, but it is not a global concurrency barrier for other operations on the same thread while deletion is in progress.

Messages

class oracleagentmemory.apis.thread.Message

Bases: object

• Parameters:
  • role str
  • content str
  • timestamp str | None
  • metadata dict[str, Any] | None
  • id str | None

Context Cards

class oracleagentmemory.apis.contextcard.ContextCard

Bases: ABC

Abstract context-card object returned by thread APIs.

property content (abstract)

• Return Type: str
• Description: Return the rendered context-card text.

class oracleagentmemory.core.contextcard.OracleContextCard

Bases: ContextCard

Context card returned by an Oracle thread.

• Parameters:
  • summary str – Summary text embedded in the card.
  • topics Sequence[str] | None – Optional retrieval topics associated with the thread.
  • relevant_results Sequence[SearchResult] | None – Optional retrieved durable records included in the card.
  • recent_messages Sequence[Message] | None – Optional recent raw messages rendered into the card.
  • message_format str – Internal template used when rendering recent_messages.

property content

• Return Type: str

• Description: Return the rendered context-card text.

• Returns: XML-like rendered context-card text suitable for prompt assembly.
• Return type: str

Examples

card = OracleContextCard(summary="ctx")
"<summary>" in card.content and "ctx" in card.content
True

property formatted_content

• Return Type: str

• Description: Return the rendered context-card text used in prompt-building flows.

• Returns: XML-like rendered context-card text.
• Return type: str

Examples

OracleContextCard(summary="").formatted_content
''
card = OracleContextCard(summary="ctx", topics=["travel"])
"<topics>" in card.formatted_content
True

Summaries

class oracleagentmemory.apis.summary.Summary

Bases: ABC

Abstract thread-summary object returned by thread APIs.

property content (abstract)

• Return Type: str
• Description: Return the synthesized summary text.

class oracleagentmemory.core.summary.OracleSummary

Bases: Summary

Summary returned by an Oracle thread.

• Parameters: content str – Summary text synthesized from the thread transcript.

Examples

summary = OracleSummary(content="Plan the Rome itinerary.")
summary.content
'Plan the Rome itinerary.'
str(summary)
'Plan the Rome itinerary.'

property content

• Return Type: str

• Description: Return the synthesized summary text.

• Returns: Summary text for the thread.
• Return type: str

Examples

OracleSummary(content="Keep the tea preference in mind.").content
'Keep the tea preference in mind.'

property formatted_content

• Return Type: str

• Description: Return the rendered summary text used in prompt-building flows.

• Returns: Rendered summary text.
• Return type: str

Examples

OracleSummary(content="Thread recap").formatted_content
'Thread recap'