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 retrieval data. This is broader than OracleThread.delete_message(), which deletes only the raw message row. Client-level deletion waits for relevant earlier background extraction: thread deletion waits for that thread, memory deletion waits for the stored target’s thread when present, and user or agent deletion waits for known owned threads whether or not cascade cleanup is enabled. These waits cover only work accepted by the same client before the wait begins.

class oracleagentmemory.core.OracleAgentMemory

Bases: IAgentMemory

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

Create a memory client.

Warning: SchemaPolicy.CREATE_IF_NECESSARY can be more expensive than normal client startup because it may apply managed schema DDL and best-effort data rewrites before initialization succeeds. Plan the first open of an older managed schema as a migration or maintenance operation when that schema may contain many rows.

If schema setup must create the managed expired-record purge job but the database user lacks the scheduler-job privilege, initialization warns and continues. Expired messages and memories stay hidden from reads and search, but they are not physically purged until the job is created by a user with CREATE JOB or an equivalent scheduler privilege.

When SchemaPolicy.CREATE_IF_NECESSARY first creates a managed hybrid index over an existing schema, Oracle scans the stored search text and builds the managed hybrid-index state from the configured in-database model. Client startup waits for that DDL to finish, so plan the first hybrid upgrade as a migration or maintenance operation for large schemas. SearchIndexSyncMode controls ongoing maintenance after the index exists; it does not make the first index build asynchronous.

Examples

To access a schema created by another database user, configure memory_rw_pool for the application DB user and set memory_schema_owner to the owning user’s unquoted database name.

from oracleagentmemory.core import (
    MemoryExtractionConfig,
    SearchIndexSyncMode,
    OracleAgentMemory,
    SchemaPolicy,
    SearchStrategy,
)
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
read_only_client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
)
pruned_search_client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
    pruner_llm=llm,
)
shared_client = OracleAgentMemory(
    connection=memory_rw_pool,
    embedder=embedder,
    llm=llm,
    schema_owner=memory_schema_owner,
)

Use an in-DB embedding model to exploit Oracle hybrid index search:

from oracleagentmemory.core.embedders import OracleDBEmbedder
db_embedder = OracleDBEmbedder(
    connection=db_pool,
    model="DOC_MODEL",
    embedding_dimension=768,
)
hybrid_client = OracleAgentMemory(
    connection=db_pool,
    embedder=db_embedder,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    search_strategy=SearchStrategy.HYBRID,
    search_index_sync=SearchIndexSyncMode.ON_COMMIT,
    memory_store_id=memory_store_id,
)

method add_agent

Add an agent profile record to the store.

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",
    metadata={"source": "catalog"},
)
'a1'

method add_agent_async (async)

Add an agent profile record to the store asynchronously.

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,
)
import asyncio
asyncio.run(client.add_agent_async(
    "a1",
    "Support assistant",
    metadata={"source": "catalog"},
))
'a1'

method add_image

Add an image record to the client.

Examples

image_id = client.add_image(
    b"image-bytes",
    description="Image description",
    mime_type=ImageMimeType.PNG,
    image_id="img-1",
    user_id="user-1",
)
image_id
'img-1'

method add_image_async (async)

Persist one standalone image through the configured store.

When description is omitted or None, the configured LLM generates a caption.

method add_memory

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

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_memory_async (async)

Add a memory in the memory system asynchronously.

Examples

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

method add_user

Add a user profile record to the store.

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.",
    metadata={"source": "crm"},
)
'u1'

method add_user_async (async)

Add a user profile record to the store asynchronously.

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,
)
import asyncio
asyncio.run(client.add_user_async(
    "u1",
    "Prefers concise answers.",
    metadata={"source": "crm"},
))
'u1'

method close

Close the agent memory component.

Closing stops accepting new background work, including memory extraction and image-description generation, and waits for pending work to finish up to the configured timeout. If that timeout expires, close() returns even if some work is still unfinished. The method is idempotent.

Examples

client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
)
client.close()

method close_async (async)

Asynchronously close the agent memory component.

This method follows the same shutdown behavior as close(). If the timeout expires, it can return while background work is still running.

Examples

import asyncio
asyncio.run(client.close_async())

method create_thread

Create and register a thread.

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 create_thread_async (async)

Create and register a thread asynchronously.

Examples

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

method delete_agent

Delete an agent profile record by identifier.

Notes

Before deleting the profile, this method waits up to 300 seconds for earlier background extraction already accepted for owned threads known through this agent memory component. This wait applies whether or not cascade cleanup is enabled. Cascading cleanup is planned and executed inside the backing store as one operation. The method does not wait for work accepted after the wait begins or for work started by another agent memory component or process. Concurrent actor-scoped use while deletion is in progress is unsupported.

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_agent_async (async)

Delete an agent profile record by identifier asynchronously.

Notes

This method follows the background-extraction wait and concurrency behavior documented by delete_agent().

Examples

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
asyncio.run(client.add_agent_async("a-delete", "Support assistant"))
'a-delete'
asyncio.run(client.delete_agent_async("a-delete"))
1

method delete_image

Delete an image record by identifier.

method delete_image_async (async)

Delete one standalone image through the configured store.

method delete_memory

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

Notes

Before deleting a thread-scoped record, this method resolves its stored thread and waits for earlier background extraction accepted through this agent memory component. It does not wait for unrelated threads, work accepted after the wait begins, or work started by another agent memory component or process. Records without a thread scope and unknown identifiers do not cause an extraction wait.

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_memory_async (async)

Delete a memory-like record asynchronously.

Notes

This method follows the targeted background-extraction wait and concurrency behavior documented by delete_memory().

Examples

import asyncio
memory_id = asyncio.run(client.add_memory_async(
    "Temporary memory", memory_id="mem-delete"
))
asyncio.run(client.delete_memory_async(memory_id))
1

Delete a relation by identifier or complete endpoint tuple.

When no relation_id is supplied, provide every source, target, type, and relation-label argument in the stored source-to-target orientation.

Examples

client.delete_record_link(relation_id="relation-id")
1

Asynchronously delete a relation by ID or complete endpoint tuple.

method delete_thread

Delete all records associated with a thread identifier.

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 retrieval data. This differs from OracleThread.delete_message(), which removes only the raw message record and does not cascade to derived memories created from that message. Before deleting the thread, this method waits for earlier background extraction already accepted for that thread through this agent memory component. It does not wait for background work accepted after that wait begins or for work started by another agent memory component or process. Concurrent use of the same thread while deletion is in progress is unsupported.

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_thread_async (async)

Delete all records associated with a thread identifier asynchronously.

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 retrieval data. This differs from OracleThread.delete_message(), which removes only the raw message record and does not cascade to derived memories created from that message. Before deleting the thread, this method waits for earlier background extraction already accepted for that thread through this agent memory component. It does not wait for background work accepted after that wait begins or for work started by another agent memory component or process. Concurrent use of the same thread while deletion is in progress is unsupported.

Examples

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
thread = asyncio.run(client.create_thread_async(thread_id="c-delete"))
asyncio.run(client.delete_thread_async(thread.thread_id))
1

method delete_user

Delete a user profile record by identifier.

Notes

Before deleting the profile, this method waits up to 300 seconds for earlier background extraction already accepted for owned threads known through this agent memory component. This wait applies whether or not cascade cleanup is enabled. Cascading cleanup is planned and executed inside the backing store as one operation. The method does not wait for work accepted after the wait begins or for work started by another agent memory component or process. Concurrent actor-scoped use while deletion is in progress is unsupported.

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 delete_user_async (async)

Delete a user profile record by identifier asynchronously.

Notes

This method follows the background-extraction wait and concurrency behavior documented by delete_user().

Examples

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

method get_thread

Retrieve a previously created thread.

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="c2", user_id="u1")
loaded = client.get_thread("c2")
loaded.user_id
'u1'

method get_thread_async (async)

