Use Oracle AI Agent Memory hybrid search when persistent AI agent memory needs both semantic similarity and exact text precision.
Companion Notebook: Hybrid Search for Oracle AI Agent Memory: Combining Semantic Recall with Exact Match
Key Takeaways
- Vector search is strong for semantic recall, but agent memory often contains exact strings that should remain first-class retrieval signals.
- Identifiers such as issue IDs, invoice numbers, error codes, customer aliases, and SKUs can determine whether a retrieved memory is correct.
- Keyword search handles exact text well but misses relevant context when users ask with different wording.
- Hybrid search combines semantic retrieval and exact text matching so agents can recall both the named item and the surrounding context.
- Scoped retrieval and hybrid search solve different parts of the problem: scope controls which memories are eligible to be searched, while hybrid search controls how those eligible memories are ranked.
- Oracle AI Agent Memory uses `SearchStrategy.HYBRID` with `OracleDBEmbedder`, while `SearchIndexSyncMode` controls managed search-index refresh behavior.
- The companion notebook validates hybrid retrieval across five exact, semantic, and mixed-query scenarios using deliberately similar memories and confirms the expected memory at rank one in every scenario.
This guide shows how to build hybrid retrieval for agent memory with Oracle AI Agent Memory, combining semantic recall with exact text matching.
The retrieval problem hybrid search solves
A useful agent memory system has to do two things at once. It must remember by meaning when the user paraphrases, and it must stay exact when the user refers to a specific business object, system event, or operational handle. Many retrieval misses happen in the gap between those two needs: the query is semantically close to several memories, but only one memory contains the exact identifier that should anchor the answer.
Hybrid search closes that gap. Instead of treating semantic recall and exact text matching as separate retrieval systems, it gives the memory layer a combined path for vector and keyword search. The agent can retrieve the surrounding context and preserve the literal token that makes the memory trustworthy.
That is the core value of agent memory hybrid search: long-term agent memory can stay flexible without losing the exact text that enterprise workflows depend on.
This article uses one support/finance scenario throughout. A customer alias, Northstar Renewals, has a renewal blocker tied to invoice INV-48291 after reconciliation failed with ORA-27102. The examples show how hybrid search retrieves the right memory when the user asks by exact identifier and when they ask by meaning.
Setting up Oracle AI Agent Memory
Oracle AI Agent Memory provides a durable memory layer for AI agents. It stores scoped memories, retrieves relevant context for later turns, and helps applications separate what the agent is allowed to remember from how memories are ranked.
Hybrid search expands that retrieval model so an agent can recall by semantic meaning and by exact text in the same workflow, while memory governance remains tied to scope and application policy.
The setup has four main components:
- `OracleAgentMemory` is the durable memory layer. It stores memories, applies scope, and exposes search.
- `OracleDBEmbedder` connects retrieval to Oracle-backed embedding behavior used by the memory store.
- `SearchStrategy.HYBRID` tells the memory layer to combine semantic and exact-text retrieval signals.
- `SearchIndexSyncMode` controls when the managed search index is refreshed after memories are written.
Start by installing the oracleagentmemory package in the notebook or application environment. The hybrid-search API is configured in application code; the database schema and index setup are handled through the Oracle-backed memory store.
This makes Oracle AI Database agent memory a practical pattern for applications that need durable memories, scoped retrieval, and database-managed search.
```bash
pip install oracleagentmemory==26.6.0
``` The core imports for a hybrid-search configuration look like this:
```python
from oracleagentmemory.apis.searchscope import SearchScope
from oracleagentmemory.core import (
MemoryExtractionConfig,
OracleAgentMemory,
SchemaPolicy,
SearchIndexSyncMode,
SearchStrategy,
)
from oracleagentmemory.core.embedders import OracleDBEmbedder
``` Why vector memory is not always enough
Agent memory is not only a semantic archive of previous conversations. In enterprise systems, memory records often include short strings that carry operational meaning.
A single identifier can point to the correct incident, invoice, customer, model, file, run, or database error. If retrieval treats that identifier like ordinary prose, the agent can return a memory that is semantically related but operationally wrong.
Vector search helps when users paraphrase. It is especially useful when a user asks about a topic without repeating the exact words stored in memory.
But vector similarity is not the same as exactness. A short token can be diluted by the rest of the sentence, especially when the surrounding context is broad or when several memories are about similar workflows.
Where exact text matters
Exact text matters whenever a memory must point to a specific object rather than a general topic. Common examples include:
- Issue IDs and ticket references used in engineering and support workflows.
- Invoice, order, contract, and purchase-order numbers used in business workflows.
- Database, application, and integration error codes used in troubleshooting.
- Customer aliases, account IDs, and tenant names used for scoped recall.
- Product SKUs, model numbers, filenames, branch names, and run IDs used by operational agents.
These values are small, but they often carry more authority than nearby prose. A robust agent memory layer should preserve that literal signal while still supporting semantic lookup and exact-match retrieval.
Types of search
| Vector search | Keyword search | Hybrid search |
| Finds by meaning and paraphrase | Finds by exact text (literal identifiers) | Combines semantic and exact-text signals in one ranked retrieval path |
| Example query: “What blocked the renewal?” | Example query: “INV-48291” | Example queries: “INV-48291” and “What blocked the renewal?” |
The differences become clearer when you compare what each mode optimizes for.
The following comparison explains the retrieval modes conceptually. The companion notebook executes the hybrid configuration and evaluates it across exact, semantic, and mixed queries; it is not a benchmark of three separately executed strategies.
| Mode | Best at | Weak spot | Agent memory fit |
| Vector search | Paraphrase, semantic similarity, concept recall | Short identifiers may be low-signal | Good for natural-language recall |
| Keyword search | Literal identifiers, error codes, aliases, filenames | Brittle when wording changes | Good when exact strings matter |
| Hybrid search | Natural language plus exact handles | Requires database embedding and managed index setup | Strong fit when both semantic and exact-text retrieval matter |
Use hybrid search when:
- Users ask in natural language but refer to exact business objects.
- Memories include identifiers, aliases, filenames, error codes, or transaction IDs.
- Several memories are semantically similar, but one exact token should decide the result.
- The agent needs scoped retrieval across user, agent, tenant, or thread boundaries.
How Oracle AI Agent Memory supports hybrid retrieval for agent memory
Oracle AI Agent Memory exposes hybrid retrieval as a memory-store configuration. The application supplies an Oracle-backed embedder, selects `SearchStrategy.HYBRID`, and chooses an index synchronization mode. The result is one memory layer that can retrieve by meaning and exact text over the same stored memories, while still respecting user, agent, and thread scope.
`OracleDBEmbedder` is important because hybrid search relies on the database-managed embedding and index path. `SearchStrategy.HYBRID` selects the hybrid retrieval backend. `SearchIndexSyncMode` defines when new or updated memory content becomes searchable through the managed index. Together, these settings make retrieval behavior explicit in application code rather than hiding it behind an ad hoc query pipeline.
The configuration below shows the minimum pattern: choose an Oracle-backed embedder, set `SearchStrategy.HYBRID`, and choose how the search index should refresh:
```python
db_embedder = OracleDBEmbedder(
connection=connection,
model=CONFIG["ORACLE_DB_EMBEDDING_MODEL"],
embedding_dimension=CONFIG["ORACLE_DB_EMBEDDING_DIMENSION"],
)
memory = OracleAgentMemory(
connection=connection,
embedder=db_embedder,
memory_extraction_config=MemoryExtractionConfig(
extract_memories=False
),
schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
search_strategy=SearchStrategy.HYBRID,
search_index_sync=SearchIndexSyncMode.ON_COMMIT,
memory_store_id="hybrid_blog",
)
``` Memory extraction is disabled because the example inserts controlled durable memories directly and focuses specifically on retrieval behavior.
In a typical workflow, the agent writes durable memories with user, agent, or thread scope. Later, search requests use `SearchScope` to restrict eligible records before ranking happens. That separation matters: scope decides what the agent is allowed to remember, while hybrid search decides how eligible memories are ranked.
Hybrid retrieval flow
In an agent workflow, hybrid search is most useful when it sits between memory scoping and context assembly:
`SearchScope` and hybrid search are complementary. Scope determines which records are eligible for retrieval; hybrid search ranks only those eligible records. In the notebook, each evaluation query uses the same generated finance-user and support-agent scope, and retrieval is restricted to durable memory records by passing `record_types=[“memory”]`.
This flow is the reason hybrid search fits agent memory well. The application first narrows the memory universe with scope. Hybrid retrieval then combines semantic and exact-text signals only over eligible records. The final output is not just a matching row; it is a ranked context package the agent can use in the next step.
```python
user_id = "finance_user_123"
agent_id = "support_finance_agent"
scope = SearchScope(user_id=user_id, agent_id=agent_id)
memory.add_memory(
content=(
"Northstar Renewals has a renewal blocker: invoice INV-48291 "
"failed reconciliation after ORA-27102 during month-end processing."
),
user_id=user_id,
agent_id=agent_id,
)
async def search_memory(query, scope, max_results=5):
return await memory.search_async(
query=query,
scope=scope,
max_results=max_results,
record_types=["memory"],
)
exact_results = await search_memory("INV-48291", scope)
semantic_results = await search_memory(
"What blocked the Northstar renewal?",
scope,
)
``` Both calls use the same `SearchScope`, hybrid strategy, and managed hybrid index. Only the query style changes.
For example, a user might ask “INV-48291” or “What blocked the renewal?” over the same scoped memories.
A vector-only search may understand the renewal-blocker question but underweight the exact invoice or error code. A keyword-only search may find INV-48291 or ORA-27102 but miss a paraphrased question such as “What blocked the renewal?”
Hybrid search gives both signals a chance to influence ranking, so the agent can retrieve the Northstar Renewals memory with the exact invoice ID, the ORA-27102 error code, and the natural-language explanation.
Testing hybrid retrieval with deliberately similar memories
The companion notebook does not test hybrid retrieval against a single obvious memory. It creates a deliberately similar set of memories, so the retrieval path has to choose between records that share overlapping business, invoice, customer, renewal, and error-code vocabulary.
The notebook stores five durable memories:
- A target renewal-blocker memory for Northstar Renewals, containing invoice INV-48291, Oracle error ORA-27102, and the failed reconciliation that blocked the renewal.
- A neighboring invoice memory for Northstar Renewals, containing invoice INV-48290, which is marked as paid and does not require follow-up.
- A different customer renewal-delay memory for Milan Office Supplies, where the delay is caused by an approval workflow rather than reconciliation.
- A general ORA-27102 troubleshooting memory that explains the database error without tying it to the Northstar invoice.
- A Northstar customer-alias memory that maps Northstar Renewals to its enterprise account name.
This setup makes the demonstration more realistic. The expected result must outrank memories that are partially similar, such as another Northstar invoice, another renewal delay, or another ORA-27102-related record. That is the behavior an enterprise agent memory system needs: not just finding something related but retrieving the memory that preserves the right operational detail.
Evaluating exact, semantic, and mixed queries
The notebook then evaluates the same hybrid-search configuration across five query scenarios. Each query uses the same `SearchScope`, the same `SearchStrategy.HYBRID` configuration, and the same managed hybrid index. Only the query wording changes.
The five query categories are:
- Exact invoice identifier: a query for INV-48291.
- Exact Oracle error code: a query for ORA-27102.
- Semantic renewal-blocker question: a natural-language question about what blocked the Northstar renewal.
- Semantic customer question: a natural-language question about the Milan customer renewal delay.
- Mixed customer and invoice question: a question that combines customer context with invoice reconciliation.
The validation checks whether the expected memory appears as the top-ranked result.
| Query type | Expected memory | Rank | Validation |
| Exact invoice ID | Renewal blocker | 1 | PASS |
| Exact error code | Error reference | 1 | PASS |
| Semantic renewal question | Renewal blocker | 1 | PASS |
| Semantic customer question | Milan renewal | 1 | PASS |
| Mixed customer and invoice question | Renewal blocker | 1 | PASS |
This is a controlled functional evaluation, not a statistical benchmark comparing vector, keyword, and hybrid search. The purpose is to show that one hybrid-search configuration can retrieve the expected durable memory across exact, semantic, and mixed query styles.
Reading the notebook results
The results show that exact identifiers remained useful retrieval signals. The invoice query returned the renewal-blocker memory, while the ORA-27102 query returned the general error-reference memory. This matters because both the target renewal memory and the general troubleshooting memory contain the same error code, but they serve different user intents.
The semantic queries also returned the intended memories without requiring the user to repeat the exact stored wording. For example, the renewal-blocker question retrieved the Northstar renewal memory, while the Milan customer question retrieved the separate Milan renewal-delay memory.
The mixed query is the most representative enterprise case. It combines business context with an implied operational object: the user asks which invoice failed reconciliation for Northstar. The expected result is the memory containing INV-48291, ORA-27102, and the failed reconciliation context.
The notebook also displays distance values for the ranked results. In this result set, smaller distance values indicate stronger matches. However, distance should be treated as a retrieval signal for inspection, not as a universal accuracy score. The more important validation is whether the expected memory was returned at rank one for each query.
How hybrid search improves enterprise agent accuracy
Hybrid search improves retrieval accuracy because it matches how enterprise memory is actually written. A memory record rarely contains only natural-language explanation or only an identifier. It usually contains both: a named handle plus the context that explains why the handle matters.
- Higher precision for identifier-driven questions because exact strings can influence ranking.
- Better recall for paraphrased questions because semantic search still finds related memory records.
- More useful context packages because the agent can retrieve both the handle and the surrounding explanation.
- Lower risk of plausible but wrong recall when several memories are semantically similar.
- Developers can inspect the ranked memories, metadata, and distances to verify whether the expected operational context was retrieved.
This is especially useful for support agents, finance assistants, operations copilots, developer agents, and workflow agents that must remember prior decisions, tool outputs, system errors, or customer-specific context.
The practical benefit is not only better search quality; it is better agent behavior.
Better retrieval can improve grounding, but the model still needs normal validation and application controls. Hybrid search gives the retrieval layer a stronger chance of selecting the memory that a human operator would have recognized immediately.
Production notes: schema and index setup
For production, treat hybrid search as part of the memory-store design, not as a last-minute query option. The schema should be owned by a dedicated application user with the right privileges, tablespace quota, and deployment controls. Memory scope should also match the application boundary, such as user, agent, tenant, or thread.
`SchemaPolicy.CREATE_IF_NECESSARY` is useful during first-time setup or when upgrading a schema so it can support hybrid search. For a large existing memory store, the first hybrid index build may take time because Oracle needs to prepare the managed search structures over stored memory content. Treat that step as a planned migration rather than a normal application startup task.
After the schema and index are ready, production applications may prefer `SchemaPolicy.REQUIRE_EXISTING`. That lets startup validate the expected schema instead of creating or modifying database objects.
`SearchIndexSyncMode` is a freshness and operations tradeoff:
- `ON_COMMIT` is best for notebooks, demos, and interactive applications because newly committed memories become searchable immediately.
- `MANUAL` is useful for bulk loads, backfills, and migrations where teams want to ingest many records first and refresh the index on a controlled schedule.
- `AUTO` delegates background maintenance to Oracle-managed behavior, which can fit production workloads where some freshness lag is acceptable. `AUTO` is supported for `SearchStrategy.HYBRID`; keyword-only search does not support `AUTO`.
The database-resident embedding model is also part of the production contract. The same model and embedding dimension should be used by `OracleDBEmbedder` and the managed hybrid index so query embeddings and indexed memory vectors remain compatible.
Before publishing an agent that depends on durable memory, test the retrieval path with representative records. Include exact-identifier queries, semantic queries, mixed queries, scoped retrieval checks, and index freshness checks after writes. If the application has many similar records, include distractor memories in the test set so the expected result has to outrank nearby alternatives.
Teams can also pair hybrid retrieval with custom memory extraction when they need more predictable stored facts. Extraction controls what gets remembered; scope controls which records are eligible; hybrid search controls how eligible memories are ranked.
Conclusion
AI agent memory needs more than semantic similarity. Vector search helps agents remember by meaning, but enterprise workflows often depend on exact strings such as invoice numbers, error codes, customer aliases, file names, and transaction IDs. Keyword search helps with those strings, but it can be brittle when users ask in natural language.
Hybrid search gives the memory layer a practical middle ground. It preserves literal identifiers while still supporting semantic recall, so an agent can retrieve both the named object and the context that explains why it matters.
In the companion notebook, one `SearchStrategy.HYBRID` configuration retrieves the expected durable memory across exact, semantic, and mixed query styles. The deliberately similar memory set makes the demo more realistic: the target memory has to outrank records that overlap on customer, invoice, renewal, or error-code vocabulary.
For Oracle AI Agent Memory, `SearchStrategy.HYBRID`, `OracleDBEmbedder`, `SearchScope`, and `SearchIndexSyncMode` provide the core application controls for this pattern. Together, they help developers build memory systems that are scoped, durable, searchable by meaning, and precise when exact text matters.
Run the companion notebook to configure Oracle AI Agent Memory hybrid search, load the deliberately similar memory set, and inspect the ranked results for exact, semantic, and mixed queries.
Frequently Asked Questions
What is Oracle AI Agent Memory? Oracle AI Agent Memory is a durable memory layer for AI agents. It lets applications store memories, retrieve relevant context later, and use scope controls such as user, agent, and thread scope so the agent searches only eligible memories before ranking results.
Why use hybrid search for agent memory? Hybrid search is useful for agent memory because many memories contain both meaning and exact text. Vector search helps with paraphrased questions, while keyword search helps with identifiers such as issue IDs, SKUs, invoice numbers, aliases, and error codes. Hybrid search combines both signals so the agent can retrieve the right memory and the surrounding context.
Is vector search still useful for agent memory? Yes. Vector search remains essential for paraphrase, concept recall, and long natural-language memories. Hybrid search adds exact-text strength instead of replacing vector search.
How do I build hybrid retrieval for agent memory? Configure OracleAgentMemory with `OracleDBEmbedder`, set `SearchStrategy.HYBRID`, choose `SearchIndexSyncMode`, store scoped memories, then test exact, semantic, and mixed queries.
When should I use keyword-only search? Use keyword-only search when retrieval is almost entirely literal text matching and embeddings are unnecessary. Many agent memory workloads need both exact strings and semantic context, which makes hybrid search a better default.
What is the difference between scoped retrieval and hybrid search? Scoped retrieval controls which memories are eligible to be searched. Hybrid search controls how those eligible memories are ranked using both semantic and exact-text signals.
Why does hybrid search require `OracleDBEmbedder`? The hybrid path uses Oracle-managed indexing and database-side embedding metadata. `OracleDBEmbedder` keeps the application embedder aligned with the database-backed retrieval path.
Which `SearchIndexSyncMode` should I start with? For notebooks and interactive demos, `ON_COMMIT` is the simplest starting point. For bulk ingestion, `MANUAL` gives more control. `AUTO` is useful when Oracle-managed hybrid index maintenance fits the workload.
What should I test before publishing an agent memory workflow? Test exact-identifier queries, semantic queries, scoped retrieval, index freshness after writes, and behavior when multiple similar memories exist. The strongest demos show both exact and natural-language retrieval over the same records.