Get Started with Agent Memory

This article guides you through installing Agent Memory and performing basic memory operations, including storing and retrieving user context.

Prerequisites

Ensure that you have:

Oracle AI Database Feature Requirements

Oracle Agent Memory’s DB-backed store requires Oracle AI Database 23ai or later (database version 23.4 or later). For Oracle AI Vector Search, set the database COMPATIBLE initialization parameter to 23.4.0 or later.

The selected search strategy has these additional requirements:

During managed-schema initialization, Oracle Agent Memory validates the connected database version before running DDL and reports an upgrade action when the selected search strategy is unavailable.

Managed Database Setup

When a schema owner creates or re-creates a memory store, the Oracle Agent Memory Python package prepares the managed database objects it needs. The owner needs the Oracle CREATE TABLE and CREATE PROCEDURE system privileges.

Connect as the schema owner for schema setup. An application connection using schema_owner accesses an existing store and must use SchemaPolicy.REQUIRE_EXISTING; it does not create or update the owner’s managed database objects.

Install the SDK

You can find all versions and supported platforms of oracleagentmemory on the Software Download page.

To install Agent Memory, run:

pip install "oracleagentmemory==26.8.0"

Installing with pip pulls prebuilt binary wheels on supported platforms.

Logging and diagnostics

Oracle AI Agent Memory emits diagnostic messages through standard Python logging under logger names starting with oracleagentmemory. The SDK does not configure handlers or log levels; applications can route these logs to their existing console, file, or observability pipeline. Some log records use Python logging’s extra fields for safe structured diagnostics, which can be captured by structured logging handlers.

import logging

logging.basicConfig(level=logging.INFO)
logging.getLogger("oracleagentmemory").setLevel(logging.INFO)

For troubleshooting in controlled environments, enable DEBUG logs:

logging.getLogger("oracleagentmemory").setLevel(logging.DEBUG)

Keep production deployments at a non-DEBUG level. DEBUG logs are intended for development and support diagnostics, and log message text should not be treated as a stable public API.

Time-to-Live and Expired-Record Purge

Oracle DB-backed messages and memories can expire automatically through a combination of schema-level retention defaults and per-record ttl_days / ttl_anchor values on write and update APIs.

When Oracle Agent Memory creates or upgrades its managed schema, it also creates a daily DBMS_SCHEDULER purge job that physically removes expired rows, their retrieval chunks, and orphaned retrieval chunks whose supported source row no longer exists. If schema setup needs to create that job but the database user lacks CREATE JOB, setup completes with a warning: expired rows remain filtered out of reads and search, but expired and orphaned chunks are not physically purged until a privileged user creates the job. Under SchemaPolicy.REQUIRE_EXISTING, a missing purge job is tolerated and logged at DEBUG level.

Linked-memory schemas also create a trigger that revalidates surviving memories after a link is deleted, including when the purge job deletes an expired memory and Oracle cascades its links. The schema owner needs CREATE TRIGGER during schema creation or upgrade; normal runtime users do not need that privilege.

For the full retention model, MemoryRetentionConfig setup, purge-job verification queries, manual DBA job creation, and Python examples using TimeToLiveAnchor, see Use Time-to-Live for Messages and Memories.

Linked-Memory Schema Permissions

The linked-memory schema includes an Oracle SQL property graph and a database trigger that keeps lifecycle state correct when links are deleted.

If you set memory_store_id, the managed graph name is prefixed in the same way as the tables. For example, memory_store_id="SALES" creates SALES_MEMORY_GRAPH.

The APP_SCHEMA and APP_USER values are placeholders. Replace them with your database user names. The examples use uppercase because unquoted Oracle identifiers are stored in uppercase.

  1. During schema setup, grant the schema owner CREATE PROPERTY GRAPH and CREATE TRIGGER. These are required with SchemaPolicy.CREATE_IF_NECESSARY or SchemaPolicy.RECREATE whenever the managed graph or link-deletion trigger must be created. 
    GRANT CREATE PROPERTY GRAPH TO APP_SCHEMA;
