docs: document read-fresh guarantee in DefaultSessionStore#476
Conversation
- Extended Multi-Process Safety section with read-fresh behavior details - Added Mermaid sequence diagram showing cross-instance communication - Completed DefaultSessionStore methods table with 9 missing methods - Added cross-platform read-fresh note to persistence-json.mdx - Updated session protocol with DefaultSessionStore improvements and custom store tip - Added PR chronology to persistence overview concurrency section All read methods (get_chat_history, get_session, get_sessions_by_agent) now reload from disk under FileLock on every call, ensuring multi-process safety without stale cache windows. Co-authored-by: Mervin Praison <MervinPraison@users.noreply.github.com>
Qodo reviews are paused for this user.Troubleshooting steps vary by plan Learn more → On a Teams plan? Using GitHub Enterprise Server, GitLab Self-Managed, or Bitbucket Data Center? |
|
Warning Review limit reached
More reviews will be available in 52 minutes and 4 seconds. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (3)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the documentation to detail the multi-process safety improvements of the session store, explaining how both read and write paths now reload from disk under a file lock to prevent cache staleness. It also updates the API reference tables and adds a Mermaid sequence diagram. The review feedback points out that the Mermaid sequence diagram contains unsupported class definitions that will cause rendering errors, and suggests correcting a tip about the SessionStoreProtocol to avoid referencing methods that are not actually part of the protocol.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
| classDef writer fill:#8B0000,stroke:#7C90A0,color:#fff | ||
| classDef reader fill:#8B0000,stroke:#7C90A0,color:#fff | ||
| classDef file fill:#189AB4,stroke:#7C90A0,color:#fff | ||
|
|
||
| class Writer writer | ||
| class Reader reader | ||
| class Disk file |
There was a problem hiding this comment.
Mermaid sequenceDiagram does not support classDef or class statements (which are used in flowcharts or class diagrams). Including them will cause a rendering error in GitHub and other Markdown viewers. These lines should be removed.
| </Tip> | ||
|
|
||
| <Tip> | ||
| If your custom store backs onto shared storage (Redis, Postgres, S3, another file system), make `get_chat_history`, `get_session`, and `get_sessions_by_agent` read from that backing store on every call rather than caching in process memory. `DefaultSessionStore` guarantees this; downstream code such as `BotSessionManager._load_history` relies on it. |
There was a problem hiding this comment.
The SessionStoreProtocol only defines five core methods: add_message, get_chat_history, clear_session, delete_session, and session_exists. It does not define get_session or get_sessions_by_agent, nor does BotSessionManager or other downstream code rely on those methods being present in custom stores. This tip should be updated to only mention get_chat_history to avoid confusing developers implementing custom stores.
If your custom store backs onto shared storage (Redis, Postgres, S3, another file system), make get_chat_history read from that backing store on every call rather than caching in process memory. DefaultSessionStore guarantees this; downstream code such as BotSessionManager._load_history relies on it.
There was a problem hiding this comment.
Pull request overview
This PR updates the documentation to reflect the “read-fresh under FileLock” guarantee for DefaultSessionStore, ensuring multi-process/multi-instance users understand that key read APIs reload from disk and don’t serve stale in-memory cache data.
Changes:
- Expanded multi-process safety docs to explicitly cover disk-fresh reads (plus a sequence diagram).
- Updated protocol/custom-store guidance to encourage “read from backing store on each call” behavior.
- Added/updated persistence docs to mention read-side locking/reload behavior and the PR chronology.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| docs/features/session-persistence.mdx | Documents read-fresh guarantees, adds a Mermaid sequence diagram, and expands the DefaultSessionStore methods table. |
| docs/features/persistence-json.mdx | Adds a cross-platform note clarifying that key read APIs lock + reload from disk each call. |
| docs/features/session-protocol.mdx | Adds custom-store guidance and updates the DefaultSessionStore card to mention read-fresh behavior. |
| docs/persistence/overview.mdx | Adds PR chronology text documenting evolution from write-side to read-side concurrency/read-fresh guarantees. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| <Tip> | ||
| If your custom store backs onto shared storage (Redis, Postgres, S3, another file system), make `get_chat_history`, `get_session`, and `get_sessions_by_agent` read from that backing store on every call rather than caching in process memory. `DefaultSessionStore` guarantees this; downstream code such as `BotSessionManager._load_history` relies on it. | ||
| </Tip> |
| <CardGroup cols={2}> | ||
| <Card icon="file" title="DefaultSessionStore"> | ||
| JSON file-based persistence with atomic writes and file locking. Zero dependencies. | ||
| JSON file-based persistence with atomic writes and file locking. Zero dependencies. All mutating methods *and* read methods reload from disk inside the file lock, so multiple processes can safely share one session directory. |
| | `clear_session(session_id)` | Clear all messages | | ||
| | `delete_session(session_id)` | Delete session completely | | ||
| | `list_sessions(limit)` | List all sessions | | ||
| | `invalidate_cache(session_id)` | Drop the in-memory cache entry (no-op for reads; reads always reload) | |
| The session store uses file locking to ensure safe concurrent access: | ||
| The session store is safe under concurrent multi-process and multi-instance use on **both reads and writes**: | ||
|
|
||
| - **Atomic writes** — every mutator (`add_message`, `set_agent_info`, `set_gateway_info`, `clear_session`, `update_session_metadata`) reloads the session from disk inside `FileLock`, mutates, then atomically writes (temp file + `os.replace`). Concurrent writers cannot drop each other's messages. |
| These improvements were added in PraisonAI PR #1466 to ensure robust multi-threaded operation in production environments. | ||
| </Note> | ||
|
|
||
| The JSON session store (`DefaultSessionStore`) reloads from disk under `FileLock` for every mutator as of PR #1709 (metadata), PR #1724 (agent info, gateway info, clear), and PR #1727 (`LocalManagedAgent._persist_state`). PRs #1759 and #1764 extended the same `FileLock`-guarded reload to the read path (`get_chat_history`, `get_session`, `get_sessions_by_agent`), so two processes pointed at the same `~/.praisonai/sessions/` directory observe each other's writes without any stale-cache window. |
Fixes #474
Fixes #449
Summary
Documents the read-fresh guarantee changes from PraisonAI PR #1764 that ensure DefaultSessionStore reads always reload from disk under FileLock.
Changes Made
docs/features/session-persistence.mdx
docs/features/persistence-json.mdx
docs/features/session-protocol.mdx
docs/persistence/overview.mdx
Implementation Verified
All documentation changes are based on verified SDK source code:
Generated with Claude Code