Retrieve a previously created thread asynchronously.

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,
)
import asyncio
created = asyncio.run(client.create_thread_async(
    thread_id="c2", user_id="u1"
))
loaded = asyncio.run(client.get_thread_async("c2"))
loaded.user_id
'u1'

Create a directed relation between two stored records.

Currently, both endpoints must be memory-like records: "memory", "fact", "guideline", or "preference". Built-in relation types are "supersedes" ("is_superseded_by"), "contradicts", "refines" ("is_refined_by"), "supports" ("is_supported_by"), and "duplicates". "contradicts" and "duplicates" use the same label in reverse.

Only one orientation can be stored for an endpoint pair. opposite_relation_type names the relation when traversing from target to source. For example, if new "supersedes" old, the reverse traversal is old "is_superseded_by" new.

Examples

client.link_records(
    "fact-1", "fact", "memory-1", "memory", "supports"
)
'relation-id'

Asynchronously create a typed relation between stored records.

Currently, both endpoints must be memory-like records: "memory", "fact", "guideline", or "preference". Built-in relation types are "supersedes" ("is_superseded_by"), "contradicts", "refines" ("is_refined_by"), "supports" ("is_supported_by"), and "duplicates". "contradicts" and "duplicates" use the same label in reverse.

method list_agents

List persisted agent profile records.

Examples

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_agent("a1", "Support assistant", metadata={"source": "catalog"})
'a1'
[record.id for record in client.list_agents(metadata_filter={"source": "catalog"})]
['a1']

method list_agents_async (async)

List persisted agent profile records asynchronously.

Examples

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    await client.add_agent_async(
        "a1",
        "Support assistant",
        metadata={"source": "catalog"},
    )
    records = await client.list_agents_async(metadata_filter={"source": "catalog"})
    return [record.id for record in records]
anyio.run(main)
['a1']

method list_images

List persisted standalone image records.

Examples

images = client.list_images(user_id="u1", limit=10)
[image.id for image in images]
['img-1']

method list_images_async (async)

List persisted standalone image records asynchronously.

Examples

images = await client.list_images_async(
    user_id="u1",
    limit=10,
)
[image.id for image in images]
['img-1']

method list_memories

List persisted memory-like records.

Examples

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_memory("User likes pizza.", user_id="u1", memory_id="mem-1")
'mem-1'
[record.id for record in client.list_memories(user_id="u1", limit=10)]
['mem-1']

method list_memories_async (async)

List persisted memory-like records asynchronously.

Examples

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    await client.add_memory_async("User likes pizza.", user_id="u1", memory_id="mem-1")
    records = await client.list_memories_async(user_id="u1", limit=10)
    return [record.id for record in records]
anyio.run(main)
['mem-1']

method list_messages

List persisted chat message records.

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")
message_id = thread.add_messages([{"role": "user", "content": "Hello"}])[0]
[record.id for record in client.list_messages(thread_id="c1", limit=10)] == [message_id]
True

method list_messages_async (async)

List persisted chat message records asynchronously.

Examples

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    thread = await client.create_thread_async(thread_id="c1", user_id="u1")
    message_ids = await thread.add_messages_async(
        [{"role": "user", "content": "Hello"}]
    )
    records = await client.list_messages_async(thread_id="c1", limit=10)
    return [record.id for record in records] == message_ids
anyio.run(main)
True

method list_threads

List persisted conversation threads.

Examples

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.create_thread(thread_id="c1", user_id="u1").thread_id
'c1'
[record.thread_id for record in client.list_threads(user_id="u1", limit=10)]
['c1']

method list_threads_async (async)

List persisted conversation threads asynchronously.

Examples

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    await client.create_thread_async(thread_id="c1", user_id="u1")
    records = await client.list_threads_async(user_id="u1", limit=10)
    return [record.thread_id for record in records]
anyio.run(main)
['c1']

method list_users

List persisted user profile records.

Examples

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_user("u1", "Prefers concise answers.", metadata={"source": "crm"})
'u1'
[record.id for record in client.list_users(metadata_filter={"source": "crm"})]
['u1']

