In this release, the memory lifecycle becomes more explicit: memories can be created, connected, updated, superseded, retrieved, and governed over time.
Oracle AI Agent Memory is moving from durable recall toward memory that can evolve. The release includes graph-aware retrieval, image-aware memory, schema upgrade support, and enterprise controls. The main story for this article is Graph Memory support: memories can be connected through typed relationships, and retrieval can bring back not only directly matching memories, but also the linked context that explains how those memories relate over time.
The article builds on the public Oracle AI Agent Memory documentation and walks through the idea using the companion notebook, Graph-Aware Retrieval with Oracle AI Agent Memory.
Companion notebook: oracle_agent_memory_evolution.ipynb
Key Takeaways
- The 26.8 release extends Oracle AI Agent Memory beyond the previous release with graph-aware retrieval, image memory, schema upgrade logic, and enterprise control improvements.
- Graph Memory helps agents understand how facts relate instead of treating memory as a flat list of isolated records.
- Memory links can represent relationships such as supersedes, refines, supports, contradicts, and duplicates.
- Graph-aware retrieval can expand a direct search result with related context through settings such as num_hops and linked_results.
- Automatic linking during extraction should be the main developer experience: the application defines memory behavior, while related memories are linked as part of normal extraction.
- Explicit linking remains useful when an application has a confirmed workflow event, such as a replacement order superseding an older delivery promise.
- The companion notebook uses FreeSQL, Autonomous AI Database, and Oracle AI Database connection guidance, and sets the Developer Hub program identifier before creating any database connection.
| Release capability | What changed | Why it matters |
| Graph Memory | Memory records can now be connected with typed, directed relationships such as supersedes, refines, supports, contradicts, and duplicates. | Agents can understand how facts evolve instead of retrieving isolated memories with no relationship context. |
| Graph-aware retrieval | Search can expand from direct matches to linked memories using controls such as num_hops and max_linked_results. | Future agent turns can receive richer context while still keeping retrieval bounded. |
| Automatic memory linking | Memory extraction can identify and connect related memories as part of the normal extraction workflow. | Developers get memory evolution behavior without manually creating every relationship. |
| Image-aware memory | Images can be persisted as document records and searched through caller-provided descriptions or generated captions. | Agents can use screenshots, product images, forms, receipts, and support evidence as durable context without returning raw bytes by default. |
| Enterprise controls | Schema version 13, metadata scoping, Oracle Deep Data Security integration, persisted summaries, and pruning support more governed memory workflows. | Teams can keep memory useful, scoped, efficient, and easier to operate in production environments. |
Why This Release Matters
Persistent memory makes agents more useful because they can reuse durable context from previous interactions. But durable memory also creates a harder problem: facts change. A customer may update a delivery preference, a support case may be escalated, or a replacement commitment may replace an earlier promise. The agent should not lose history, but it also should not treat older facts as equally current.
Graph Memory addresses that gap by adding relationships between memory records. Instead of retrieving a single memory in isolation, the application can retrieve a direct match and the linked context around it. That makes memory evolution explainable: the agent can see what changed, which record is newer, and why another memory is relevant.
How Graph Memory Works
A useful technical model is to separate the feature into three layers. The memory record stores durable content. The memory link stores a typed relationship between two records. The retrieval layer decides whether to return only direct matches or to expand through eligible graph links.
The memory record is still the durable fact the agent may reuse later, such as a customer preference, case state, or support commitment. The memory link adds the missing relationship layer: it records that one memory supersedes, refines, supports, contradicts, or duplicates another memory. Graph-aware retrieval then decides how much of that relationship context should come back with the direct search result.
This separation is important for readers. Graph Memory is not just a different ranking strategy. It gives the memory system a relationship model that can preserve how facts evolve while still letting the application control retrieval scope.
Memory Link Types
The clearest way to introduce Graph Memory is through link types. Link types make the relationship explicit enough for applications and future agent turns to reason about it.
For example, supersedes is the right relationship when a newer memory should replace an older one for future use. In the notebook’s support scenario, an updated delivery window can supersede the original preference. Refines is useful when a newer memory makes an earlier memory more precise, such as narrowing a general morning-delivery preference to a specific time window. Supports is useful when a tool result or another confirmed record provides evidence for a memory. Contradicts and duplicates help model conflicting or repeated facts that the application may want to inspect or resolve.
The release models links as directed record relations. A relationship such as new_memory –supersedes–> old_memory keeps the newer memory as the source and the older memory as the target. Reverse traversal can present an opposite relationship for readability, but it does not change the stored direction of the relation.
Memory evolution also introduces lifecycle state. New memories are valid by default, while older records affected by supersedes, refines, or duplicate links can become invalid and remain available as historical context. That is the important design point: older memory is not simply deleted; it can still explain how the current state was reached.
What the Notebook Demonstrates
The notebook focuses on Graph Memory as the release’s main technical story because it underpins memory evolution. It is intentionally compact, but it still demonstrates the enterprise pattern: connect to Oracle AI Database, initialize or upgrade the managed schema, create durable memories, link them, compare normal search with graph-aware retrieval, and inspect linked results.
The walkthrough starts by installing and importing the required package, then checks that the installed package exposes the graph-memory APIs used by the workflow. It then configures a database-backed store using release-relevant hosted Oracle Database options: FreeSQL for a quick hosted demo, Autonomous AI Database for ADB validation, or Oracle AI Database for an existing service or connect descriptor. After that, the notebook initializes the managed schema, creates a small set of support memories, adds explicit links, compares direct and graph-aware search, and finally shows automatic linking during extraction. After that, the notebook initializes the managed schema, creates a small set of support memories, adds explicit links, compares direct and graph-aware search, and finally shows automatic linking during extraction.
This flow keeps the notebook close to the release story. The notebook uses graph-aware retrieval as the runnable path through the release because it is the clearest way to show memory evolution in practice. It does not try to demonstrate every new capability at once. Instead, it uses a narrow support scenario to show the most important behavior: memory can evolve through links, and retrieval can expose that linked context when the agent needs it.
Database Setup and ADB Guidance
Every Developer Hub technical asset that connects to Oracle Database should identify itself through the connection program name. The notebook sets the identifier once after imports and before the first connection is created.
Set the program identifier immediately after importing python-oracledb, before any pool or connection is created.
Set the Developer Hub program identifier
import oracledb
oracledb.defaults.program = "devrel-developerhub-graph-aware-retrieval-agent-memory"
The notebook then uses normal python-oracledb connection details for FreeSQL, Autonomous AI Database, or Oracle AI Database. This keeps the sample aligned with ADB-oriented usage while still giving readers a lightweight FreeSQL path for trying the notebook.
For database background, link to the Oracle AI Database 26ai documentation.
For readers using Autonomous Database, link to Oracle’s guide for downloading wallet/client credentials.
The python-oracledb ADB mTLS connection flow is also documented here: mTLS connection to Oracle Autonomous Database.
Initializing or Upgrading the Managed Schema
Graph Memory requires managed schema support for memory links and graph-aware retrieval. In this release, the managed schema advances to version 13. It adds the memory_link table and supporting indexes, adds lifecycle state and state-update time to memory records, and creates the memory_graph Oracle SQL Property Graph over memories and their links.
The notebook shows the pattern developers should use: choose the appropriate SchemaPolicy so the store can create or upgrade the required database objects when the environment allows it. For a fresh notebook environment, CREATE_IF_NECESSARY is convenient. For normal production startup after migration, teams should prefer REQUIRE_EXISTING so schema changes remain deliberate.
The store initialization keeps the schema policy visible. This is the line readers should notice when they want the sample to create or upgrade the managed schema for the release feature.
Initialize the managed memory store
from oracleagentmemory.stores.oracledb import OracleDBMemoryStore, SchemaPolicy
store = OracleDBMemoryStore(
**store_kwargs,
schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
)
The public takeaway is simple: release-aware notebooks should initialize the managed schema deliberately, and production teams should review schema changes before running upgrades in shared environments.
Explicit Links: When the Application Knows the Relationship
Explicit links are useful when the application already has a confirmed event. For example, a support workflow may know that a new replacement shipment supersedes an older delivery promise, or that an order-status tool result supports a memory extracted from conversation text.
Before linking anything, create a small set of support memories. This keeps the example grounded: Graph Memory is demonstrated on durable facts such as preferences, replacement context, and support state.
Add durable support memories
created = {}
for item in seed_memories:
result = memory.add_memory(
user_id=USER_ID,
agent_id=AGENT_ID,
text=item["text"],
metadata=item["metadata"],
)
created[item["label"]] = result
Use the release API for typed record relations. A new memory can be linked to an older memory with a relation such as supersedes, and applications can update or delete record links when workflow state changes.
Create explicit record links
relation_id = memory.link_records(
source_record_id=new_memory_id,
source_record_type="preference",
target_record_id=previous_memory_id,
target_record_type="preference",
relation_type="supersedes",
metadata={"reason": "new delivery preference"},
)
This turns workflow knowledge into durable relationship context. A future agent can retrieve both the current fact and the related historical fact, then understand why the newer memory should guide the response.
Automatic Linking During Extraction
Automatic linking is the feature to emphasize for developers. Most applications should not need to hand-code every relationship between memories. Instead, they can configure extraction behavior and let the memory workflow identify likely relationships as new memories are created.
This configuration supports the article’s main product message: automatic linking can make memory evolution mostly transparent to the developer.
Enable automatic link extraction
memory_extraction_config = MemoryExtractionConfig(
memory_extraction_frequency=1,
memory_link_extraction_mode=MemoryLinkExtractionMode.POST_EXTRACTION,
)The release exposes three modes: POST_EXTRACTION, DURING_EXTRACTION, and DISABLED. POST_EXTRACTION is the default and links memories after extracted memories are written, using candidate memories found by retrieval. DURING_EXTRACTION presents candidate memories during the extraction step, which can improve relationship quality at the cost of more work inside the extraction prompt. DISABLED preserves extraction behavior without automatic linking.
Automatic linking makes memory evolution mostly transparent, while explicit links remain available when the application has stronger workflow knowledge. add_memory() also exposes autonomous_linking, so applications can decide whether a directly added memory should participate in automatic link discovery.
Graph-Aware Search and linked_results
Graph-aware search starts with a direct query and can expand through memory links. With num_hops=0, the query returns direct matches. With num_hops=1, it can include one-hop linked memories. The linked context appears separately from the direct match so the application can inspect, format, or bound it before sending it to an agent prompt.
Run the same query twice: once with graph expansion disabled and once with one-hop graph expansion enabled.
Compare direct and graph-aware retrieval
direct_results = await memory.search(
query="What is the latest delivery preference?",
num_hops=0,
)
graph_results = await memory.search(
query="What is the latest delivery preference?",
num_hops=1,
max_linked_results=3,
)The key search switch is num_hops. With num_hops=0, the query behaves like direct memory search and returns only the matching records. With num_hops=1, retrieval can include one-hop linked memories around the direct match. max_linked_results bounds the amount of related context returned, which is important because graph expansion should improve the prompt, not flood it.
The release also adds include_invalid_results. Its default is True and it controls only top-level direct results. Invalid memories can still appear as linked results or traversal intermediates, because historical context may be necessary to explain how a valid memory evolved. Passing False excludes invalid memories from the top-level direct result list.
The notebook then inspects linked_results and uses formatted content to show how graph context becomes prompt-ready context. That is the practical bridge from database-backed memory to future agent behavior.
After graph-aware search, inspect the nested linked_results to see which related memories were returned with each direct result.
Inspect linked_results
linked_rows = []
for parent_rank, result in enumerate(graph_results, start=1):
for linked_rank, linked in enumerate(linked_results(result), start=1):
linked_rows.append(
{
"parent_rank": parent_rank,
"linked_rank": linked_rank,
"linked_memory": result_text(linked),
"relationship": getattr(linked, "link_type", getattr(linked, "relationship", "linked")),
}
)
display(pd.DataFrame(linked_rows))The final graph section shows how the retrieved memory and its linked context can be rendered into content that is ready to pass to an agent prompt.
Render prompt-ready graph context
if graph_results:
top_result = graph_results[0]
if hasattr(top_result, "format_content"):
print(top_result.format_content())Enterprise Controls Still Matter
Graph-aware retrieval does not replace metadata filtering, tenancy boundaries, application authorization, or security review. It complements them. The application should still constrain which memories are eligible before ranking and graph expansion. Then graph-aware retrieval can provide better context inside those boundaries.
This matters for enterprise agents because memory is not just recall. It is governed context. The system should retrieve facts that are relevant, current enough for the workflow, and scoped to the right tenant, user, case, source, and review state.
For retrieval background at the database layer, readers can also review Oracle AI Vector Search documentation. Graph-aware retrieval builds on the same need for relevant context, but adds relationship context around memory records.
Other Release Capabilities
After the graph-memory workflow, the release adds several capabilities that extend how agents store, retrieve, and govern memory. Graph Memory is the main focus of this article because it underpins memory evolution, but the broader 26.8 release also introduces image-aware memory, schema version upgrade logic, Oracle Deep Data Security integration, persisted summaries, list APIs, and post-search pruning.
Image-aware memory extends the same durable-memory idea to visual inputs. Images can be stored as standalone records or attached to messages, with image data persisted in the DOCUMENT table. MESSAGE.content can represent ordered text and image content parts, so a message can preserve multimodal context. Search remains text-first: caller-provided descriptions or generated captions are indexed and retrieved, while raw image bytes are returned only when explicitly requested. Image-aware memory extraction is configurable and disabled by default.
Oracle Deep Data Security is an opt-in enterprise control that enforces access in Oracle Database using the authenticated end-user security context. In this overview, it should be positioned at a high level: DDS complements application-layer controls and deserves a deeper dedicated article when the team wants to explain policy administration and runtime security context.
Persisted summaries move thread summaries into the managed database schema, so summaries can survive process restarts and be reused by another thread handle or client. Post-search pruning adds search configuration options such as TopKMemorySearchConfig, PruningMemorySearchConfig, reranking, pruning, and token budgets. Together, these features keep retrieved context more useful and bounded before it enters an agent prompt or context card.
Conclusion
Oracle AI Agent Memory 26.8 makes memory more useful for agents that operate over time. Graph-aware retrieval is the centerpiece because it gives agents a way to understand memory evolution instead of treating every memory as an isolated fact.
For developers, the most important pattern is simple: start with durable memory, let automatic linking handle common memory evolution cases, use explicit links when the workflow already knows the relationship, and keep retrieval scoped through metadata and application controls.
To try the pattern, open the companion notebook and run the support scenario that compares baseline search with graph-aware retrieval through linked_results.
Frequently Asked Questions
What is graph-aware retrieval?
Graph-aware retrieval searches memory records and can also return related records connected through memory links. This gives the agent relationship context, not only similar text.
How is this different from normal vector search?
Vector search finds semantically similar memories. Graph-aware retrieval can add linked memories that explain how a fact evolved, which memory supersedes another, or which record supports a current fact.
Do developers need to create every link manually?
No. Explicit links are useful for confirmed application events, but automatic linking during extraction should be the main experience for common memory evolution behavior.
Does graph-aware retrieval replace security controls?
No. Metadata filters, tenant boundaries, authorization, and security policies still define which memories are eligible. Graph-aware retrieval works inside those boundaries.
Where can developers get the package?
The package is published as oracleagentmemory on PyPI. Developers should use the release version that includes graph memory APIs before running the graph-aware retrieval notebook.