[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.

[1khazipov]

Hello! This is my first issue. May I start with this one?

[santoshkumarradha]

hey @1khazipov all yours !

[github-actions]

Thanks for picking this up, @1khazipov! 🎉

Here's what to expect:

• We'll check in after 7 days if we haven't heard an update
• After 14 days, we'll send a second reminder
• After 21 days without activity, we'll unassign to let others contribute

Tips for success:

• Drop a comment when you start working on it
• Share any blockers - we're here to help!
• Link your PR with Fixes #121 in the description

Happy coding! 🚀

[github-actions]

Hey @1khazipov! 👋

Just a friendly reminder that you're assigned to this issue. It's been about a week since assignment.

How's it going? We'd love to hear:

• Any progress updates?
• Running into any blockers we can help with?
• Need more time? (Totally fine!)

A quick comment helps us know you're still interested. If your plans have changed, no worries at all - just let us know and we can find another contributor.

Thanks for contributing to AgentField! 🚀

[github-actions]

Hi @1khazipov,

Just checking in again! It's been 14 days since we last heard from you on this issue.

Quick options:

• 💬 Drop a comment with a progress update
• 🔗 Link a draft PR if you've started working on it
• 👋 Let us know if you'd like to be unassigned (no judgment!)

If we don't hear back in 7 days, we'll unassign this issue to give other contributors a chance to help.

Thanks for understanding!