Frequently Asked Questions (FAQs) and Troubleshooting

This page covers common installation, database requirements, database access, and package compatibility questions for Oracle AI Agent Memory.

Python script/notebook for the snippets on this page.

Installation and Upgrade

Why do I see “No matching distribution found” during installation?

Oracle AI Agent Memory supports Python 3.10 through 3.14. If you install it with Python 3.9, pip may report a generic error like this:

ERROR: Could not find a version that satisfies the requirement oracleagentmemory==26.8.0 (from versions: none)
ERROR: No matching distribution found for oracleagentmemory==26.8.0

Check that the same Python interpreter is used for both python and pip:

python --version
python -m pip --version
python -m pip install oracleagentmemory

If the version is earlier than Python 3.10, create a new environment with Python 3.10, 3.11, 3.12, 3.13, or 3.14 and install again:

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install oracleagentmemory

Database Requirements

Which Oracle AI Database versions and search strategies are supported?

Oracle Agent Memory requires Oracle AI Database 23ai (23.4) or later for its DB-backed store. SearchStrategy.HYBRID additionally requires Release Update 23.6 or later. See Oracle AI Database feature requirements for the complete strategy requirements, including the required COMPATIBLE setting for Oracle AI Vector Search.

How should the database be configured for vector search?

Oracle AI Agent Memory requires vector memory to be configured in Oracle Database before using vector search or vector-index backed schemas. If the vector memory area is not configured or is too small, database operations can fail with this error:

ORA-51962: The vector memory area is out of space for the current container.

See the Oracle AI Database error help for ORA-51962.

Ask a DBA or privileged administrator to size vector memory for both the root container and the target pluggable database. The exact values depend on your database and workload; this example configures 512M at the root and 256M for the PDB:

ALTER SESSION SET CONTAINER = CDB$ROOT;
ALTER SYSTEM SET vector_memory_size = 512M SCOPE=SPFILE SID='*';
SHUTDOWN IMMEDIATE;
STARTUP;
ALTER PLUGGABLE DATABASE <PDB_NAME> OPEN;
ALTER SESSION SET CONTAINER = <PDB_NAME>;
ALTER SYSTEM SET vector_memory_size = 256M SCOPE=BOTH;
SELECT value FROM v$parameter WHERE name = 'vector_memory_size';

What if managed schema setup fails with ORA-00054?

Managed schema setup can create vector, Oracle Text, or hybrid search indexes. Those DDL operations are lock-sensitive, so a busy database can occasionally surface an error like this:

RuntimeError: Managed schema DDL failed (ORA-00054). Check that the database user has the
required schema privileges and quota to create, alter, and drop the SDK managed tables and
indexes. If those look correct, check for existing object-name conflicts or transient DDL
locks, then retry.

Oracle AI Agent Memory already retries transient ORA-00054 failures during managed vector-index, keyword-text-index, and hybrid-index creation. If the error still persists in your environment, ask a DBA or privileged administrator whether increasing the session DDL_LOCK_TIMEOUT is appropriate for the connection that runs schema setup. That setting affects DDL waiting for the whole database session, not only Oracle AI Agent Memory.

Database Users and Privileges

Can one DB user create the memory schema while another DB user uses it?

Use a privileged owner account to create the managed schema, then grant only the privileges required by each application DB user. Normal application startup should use SchemaPolicy.REQUIRE_EXISTING so it validates the schema without creating or changing DB objects.

Here, owner means the Oracle AI Database user that owns the managed tables and indexes. It is unrelated to the application-level user or agent associated with a memory record. The runtime client refers to this database user as schema_owner.

Configure one connection or pool for the schema owner and another for the application DB user:

import os

from oracleagentmemory.core.embedders import Embedder
from oracleagentmemory.core.llms import Llm
import oracledb

DB_CONNECT_STRING = os.environ.get("ORACLE_MEMORY_DB_CONNECT_STRING", "localhost:1521/FREEPDB1")
OWNER_DB_USER = os.environ.get("ORACLE_MEMORY_OWNER_DB_USER", "memory_owner")
RUNTIME_DB_USER = os.environ.get("ORACLE_MEMORY_RUNTIME_DB_USER", "memory_r")
MEMORY_STORE_ID = "APP_MEMORY"

owner_pool = oracledb.SessionPool(
    user=OWNER_DB_USER,
    password=os.environ["ORACLE_MEMORY_OWNER_DB_PASSWORD"],
    dsn=DB_CONNECT_STRING,
)
runtime_pool = oracledb.SessionPool(
    user=RUNTIME_DB_USER,
    password=os.environ["ORACLE_MEMORY_RUNTIME_DB_PASSWORD"],
    dsn=DB_CONNECT_STRING,
)

The examples below assume embedder and llm are already configured for your application. They also set memory_store_id="APP_MEMORY", which uses the APP_MEMORY_ object-name prefix. The shared AGENT_MEMORY_STORES table has no prefix; application users need SELECT on it so they can read the store’s saved configuration. It contains rows for every store in this owner schema, so that grant also permits reading those registry rows. See the warning in the views section below for the visibility implications.

