# How Oracle AI Database Serves as a Unified Memory Core for AI Agents

> Discover how Oracle AI Database unifies vector embeddings, chat history, and more into one ACID-compliant engine. Learn how the MemoryManager queries all agent memory layers with a single connection.

- Repository: [Oracle Developers/oracle-ai-developer-hub](https://github.com/oracle-devrel/oracle-ai-developer-hub)
- Tags: architecture
- Published: 2026-05-10

---

**Oracle AI Database consolidates vector embeddings, relational chat history, JSON documents, and full-text search into a single ACID-compliant engine, enabling the `MemoryManager` class to query every agent memory layer through one database connection.**

The `oracle-devrel/oracle-ai-developer-hub` repository demonstrates a single-engine architecture where Oracle AI Database (formerly Oracle Database 26ai) eliminates the need for separate vector stores, key-value caches, and graph databases. Instead of wiring multiple data stores together, the platform stores every layer of agent memory—conversational turns, knowledge base embeddings, tool definitions, and entity relationships—inside one Oracle schema that supports hybrid SQL, vector search, and Oracle Text queries.

## The Seven Memory Types of a Unified Architecture

Oracle AI Database stores every kind of data an AI agent needs within a single schema, removing the operational complexity of piecing together multiple data stores. According to the repository’s documentation in [`notebooks/agent_memory/README.md`](https://github.com/oracle-devrel/oracle-ai-developer-hub/blob/main/notebooks/agent_memory/README.md) and [`workshops/agent_memory_workshop/docs/part-3-memory-engineering.md`](https://github.com/oracle-devrel/oracle-ai-developer-hub/blob/main/workshops/agent_memory_workshop/docs/part-3-memory-engineering.md), the platform abstracts seven distinct memory types, each backed by a specific table or vector-enabled store:

- **Conversational**: Relational table `chat_history` stores raw chat turns (role, content, timestamp) in a **CLOB** column for durability.
- **Knowledge Base**: Vector-enabled table `SEMANTIC_MEMORY` holds embeddings and full-text of research papers and documents.
- **Workflow**: Vector-enabled table `WORKFLOW_MEMORY` records step-by-step execution traces.
- **Toolbox**: Vector-enabled table `TOOLBOX_MEMORY` stores serialized tool definitions for retrieval.
- **Entity**: Vector-enabled table `ENTITY_MEMORY` captures named entities such as people, places, and financial instruments.
- **Summary**: Vector-enabled table `SUMMARY_MEMORY` contains compressed snapshots of older conversations.
- **Tool Log**: Relational table `TOOL_LOG` archives large tool outputs for later inspection.

Because all memory lives in the same database, agents can **join** across types. A single query can retrieve a relevant research paper via vector search and immediately join on `ENTITY_MEMORY` records to extract associated people, or combine relational filters (`WHERE year > 2020`) with vector similarity in one statement.

## Inside the MemoryManager Class

The core of this design is the **`MemoryManager`** class implemented in [`apps/finance-ai-agent-demo/backend/memory/manager.py`](https://github.com/oracle-devrel/oracle-ai-developer-hub/blob/main/apps/finance-ai-agent-demo/backend/memory/manager.py). This class provides CRUD methods for each memory layer and handles **scoping by `thread_id`**, ensuring every user or session operates within an isolated memory namespace.

Initialize the manager with a single `oracledb` connection that serves all memory operations:

```python
from apps.finance_ai_agent_demo.backend.memory.manager import MemoryManager

# conn is an oracledb.Connection already created elsewhere

mem = MemoryManager(
    conn=conn,
    conversation_table="CHAT_HISTORY",
    knowledge_base_vs=oracle_vs_kb,
    workflow_vs=oracle_vs_wf,
    toolbox_vs=oracle_vs_toolbox,
    entity_vs=oracle_vs_entity,
    summary_vs=oracle_vs_summary,
)

```

### Conversational Memory and Session State

The manager persists conversational turns using `write_conversational_memory` and retrieves context with `read_conversational_memory`, both scoped to a `thread_id`:

```python

# Store a user turn

turn_id = mem.write_conversational_memory(
    content="What is the interest rate for savings accounts?",
    role="user",
    thread_id="session-123",
)

# Retrieve recent context for the next LLM call

context = mem.read_conversational_memory(thread_id="session-123", limit=5)

```

### Semantic and Knowledge Base Storage

Vector embeddings for documents are stored via `write_knowledge_base`, which inserts into the `SEMANTIC_MEMORY` table:

```python
mem.write_knowledge_base(
    text="Savings accounts earn 0.5 % APY as of 2024‑Q1.",
    metadata={"source": "internal policy", "topic": "banking"},
)

```

## Durable Session Persistence with OracleSession

Session-level persistence is implemented in **Part 8** of the “From RAG to Agents” workshop, documented in [`workshops/from_rag_to_agents_workshop/docs/part-8-session-memory.md`](https://github.com/oracle-devrel/oracle-ai-developer-hub/blob/main/workshops/from_rag_to_agents_workshop/docs/part-8-session-memory.md). The **`OracleSession`** adapter stores JSON-encoded messages in the same `chat_history` table, proving that **session memory**—the mechanism allowing agents to recall prior turns across separate calls—is simply another view on the same durable relational table.

```python
from apps.from_rag_to_agents_workshop.docs.part_8_session_memory import OracleSession
import json

session = OracleSession(session_id="session-123", connection=conn)

# Store a JSON-encoded turn

await session.add_items([{"role": "assistant", "content": "The rate is 0.5 %"}])

# Retrieve full chronological history

history = await session.get_items()

# Controlled forgetting: pop the most recent turn

last_turn = await session.pop_item()

```

This design eliminates the need for external in-memory caches like Redis, as every write is **ACID-compliant** and survives container restarts or crashes.

## Hybrid Retrieval and Cross-Memory Joins

The unified query surface allows agents to mix `vector_distance` calculations with Oracle Text (`CONTAINS`) predicates. The `MemoryManager` implements hybrid retrieval in the `_read_toolbox_hybrid` method (lines 85‑99 of [`manager.py`](https://github.com/oracle-devrel/oracle-ai-developer-hub/blob/main/manager.py)), which merges vector similarity with full-text relevance using **Reciprocal Rank Fusion (RRF)** scoring:

```python

# Hybrid toolbox retrieval (vector + Oracle Text)

tools = mem.read_toolbox(query="search for latest rates", k=3)

# Returns OpenAI-compatible function schemas ranked by combined relevance

```

Performing both vector and lexical search within the same transaction boundary ensures high-quality tool retrieval without deploying a separate ranking service. The single `oracledb` connection handles authentication and transaction management for all operations, simplifying the agent architecture.

## Configuration and Vector Performance Tuning

Oracle AI Database automatically manages **HNSW indexes** for vector-enabled tables. For large corpora, the repository specifies tuning the `vector_memory_size` parameter via `ALTER SYSTEM SET`, as shown in [`workshops/information_retrieval_to_RAG/docs/part-1-oracle-setup.md`](https://github.com/oracle-devrel/oracle-ai-developer-hub/blob/main/workshops/information_retrieval_to_RAG/docs/part-1-oracle-setup.md):

```sql
ALTER SYSTEM SET vector_memory_size = 2G SCOPE = BOTH;

```

This provisioning ensures sufficient in-memory space for high-performance similarity searches across the knowledge base, workflow, and entity stores.

## Summary

- Oracle AI Database converges seven distinct memory types—conversational, semantic, workflow, toolbox, entity, summary, and tool logs—into a single schema.
- The `MemoryManager` class in [`apps/finance-ai-agent-demo/backend/memory/manager.py`](https://github.com/oracle-devrel/oracle-ai-developer-hub/blob/main/apps/finance-ai-agent-demo/backend/memory/manager.py) provides a unified CRUD interface scoped by `thread_id`.
- **ACID-compliant** storage in relational tables with CLOB columns ensures durable session persistence without external caches.
- Hybrid search combining `vector_distance` and Oracle Text `CONTAINS` enables high-precision retrieval within a single SQL connection.
- Vector performance is tuned via the `vector_memory_size` system parameter to support large-scale agent deployments.

## Frequently Asked Questions

### What is the difference between conversational memory and semantic memory in Oracle AI Database?

**Conversational memory** stores raw chat turns (user and assistant messages) in the `chat_history` relational table using CLOB columns for durability across sessions, while **semantic memory** stores vector embeddings and full-text of documents in the `SEMANTIC_MEMORY` table for similarity search. The former maintains dialogue state, while the latter provides the knowledge base for retrieval-augmented generation.

### How does OracleSession ensure chat history survives container restarts?

The `OracleSession` adapter writes JSON-encoded messages to the same `chat_history` table used by the `MemoryManager`, leveraging Oracle’s native **ACID transaction semantics**. Because data is persisted to disk rather than held in process memory, agents recover their full session state after crashes or container restarts by simply reconnecting to the database and querying by `session_id`.

### Can agents query vector embeddings and relational data in the same SQL statement?

Yes. Oracle AI Database supports hybrid queries that combine `vector_distance` functions for similarity search with standard relational predicates and Oracle Text `CONTAINS` clauses. This allows a single query to join vector-enabled tables like `SEMANTIC_MEMORY` with relational tables like `ENTITY_MEMORY` or `chat_history`, filtering by metadata columns while ranking by vector similarity.

### How is the vector memory size configured for large document corpora?

Administrators configure the `vector_memory_size` initialization parameter using `ALTER SYSTEM SET vector_memory_size = <size> SCOPE = BOTH`, as documented in the workshop setup guides. This allocates in-memory space for HNSW indexes used by vector-enabled tables such as `SEMANTIC_MEMORY` and `TOOLBOX_MEMORY`, ensuring low-latency similarity searches at scale.