| **Note:** The Memory Advice API Beta is now over and the library is deprecated. [learn more about alternative memory management approaches](https://developer.android.com/games/optimize/memory-allocation).

The Memory Advice API is an experimental native API that
helps Android apps stay within safety limits for memory use. The API
achieves this by estimating the amount of memory resources that are in use, and
then notifying the app when certain thresholds are exceeded. The API can
also report the estimated percentage of memory use directly to your app.

The estimations provided by the API help to determine when your app should
adjust its memory use, or to find areas to improve in future versions of your
app. The adjustments could include anything that changes memory consumption, such
as lowering the details and quality of visual and audio assets.

The estimated memory resources include native heap memory allocated by malloc,
and graphics memory allocated by the OpenGL ES and Vulkan Graphics APIs making
the Memory Advice API ideal for games and graphic intensive apps.

The estimates are made based on the following:

- Device metrics collected by the API
- Machine learning data from devices
- Device testing

At the API level, the Memory Advice API defines a set of memory
advice states and communicates them to apps with a set of functions.

[Get Started](https://developer.android.com/games/sdk/memory-advice/start)
[Get Started for Unity games](https://developer.android.com/games/engines/unity/memory-advice)

## Distributions

The Memory Advice API is a part of the Android Games Development
Kit (AGDK) and is distributed through the following channels:

- Binary releases in the [Android Games Jetpack libraries](https://developer.android.com/jetpack/androidx/releases/games).
- Binary releases on the [AGDK download page](https://developer.android.com/games/agdk/get-agdk#agdk-libraries).
- Source code on [AOSP](https://android.googlesource.com/platform/frameworks/opt/gamesdk/+/refs/heads/master/test/memoryadvice).

Games should use the Memory Advice API release that is
recommended for their build environment. For Android Studio, we recommend the
Jetpack release. For the [Android Game Development Extension](https://developer.android.com/games/agde)
(AGDE), we recommend the release on the AGDK download page.

## Features

This section describes the Memory Advice API features.

### Memory state

The API reports the following memory states to apps:

- MEMORYADVICE_STATE_OK
- MEMORYADVICE_STATE_APPROACHING_LIMIT
- MEMORYADVICE_STATE_CRITICAL

For details, see the [memoryadvice_memorystate](https://developer.android.com/reference/games/memory-advice/group/memory-advice#memoryadvice_memorystate) reference pages.

### Reporting the memory state

The API supports reporting the memory state through either a polling or a callback mechanism:

- **Polling** :  

  An app can call the API at any time to retrieve the memory state.

- **Callback** :  

  An app can register a callback function with the Memory Advice API.
  The app specifies the calling frequency for the callback. The API
  uses the frequency to determine when to execute the callback when the application memory
  condition is approaching the safe limit or is critically low. The callback is not invoked
  if the memory condition is safe. The callback is executed from its own thread,
  not from a thread belonging to the app.

### Cost and calling frequency considerations

The Memory Advice API uses computational time to generate
the memory status. The cost varies by device, but is usually between 1ms and 3ms
per call. You should consider this overhead when determining how often
to poll the memory state, or what frequency to specify for the memory state callback.

## Requirements

**Device requirements**

- Android 4.4 (API level 19) or higher.

**App requirements**

- The API only supports native apps (apps primarily written in C/C++).

- The API only supports physical devices; emulators are not supported.

**NDK version requirements**

The Memory Advice API release supports most popular NDK versions,
refer to the [release notes](https://developer.android.com/jetpack/androidx/releases/games)
for the supported NDK list.
| **Note:** Addition versions of the NDK are supported by [the full AGDK library](https://developer.android.com/games/agdk/get-agdk#agdk-libraries).

## Additional Resources

- [Memory Advice API release notes](https://developer.android.com/jetpack/androidx/releases/games)
- [Memory Advice API reference documentation](https://developer.android.com/reference/games/memory-advice/group/memory-advice)
- [Memory Advice sample on GitHub](https://github.com/android/games-samples/blob/main/agdk/agdktunnel/app/src/main/cpp/memory_consumer.cpp#L168)
- [Memory Advice API source code](https://android.googlesource.com/platform/frameworks/opt/gamesdk/+/refs/heads/master/games-memory-advice/)

## Issues and Feedback

The Memory Advice API is in beta and welcomes feedback, if you have suggestions or
find issues while using the API, [create an issue in IssueTracker](https://issuetracker.google.com/issues/new?component=897320&template=1456805).