Agent Memory

This page presents the concrete Oracle AI Agent Memory implementation.

Oracle Agent Memory

Note: OracleAgentMemory.delete_thread() is the supported path for thread-scoped cascading cleanup. It removes the thread together with associated messages, durable memories, and managed vector or chunk data. This is broader than OracleThread.delete_message(), which deletes only the raw message row.

class oracleagentmemory.core.OracleAgentMemory

Bases: IAgentMemory

Agent-memory client backed by Oracle DB or a caller-provided store.

Create a memory client.

• Parameters:
  • store OracleMemoryStore – Optional preconfigured store instance. When provided, the client uses this store directly instead of instantiating its own store. This is useful when callers need store configuration beyond the constructor options exposed by OracleAgentMemory.
  • connection object – Optional Oracle DB connection/pool. When provided, the DB store is used. Passing a raw connection enables single-session mode for this client instance, so concurrent requests should use a connection pool instead. When omitted, callers must pass an explicit store.
  • embedder IEmbedder | str – Embedder implementation instance, or a LiteLLM embedding model identifier. When omitted, no embedder is attached and callers must provide precomputed vectors through lower-level store APIs.
  • llm ILlm – Optional LLM adapter used by threads for memory extraction and/or context summarization. By default, threads created or loaded from this client require an LLM so recent messages can be mined for durable memories. Pass an llm here, provide one later in create_thread, or opt out with extract_memories=False.
  • extract_memories bool – When True, threads created or loaded by this client require an LLM and automatic memory extraction remains enabled. Set to False to disable automatic memory extraction and allow those threads to operate without an LLM. Defaults to True so missing extraction LLMs fail fast.
  • schema_policy SchemaPolicy | str – DB schema setup policy used only when constructing a DB store from connection. Defaults to SchemaPolicy.REQUIRE_EXISTING.
  • table_name_prefix str – Optional DB table/index prefix used only when constructing a DB store from connection.
• Raises: ValueError – If conflicting store configuration is provided, such as passing both store and connection, DB-specific options without a DB connection, or omitting both store and connection.

Examples

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
read_only_client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    extract_memories=False,
)

method add_agent

Add an agent profile record to the store.

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

Notes

Agent profile records are stored in the client-level store and are intentionally unscoped. The returned record identifier is the same public identifier the application uses as agent_id.

Examples

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_agent("a1", "Support assistant")
'a1'

method add_memory

Add a memory in the memory system, attributed to the indicated user, agent and thread.

• Parameters:
  • content str – Memory content to persist.
  • user_id str – Optional scope identifiers associated with the stored memory.
  • agent_id str – Optional scope identifiers associated with the stored memory.
  • thread_id str – Optional scope identifiers associated with the stored memory.
  • 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

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
memory_id = client.add_memory("User likes pizza", memory_id="mem-1")
memory_id
'mem-1'

method add_user

Add a user profile record to the store.

• Parameters:
  • user_id str – User identifier.
  • information str – Free-form information about the user.
• Returns: Identifier of the stored user profile.
• Return type: str

Notes

User profile records are stored in the client-level store and are intentionally unscoped. The returned record identifier is the same public identifier the application uses as user_id.

Examples

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_user("u1", "Prefers concise answers.")
'u1'

method create_thread

Create and register a thread.

• Parameters:
  • thread_id str – Thread identifier. If omitted, a new one is generated.
  • user_id str – User identifier attached to this thread record. If omitted, a new one is generated.
  • agent_id str – Agent identifier attached to this thread record. If omitted, a new one is generated.
  • metadata dict[str, Any] | None – Optional JSON-like metadata persisted on the thread row.
  • llm ILlm – Optional LLM override for this thread. If omitted, the client-level LLM configured at construction time is used. By default, either the client or the thread must provide an LLM so automatic memory extraction can run. Set extract_memories=False here or on the client to opt out of that requirement.
  • extract_memories bool – Optional per-thread override for automatic memory extraction. When True, this thread requires an LLM so automatic extraction can run. Set to False to disable automatic extraction for this thread and allow operation without an LLM. When omitted, the client-level extract_memories setting is used.
  • max_message_token_length int – Maximum prompt-time message size before truncation or summarization during memory extraction and context-summary updates. Stored message content remains unchanged. When omitted, defaults to 15_000 tokens.
  • message_shortening_input_token_limit int – Maximum size, in tokens, of the message excerpt sent to the LLM when shortening oversized prompt-time message copies. When omitted, defaults to 30_000 tokens.
  • memory_extraction_window int – Number of recent messages to include during memory extraction. Set to -1 to perform one extraction per add_messages call using the full batch of newly added messages. When omitted, defaults to -1.
  • context_summary_update_frequency int – Frequency of context-summary refreshes. Set to -1 to perform one summary update per add_messages call using the full batch of newly added messages. When omitted, defaults to -1.
  • memory_extraction_frequency int – Frequency of memory extraction updates. Set to -1 to perform one extraction per add_messages call using the full batch of newly added messages. When omitted, defaults to -1.
  • memory_extraction_token_limit int – Maximum size, in tokens, of the LLM prompts used for memory extraction and running summary updates. When omitted, defaults to 100_000.
  • context_card_token_limit int – Maximum size, in tokens, of the LLM prompts used for context-card summarization. When omitted, defaults to 100_000.
  • enable_context_summary bool – Whether to keep a running context summary for this thread.
  • **kwargs (Any) – Additional implementation-specific thread options.
