Customize Automatic Memory Extraction

Automatic memory extraction can capture useful details without additional configuration. Custom instructions let an application add guidance to the extraction process when the default behavior needs to be tailored for a specific use case.

This guide explains how to guide Oracle AI Agent Memory’s automated memory extraction with custom instructions.

Custom instructions let you provide domain-specific guidance about which details are worth preserving as durable memory. They are useful when your application needs extraction to reflect expert judgment, product policy, or workflow-specific priorities instead of treating every potentially memorable detail the same way.

Note: Use custom instructions when memory extraction should follow application-specific guidance. Default extraction is appropriate when no additional guidance is needed.

Hint: See the Get Started with Agent Memory for how to install oracleagentmemory. If you need a local Oracle AI Database for this example, follow Run Oracle AI Database locally.

Configure Client-Level Extraction Instructions

Create the Oracle Agent Memory component with an Oracle DB connection or pool, an embedder, an LLM, and support-focused extraction instructions. These instructions apply to threads created or loaded through this client unless a thread provides its own extraction instructions.

import oracledb

from oracleagentmemory.core import MemoryExtractionConfig, MemoryLinkExtractionMode, SchemaPolicy
from oracleagentmemory.core.embedders.embedder import Embedder
from oracleagentmemory.core.llms.llm import Llm
from oracleagentmemory.core.oracleagentmemory import OracleAgentMemory

embedder = Embedder(model="YOUR_EMBEDDING_MODEL")
llm = Llm(model="YOUR_MEMORY_LLM")
db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="localhost:1521/...",
)
memory_store_id = "T_MEM_EXTRACTION"

support_extraction_instructions = """
Only extract customer support facts:
- order ids
- return requests
- delivery problems
Ignore greetings, small talk, and one-off troubleshooting text.
""".strip()

memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
    memory_extraction_config=MemoryExtractionConfig(
        memory_extraction_custom_instructions=support_extraction_instructions
    ),
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_store_id=memory_store_id,
)

API Reference: OracleAgentMemory

OracleThread

Extract Support Memories from Thread Messages

Create a support thread and add user and assistant messages. The example sets memory_extraction_config=MemoryExtractionConfig(memory_extraction_frequency=1) so add_messages() runs automated extraction immediately for the inserted turn. The custom instructions keep the extracted memory focused on order IDs, return requests, and delivery problems.

support_thread = memory.create_thread(
    thread_id="support_ticket_7421",
    user_id="customer_123",
    memory_extraction_config=MemoryExtractionConfig(memory_extraction_frequency=1),
)

#add_messages persists the turn and runs automated memory extraction because
#MemoryExtractionConfig(memory_extraction_frequency=1) is set for this thread.
support_thread.add_messages(
    [
        {
            "role": "user",
            "content": (
                "Hi, order 7421 arrived damaged. I need a return request "
                "and a replacement delivery."
            ),
        },
        {
            "role": "assistant",
            "content": "I can help start the return request for order 7421.",
        },
    ]
)

results = support_thread.search(
    "return request order 7421",
    max_results=5,
    record_types=["fact"],
)
for result in results:
    print(f"- [{result.record.record_type}] {result.content}")
#- [fact] Customer reported damaged order 7421 and requested a return and replacement delivery.

The output shown earlier is illustrative. The exact memory text depends on the configured extraction LLM, but the extracted memories should follow the custom instructions supplied to the client.

The difference is easiest to see by comparing the kind of memory the extractor is asked to keep:

With custom instructions

The extractor keeps the durable customer-support fact and ignores the greeting and conversational wording.

- [fact] Customer reported damaged order 7421 and requested a return and replacement delivery.

Without custom instructions

The extractor may keep a broader conversation memory because the default extraction prompt is not scoped to support operations.

- [memory] The user contacted support about order 7421 and discussed a damaged delivery.

API Reference: OracleThread

OracleSearchResult

Configure Automatic Memory Linking

Automatic memory linking connects a newly extracted memory to relevant existing memories. The SDK retrieves a bounded set of candidate memories and asks the extraction LLM to decide whether a typed link should be created. By default, POST_EXTRACTION makes that decision in one additional request after the memories have been extracted.

The link type describes the relationship from the new memory to the existing candidate. supersedes, refines, and duplicates preserve the older memory as history and mark it invalid. supports and contradicts keep both memories valid. Automatic linking is limited to the retrieved candidates; use the explicit linking APIs when a relationship must always be recorded.

Use MemoryExtractionConfig to customize automatic linking:

memory_link_extraction_mode controls when links are resolved. Use POST_EXTRACTION for a separate link-resolution request, DURING_EXTRACTION to resolve links in the extraction request, or DISABLED to create no automatic links.
memory_link_extraction_custom_instructions adds guidance to the link-resolution prompt, such as which relationship types are appropriate for a domain.
memory_link_extraction_token_limit sets the total input-token budget for post-extraction link resolution. Values less than 1 disable this limit.

As with the extraction settings described earlier, provide these fields at client level or override them for a specific thread. The following example updates the support thread to link only meaningful changes in support facts:

memory.update_thread(
    "support_ticket_7421",
    memory_extraction_config=MemoryExtractionConfig(
        memory_link_extraction_mode=MemoryLinkExtractionMode.POST_EXTRACTION,
        memory_link_extraction_custom_instructions=(
            "Only link a new support fact when it supersedes or refines "
            "an existing support fact. Do not create supports or contradicts links."
        ),
        memory_link_extraction_token_limit=8_000,
    ),
)

The same settings can be passed to create_thread() or included in the client’s MemoryExtractionConfig. For details on manually creating links and retrieving linked context, see Create and Search Linked Memory Graphs.

API Reference: MemoryExtractionConfig

