Frequently Asked Questions (FAQs) and Troubleshooting

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

Installation and Upgrade

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

Oracle AI Agent Memory supports Python 3.10 through 3.13. 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.4.0 (from versions: none)
ERROR: No matching distribution found for oracleagentmemory==26.4.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, or 3.13 and install again:

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

Python 3.14 is not currently supported because the package follows the supported Python range of its LiteLLM dependency.

Database Requirements

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 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';

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 runtime user. Normal application startup should use SchemaPolicy.REQUIRE_EXISTING so it validates the schema without creating or changing DB objects.

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

import os

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; if you omit that argument, use the unprefixed managed object names in your grants.

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,
)

Use SchemaPolicy.CREATE_IF_NECESSARY instead when you intentionally want the owner account to apply supported non-destructive upgrades for an older managed schema.

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

Ask a DBA or privileged administrator to grant the runtime 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.APP_MEMORY_ORACLEAGENTMEMORY_SCHEMA_META 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 a runtime user that creates threads, adds messages, adds memories, updates records, or deletes records, grant the connection privilege and DML on the managed tables.

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.APP_MEMORY_ORACLEAGENTMEMORY_SCHEMA_META 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 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,
    schema_policy=SchemaPolicy.REQUIRE_EXISTING,
)

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 runtime 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,
)

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.6.0 uses litellm>=1.84.0,<2, which allows newer compatible openai and python-dotenv versions. If your resolver reports a conflict: