[Python SDK] Document memory scope hierarchy #121
Description
Summary
The Python SDK memory module supports different scopes (global, session, actor, workflow) but lacks documentation explaining the scope hierarchy and when to use each scope.
Current State
- File:
sdk/python/agentfield/memory.py - Issue: Scope hierarchy and use cases not documented
Tasks
Add comprehensive documentation explaining:
- Available scopes: List all memory scopes with descriptions
- Scope hierarchy: Explain how scopes relate to each other
- Use cases: When to use each scope
- Lifecycle: When data in each scope is cleared
- Examples: Code examples for common patterns
Documentation Content
"""
Memory Scope Hierarchy
======================
AgentField provides four memory scopes for storing agent data:
Global Scope
------------
- Shared across all agents and sessions
- Persists until explicitly deleted
- Use for: Configuration, shared knowledge bases, cross-agent state
Session Scope
-------------
- Scoped to a single user session (conversation)
- Cleared when session ends
- Use for: Conversation context, user preferences within a session
Actor Scope
-----------
- Scoped to a single agent across all sessions
- Persists across sessions
- Use for: Agent-specific learned data, agent configuration
Workflow Scope (Run Scope)
--------------------------
- Scoped to a single workflow execution
- Cleared when workflow completes
- Use for: Intermediate results, execution-specific state
Hierarchy Diagram
-----------------
Global (widest)
|
Session
|
Actor
|
Workflow/Run (narrowest)
Example Usage
-------------
>>> # Store in global scope
>>> await agent.memory.set("config", value, scope="global")
>>>
>>> # Store in session scope
>>> await agent.memory.set("context", value, scope="session")
"""Acceptance Criteria
- Module-level docstring explains all scopes
- Each scope has a clear description and use case
- Include hierarchy diagram (ASCII art)
- Include code examples
- Documentation renders correctly with
help(memory)
Files
sdk/python/agentfield/memory.py
Using AI to solve this issue? Read our AI-Assisted Contributions guide for testing requirements, prompt strategies, and common pitfalls to avoid.