Agent Memory

This page presents the concrete Oracle AI Agent Memory implementation.

Oracle Agent Memory

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.

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 (not tied to a specific thread).

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.
  • 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. The same cadence is reused for thread summarization metadata refreshed during add_messages. When omitted, defaults to 4.
  • 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 extraction prompt size in tokens. 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_memory

Delete a memory record by identifier.

• Parameters: memory_id str – Memory identifier.
• Returns: Number of deleted memory 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.
  • allow_non_existing bool – When True, deleting a missing thread is treated as a no-op.
• Returns: Number of deleted thread rows (0 or 1).
• Return type: int

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 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 extraction prompt size in tokens.
  • 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'