SETUP.md

MemoRizz Setup Guide for Oracle AI Database

This guide provides step-by-step instructions for setting up MemoRizz with Oracle AI Database on your local machine.

Table of Contents

1. Prerequisites
2. Quick Start
3. Detailed Setup
4. Configuration
5. Verification
6. Troubleshooting
7. Next Steps

---

Prerequisites

Before you begin, ensure you have the following installed:

Required Software

• Python 3.7+ - Check with python --version or python3 --version
• Docker - Required for running Oracle Database locally
  • Check with docker --version
  • Install from docker.com
  • Apple Silicon Note: Oracle Free may require emulation. Use PLATFORM_FLAG="--platform linux/amd64" if you encounter issues
• Git - For cloning the repository (if installing from source)
• python-dotenv (Optional but recommended) - For .env file support
  • Install with: pip install python-dotenv

Required Python Packages

Install MemoRizz and Oracle driver:

# Install MemoRizz
pip install memorizz

# Install Oracle driver (or use: pip install memorizz[oracle])
pip install oracledb

# Install OpenAI SDK (for LLM and embeddings)
pip install openai

Hugging Face support: Sentence Transformers + Transformers + Accelerate are bundled with the base memorizz wheel, so no extra install command is required before selecting embedding_provider="huggingface" or the Hugging Face LLM provider.

API Keys

• OpenAI API Key - Required for embeddings and LLM functionality
  • Get one at platform.openai.com

---

Quick Start

For a quick setup with default settings, follow these steps:

Step 1: Start Oracle Database

# Make the script executable (if needed)
chmod +x install_oracle.sh

# Start Oracle Database
./install_oracle.sh

For Apple Silicon (M1/M2/M3) users:

# Oracle Free may require emulation on ARM64
export PLATFORM_FLAG="--platform linux/amd64"
./install_oracle.sh

Oracle Image Version Selection:

# Use lite version (default, 1.78GB - recommended for development)
./install_oracle.sh

# Use full version (9.93GB - includes all features)
export ORACLE_IMAGE_TAG="latest"
./install_oracle.sh

# Use custom tag
export ORACLE_IMAGE_TAG="custom-tag"
./install_oracle.sh

This will:

• Pull Oracle Database 23ai Free Lite Docker image (1.78GB, default) if not already present
• Create a persistent Docker volume (oracle-memorizz-data) for data storage
• Create and start a container named oracle-memorizz
• Wait for the database to be ready (~2-3 minutes)
• Data persists between container restarts thanks to the Docker volume

Oracle Image Versions:

• Lite version (default): latest-lite - 1.78GB, faster download, recommended for development
• Full version: latest - 9.93GB, includes all features and tools
• Custom tag: Any other tag can be specified via ORACLE_IMAGE_TAG

To use the full version:

export ORACLE_IMAGE_TAG="latest"
./install_oracle.sh

Default Connection Details:

• Host: localhost
• Port: 1521
• Service Name: FREEPDB1
• Admin User: system
• Admin Password: MyPassword123!

Note: The Docker volume ensures your data persists even if you stop/remove the container. To remove all data, delete the volume: docker volume rm oracle-memorizz-data

Step 2: Set Up Database Schema

Option A: Using CLI command (Recommended - works for all installation methods)

# After installing memorizz[oracle]
memorizz setup-oracle

# Or using Python module
python -m memorizz.cli setup-oracle

Option B: Using the examples script (Repo-cloned users only)

# Only works if you cloned the repository
# Note: CLI command (Option A) is recommended for most users
python examples/setup_oracle_user.py

Option C: Using Python directly

from memorizz.memory_provider.oracle.setup import setup_oracle_user

setup_oracle_user()

Automatic Mode Detection

The setup function automatically detects your database configuration and adapts:

Admin Mode (Local/Self-Hosted Databases):

• Detects when admin credentials are available
• Creates new user with all required privileges
• Grants permissions automatically
• Full setup with user creation

