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.
  • 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_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 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.
  • 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 LLM prompts used for memory extraction and running summary updates. Longer prompts are truncated. If negative or 0, prompt truncation is disabled.
  • context_card_token_limit int – Maximum size, in tokens, of the LLM prompts used for context-card summarization. Defaults to 100_000 tokens. Longer prompts are truncated. If negative or 0, prompt truncation is disabled.
  • 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-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 extracted memories do not persist per-message provenance, 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.
  • 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 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

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.
  • 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 context-card object for the thread.
• Return type: OracleContextCard

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: 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

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.

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'