method list_users_async (async)

List persisted user profile records asynchronously.

Examples

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    await client.add_user_async(
        "u1",
        "Prefers concise answers.",
        metadata={"source": "crm"},
    )
    records = await client.list_users_async(metadata_filter={"source": "crm"})
    return [record.id for record in records]
anyio.run(main)
['u1']

Search synchronously for records relevant to a query.

Notes

Explicit None scope values still follow the resolved exact-match rules: exact_*_match=False leaves that dimension unconstrained, while exact_*_match=True matches only records unscoped on that dimension.

method search_async (async)

Search asynchronously for records relevant to a query.

Notes

Explicit None scope values still follow the resolved exact-match rules: exact_*_match=False leaves that dimension unconstrained, while exact_*_match=True matches only records unscoped on that dimension.

method update_image

Update a stored image record by identifier.

Notes

Omitted fields remain unchanged. Scope updates are not supported by this API. Metadata replacement is whole-object replacement, not recursive JSON merge.

method update_image_async (async)

Update one standalone image through the configured store.

Omit image to preserve the existing bytes. If image is provided, mime_type must be provided with it. Omit description to preserve the existing description. Pass None to generate a new description with the configured LLM; a non-null description replaces it directly. Metadata, timestamp, and expiration settings are updated when supplied.

method update_memory

Update a stored memory-like record by identifier.

Notes

Omitted fields are preserved from the stored record. Stored scope remains unchanged. Metadata replacement is whole-object replacement, not recursive JSON merge.

method update_memory_async (async)

Update a stored memory-like record by identifier asynchronously.

Notes

Omitted fields are preserved from the stored record. Stored scope remains unchanged. Metadata replacement is whole-object replacement, not recursive JSON merge.

Examples

import asyncio
memory_id = asyncio.run(client.add_memory_async("Original memory"))
(
    asyncio.run(client.update_memory_async(
        memory_id, content="Updated memory"
    ))
    == memory_id
)
True

Update mutable fields of one stored relation.

Omitted values are preserved. When relation_type changes to a built-in memory relation type, its fixed reverse label replaces opposite_relation_type. Pass None for timestamp or metadata to clear that value.

Examples

client.update_record_link("relation-id", relation_type="supports")
1

Asynchronously update one stored relation.

method update_thread

Persist thread metadata and durable runtime configuration updates.

Notes

Runtime configuration is resolved from the stored conversation thread plus the explicit overrides passed to this call, matching get_thread semantics before persisting the result. Omitted metadata and runtime config updates are resolved from stored data, not from any previously loaded OracleThread instance, and only explicitly provided metadata updates or durable runtime-config overrides are written back. Metadata replacement is whole-object replacement, not recursive JSON merge. Thread ownership is not mutable through this API, so user_id and agent_id remain unchanged. Mutable runtime state, such as extraction counters, is left untouched.

Examples

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
updated = client.update_thread(
    "c1",
    metadata={"flags": {"vip": True}},
    message_shortening_input_token_limit=12_000,
)
updated.message_shortening_input_token_limit
12000

method update_thread_async (async)

Persist updated thread metadata and durable runtime configuration asynchronously.

method wait_for_memory_extraction

Wait for earlier background memory extraction started by this client.

This method waits for background extraction already started through this OracleAgentMemory instance, across all threads owned by this agent memory component. It does not wait for extraction started after this wait begins, for extraction started by another agent memory component, or for extraction running in another process. Extraction failures count as finished for this wait.

Examples

client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
)
client.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().

Examples

import asyncio
asyncio.run(client.wait_for_memory_extraction_async(timeout=10))

Image Input Limits

class oracleagentmemory.core.ImageInputLimitConfig

Bases: object

Configure raw image and LLM image-request limits.

Omitted fields inherit from the next broader configuration scope. Client fields inherit SDK defaults, while per-thread fields inherit the client configuration. Validation cannot be disabled, and resolved values cannot exceed the SDK’s absolute maxima.