User-Only Mode (Hosted Databases like FreeSQL.com):

• Detects when admin access is not available
• Uses your existing schema/user
• Checks available privileges
• Creates tables and views in your schema
• Warns about missing privileges

What the setup does:

• ✅ Automatically detects setup mode (admin vs user-only)
• ✅ Creates relational schema (12 tables + indexes)
• ✅ Creates JSON Duality Views (10 views)
• ✅ Verifies the setup
• ✅ Shows detected mode and available privileges

Default Credentials (Local Docker):

• User: memorizz_user
• Password: SecurePass123!
• DSN: localhost:1521/FREEPDB1

For Hosted Databases (FreeSQL.com, etc.):

• Set ORACLE_USER to your existing schema username
• Set ORACLE_PASSWORD to your schema password
• Set ORACLE_DSN to your database connection string
• The setup will automatically use user-only mode

Step 3: Configure Your Application

Option A: Using .env file (Recommended)

# Copy the example file
cp .env.example .env

# Edit .env and fill in your credentials
# Then load it in your Python code:

from dotenv import load_dotenv
load_dotenv()  # Loads from .env file

import os
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
ORACLE_USER = os.getenv("ORACLE_USER")
# ... etc

Option B: Environment Variables

export OPENAI_API_KEY="your-openai-api-key"
export ORACLE_USER="memorizz_user"
export ORACLE_PASSWORD="SecurePass123!"
export ORACLE_DSN="localhost:1521/FREEPDB1"

See examples/example_with_env.py for a complete example using .env files.

Step 4: Create Your First Agent

import os
from memorizz.memory_provider.oracle import OracleProvider, OracleConfig
from memorizz.memagent.builders import MemAgentBuilder

# Set up your API keys
os.environ["OPENAI_API_KEY"] = "your-openai-api-key"

# Configure Oracle memory provider
oracle_config = OracleConfig(
    user=os.environ.get("ORACLE_USER", "memorizz_user"),
    password=os.environ.get("ORACLE_PASSWORD", "SecurePass123!"),
    dsn=os.environ.get("ORACLE_DSN", "localhost:1521/FREEPDB1"),
    embedding_provider="openai",
    embedding_config={
        "model": "text-embedding-3-small",
        "api_key": os.environ["OPENAI_API_KEY"]
    }
)
oracle_provider = OracleProvider(oracle_config)

# Create a MemAgent using the builder pattern
agent = (MemAgentBuilder()
    .with_instruction("You are a helpful assistant with persistent memory.")
    .with_memory_provider(oracle_provider)
    .with_llm_config({
        "provider": "openai",
        "model": "gpt-4o-mini",
        "api_key": os.environ["OPENAI_API_KEY"]
    })
    .build()
)

# Save the agent to Oracle
agent.save()

# Start conversing - the agent will remember across sessions
response = agent.run("Hello! My name is John and I'm a software engineer.")
print(response)

# Later in another session...
response = agent.run("What did I tell you about myself?")
print(response)  # Agent remembers John is a software engineer

---

Detailed Setup

Customizing Credentials

You can customize all credentials using environment variables:

For Oracle Database Container

# Set custom admin password before starting Oracle
export ORACLE_ADMIN_PASSWORD="YourSecurePassword123!"
./install_oracle.sh

# Or use full version instead of lite (default)
export ORACLE_IMAGE_TAG="latest"
export ORACLE_ADMIN_PASSWORD="YourSecurePassword123!"
./install_oracle.sh

For Database Schema Setup

# Set custom credentials before running setup
export ORACLE_ADMIN_USER="system"
export ORACLE_ADMIN_PASSWORD="YourSecurePassword123!"
export ORACLE_USER="memorizz_user"
export ORACLE_PASSWORD="YourMemorizzPassword123!"
export ORACLE_DSN="localhost:1521/FREEPDB1"

python examples/setup_oracle_user.py

Environment Variables Reference:

Variable	Default	Description
ORACLE_ADMIN_USER	system	Oracle admin username
ORACLE_ADMIN_PASSWORD	MyPassword123!	Oracle admin password
ORACLE_IMAGE_TAG	latest-lite	Oracle Docker image tag (options: latest-lite 1.78GB, latest 9.93GB, or custom)
ORACLE_USER	memorizz_user	MemoRizz database user
ORACLE_PASSWORD	SecurePass123!	MemoRizz database password
ORACLE_DSN	localhost:1521/FREEPDB1	Oracle connection string
ORACLE_TABLESPACE_NAME	auto (MEMORIZZ_USER_TS)	Target tablespace for VECTOR columns; created if missing
ORACLE_DATAFILE_DIR	auto-detected	Directory for new tablespace datafile (useful when Oracle Managed Files is disabled)
ORACLE_TABLESPACE_DATAFILE	auto-detected	Full path override for new tablespace datafile
ORACLE_TABLESPACE_SIZE_MB	100	Initial datafile size for the created tablespace
ORACLE_TABLESPACE_AUTOEXTEND_MB	10	Autoextend increment for the created tablespace
OPENAI_API_KEY	(required)	OpenAI API key for embeddings/LLM
PLATFORM_FLAG	(empty)	Docker platform flag (use --platform linux/amd64 for Apple Silicon)

Manual Oracle Setup (Alternative)

If you prefer to set up Oracle manually or use an existing Oracle instance:

1. Start Oracle Database

Using Docker:

# Lite version (1.78GB, recommended)
docker pull container-registry.oracle.com/database/free:latest-lite

docker run -d \
  --name oracle-memorizz \
  -p 1521:1521 \
  -e ORACLE_PWD=MyPassword123! \
  container-registry.oracle.com/database/free:latest-lite

# Or full version (9.93GB)
# docker pull container-registry.oracle.com/database/free:latest
# docker run -d --name oracle-memorizz -p 1521:1521 \
#   -e ORACLE_PWD=MyPassword123! \
#   container-registry.oracle.com/database/free:latest

# Wait for database to be ready
docker logs -f oracle-memorizz
# Wait until you see: "DATABASE IS READY TO USE!"

Using Existing Oracle Instance:

• Ensure Oracle Database 23ai or later is running
• Note your connection details (host, port, service name)

Using Hosted Databases (FreeSQL.com, Oracle Cloud, etc.):

• Sign up for a hosted Oracle database service
• Get your connection credentials (user, password, DSN)
• Set environment variables and run setup (see below)
• The setup will automatically detect user-only mode

2. Create Database User (Manual SQL)

Note: For hosted databases, skip this step - you'll use your existing schema. The automated setup will detect this automatically.

Connect as SYSTEM or DBA:

-- Create user
CREATE USER memorizz_user IDENTIFIED BY "SecurePass123!";

-- Grant basic privileges
GRANT CREATE SESSION TO memorizz_user;
GRANT CREATE TABLE TO memorizz_user;
GRANT CREATE INDEX TO memorizz_user;
GRANT CREATE VIEW TO memorizz_user;
GRANT UNLIMITED TABLESPACE TO memorizz_user;

-- Grant AI Vector Search privileges (Oracle 23ai+)
GRANT EXECUTE ON DBMS_VECTOR TO memorizz_user;
GRANT EXECUTE ON DBMS_VECTOR_CHAIN TO memorizz_user;

-- Grant JSON Duality View privileges
GRANT SODA_APP TO memorizz_user;
GRANT SELECT ANY TABLE TO memorizz_user;

3. Create Schema

The automated setup script (memorizz setup-oracle) handles this automatically. It will:

• Detect if you have admin access (admin mode) or need to use existing schema (user-only mode)
• Create all required tables and views
• Verify the setup

You can also run the SQL files manually:

# SQL files are located at:
# src/memorizz/memory_provider/oracle/schema_relational.sql
# src/memorizz/memory_provider/oracle/duality_views.sql