• Returns: A OracleThread.
• Return type: OracleThread
• Raises: ValueError – If no LLM is available for automatic memory extraction and the thread and client were not configured with extract_memories=False.

Examples

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
thread = client.create_thread(thread_id="c1", user_id="u1")
thread.thread_id
'c1'

method delete_agent

Delete an agent profile record by identifier.

• Parameters:
  • agent_id str – Agent identifier whose profile should be removed.
  • cascade bool – When True (default), also delete records scoped to this agent. This includes deleting owned threads themselves, the messages and memory-like records removed with those threads, and any remaining directly agent-scoped records such as messages, memories, guidelines, facts, or preferences. This scoped cleanup still runs when the matching agent-profile row is already absent. Set to False to remove only the profile record.
• Returns: Number of deleted agent-profile rows (0 or 1). This may still be 0 when scoped rows were removed during cascade cleanup.
• Return type: int

Notes

Cascading deletes are planned and executed inside the backing store so the profile delete and all scoped child deletes happen in one store operation.

Examples

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_agent("a-delete", "Support assistant")
'a-delete'
client.delete_agent("a-delete")
1

method delete_memory

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

• Parameters: memory_id str – Memory identifier. The identifier may refer to a stored memory, guideline, fact, or preference record.
• Returns: Number of deleted memory-like rows (0 or 1).
• Return type: int

Examples

client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
memory_id = client.add_memory("Temporary memory", memory_id="mem-delete")
client.delete_memory(memory_id)
1

method delete_thread

Delete all records associated with a thread identifier.

• Parameters: thread_id str – Thread identifier to delete.
• Returns: Number of deleted thread rows (0 or 1).
• Return type: int

Notes

Use this operation when you need retention-complete removal of a thread. The backing store deletes the thread together with associated thread-scoped messages, durable memories, and managed vector or chunk rows. This differs from OracleThread.delete_message(), which removes only the raw message record and does not cascade to derived memories created from that message.

Examples

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
thread = client.create_thread(thread_id="c-delete")
client.delete_thread(thread.thread_id)
1

method delete_user

Delete a user profile record by identifier.

• Parameters:
  • user_id str – User identifier whose profile should be removed.
  • cascade bool – When True (default), also delete records scoped to this user. This includes deleting owned threads themselves, the messages and memory-like records removed with those threads, and any remaining directly user-scoped records such as messages, memories, guidelines, facts, or preferences. This scoped cleanup still runs when the matching user-profile row is already absent. Set to False to remove only the profile record.
• Returns: Number of deleted user-profile rows (0 or 1). This may still be 0 when scoped rows were removed during cascade cleanup.
• Return type: int

Notes

Cascading deletes are planned and executed inside the backing store so the profile delete and all scoped child deletes happen in one store operation.

Examples

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_user("u-delete", "Prefers concise answers.")
'u-delete'
client.delete_user("u-delete")
1

method get_thread

Retrieve a previously created thread.

• Parameters:
  • thread_id str – Identifier used when creating the thread.
  • llm ILlm – Optional LLM override for the reopened thread. When omitted, the client-level LLM configured at construction time is used.
  • extract_memories bool – Optional override for automatic memory extraction on the reopened thread. When omitted, the client-level extract_memories setting is used.
  • max_message_token_length int – Optional override for the maximum prompt-time message size before truncation or summarization during memory extraction and context-summary updates. Stored message content remains unchanged.
  • message_shortening_input_token_limit int – Optional override for the maximum size, in tokens, of the message excerpt sent to the LLM when shortening oversized prompt-time message copies.
  • memory_extraction_window int – Optional override for the number of recent messages used during memory extraction.
  • context_summary_update_frequency int – Optional override for the frequency of context-summary refreshes.
  • memory_extraction_frequency int – Optional override for the frequency of memory extraction updates.
  • memory_extraction_token_limit int – Optional override for the maximum size, in tokens, of the LLM prompts used for memory extraction and running summary updates.
  • context_card_token_limit int – Optional override for the maximum size, in tokens, of the LLM prompts used for context-card summarization.
  • enable_context_summary bool – Optional override for whether the reopened thread should keep a running context summary.
• Returns: A thread handle reconstructed from store metadata.
• Return type: OracleThread
• Raises:
  • KeyError – If the thread id is unknown to this client instance.
  • ValueError – If no LLM is available for automatic memory extraction and the client was not configured with extract_memories=False.

Notes

Explicit per-call overrides take precedence. When runtime overrides are omitted, reopened threads use persisted runtime config when available before falling back to SDK defaults.

Examples

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
created = client.create_thread(thread_id="c1", user_id="u1")
loaded = client.get_thread("c1")
loaded.user_id
'u1'