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

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 and 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. 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:

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:

# 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:

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. 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.

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), which merges vector similarity with full-text relevance using Reciprocal Rank Fusion (RRF) scoring:

# 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:

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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}