Using Hosted Databases (FreeSQL.com, Oracle Cloud, etc.)

MemoRizz works with hosted Oracle databases! The setup automatically adapts to your environment.

Setup for Hosted Databases

1. Get your credentials from your database provider:

   • Username (your schema name)
   • Password
   • Connection string (DSN)

2. Set environment variables:

   export ORACLE_USER="your_schema_name"
   export ORACLE_PASSWORD="your_password"
   export ORACLE_DSN="host:port/service_name"
   # Example for FreeSQL.com:
   # export ORACLE_DSN="db.freesql.com:1521/23ai_34ui2"

3. Run the setup:

   memorizz setup-oracle

   The setup will:

   • ✅ Automatically detect user-only mode
   • ✅ Use your existing schema
   • ✅ Check available privileges
   • ✅ Create tables and views
   • ✅ Warn about any missing privileges

What to Expect

User-Only Mode Output:

ℹ User-only mode detected: Using existing schema
  Admin connection failed (this is OK for hosted databases)
  Will use existing user: your_schema_name
  ✓ Connected as your_schema_name

  User privileges:
    ✓ CREATE_TABLE
    ✓ CREATE_VIEW
    ✗ DBMS_VECTOR (may need admin to grant)
    ✗ SODA_APP (may need admin to grant)

Note: Some privileges (like DBMS_VECTOR and SODA_APP) may require admin access. If these are missing:

• Contact your database administrator to grant them
• Or use features that don't require these privileges
• The setup will still work for basic functionality

---

Configuration

Oracle Provider Configuration

The OracleConfig class supports various configuration options:

from memorizz.memory_provider.oracle import OracleConfig

config = OracleConfig(
    user="memorizz_user",                    # Database username
    password="SecurePass123!",               # Database password
    dsn="localhost:1521/FREEPDB1",          # Connection string
    schema="memorizz",                       # Schema name (optional)
    lazy_vector_indexes=False,               # Create indexes immediately
    embedding_provider="openai",             # Embedding provider
    embedding_config={                       # Embedding configuration
        "model": "text-embedding-3-small",
        "api_key": "your-key"
    },
    pool_min=1,                              # Min connection pool size
    pool_max=5,                              # Max connection pool size
    pool_increment=1                         # Pool increment size
)

Connection String Formats

Basic Format:

dsn="localhost:1521/FREEPDB1"

Easy Connect Plus:

dsn="myhost.example.com:1521/xepdb1"

TNS Format:

dsn="""(DESCRIPTION=
    (ADDRESS=(PROTOCOL=TCP)(HOST=myhost)(PORT=1521))
    (CONNECT_DATA=(SERVICE_NAME=FREEPDB1)))"""

TNS Alias (requires tnsnames.ora):

dsn="mydb_alias"

Embedding Provider Configuration

MemoRizz supports multiple embedding providers:

OpenAI:

embedding_provider="openai"
embedding_config={
    "model": "text-embedding-3-small",
    "api_key": "your-openai-key"
}

Voyage AI:

embedding_provider="voyageai"
embedding_config={
    "model": "voyage-3-large",
    "api_key": "your-voyage-key"
}

Ollama (Local):

embedding_provider="ollama"
embedding_config={
    "model": "nomic-embed-text",
    "base_url": "http://localhost:11434"
}

---

Verification

Verify Oracle Database is Running

# Check Docker container status
docker ps | grep oracle-memorizz

# Check container logs
docker logs oracle-memorizz

# Test connection (requires oracledb)
python -c "import oracledb; conn = oracledb.connect(user='system', password='MyPassword123!', dsn='localhost:1521/FREEPDB1'); print('✓ Connected successfully!'); conn.close()"

Verify Database Schema

import oracledb

conn = oracledb.connect(
    user="memorizz_user",
    password="SecurePass123!",
    dsn="localhost:1521/FREEPDB1"
)
cursor = conn.cursor()

