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 thread handle.

• 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.
  • 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 record_type="memory".
  • 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.
  • context_summary_update_frequency int – Number of messages after which the context summary should be updated. Set to -1 to summarize only once per add_messages call using the full batch of newly added messages. The same cadence is reused for refreshing thread summarization metadata during transcript writes.
  • 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.
  • memory_extraction_token_limit int – Maximum size, in tokens, of the prompts used in memory extraction. Longer prompts will be truncated. If negative or 0, no truncation is performed.
  • 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.
  • client Any | None

Examples

from oracleagentmemory.core import OracleAgentMemory
db_pool = ...
client = OracleAgentMemory(connection=db_pool, embedder=embedder)
thread = client.create_thread(
    thread_id="c1",
    llm=llm,
    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.
  • 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.
  • **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_messages

Add messages to the thread and index them.

• Parameters:
  • messages list[Message | MessageT] – List of messages to append. Messages can be Message objects or dictionaries with role and content (and optional id).
  • **store_kwargs (Any) – Store-specific write options forwarded to the backing store.
• Returns: Identifiers of inserted message records.
• Return type: list[str]

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.

• Parameters:
  • messages list[Message | MessageT]
  • store_kwargs Any
• Return type: list[str]

method delete_memory

Delete a memory record from this exact thread by identifier.

• Parameters: memory_id str – Memory identifier. Only memories 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 records (0 or 1). Returns 0 when the identifier does not exist or belongs to a different thread.
• Return type: int

Notes

Successful deletion clears derived thread-summary state so later summary and context-card calls rebuild from the remaining transcript. Derived memories are not deleted automatically because extracted memories do not currently persist per-message provenance.

Examples

thread.delete_message("123")
0

method get_context_card

Return an XML-like context card 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.
  • max_relevant_results int – Maximum number of retrieved durable records to include.
  • max_recent_messages int – Maximum number of trailing raw messages to embed verbatim.
  • **kwargs (Any) – Reserved for future context-card options. Unexpected keyword arguments raise TypeError.
• Returns: A card containing a thread context summary based on the most recent messages.
• Return type: str

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()
True

method get_context_card_async (async)

Asynchronously return an XML-like context card for the thread.

• Parameters:
  • fallback_message_count int – Number of recent messages to use when deriving the fallback summary text for retrieval and rendering.
  • max_relevant_results int – Maximum number of retrieved durable records to include.
  • max_recent_messages int – Maximum number of trailing raw messages to embed verbatim.
  • **kwargs (Any) – Reserved for future context-card options. Unexpected keyword arguments raise TypeError.
• Returns: A card containing a thread context summary based on the most recent messages.
• Return type: str

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_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: One assistant message containing the summary, or an empty list if the thread has no messages.
• Return type: list[Message]

Examples

len(thread.add_messages([{"role": "assistant", "content": "Summary source message"}]))
1
summary = thread.get_summary()
len(summary) >= 1
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: One assistant message containing the summary, or an empty list if the thread has no messages.
• Return type: list[Message]

Messages

class oracleagentmemory.apis.thread.Message

Bases: object

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