GRANT CREATE TRIGGER TO APP_SCHEMA;
-- Run OracleAgentMemory schema setup as APP_SCHEMA.
REVOKE CREATE PROPERTY GRAPH FROM APP_SCHEMA;
REVOKE CREATE TRIGGER FROM APP_SCHEMA;

    Grant them again before a later SDK upgrade if that upgrade needs to create or recreate the managed graph or link-deletion trigger.

  2. During normal application runtime, decide which user connects to Oracle:
    • If the runtime user is APP_SCHEMA, no additional graph grant is needed. The graph owner can access its own graph.
    • If the runtime user is different, run the following as APP_SCHEMA after schema setup. The default graph name is MEMORY_GRAPH; use the prefixed name when memory_store_id is set. 
      GRANT SELECT ON PROPERTY GRAPH APP_SCHEMA.MEMORY_GRAPH TO APP_USER;

      The runtime user also needs the normal database access required by the rest of the Oracle Agent Memory deployment.

SchemaPolicy.REQUIRE_EXISTING skips the first step because it expects the graph and trigger to exist already. A separate runtime user still needs access to the managed property graph.

Initialize the Memory Instance

Create an OracleAgentMemory instance by configuring the embedder, LLM, and database connection.

import oracledb

from oracleagentmemory.core import SchemaPolicy
from oracleagentmemory.core.oracleagentmemory import OracleAgentMemory
from oracleagentmemory.apis.searchscope import SearchScope
from oracleagentmemory.core.embedders.embedder import Embedder
from oracleagentmemory.core.llms.llm import Llm

embedder = Embedder(model="YOUR_EMBEDDING_MODEL")
llm = Llm(model="YOUR_LLM")
db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="YOUR DB CONNECT STRING",
)
memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_store_id="T_GET_STARTED",
)

Note: By default, managed Oracle AI Database schemas do not set a retention period for messages and memories. Configure MemoryRetentionConfig or per-record time-to-live settings to use a different retention period. For more information, see Use Time-to-Live for Messages and Memories.

Store Memory Entries

Start by creating a thread, adding messages, and storing a memory entry for the user.

messages = [
    {
        "role": "user",
        "content": (
            "Orange juice has become my favorite breakfast drink lately, "
            "what can I pair it with?"
        ),
    },
    {
        "role": "assistant",
        "content": (
            "Nice! Orange juice goes great with something savory. "
            "Try eggs and toast, avocado toast, or a breakfast sandwich."
        ),
    },
]

thread = memory.create_thread(user_id="user_123")
#add_messages will add messages to the DB and extract memories automatically
thread.add_messages(messages)
#add_memory adds memory to the DB
thread.add_memory("The user likes orange juice with breakfast.")

Retrieve Memory Entries

Search memories using a user-scoped query.

results = memory.search(query="orange juice", scope=SearchScope(user_id="user_123"))
for result in results:
    print(f"- [{result.record.record_type}] {result.content}")

Output:

- [memory] The user likes orange juice with breakfast.
- [message] Orange juice has become my favorite breakfast drink lately, what can I pair it with?
- [message] Nice! Orange juice goes great with something savory. Try eggs and toast,
            avocado toast, or a breakfast sandwich.

Note: The output shown is illustrative. Future versions may return additional result types, fields, or ordering.

Model Compatibility

The following Large Language Models (LLMs) and Embedding Models are compatible with oracleagentmemory.

LLMs

The following Large Language Models (LLMs) have been confirmed to be compatible.

OCI-hosted models

OpenAI

self-hosted LLMs

Anthropic

Gemini

Embeddings

The following Embedding Models have been confirmed to be compatible.

OCI-hosted models

OpenAI

Self-hosted LLMs

Gemini