# Check tables
cursor.execute("""
    SELECT table_name FROM user_tables
    WHERE table_name IN ('AGENTS', 'AGENT_LLM_CONFIGS', 'AGENT_MEMORIES',
                         'PERSONAS', 'TOOLBOX', 'CONVERSATION_MEMORY',
                         'LONG_TERM_MEMORY', 'SHORT_TERM_MEMORY',
                         'WORKFLOW_MEMORY', 'SHARED_MEMORY', 'SUMMARIES',
                         'SEMANTIC_CACHE')
    ORDER BY table_name
""")
tables = cursor.fetchall()
print(f"Found {len(tables)} tables: {[t[0] for t in tables]}")

# Check views
cursor.execute("""
    SELECT view_name FROM user_views
    WHERE view_name LIKE '%_DV'
    ORDER BY view_name
""")
views = cursor.fetchall()
print(f"Found {len(views)} duality views: {[v[0] for v in views]}")

cursor.close()
conn.close()

Verify Vector Support

import oracledb

conn = oracledb.connect(
    user="memorizz_user",
    password="SecurePass123!",
    dsn="localhost:1521/FREEPDB1"
)
cursor = conn.cursor()

# Check Oracle version
cursor.execute("SELECT * FROM V$VERSION WHERE BANNER LIKE '%23ai%' OR BANNER LIKE '%26ai%'")
version = cursor.fetchone()
if version:
    print(f"✓ Oracle version: {version[0]}")
else:
    print("⚠ Oracle 23ai+ not detected")

# Test VECTOR datatype
try:
    cursor.execute("CREATE TABLE test_vectors (id NUMBER, vec VECTOR(1536, FLOAT32))")
    cursor.execute("DROP TABLE test_vectors")
    print("✓ VECTOR datatype supported")
except Exception as e:
    print(f"✗ VECTOR datatype not available: {e}")

cursor.close()
conn.close()

---

Troubleshooting

Oracle Connection Issues

Problem: Cannot connect to Oracle database

Solutions:

1. Verify Oracle container is running:

   docker ps | grep oracle-memorizz

2. Check container logs for errors:

   docker logs oracle-memorizz

3. Verify connection details:

   • Host: localhost
   • Port: 1521
   • Service Name: FREEPDB1
   • Password matches what you set

4. Test connection manually:

   import oracledb
   try:
       conn = oracledb.connect(
           user="system",
           password="MyPassword123!",
           dsn="localhost:1521/FREEPDB1"
       )
       print("✓ Connection successful!")
       conn.close()
   except Exception as e:
       print(f"✗ Connection failed: {e}")

Apple Silicon (M1/M2/M3) Issues

Problem: Oracle container fails to start or runs very slowly

Solutions:

1. Use platform flag for emulation:

   export PLATFORM_FLAG="--platform linux/amd64"
   ./install_oracle.sh

2. Verify Docker Desktop is using Rosetta 2 (if available):

   • Docker Desktop → Settings → General → Use Rosetta for x86/amd64 emulation

3. Performance note: Emulation may be slower than native. Consider using a cloud Oracle instance for better performance on Apple Silicon.

Vector Index Creation Fails

Problem: Vector indexes fail to create during initialization

Solutions:

1. Verify Oracle version supports VECTOR datatype (23ai+ required)
2. Use lazy index creation:

   config = OracleConfig(
       user="memorizz_user",
       password="SecurePass123!",
       dsn="localhost:1521/FREEPDB1",
       lazy_vector_indexes=True  # Create indexes on first use
   )

3. Check user has CREATE INDEX privilege
4. Verify sufficient tablespace available

ORA-02236: invalid file name

Problem: Setup script reports ORA-02236: invalid file name while creating the default tablespace. This happens when Oracle Managed Files isn't configured, so Oracle needs an explicit datafile location.

Solutions:

1. Tell the setup script where datafiles live inside the Oracle server/container:

   # Directory that already contains other datafiles (inside the container/DB host)
   export ORACLE_DATAFILE_DIR="/opt/oracle/oradata/FREEPDB1"
   
   # Or supply the full path you want to use
   export ORACLE_TABLESPACE_DATAFILE="/opt/oracle/oradata/FREEPDB1/memorizz_ts01.dbf"

2. (Optional) Override the tablespace name or size:

   export ORACLE_TABLESPACE_NAME="MEMORIZZ_TS"
   export ORACLE_TABLESPACE_SIZE_MB="200"
   export ORACLE_TABLESPACE_AUTOEXTEND_MB="25"

3. Re-run python -m memorizz.memory_provider.oracle.setup (or memorizz setup-oracle).

If you run Oracle outside Docker, update the paths to match the server's filesystem. The script will now reuse that path when creating the tablespace.

Schema Creation Issues

Problem: Tables or views fail to create

Solutions:

1. Verify user has required privileges:

   SELECT * FROM USER_SYS_PRIVS WHERE USERNAME = 'MEMORIZZ_USER';

2. Check for existing objects:

   SELECT table_name FROM user_tables;
   SELECT view_name FROM user_views;

3. Drop and recreate user (if needed):

   python examples/setup_oracle_user.py
   # Script will drop existing user and recreate

Embedding Dimension Mismatch

Problem: Dimension mismatch errors when storing embeddings

Solutions:

1. Check current embedding dimensions:

   from memorizz.embeddings import get_embedding_dimensions
   dims = get_embedding_dimensions()
   print(f"Current dimensions: {dims}")

2. Ensure consistent dimensions across configuration:

   embedding_config={
       "model": "text-embedding-3-small",
       "dimensions": 1536  # Explicitly set dimensions
   }

Performance Issues

Problem: Slow queries or high memory usage

Solutions:

1. Increase connection pool size:

   config = OracleConfig(
       pool_min=2,
       pool_max=10,
       pool_increment=2
   )

2. Rebuild vector indexes for better accuracy:

   ALTER INDEX idx_tablename_vec REBUILD
   ORGANIZATION NEIGHBOR PARTITIONS
   DISTANCE COSINE
   WITH TARGET ACCURACY 99;

3. Gather table statistics:

   EXEC DBMS_STATS.GATHER_TABLE_STATS('MEMORIZZ_USER', 'CONVERSATION_MEMORY');

---

Quick Restart

If you've already set up MemoRizz and just need to restart Oracle:

# Start existing Oracle container (data persists via Docker volume)
docker start oracle-memorizz

# Or use the helper script
./install_oracle.sh  # Will detect existing container and start it

# Verify it's running
docker ps | grep oracle-memorizz

Your data persists between restarts thanks to the Docker volume (oracle-memorizz-data).

To completely reset (⚠️ WARNING: This deletes all data):

# Stop and remove container
docker stop oracle-memorizz
docker rm oracle-memorizz

# Remove volume (deletes all data)
docker volume rm oracle-memorizz-data

# Start fresh
./install_oracle.sh
python examples/setup_oracle_user.py

---

Next Steps

After completing the setup:

1. Explore Examples:

   • Single Agent Demo
   • Multi-Agent Example
   • Persona Example
   • Toolbox Example

2. Read Documentation:

   • Main README
   • Oracle Provider README
   • Memory Architecture

3. Build Your First Agent:

   from memorizz.memagent.builders import MemAgentBuilder
   from memorizz.memory_provider.oracle import OracleProvider, OracleConfig
   
   # Your agent code here...

---

Additional Resources

• Oracle Database 23ai Documentation: oracle.com
• Oracle AI Vector Search: Vector Search Guide
• Python Oracle Driver: python-oracledb
• MemoRizz GitHub: github.com/RichmondAlake/memorizz

---

Support

If you encounter issues:

1. Check the Troubleshooting section above
2. Review the Oracle Provider README
3. Check example notebooks in the examples/ directory
4. Open an issue on GitHub

---

Happy coding with MemoRizz! 🧠