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:

Install the SDK

To install Agent Memory, run:

pip install "oracleagentmemory==26.6.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.

Initialize the Memory Instance

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

import oracledb

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)

Note: By default, managed Oracle 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

As of April 2026, 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

Gemini