docs: Update session-hierarchy for invalidate_cache() + multi-worker cache consistency#494
Conversation
…cache consistency (fixes #493) - Add Multi-Worker Safety section with sequence diagram showing cross-instance consistency - Add Cache Invalidation section documenting new invalidate_cache() method - Update API Reference with get_extended_session() and invalidate_cache() signatures - Add Best Practices AccordionGroup with multi-worker guidance - Update Quick Start to be agent-centric per AGENTS.md requirements - Add Related CardGroup linking to session management concepts - Include hero Mermaid diagram with standard color scheme 🤖 Generated with Claude Code Co-authored-by: Mervin Praison <MervinPraison@users.noreply.github.com>
|
Warning Review limit reached
More reviews will be available in 50 minutes and 50 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 (1)
✨ 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 |
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? |
![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 session hierarchy documentation to explain multi-worker safety, cache invalidation, and best practices, including new Mermaid diagrams and API references. However, several issues were identified in the documentation and underlying implementation: the Agent initialization examples incorrectly pass an unsupported session_store parameter, which will cause runtime errors; the invalidate_cache method in HierarchicalSessionStore is functionally incomplete as it fails to clear the _extended_cache; and a code comment inaccurately describes the default directory behavior when session_dir is omitted.
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.
| agent = Agent( | ||
| name="Assistant", | ||
| instructions="You can fork conversations and create snapshots", | ||
| session_store=store | ||
| ) |
There was a problem hiding this comment.
The Agent class constructor does not accept a session_store parameter. Attempting to initialize an Agent with session_store=store will raise a TypeError: __init__() got an unexpected keyword argument 'session_store' at runtime.
Please correct the documentation to show the proper way to configure or associate a custom HierarchicalSessionStore with an Agent (for example, by passing it via the memory configuration or another supported mechanism).
| agent1 = Agent( | ||
| name="Assistant", | ||
| session_store=HierarchicalSessionStore(session_dir=shared_dir) | ||
| ) | ||
|
|
||
| # Worker 2 | ||
| agent2 = Agent( | ||
| name="Assistant", | ||
| session_store=HierarchicalSessionStore(session_dir=shared_dir) | ||
| ) |
There was a problem hiding this comment.
Similar to the previous comment, the Agent class constructor does not accept a session_store parameter. Initializing agent1 and agent2 with session_store=... will raise a TypeError at runtime.
Please update this multi-worker setup example to use the correct configuration pattern for associating a custom session store with Agent instances.
| def invalidate_cache(self, session_id: Optional[str] = None) -> None: | ||
| """Clear in-memory caches. Pass session_id for one session, omit for all.""" |
There was a problem hiding this comment.
The documented invalidate_cache method on HierarchicalSessionStore is currently broken/incomplete in the codebase.
HierarchicalSessionStore inherits invalidate_cache from DefaultSessionStore, which only clears self._cache (holding SessionData objects). However, HierarchicalSessionStore introduces and uses self._extended_cache to cache ExtendedSessionData objects. Because invalidate_cache is not overridden in HierarchicalSessionStore to clear self._extended_cache, calling store.invalidate_cache() will leave the extended cache intact, and subsequent calls to get_extended_session() will continue to return stale cached data instead of reloading fresh from disk.
To fix this, HierarchicalSessionStore in praisonaiagents/session/hierarchy.py must override invalidate_cache to also clear self._extended_cache:
def invalidate_cache(self, session_id: Optional[str] = None) -> None:
"""Clear in-memory caches. Pass session_id for one session, omit for all."""
super().invalidate_cache(session_id)
with self._lock:
if session_id:
self._extended_cache.pop(session_id, None)
else:
self._extended_cache.clear()Please implement this override in praisonaiagents/session/hierarchy.py to ensure the documented cache invalidation behavior works as expected.
|
|
||
| # Bad: New instance per request | ||
| def handle_request(): | ||
| store = HierarchicalSessionStore() # Creates new temp dir each time |
There was a problem hiding this comment.
The comment # Creates new temp dir each time is inaccurate. When session_dir is not provided, HierarchicalSessionStore (via DefaultSessionStore) defaults to DEFAULT_SESSION_DIR (which points to a centralized, persistent directory like ~/.praisonai/sessions/), rather than creating a new temporary directory on each instantiation.
While creating a new store instance per request is still inefficient and should be avoided, the explanation of why it is bad should be corrected to avoid misleading users.
store = HierarchicalSessionStore() # Re-initializes store and re-reads centralized directory each time
1 participant
Fixes #493
Summary
Changes Based on Upstream PR #1785
Documentation Standards
🤖 Generated with Claude Code