Metadata-Version: 2.5
Name: openai-agents-memorysync
Version: 1.0.0
Summary: MemorySync memory for the OpenAI Agents SDK: a drop-in Session implementation with durable server-side history, long-term memory instructions, and agent memory tools.
Project-URL: Homepage, https://memorysync.io
Project-URL: Documentation, https://docs.memorysync.io/guides/openai-agents
Project-URL: API Reference, https://docs.memorysync.io/api/overview
Project-URL: Changelog, https://docs.memorysync.io/release-notes
Project-URL: Support, https://docs.memorysync.io/debugging/support
Project-URL: Status, https://status.memorysync.io
Author: MemorySync
License: MIT
Keywords: agent-memory,agents-sdk,ai,ai-agents,llm,long-term-memory,memory,memorysync,openai,openai-agents,session
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx<1.0,>=0.25
Requires-Dist: memorysync>=1.9
Description-Content-Type: text/markdown

# openai-agents-memorysync

Long-term memory for the [OpenAI Agents SDK](https://github.com/openai/openai-agents-python), backed by [MemorySync](https://memorysync.io) — including the first drop-in implementation of the SDK's Session protocol from any memory vendor.

- **`MemorySyncSession`** — durable server-side conversation history for `Runner.run(..., session=...)`: survives restarts and deploys, follows multi-agent handoffs, extracts long-term memory automatically.
- **`memory_instructions`** — dynamic instructions that inject recalled memory context per run.
- **Five agent tools** — add, search, list, update, delete; they never raise.
- **Async helpers** — `get_memory_context`, `search_memories`, `save_turn`.

```bash
pip install openai-agents-memorysync openai-agents
```

Set `MEMORYSYNC_API_KEY` in the environment (create a key at [app.memorysync.io](https://app.memorysync.io)), or pass `api_key` explicitly. Python 3.10+. The package never imports the Agents SDK at runtime — the Session contract is a structural protocol — so it never constrains which SDK version you run.

## The drop-in session

```python
from agents import Agent, Runner
from openai_agents_memorysync import MemorySyncSession

agent = Agent(name="Assistant", instructions="You are a helpful assistant.")

session = MemorySyncSession(
    "thread-42",          # the conversation
    user_id="customer-7", # the end user it belongs to — required
)

# First conversation
await Runner.run(agent, "I'm vegetarian and I fly aisle.", session=session)

# Any later run — same session id, any process, any deploy
result = await Runner.run(agent, "Book my trip.", session=session)
# The model saw the full prior history — no manual .to_input_list() plumbing.
```

Items are stored and returned **byte-for-byte** — assistant messages, function calls, tool outputs, reasoning items — verified in the test suite against OpenAI's own `SQLiteSession`, item for item. Each session lives in its own server-side namespace: `clear_session()` can only ever reach that one conversation, and function-call JSON never pollutes the user's long-term memories.

**Multi-agent handoffs:** the SDK shares one session across every agent in a run, so with a correct Session implementation, cross-handoff memory needs no extra code.

**Failure discipline:** the transcript IS the conversation state, so session-plane errors raise (a silently empty history would corrupt every following turn); the auxiliary long-term plane degrades through `on_error`. `pop_item`/`clear_session` refuse loudly when the key cannot delete. Transcript writes converge under retries — total and partial batch failures alike — via position + content-hash seeds.

## Long-term memory in instructions

```python
from openai_agents_memorysync import memory_instructions

agent = Agent(
    name="Assistant",
    instructions=memory_instructions(
        "You are a helpful assistant.",
        user_id="customer-7",                      # or a per-run resolver:
        # user_id=lambda ctx: ctx.context.user_id,
    ),
)
```

Every run starts with what MemorySync knows about the user. Recall failure degrades to the base instructions — reported through `on_error`, never thrown. Modes: `"profile"` (default), `"query"`, `"full"`.

## Agent tools

```python
from openai_agents_memorysync import create_memory_tools

agent = Agent(
    name="Assistant",
    instructions="Use the memory tools to remember durable facts.",
    tools=create_memory_tools(user_id="customer-7"),
)

# Untrusted agents: search + list only.
create_memory_tools(user_id="customer-7", read_only=True)
```

`add_memory`, `search_memory`, `list_memories`, `update_memory`, `delete_memory` — the same five operations, same response strings as the MemorySync LangChain, AI SDK, CrewAI and Mastra tool sets. All async; failures return short readable strings, never exceptions.

## Helpers

```python
from openai_agents_memorysync import get_memory_context, save_turn, search_memories

context = await get_memory_context("what should I cook?", user_id="customer-7")
hits = await search_memories("dietary preferences", user_id="customer-7")
await save_turn(user_id="customer-7", user="I'm vegetarian", assistant="Noted!")
```

All surfaces share the same idempotency seeds, so mixing styles cannot double-store a turn. `save_turn` raises on failure — an explicit persist call is owed the truth.

## Version support

| Package | Requires | Runtime |
| --- | --- | --- |
| `openai-agents-memorysync` 1.0.0 | `openai-agents` installed alongside (any current 0.x) | Python 3.10+ |

CI drives a real `Runner` — SQLite parity oracle, handoffs, retry convergence — against the latest `openai-agents` release on every push.

## Documentation

- [OpenAI Agents SDK Memory guide](https://docs.memorysync.io/guides/openai-agents)
- [MemorySync docs](https://docs.memorysync.io)
- [Get an API key](https://app.memorysync.io)
