Learn how Oracle AI Agent Memory uses custom extraction instructions, thread-level overrides, and tool-result metadata to turn support conversations into durable, scoped memory.
Companion notebook: custom_memory_extraction_agent_memory.ipynb
Key Takeaways
- Oracle AI Agent Memory can transform raw user-agent messages into durable memories stored in Oracle AI Database.
- Default extraction provides a general memory baseline; custom extraction instructions make memory formation reflect a domain-specific policy.
- A customer-support agent should preserve durable facts such as order IDs, return requests, delivery issues, escalation commitments, tool-confirmed statuses, and stable communication preferences.
- Good memory is selective: the extractor should ignore greetings, speculation, credentials, payment details, one-time codes, and temporary conversational wording.
- Client-level custom instructions define the default extraction behavior, while thread-level overrides allow narrower policies for special workflows such as escalations.
- Tool-result metadata can be inherited into memories, making later search more scoped, auditable, and aligned with enterprise retrieval boundaries.
- The notebook verifies database connectivity and table-creation permissions before running memory operations.
Why Agents Need Selective Memory
Oracle AI Agent Memory provides a database-backed memory layer for AI agents, so applications can store messages, durable memories, metadata, summaries, and prompt-ready context in Oracle AI Database.
AI agents are most useful when they can carry context forward. A support agent may need to remember that a customer reported a damaged item, prefers SMS updates, or was promised an escalation by Friday. Without persistent memory, the agent has to rediscover these facts from chat history or ask the user again.
But remembering everything is not the same as remembering well. Real conversations contain greetings, clarifications, temporary codes, apologies, repeated facts, speculation, and sometimes sensitive information. If every detail becomes durable memory, future retrieval becomes noisier and harder to govern.
Custom memory extraction addresses this by turning extraction into an application policy. Instead of only asking the model to summarize a conversation, developers can define what their workflow considers useful memory and what should be ignored.
The Customer-Support Use Case
The companion notebook uses a customer-support workflow because it has a realistic mix of natural language, exact identifiers, tool results, and policy boundaries. This is the kind of workflow where a generic transcript summary is not enough.
The support conversation includes durable facts such as order identifiers, return intent, delivery problems, replacement commitments, and customer preferences. It also includes details that should not become long-term memory, such as temporary wording, credentials, payment details, and speculation.
- Preserve exact identifiers such as order IDs, return IDs, and case IDs.
- Preserve confirmed support facts such as delivery issues, product defects, return requests, and replacement commitments.
- Preserve stable preferences that should influence future interactions.
- Preserve tool-confirmed facts when a tool result is the source of truth.
- Ignore small talk, unconfirmed guesses, secrets, payment details, and one-time codes.
From Conversation Text to Durable Memory
Oracle AI Agent Memory stores the conversation and uses an extraction workflow to form higher-level memories. In a support case, those memories should be concise, durable, and useful for later retrieval. A memory like “Customer prefers morning delivery windows for replacement shipments” is more reusable than several raw turns where the user mentioned their preference indirectly.
The notebook first establishes a baseline extraction path. This baseline is useful because it shows the general extraction behavior before any domain-specific policy is added. The custom path then uses the same kind of support conversation but adds explicit extraction instructions.
SUPPORT_EXTRACTION_INSTRUCTIONS = """
Extract only durable customer-support memory that can help future support interactions.
Preserve confirmed order IDs, return requests, delivery issues, escalation reasons,
stable customer preferences, and tool-derived support facts.
Ignore greetings, small talk, speculation, credentials, payment secrets,
one-time verification codes, and temporary conversational wording.
""".strip()
These instructions guide the LLM-assisted extraction step. They help shape what should become durable memory, but they should not be treated as deterministic filtering, guaranteed redaction, or a replacement for application-level security controls.
This instruction block is intentionally written like a product policy. It does not ask the extractor to remember more; it asks the extractor to remember better. The policy defines durable support memory, instructs the extractor to preserve exact identifiers, and excludes information that should not influence future agent behavior.
Baseline Extraction vs. Custom Extraction
The notebook shows the comparison directly. A baseline client uses the package’s general extraction behavior. A custom client uses the same support scenario with custom extraction instructions. This makes the effect of the policy visible rather than theoretical.
from oracleagentmemory.core import MemoryExtractionConfig, OracleAgentMemory
base_memory = OracleAgentMemory(
store=base_store,
llm=memory_llm,
memory_extraction_config=MemoryExtractionConfig(
memory_extraction_frequency=1,
enable_context_summary=False,
),
)
custom_memory = OracleAgentMemory(
store=custom_store,
llm=memory_llm,
memory_extraction_config=MemoryExtractionConfig(
memory_extraction_frequency=1,
enable_context_summary=False,
memory_extraction_custom_instructions=SUPPORT_EXTRACTION_INSTRUCTIONS,
),
)
The important design point is that the application owns the memory policy. The model helps extract memories, but the application defines what kinds of facts should survive, which exact identifiers matter, and what kinds of text should be excluded.
Because this policy is evaluated by an LLM-assisted extraction step, it should be treated as guidance rather than deterministic filtering, guaranteed redaction, or a replacement for application-level security controls.
For the reader, the expected outcome is straightforward: baseline extraction demonstrates general memory formation; custom extraction demonstrates memory formation shaped by support workflow priorities.
What to Look for in the Output
The most important signal is not that the custom path creates more memory records. The stronger signal is that the memory records are better shaped for the workflow. The custom extraction path should preserve durable support facts while avoiding temporary or sensitive details that should not guide future conversations.
- The order identifier remains available as an exact support reference.
- The return or replacement context is preserved as durable case state.
- The customer’s stable delivery or communication preference is retained.
- Temporary details, such as a one-time lobby or access code, are not treated as reusable memory.
- Tool-confirmed status can be preserved with metadata that describes the source and workflow tag.
This before-and-after comparison is what makes custom extraction practical: it shows how memory can become more useful, searchable, and governable without turning the full transcript into long-term state.
| Signal in the notebook | Baseline extraction | Custom extraction |
| Exact support identifiers | May preserve the identifier if it is generally salient. | Explicitly preserves order, return, and case identifiers as durable support references. |
| Return or replacement state | May summarize the conversation at a general level. | Keeps confirmed return, replacement, delivery, and escalation facts as reusable case state. |
| Customer preference | May capture the preference if it appears important in the conversation. | Preserves stable communication and delivery preferences that should influence future interactions. |
| Temporary detail | May not have a domain-specific reason to exclude it. | Treats one-time codes, temporary instructions, and conversational noise as non-durable. |
| Tool-confirmed fact | May treat tool output like another message. | Preserves tool-derived support facts and selected source metadata for scoped retrieval. |
Client-Level Defaults and Thread-Level Overrides
Not every conversation in an application needs the same extraction policy. Most support threads may follow a broad support-memory policy, while an escalation thread may need a narrower policy focused only on shipment commitments and customer-facing follow-up deadlines.
Oracle AI Agent Memory supports this pattern by allowing custom extraction instructions at the client level and overrides at the thread level. The client-level policy becomes the default. A thread-level override can refine the policy for one conversation.
escalation_thread = custom_memory.create_thread(
thread_id=f"escalation_support_{RUN_ID}",
user_id=USER_ID,
agent_id=AGENT_ID,
memory_extraction_config=MemoryExtractionConfig(
memory_extraction_frequency=1,
enable_context_summary=False,
memory_extraction_custom_instructions=ESCALATION_EXTRACTION_INSTRUCTIONS,
),
) The notebook also shows lifecycle control for thread-level instructions. A workflow can update the thread policy when the support state changes, or clear the override to return to the client-level default.
updated_escalation_thread = custom_memory.update_thread(
escalation_thread.thread_id,
memory_extraction_config=MemoryExtractionConfig(
memory_extraction_custom_instructions=(
"Extract only shipment escalation commitments and customer-facing follow-up deadlines."
)
),
)
cleared_escalation_thread = custom_memory.update_thread(
escalation_thread.thread_id,
memory_extraction_config=MemoryExtractionConfig(
memory_extraction_custom_instructions=None
),
) 
Common Patterns for Custom Extraction Instructions
Custom extraction instructions are flexible by design. Developers do not need a different memory API for every workflow. Instead, they can express the workflow’s memory policy through instructions passed into the extraction configuration.
The useful pattern is to write instructions as a boundary: what to preserve, what to ignore, and which source or metadata signals should influence the extracted memory. The following patterns are not separate package objects; they are practical ways to structure `memory_extraction_custom_instructions` for common agent workflows.
| Pattern | Use when | Instruction focus |
| Support memory policy | A support agent needs durable case context across future interactions. | Preserve order IDs, return IDs, delivery issues, replacement commitments, escalation reasons, and stable preferences. Ignore greetings, credentials, payment details, one-time codes, and temporary wording. |
| Escalation-only policy | One thread needs a narrower policy than the default client-level behavior. | Preserve escalation reason, owner or team, customer-facing follow-up deadline, and confirmed commitments. Ignore general troubleshooting and repeated background context. |
| Tool-result policy | The agent receives tool outputs that should be treated as authoritative workflow state. | Preserve tool-confirmed facts, keep exact identifiers, inherit selected metadata such as tenant, source, and tags, and distinguish tool-confirmed facts from user-reported claims. |
Tool-Aware Extraction with Metadata
Tool-aware extraction is especially useful in enterprise workflows because many agents do not rely only on user messages. They call tools, retrieve operational state, and produce tool results that may be more authoritative than the natural-language conversation.
In the support notebook, a tool result can carry metadata such as tenant, source, and tags. The extraction policy can tell the memory layer to preserve tool-derived support facts, and selected metadata can be inherited into the extracted memory.
tool_thread = custom_memory.create_thread(
thread_id=f"tool_support_{RUN_ID}",
user_id=USER_ID,
agent_id=AGENT_ID,
memory_extraction_config=MemoryExtractionConfig(
memory_extraction_frequency=1,
enable_context_summary=False,
memory_extraction_custom_instructions=TOOL_AWARE_EXTRACTION_INSTRUCTIONS,
memory_extraction_inherit_message_metadata=["tenant", "source", "tags"],
),
) This pattern lets the application preserve not only the memory text, but also where the remembered fact came from. Later, scoped retrieval can use both natural-language query text and metadata filters.
tool_filtered_results = await tool_thread.search_async(
"replacement shipment delayed backordered hinge escalate",
max_results=5,
exact_thread_match=True,
record_types=["memory", "fact", "preference", "guideline"],
metadata_filter={
"tenant": "acme",
"source": "support-copilot",
"tags": ["support", "tool:order_status", "replacement"],
},
) 
Why Metadata Matters for Memory Governance
Memory retrieval should be relevant, but it also needs boundaries. In enterprise systems, an application may need to search only within a tenant, case, workflow, source system, or review state. Similarity ranking alone is not an authorization or governance model. Metadata filters complement, but do not replace, application authentication and authorization.
Metadata gives the application a way to constrain which memories are eligible before ranking. In this article’s use case, metadata can distinguish support-copilot facts from raw conversation messages, tag memories that came from an order-status tool, or keep tenant-specific facts scoped to the right customer context.
This is also why custom extraction and metadata inheritance belong together. Custom extraction shapes the content of the memory. Metadata inheritance shapes how that memory can be retrieved, filtered, reviewed, and governed later.
Running the Companion Notebook
The companion notebook starts with a practical database setup path. The setup cells connect to an Oracle AI Database schema, verify a simple query, and verify table-creation permissions before the memory store is initialized.
For a lightweight trial environment, developers can use FreeSQL to get an Oracle AI Database schema before moving to a managed development or production database environment.
That table-permission check matters because Oracle AI Agent Memory manages database-backed storage objects. If a developer can connect but cannot create tables, the memory workflow will fail later during schema setup. Surfacing that issue early makes the notebook more practical.
The notebook also sets the Developer Hub program identifier before creating the database connection pool. This follows the Developer Hub convention for technical assets that connect to Oracle AI Database and makes the notebook identifiable in database telemetry.
For environments with a database-resident embedding model, the same pattern can use Oracle AI Database-backed embeddings and Oracle AI Vector Search. For the custom extraction article, the main focus remains memory formation: how raw conversations become durable, domain-specific memories with the right policy and metadata.
For database-level retrieval background, see the Oracle AI Vector Search documentation.
What the Companion Notebook Demonstrates
- Connect to Oracle AI Database and verify table permissions.
- Set the Developer Hub program identifier before opening the database connection.
- Configure Oracle AI Agent Memory for a support workflow.
- Add a support conversation containing exact identifiers, support commitments, preferences, and details that should not become memory.
- Run baseline extraction as a general-purpose reference point.
- Apply support-specific custom extraction instructions.
- Compare extracted memories before and after customization.
- Override extraction instructions for one escalation thread.
- Update and clear thread-level extraction instructions.
- Extract tool-derived support facts and inherit selected metadata.
- Search with metadata filters to retrieve scoped memory results.
- Clean up memory records and database objects after the run.
Security and Deployment Notes
Custom extraction instructions are not a substitute for application security controls. Oracle AI Agent Memory persists data in the database schema selected by the application owner, while the surrounding application remains responsible for authenticating users, enforcing access control, and passing the correct user, agent, and thread scope into memory operations.
Applications should avoid sending secrets or unnecessary sensitive information into memory ingestion flows unless that behavior is explicitly intended and reviewed. Extraction instructions can guide what the model should preserve or ignore, but they should be treated as policy guidance rather than a hard redaction guarantee.
- Keep credentials, payment details, and one-time verification codes out of memory ingestion when possible.
- Use exact user, agent, thread, and tenant scope for retrieval.
- Use metadata filters for workflow boundaries such as source system, review status, or tool tag.
- Review custom extraction instructions with domain owners, not only with developers.
- Use cleanup steps in notebooks and development schemas to avoid leaving test data behind.
Conclusion
Custom memory extraction makes agent memory more useful by making it selective. Instead of treating every conversation as durable knowledge, developers can define what their application should preserve, which identifiers matter, what metadata should follow extracted memories, and when a specific thread needs a narrower policy.
For customer-support agents, this means future interactions can draw on the right facts: order IDs, delivery issues, return requests, escalation commitments, stable preferences, and tool-confirmed statuses. The agent gets memory that is easier to retrieve, easier to scope, and better aligned with the workflow it serves.
A practical way to start is with a narrow extraction policy, inspect the extracted memories, and then expand the policy and metadata taxonomy with domain owners.
Frequently Asked Questions
What is custom memory extraction?
Custom memory extraction lets developers guide what Oracle AI Agent Memory should preserve as durable memory and what it should ignore when processing conversation messages.
Why should an agent not remember everything?
Full transcripts contain temporary wording, repeated details, speculation, and sometimes sensitive data. Durable memory should preserve reusable facts, preferences, commitments, and workflow state.
What is the difference between baseline and custom extraction?
Baseline extraction shows general-purpose memory formation. Custom extraction adds domain-specific instructions so the memory output reflects the application’s workflow policy.
What is a thread-level extraction override?
A thread-level override is a custom extraction policy applied to one thread. It can narrow or change the default client-level policy for a specific workflow such as an escalation.
How does tool metadata help?
Tool metadata records where a memory came from and how it should be scoped. It can help retrieve only memories from a specific tenant, source system, or tool result.
Does the notebook require FreeSQL?
No. FreeSQL is a lightweight trial setup path. The same memory APIs can run against another Oracle AI Database environment with the required credentials and permissions.