oracleagentmemory 26.4.0

Python client library for Oracle AI Database Agent Memory

Oracle AI Agent Memory

Persistent memory for enterprise AI agents on Oracle AI Database.

Oracle AI Agent Memory helps agents retain context across interactions, compact active conversations, and retrieve durable user, agent, and thread memories when they matter. It is designed for Python applications that need persistent memory backed by Oracle AI Database.

Get Started

Install the package:

pip install oracleagentmemory

Do you need a local Oracle AI Database for development? See how to run Oracle AI Database locally: https://docs.oracle.com/en/database/oracle/agent-memory/26.4/agmea/run-locally.html

Create a memory client, store a short conversation, and search it back:

from oracleagentmemory.apis.searchscope import SearchScope
from oracleagentmemory.core import OracleAgentMemory
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 = ...  # an oracledb connection or connection pool

memory = OracleAgentMemory(connection=db_pool, embedder=embedder, llm=llm)

messages = [
    {
        "role": "user",
        "content": "Orange juice has become my favorite breakfast drink lately. What can I pair it with?",
    },
    {
        "role": "assistant",
        "content": "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.")

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

OracleAgentMemory uses your Oracle Database connection or pool as the persistence layer, your embedding model for retrieval, and an optional LLM for memory extraction, summaries, and context cards.

LongMemEval Results

Benchmark	Score	Correct
LongMemEval	94.4	472 / 500
Knowledge Update	94.0	73 / 78
Multi-session Reasoning	88.0	117 / 133
Temporal Reasoning	98.0	130 / 133
Single-session User	97.0	68 / 70
Single-session Assistant	100.0	56 / 56
Preference	93.0	28 / 30

Configuration note:

LongMemEval full 500-question evaluation. Answering with GPT-5.5 using xhigh reasoning effort. Mean answer LLM total tokens: 29,042; mean thinking tokens: 1,178.

Why Oracle AI Agent Memory?

Oracle AI Agent Memory is built for teams that want persistent agent memory on Oracle AI Database. It helps applications move beyond single-turn prompts by storing conversation history, durable memories, and prompt-ready short-term context in Oracle AI Database.

It gives agents a consistent way to:

• remember useful information across sessions;
• keep active threads compact and context-rich;
• retrieve memories by user, agent, and thread scope;
• use LLM-backed extraction when automatic memory formation is useful;
• write explicit memories when deterministic application control is preferred;
• integrate memory into existing Python agent applications.

Core Concepts

Threads

A thread represents an ongoing conversation or task. Threads can store user and assistant messages, return recent messages, and produce short-term context for an agent prompt.

thread = memory.create_thread(user_id="user_123")
thread.add_messages([
    {"role": "user", "content": "Remember that I like morning meetings."},
    {"role": "assistant", "content": "I will keep that in mind."},
])

Durable Memories

A durable memory is information intended to survive beyond the active thread. Applications can add durable memories directly.

thread.add_memory("The user prefers morning meetings.")

When an LLM is configured and memory extraction is enabled, Oracle AI Agent Memory can also extract durable memories from thread messages.

Search Scope

Search is scoped explicitly so applications can control which memories are eligible for retrieval.

results = memory.search(
    query="When does the user prefer meetings?",
    scope=SearchScope(user_id="user_123"),
)

Context Cards

For longer conversations, get_context_card() creates prompt-ready short-term context with a summary, relevant durable records, retrieval topics, and recent messages.

context = thread.get_context_card()

Use context cards when a model needs continuity without receiving the full conversation transcript.

Security and Deployment Notes

Oracle AI Agent Memory uses the database connection, model providers, credentials, and network configuration supplied by the integrating application. For production deployments:

• use encrypted database connections and secure model-provider endpoints;
• keep secrets out of source code and checked-in configuration;
• apply end-user authentication and authorization before memory operations;
• pass correct memory scope values for every request;
• bound message sizes, retrieval sizes, and provider usage for your workload;
• review LLM-backed extraction and summarization carefully before using them with sensitive data.

License

Oracle AI Agent Memory is dual-licensed under:

• Apache License 2.0
• Universal Permissive License (UPL) 1.0

You may choose either license.