[Python SDK] Document memory scope hierarchy

[santoshkumarradha]

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:

1. Available scopes: List all memory scopes with descriptions
2. Scope hierarchy: Explain how scopes relate to each other
3. Use cases: When to use each scope
4. Lifecycle: When data in each scope is cleared
5. 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.