Bootstrap the schema as the owner:

from oracleagentmemory.core import (
    OracleAgentMemory,
    SchemaPolicy,
)

owner_memory = OracleAgentMemory(
    connection=owner_pool,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.CREATE_IF_EMPTY,
    memory_store_id=MEMORY_STORE_ID,
)

This initialization runs while connected as the schema owner. If needed, it creates the database tables and internal database code (PL/SQL package) that Oracle Agent Memory uses in that schema. Run it before application clients connect with schema_owner.

If the existing database tables or internal database code do not match the installed Python package, normal startup does not replace them. Connect as the schema owner and use SchemaPolicy.RECREATE only when replacing the named store is acceptable. Otherwise, ask the database administrator to update the owner schema before application clients reconnect.

Use SchemaPolicy.CREATE_IF_NECESSARY instead when you intentionally want the owner account to apply supported non-destructive upgrades for an older managed schema. Treat this as a coordinated maintenance operation: run one schema-owner connection, stop application instances that write to the managed tables, and do not let multiple clients perform the upgrade concurrently. After the upgrade completes successfully, restart application instances with SchemaPolicy.REQUIRE_EXISTING. This restriction matters because managed upgrades can perform data backfills, and Oracle AI Database commits DDL statements implicitly, so an upgrade may temporarily expose intermediate table shapes.

If an upgrade is interrupted, resolve the reported database issue and rerun the same schema-owner operation. Supported upgrade steps recognize their documented intermediate states and can resume without starting over.

Treat schema lifecycle operations (creation, repair, upgrade, re-creation, and deletion) as coordinated maintenance work. For a given memory store, run only one lifecycle operation at a time from one schema-owner connection. Do not mix Oracle Agent Memory Python package administration with manual database administration for the same store, and do not change the managed database tables or internal database code while a lifecycle operation is in progress. Normal application clients should use SchemaPolicy.REQUIRE_EXISTING.

Why does owner-side schema setup fail before creating a memory store?

Before it creates or opens a same-schema store, the Oracle Agent Memory Python package may need to create the database tables and internal database code it uses in the schema owner’s account. The owner needs CREATE TABLE and CREATE PROCEDURE, together with the privileges required by the selected store features. For example, linked memory needs CREATE TRIGGER and CREATE PROPERTY GRAPH. See Get Started with Agent Memory for the feature-specific privileges.

An application connection that uses schema_owner is not allowed to prepare or change the owner’s database tables or internal database code. Connect as the owner to perform schema lifecycle operations, then reconnect application clients with SchemaPolicy.REQUIRE_EXISTING.

What privileges should I grant to a read-only runtime user?

Ask a DBA or privileged administrator to grant the application DB user the normal database privilege required to connect, such as CREATE SESSION. Then grant SELECT on the managed objects from the schema owner. This lets the user search existing memories without writing messages, memories, threads, or profiles.

Run this as a DBA or privileged administrator:

GRANT CREATE SESSION TO memory_r;

Then run these grants as memory_owner. The object names include the APP_MEMORY_ prefix used in the Python examples above:

GRANT SELECT ON memory_owner.AGENT_MEMORY_STORES TO memory_r;
GRANT EXECUTE ON memory_owner.DBMS_AGENT_MEMORY_STORE TO memory_r;
GRANT SELECT ON memory_owner.APP_MEMORY_THREAD TO memory_r;
GRANT SELECT ON memory_owner.APP_MEMORY_ACTOR_PROFILE TO memory_r;
GRANT SELECT ON memory_owner.APP_MEMORY_MESSAGE TO memory_r;
GRANT SELECT ON memory_owner.APP_MEMORY_MEMORY TO memory_r;
GRANT SELECT ON memory_owner.APP_MEMORY_RECORD_CHUNKS TO memory_r;

What privileges should I grant to a read/write runtime user?

For an application DB user that creates threads, adds messages, adds memories, updates records, or deletes records, use the database user that owns the managed schema and grant it the connection privilege required by the database.

Run this as a DBA or privileged administrator:

GRANT CREATE SESSION TO memory_rw;

Then run these grants as memory_owner:

GRANT SELECT ON memory_owner.AGENT_MEMORY_STORES TO memory_rw;
GRANT EXECUTE ON memory_owner.DBMS_AGENT_MEMORY_STORE TO memory_rw;
GRANT SELECT, INSERT, UPDATE, DELETE ON memory_owner.APP_MEMORY_THREAD TO memory_rw;
GRANT SELECT, INSERT, UPDATE, DELETE ON memory_owner.APP_MEMORY_ACTOR_PROFILE TO memory_rw;
GRANT SELECT, INSERT, UPDATE, DELETE ON memory_owner.APP_MEMORY_MESSAGE TO memory_rw;
GRANT SELECT, INSERT, UPDATE, DELETE ON memory_owner.APP_MEMORY_MEMORY TO memory_rw;
GRANT SELECT, INSERT, UPDATE, DELETE ON memory_owner.APP_MEMORY_RECORD_CHUNKS TO memory_rw;

How do I grant an application DB user access to an in-database embedding model?

