Metadata-Version: 2.4
Name: oracleagentmemory
Version: 26.4.0
Summary: Python client library for Oracle AI Database Agent Memory
Author: Oracle
License-Expression: Apache-2.0 OR UPL-1.0
License-File: LICENSE-APACHE.txt
License-File: LICENSE-UPL.txt
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: anyio<5,>=4.0
Requires-Dist: cryptography<47,>=46.0.7
Requires-Dist: exceptiongroup<2,>=1.3
Requires-Dist: litellm<1.84.0,>=1.83.7
Requires-Dist: numpy<3,>=1.23
Requires-Dist: oracledb<4,>=3.4.2
Requires-Dist: pydantic<3,>=2.12.5
Requires-Dist: sniffio<2,>=1.3
Requires-Dist: typing-extensions<5,>=4.0
Description-Content-Type: text/markdown

# Oracle AI Agent Memory

[![Oracle AI Agent Memory docs][badge-docs]][docs] [![License][badge-license]](#license)

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:

```bash
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:

```python
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.

```python
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.

```python
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.

```python
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.

```python
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.

[badge-docs]: https://img.shields.io/badge/documentation-Oracle%20AI%20Agent%20Memory-orange
[badge-license]: https://img.shields.io/badge/license-apache_2.0+UPL_1.0-green
[docs]: https://docs.oracle.com/en/database/oracle/agent-memory/index.html
