Add offset parameter to get_items() for pagination

[ecanlar]

Summary

• Adds offset parameter to get_items() across all session backends, enabling real pagination over conversation history
• Currently limit only truncates (returns the latest N items) — with offset, users can now paginate through the full history
• Fully backward compatible: offset defaults to 0

Usage

# Page 1: 10 most recent items
page1 = await session.get_items(limit=10, offset=0)

# Page 2: next 10 items  
page2 = await session.get_items(limit=10, offset=10)

# Skip the 5 most recent, get the rest
older = await session.get_items(offset=5)

Backends updated

Backend	File
Session protocol	src/agents/memory/session.py
SessionABC	src/agents/memory/session.py
SQLiteSession	src/agents/memory/sqlite_session.py
AsyncSQLiteSession	src/agents/extensions/memory/async_sqlite_session.py
SQLAlchemySession	src/agents/extensions/memory/sqlalchemy_session.py
RedisSession	src/agents/extensions/memory/redis_session.py
DaprSession	src/agents/extensions/memory/dapr_session.py
AdvancedSQLiteSession	src/agents/extensions/memory/advanced_sqlite_session.py
EncryptedSession	src/agents/extensions/memory/encrypt_session.py
OpenAIResponsesCompactionSession	src/agents/memory/openai_responses_compaction_session.py
OpenAIConversationsSession	src/agents/memory/openai_conversations_session.py

Test plan

• All 33 existing session tests pass (backward compatible)
• New test_sqlite_session_get_items_with_offset — verifies limit+offset pagination, offset-only, and edge cases

Closes #2810

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4b76578b40

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Honor offset in OpenAIConversationsSession.get_items

get_items now advertises an offset argument, but this method never applies it in either query path, so get_items(offset=...) returns the same page as offset=0. This breaks pagination specifically for the OpenAI-backed session and can cause duplicate pages when callers iterate through history using offsets.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Clamp Redis LRANGE indices for large offsets

The Redis pagination math passes raw negative indices to LRANGE; when offset exceeds the list length, Redis normalizes out-of-range indices instead of erroring, so ranges like 0, -(offset+1) can still return the oldest element(s) instead of an empty list. That makes get_items(offset>=len(history)) return stale data and breaks page boundaries.

Useful? React with 👍 / 👎.

[ecanlar]

Thanks for your response!

In my case, I’m developing an assistant (chatbot) that manages a growing history of user sessions in production. As the number of sessions increases, retrieving all of them at once is not scalable and negatively impacts both performance and user experience.

Pagination becomes necessary to:

• Efficiently load session history in chunks
• Reduce latency and memory usage
• Support UI patterns like infinite scroll or page-based navigation

Using an offset (or cursor-based pagination) is a standard approach in these scenarios and would make the Sessions API much more practical for real-world applications.

I believe this is not an edge case but a common requirement for any production system that stores conversational history over time.

Thanks for considering it!

[seratch]

I mean, just having the offset parameter on the session store side is not enough, because the agent runner does not pass that parameter to your session store. Also, it is not obvious what offset value would be optimal. So, if your app needs to limit the size or number of items, I recommend implementing that logic within the get_items method, such as setting an upper limit on the number of items to return or compacting items at the right time.