fix: GlobalRuntime direct access for auxiliary memory

[amithad]

Description

There was no way of accessing the auxiliary cache without accessing the Runtime object for users. This PR solves that by introducing AuxiliaryCache class.

Direct exposure of GlobalRuntime class has also been removed.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Performance improvement
• Test update
• CI/CD update
• Other (please describe):

Related Issues

Changes Made

• Introduced AuxiliaryCache
• Replaced GlobalRuntime access with ModuleLoader wherever needed
• Documentation and examples have been updated

Testing

• Unit tests pass locally
• Integration tests pass locally
• Manual testing completed
• New tests added for changes

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published

Screenshots (if applicable)

Additional Notes

[Copilot]

Pull request overview

This PR refactors the auxiliary memory access pattern by introducing the AuxiliaryCache class as a cleaner public API for accessing volatile and non-volatile caches. The change removes direct exposure of GlobalRuntime to external users while maintaining internal access through ModuleLoader.runtime().

Key changes:

• Introduced AuxiliaryCache with static methods get_volatile_cache() and get_non_volatile_cache() as the new public API
• Replaced GlobalRuntime.instance() access with ModuleLoader.runtime() in internal API handlers and services
• Updated all examples and documentation to use the new AuxiliaryCache API

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
ak-py/src/agentkernel/core/runtime.py	Added AuxiliaryCache class with static methods for cache access; moved cache retrieval methods from Runtime to AuxiliaryCache
ak-py/src/agentkernel/core/__init__.py	Updated exports to expose AuxiliaryCache instead of GlobalRuntime
ak-py/src/agentkernel/core/service.py	Changed from GlobalRuntime.instance() to ModuleLoader.runtime() for internal runtime access
ak-py/src/agentkernel/api/handler.py	Updated agent listing to use ModuleLoader.runtime() instead of GlobalRuntime.instance()
ak-py/src/agentkernel/api/mcp/akmcp.py	Updated MCP integration to use ModuleLoader.runtime() for agent access
ak-py/src/agentkernel/api/a2a/a2a.py	Updated A2A integration to use ModuleLoader.runtime() for agent access
examples/memory/key-value-cache/app.py	Updated example to use AuxiliaryCache.get_volatile_cache() instead of GlobalRuntime.instance().get_volatile_cache()
examples/memory/key-value-cache/README.md	Updated documentation to reference new AuxiliaryCache API
examples/api/hooks/demonstration.py	Updated import to use agentkernel.core.runtime.GlobalRuntime for internal demonstration purposes
examples/api/hooks/README.md	Updated example code snippets to show module-based hook registration instead of runtime-based
docs/docs/architecture/memory-management.md	Updated documentation to reference AuxiliaryCache API for cache access
docs/blog/2025-12-18-hooks-and-smart-memory.md	Updated blog examples to use AuxiliaryCache.get_volatile_cache()
ak-py/src/agentkernel/core/session/base.py	Minor docstring formatting improvement for consistency

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[tharindud]

This looks fine. However I would suggest the following changes.

• The ModuleLoader.runtime() was put in place for the module loader to access the current active runtime. This is externally set when a Runtime is activated via with.
• It would be better to refactor this code for general use. For example we could improve this by moving this to the Runtime class. For example, Runtime.current() could return the currently active runtime (either a Runtime instance captured with or defaulting to the GlobalRuntime instance).
• We can then get rid of ModuleLoader.runtime() and replace it with Runtime.current().