feat(agent-memory): add agent memory client module

[santoshnallur-sap]

Description

Adds the agent_memory module — a client for the SAP HANA Agent Memory service that lets AI agents persist and retrieve memories and conversation messages. Key capabilities:

• Memory CRUD: create, read, update, and delete named memory entries scoped to an agent/invoker pair
• Semantic search: vector-based memory search with configurable similarity threshold and result limit
• Message management: store and retrieve ordered conversation messages (USER / ASSISTANT / SYSTEM / TOOL roles) grouped by conversation thread
• OData filtering: FilterDefinition for substring filtering on content and metadata fields, with safe single-quote escaping to prevent OData injection
• Retention configuration: read and update per-category data retention policies (messages, memories, usage logs)
• Auto-configuration: resolves service credentials from a BTP-mounted volume (/etc/secrets/appfnd/hana-agent-memory/default/) with environment variable fallback (CLOUD_SDK_CFG_HANA_AGENT_MEMORY_DEFAULT_*)
• Telemetry: all client operations emit SDK-standard metrics via the existing record_metrics decorator

Type of Change

• New feature (non-breaking change that adds functionality)
• Bug fix (non-breaking change that fixes an issue)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

How to Test

1. Install the SDK and configure credentials:

   pip install sap-cloud-sdk
   export CLOUD_SDK_CFG_HANA_AGENT_MEMORY_DEFAULT_APPLICATION_URL=http://localhost:3000
   # For authenticated environments, also set:
   # CLOUD_SDK_CFG_HANA_AGENT_MEMORY_DEFAULT_UAA_URL
   # CLOUD_SDK_CFG_HANA_AGENT_MEMORY_DEFAULT_UAA_CLIENTID
   # CLOUD_SDK_CFG_HANA_AGENT_MEMORY_DEFAULT_UAA_CLIENTSECRET

2. Run unit tests:

   uv run pytest tests/agent_memory/unit/ -q

3. Verify key scenarios covered by unit tests:

   • test_client.py — all CRUD, search, and retention operations; validation errors; pagination
   • test_config.py — credential loading from mounted volume and environment variables
   • test_http_transport.py — OAuth2 token acquisition, retry, error mapping
   • test_odata.py — filter expression building and single-quote injection escaping
   • test_models.py — Memory, Message, SearchResult, RetentionConfig serialization

4. Smoke test with the public API:

   from sap_cloud_sdk.agent_memory import create_client
   
   with create_client() as client:
       mem = client.add_memory("my-agent", "user-42", "Remember to follow up on proposal")
       results = client.search_memories("my-agent", "user-42", "proposal follow up")
       client.delete_memory(mem.memory_id)

Checklist

• My code follows the project's Code Guidelines
• I have added type hints for all public APIs
• I have added unit tests covering the new functionality
• I have added or updated the user guide (user-guide.md) in the module directory
• All existing tests pass locally
• My commits follow Conventional Commits format
• No confidential or SAP-internal information is included

Additional Notes

• The OData transport layer uses requests-oauthlib for OAuth2 client-credentials flow; token refresh is handled automatically.
• FilterDefinition.target is validated against an explicit allowlist at call time; duplicate targets in a single filter list are intentionally allowed (AND-combined) so callers can express multi-value substring checks on the same field.
• The module follows the same py.typed / __all__ / user-guide.md conventions as existing SDK modules.

Disclaimer: Do not include SAP-internal or customer-specific information in this PR. This is a public repository.

[cla-assistant]

All committers have signed the CLA.

[cassiofariasmachado]

Great work and contribution!