OracleThread

Override Instructions for One Thread

Pass memory_extraction_config=MemoryExtractionConfig(memory_extraction_custom_instructions=...) to create_thread() when one thread needs a narrower extraction policy than the client default. The thread-level value takes precedence for that thread and is persisted with the thread configuration.

billing_thread = memory.create_thread(
    thread_id="billing_ticket_9310",
    user_id="customer_123",
    memory_extraction_config=MemoryExtractionConfig(
        memory_extraction_frequency=1,
        memory_extraction_custom_instructions=(
            "Only extract billing facts, invoice identifiers, and payment issues."
        ),
    ),
)

billing_thread.add_messages(
    [
        {
            "role": "user",
            "content": "Invoice INV-9310 was paid twice and needs a refund.",
        }
    ]
)

API Reference: OracleAgentMemory

OracleThread

Update or Clear Thread Instructions

Use update_thread() to change persisted extraction instructions for an existing thread. Pass None to clear the thread-level instructions so future thread handles use the client-level instructions or, if none are configured, the SDK’s normal extraction behavior.

memory.update_thread(
    "support_ticket_7421",
    memory_extraction_config=MemoryExtractionConfig(
        memory_extraction_custom_instructions=(
            "Only extract product defects and replacement requests."
        )
    ),
)

memory.update_thread(
    "support_ticket_7421",
    memory_extraction_config=MemoryExtractionConfig(
        memory_extraction_custom_instructions=None
    ),
)

Note: get_thread(..., memory_extraction_config=MemoryExtractionConfig(memory_extraction_custom_instructions=...)) can apply instructions to the returned live thread handle without updating the persisted thread configuration.

API Reference: OracleAgentMemory

OracleThread

Conclusion

In this guide we learned how to configure client-level custom extraction instructions, configure automatic memory linking, override extraction instructions for a specific thread, and update or clear thread-level extraction instructions.

→ Having learned how to customize automated extraction, you may now proceed to Use Oracle Agent Memory Short-Term APIs with LangGraph.

Full Code

Copy the complete code that follows.

#Copyright © 2026 Oracle and/or its affiliates.
#This software is under the Apache License 2.0
#(LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0) or Universal Permissive License
#(UPL) 1.0 (LICENSE-UPL or https://oss.oracle.com/licenses/upl), at your option.

#Oracle Agent Memory Code Example - Customize Automatic Memory Extraction
#------------------------------------------------------------------------

##Configure custom memory extraction instructions

import oracledb

from oracleagentmemory.core import MemoryExtractionConfig, MemoryLinkExtractionMode, SchemaPolicy
from oracleagentmemory.core.embedders.embedder import Embedder
from oracleagentmemory.core.llms.llm import Llm
from oracleagentmemory.core.oracleagentmemory import OracleAgentMemory

embedder = Embedder(model="YOUR_EMBEDDING_MODEL")
llm = Llm(model="YOUR_MEMORY_LLM")
db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="localhost:1521/...",
)
memory_store_id = "T_MEM_EXTRACTION"

support_extraction_instructions = """
Only extract customer support facts:
- order ids
- return requests
- delivery problems
Ignore greetings, small talk, and one-off troubleshooting text.
""".strip()

memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
    memory_extraction_config=MemoryExtractionConfig(
        memory_extraction_custom_instructions=support_extraction_instructions
    ),
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_store_id=memory_store_id,
)

##Extract support memories from thread messages

support_thread = memory.create_thread(
    thread_id="support_ticket_7421",
    user_id="customer_123",
    memory_extraction_config=MemoryExtractionConfig(memory_extraction_frequency=1),
)

#add_messages persists the turn and runs automated memory extraction because
#MemoryExtractionConfig(memory_extraction_frequency=1) is set for this thread.
support_thread.add_messages(
    [
        {
            "role": "user",
            "content": (
                "Hi, order 7421 arrived damaged. I need a return request "
                "and a replacement delivery."
            ),
        },
        {
            "role": "assistant",
            "content": "I can help start the return request for order 7421.",
        },
    ]
)

results = support_thread.search(
    "return request order 7421",
    max_results=5,
    record_types=["fact"],
)
for result in results:
    print(f"- [{result.record.record_type}] {result.content}")
#- [fact] Customer reported damaged order 7421 and requested a return and replacement delivery.

##Configure automatic memory linking

memory.update_thread(
    "support_ticket_7421",
    memory_extraction_config=MemoryExtractionConfig(
        memory_link_extraction_mode=MemoryLinkExtractionMode.POST_EXTRACTION,
        memory_link_extraction_custom_instructions=(
            "Only link a new support fact when it supersedes or refines "
            "an existing support fact. Do not create supports or contradicts links."
        ),
        memory_link_extraction_token_limit=8_000,
    ),
)

##Override custom instructions for one thread

billing_thread = memory.create_thread(
    thread_id="billing_ticket_9310",
    user_id="customer_123",
    memory_extraction_config=MemoryExtractionConfig(
        memory_extraction_frequency=1,
        memory_extraction_custom_instructions=(
            "Only extract billing facts, invoice identifiers, and payment issues."
        ),
    ),
)

billing_thread.add_messages(
    [
        {
            "role": "user",
            "content": "Invoice INV-9310 was paid twice and needs a refund.",
        }
    ]
)

##Update or clear thread custom instructions

memory.update_thread(
    "support_ticket_7421",
    memory_extraction_config=MemoryExtractionConfig(
        memory_extraction_custom_instructions=(
            "Only extract product defects and replacement requests."
        )
    ),
)

memory.update_thread(
    "support_ticket_7421",
    memory_extraction_config=MemoryExtractionConfig(
        memory_extraction_custom_instructions=None
    ),
)