Examples

from oracleagentmemory.core import ImageInputLimitConfig
config = ImageInputLimitConfig(
    max_raw_image_bytes=16 * 1024 * 1024,
    max_images_per_llm_request=200,
)

Memory Extraction

class oracleagentmemory.core.MemoryExtractionImageContext

Bases: str, Enum

Select how images participate in automatic memory extraction.

DISABLED omits images and image descriptions from extraction prompts. IMAGE sends original image parts. CAPTION sends image descriptions as text and requires every selected image to have a non-blank description.

CAPTION = ‘caption’

Include descriptions as text and require one for every selected image.

DISABLED = ‘disabled’

Do not include images or image descriptions in extraction prompts.

IMAGE = ‘image’

Include original image parts in extraction prompts.

MEMORY = ‘memory’

Image-specific memory extraction is not currently supported.

class oracleagentmemory.core.MemoryExtractionConfig

Bases: object

Grouped settings for automatic memory extraction.

Pass this object to OracleAgentMemory, create_thread, get_thread, or update_thread to configure automatic extraction. extraction_mode and the background queue settings also control automatic image-description generation. Each field is resolved independently. A value supplied for an operation takes precedence, followed by a saved thread value, the client value, and the SDK default. New and standalone threads have no saved thread value.

Examples

from oracleagentmemory.core import (
    MemoryExtractionImageContext,
    MemoryExtractionConfig,
    MemoryExtractionMode,
    MemoryLinkExtractionMode,
)
config = MemoryExtractionConfig(
    extract_memories=True,
    memory_extraction_image_context=MemoryExtractionImageContext.CAPTION,
    extraction_mode=MemoryExtractionMode.BACKGROUND,
    memory_link_extraction_mode=MemoryLinkExtractionMode.POST_EXTRACTION,
    memory_link_extraction_token_limit=8_000,
)

What to do when extraction or image descriptions cannot queue immediately.

Omitted values resolve to DROP.

Maximum seconds background work waits for queue capacity in wait modes.

Omitted values resolve to 300.0 seconds.

Messages after the latest valid summary before automatic refresh.

Values less than or equal to 0 refresh at every check.

Whether OAM maintains context summaries for thread reads and extraction prompts.

Whether extraction and image descriptions run inline or in background work.

Omitted values resolve to BACKGROUND.

Messages between extraction runs; values below 0 extract after every append.

Image representation; omission resolves to thread, client, then DISABLED.

Source-message metadata copied onto extracted memories.

Input token budget for prompts; values below 1 disable the limit.

Recent-message window used for extraction prompts; -1 uses only new messages.

Optional caller instructions appended to automatic link-resolution prompts.

How automatic links are resolved for extracted memories.

Omitted values resolve to POST_EXTRACTION.

Total input token budget for POST_EXTRACTION link resolution.

Values below 1 disable the limit.

class oracleagentmemory.core.MemoryExtractionMode

Bases: str, Enum

Controls when automatic extraction and image descriptions run.

INLINE completes derived work before the write method returns. BACKGROUND returns after the raw write succeeds and attempts to queue that work. Background work is best effort: generated descriptions and derived memories may appear later or may never be written if it cannot complete.

BACKGROUND = ‘BACKGROUND’

Return after the raw write and run derived work in the background.

INLINE = ‘INLINE’

Complete extraction and image descriptions before the write returns.

class oracleagentmemory.core.BackgroundExtractionQueueFullBehavior

Bases: str, Enum

Controls what happens when configured background work cannot queue in time.

Despite the extraction-specific name, this setting also applies to automatic image-description generation in background mode.

DROP = ‘DROP’

Log a warning and continue immediately when queue capacity is unavailable.

WAIT_THEN_DROP = ‘WAIT_THEN_DROP’

Wait for queue capacity up to the configured timeout, then log a warning and continue.

WAIT_THEN_RAISE = ‘WAIT_THEN_RAISE’

Wait for queue capacity up to the configured timeout, then raise TimeoutError.