When using OracleDBEmbedder with its default provider="database", the SDK executes VECTOR_EMBEDDING as the connected database user. The user’s privileges on the Agent Memory tables do not grant access to the embedding model. The account that runs the embedding SQL must also be allowed to apply that model.

If the database user owns the model, no extra grant is needed. If another schema owns the model, the model owner or a DBA must grant the runtime user permission to use it:

GRANT SELECT ON MINING MODEL memory_owner.DOC_MODEL TO memory_rw;

Because the runtime connection uses memory_rw, give the embedder the full model name:

from oracleagentmemory.core.embedders import OracleDBEmbedder

db_embedder = OracleDBEmbedder(
    connection=runtime_pool,
    model="MEMORY_OWNER.DOC_MODEL",
    embedding_dimension=384,
)

SELECT ANY MINING MODEL is a broader option for applications that need to use models in many schemas. For one known model, use the specific grant above. See Oracle’s DBMS_DATA_MINING security model for the model privilege details.

Can I use views instead of schema_owner?

Yes, but this is a secondary deployment option. Prefer schema_owner when the application DB user can receive grants on the owner schema’s objects; views add a maintenance requirement and another layer to the database setup. If you use views, after the owner schema exists and the application DB user has the required direct object grants, create same-named views in the application DB user’s schema. Use simple views that expose the complete managed objects; these views must be updatable for application DB users that need to write records. Run the following as the application DB user, or through a DBA with the required view-creation privilege:

The examples use the APP_MEMORY_ prefix derived from memory_store_id="APP_MEMORY" earlier; replace it with your own prefix when using a different ID.

CREATE VIEW AGENT_MEMORY_STORES AS
   SELECT * FROM memory_owner.AGENT_MEMORY_STORES;
CREATE VIEW APP_MEMORY_THREAD AS
   SELECT * FROM memory_owner.APP_MEMORY_THREAD;
CREATE VIEW APP_MEMORY_ACTOR_PROFILE AS
   SELECT * FROM memory_owner.APP_MEMORY_ACTOR_PROFILE;
CREATE VIEW APP_MEMORY_MESSAGE AS
   SELECT * FROM memory_owner.APP_MEMORY_MESSAGE;
CREATE VIEW APP_MEMORY_MEMORY AS
   SELECT * FROM memory_owner.APP_MEMORY_MEMORY;
CREATE VIEW APP_MEMORY_RECORD_CHUNKS AS
   SELECT * FROM memory_owner.APP_MEMORY_RECORD_CHUNKS;

When using these views, omit schema_owner and open the client with SchemaPolicy.REQUIRE_EXISTING. The SDK validates the views as the existing managed schema and leaves indexes and other schema-owned objects in the owner schema. This workaround is supported for vector-mode schemas only; use schema_owner for keyword or hybrid search. The application DB user is responsible for keeping the views aligned with the managed schema: whenever a new OAM version adds a managed table or changes the required columns, create or update the corresponding view before opening the client against that schema.

Warning: This setup does not isolate application users from each other. memory_owner.AGENT_MEMORY_STORES has a row for every store owned by memory_owner. The view exposes all of those rows. For example, if the owner has SALES and SUPPORT stores, an app user who can query this view can read registry details for both stores.

OWNER_ID stays as memory_owner; it never becomes the app user’s ID. The same is true when using schema_owner. An app user with SELECT access can read the whole registry, not only the store it opens. For isolation, put stores in different database schemas and grant access separately.

How do I connect with the runtime user after grants?

At runtime, construct the client with SchemaPolicy.REQUIRE_EXISTING using the database user that owns the managed schema:

from oracleagentmemory.core import OracleAgentMemory, SchemaPolicy

memory = OracleAgentMemory(
    connection=runtime_pool,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.REQUIRE_EXISTING,
    memory_store_id=MEMORY_STORE_ID,
    #Schema owner of the tables; this avoids ALTER SESSION
    #SET CURRENT_SCHEMA for the runtime connection.
    schema_owner=OWNER_DB_USER,
)

Read-only users can call search APIs against existing records. They cannot use write APIs such as create_thread(), add_messages(), add_memory(), update(), or delete() unless they also receive the corresponding DML privileges.

A read/write application DB user can use the same connection pattern, then call the normal write and search APIs:

memory = OracleAgentMemory(
    connection=runtime_pool,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.REQUIRE_EXISTING,
    memory_store_id=MEMORY_STORE_ID,
)

thread = memory.create_thread(user_id="user_123")
thread.add_memory("The user prefers concise answers.")

results = memory.search(
    "concise answers",
    user_id="user_123",
    record_types=["memory"],
    max_results=5,
)

Package Compatibility

How do I resolve package dependency conflicts?

Oracle AI Agent Memory depends on LiteLLM for model-provider integration. Older Oracle AI Agent Memory releases, including 26.4.0, used a tighter LiteLLM upper bound that could conflict with other agent frameworks or integration packages when they required newer openai or python-dotenv versions.

Oracle AI Agent Memory 26.8.0 uses litellm>=1.84.0,<2, which allows newer compatible openai and python-dotenv versions. If your resolver reports a conflict: