Skip to content
Back to search

Android-App-Memory-Analysis

A comprehensive toolkit for Android application memory analysis, featuring one-click live dump from connected devices and multi-source correlation analysis for deep memory insights.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gracker--android-app-memory-analysis/badge.svg)](/listings/gracker--android-app-memory-analysis)

HTML

<a href="/listings/gracker--android-app-memory-analysis"><img src="/api/listings/gracker--android-app-memory-analysis/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- Python 3.8+ - ADB (Android Debug Bridge) in your PATH or in `tools/` folder - Connected Android device with USB debugging enabled

Android 17 / API 37 Compatibility Notes

- The Demo APK now uses `compileSdk = 37`, `targetSdk = 37`, and demo version `1.1.0`, while keeping Android 16 edge-to-edge handling and 16 KB page-size alignment for native `.so` output. - The toolkit supports Android 4.0 through Android 17+ input formats; parsing logic includes newer allocator and mapping names such as Scudo, GWP-ASan, DMA-BUF, stack/TLS, and JIT caches. - Panorama analysis now treats `dumpsys meminfo` as the primary row ledger and attaches same-category `smaps` PSS/SwapPSS and mapping evidence to every comparable row. Memtrack rows remain explicitly non-comparable, while smaps-only input still reports native allocator, graphics, DMA-BUF, code, stack, and top mappings. - Android 17 app memory limits are an Android 17 all-app runtime behavior on supported devices. Live dump now archives `exit_info.txt`, `memory_limiter_status.txt`, package UID, process lists, Android release/sdk, build fingerprint, and page size before requiring PID-dependent artifacts. - For `smaps` collection, use fallback order for better device compatibility: 1) `adb shell cat /proc/<pid>/smaps` 2) `adb shell su -c "cat /proc/<pid>/smaps"` 3) `adb shell su 0 cat /proc/<pid>/smaps` - `pidof` is preferred for PID lookup, and `ps -A` parsing is used as fallback. - See [Android 17 / API 37 Adaptation Review](./docs/en/android_17_adaptation_review.md) for the Android 17 build, memory-limiter, runtime, and evidence checklist. - See [Android 16 / API 36 Adaptation Review](./docs/en/android_16_adaptation_review.md) for the Android 16 and 16 KB page-size baseline.

Installation

git clone https://github.com/Gracker/Android-App-Memory-Analysis.git
cd Android-App-Memory-Analysis

Usage

One-Click Live Dump & Analysis (Recommended)

# List running apps on connected device
python3 analyze.py live --list

# Dump and analyze a specific app
python3 analyze.py live --package com.example.app

# Quick mode (skip hprof for faster results)
python3 analyze.py live --package com.example.app --skip-hprof

# Dump only (no analysis)
python3 analyze.py live --package com.example.app --dump-only -o ./dumps

Panorama Analysis (Multi-Source Correlation)

# Analyze existing dump directory
python3 analyze.py panorama -d ./dumps/com.example.app_20231225_120000

# Analyze individual files
python3 analyze.py panorama -m meminfo.txt -g gfxinfo.txt -H app.hprof -S smaps.txt

# Analyze privileged process mappings only
python3 analyze.py panorama -S smaps.txt --json -o smaps_panorama.json

Individual File Analysis

# Analyze Java heap (HPROF)
python3 analyze.py hprof demo/hprof_sample/heapdump_latest.hprof.gz

# Analyze native memory (smaps)
python3 analyze.py smaps demo/smaps_sample/smaps

# Analyze meminfo
python3 analyze.py meminfo dump/meminfo.txt

# Analyze gfxinfo
python3 analyze.py gfxinfo dump/gfxinfo.txt

# Traditional combined analysis (HPROF + smaps)
python3 analyze.py combined -H demo/hprof_sample/heapdump_latest.hprof.gz -S demo/smaps_sample/smaps

# Enhanced combined analysis (meminfo-aware, mtrack included)
python3 analyze.py combined --modern --hprof demo/hprof_sample/heapdump_latest.hprof.gz --smaps demo/smaps_sample/smaps --meminfo demo/smaps_sample/meminfo.txt --json-output report.json

# One-command demo shortcut (built-in hprof+smaps+meminfo)
python3 analyze.py combined --demo --json-output demo_report.json

Notes: - `combined` defaults to legacy mode (`combined_analyzer.py`) unless `--modern`, `--meminfo`, `--pid`, `--json-output`, or `--demo` is provided. - In modern mode with `-p/--pid`, the tool auto-collects `smaps` and tries to collect `dumpsys meminfo -d`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 281 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Android App Memory Analysis
  2. [中文版本](./README_zh.md) | English Version
  3. A comprehensive toolkit for Android application memory analysis, featuring **one-click live dump** from connected devices and **multi-source correlation analysis** for deep memory insights.
  4. ## Features
  5. ### Core Capabilities
  6. | Feature | Description | Root Required |
  7. |---------|-------------|---------------|
  8. | **Live Dump** | One-click dump all memory data from connected device | Partial (see below) |
  9. | **Panorama Analysis** | Multi-source correlation (meminfo + gfxinfo + hprof + smaps) | No |
  10. | **HPROF Analysis** | Java heap analysis, leak detection, large object tracking | No |
  11. | **SMAPS Analysis** | Native memory mapping, detailed memory classification | Yes |
  12. | **Meminfo Analysis** | Parse `dumpsys meminfo` including Native Allocations | No |
  13. | **Gfxinfo Analysis** | Parse `dumpsys gfxinfo` for GPU/Graphics stats | No |
  14. ### Root Permission Requirements
  15. | Data Source | Without Root | With Root |
  16. |-------------|--------------|-----------|
  17. | dumpsys meminfo | ✅ Full data | ✅ Full data |
  18. | dumpsys gfxinfo | ✅ Full data | ✅ Full data |
  19. | hprof dump | ⚠️ Debuggable apps only | ✅ All apps |
  20. | smaps | ❌ Permission denied | ✅ Full data |
  21. ## Quick Start
  22. ### Prerequisites
  23. - Python 3.8+
  24. - ADB (Android Debug Bridge) in your PATH or in `tools/` folder
  25. - Connected Android device with USB debugging enabled
  26. ### Android 17 / API 37 Compatibility Notes
  27. - The Demo APK now uses `compileSdk = 37`, `targetSdk = 37`, and demo version `1.1.0`, while keeping Android 16 edge-to-edge handling and 16 KB page-size alignment for native `.so` output.
  28. - The toolkit supports Android 4.0 through Android 17+ input formats; parsing logic includes newer allocator and mapping names such as Scudo, GWP-ASan, DMA-BUF, stack/TLS, and JIT caches.
  29. - Panorama analysis now treats `dumpsys meminfo` as the primary row ledger and attaches same-category `smaps` PSS/SwapPSS and mapping evidence to every comparable row. Memtrack rows remain explicitly non-comparable, while smaps-only input still reports native allocator, graphics, DMA-BUF, code, stack, and top mappings.
  30. - Android 17 app memory limits are an Android 17 all-app runtime behavior on supported devices. Live dump now archives `exit_info.txt`, `memory_limiter_status.txt`, package UID, process lists, Android release/sdk, build fingerprint, and page size before requiring PID-dependent artifacts.
  31. - For `smaps` collection, use fallback order for better device compatibility:
  32. 1) `adb shell cat /proc/<pid>/smaps`
  33. 2) `adb shell su -c "cat /proc/<pid>/smaps"`
  34. 3) `adb shell su 0 cat /proc/<pid>/smaps`
  35. - `pidof` is preferred for PID lookup, and `ps -A` parsing is used as fallback.
  36. - See [Android 17 / API 37 Adaptation Review](./docs/en/android_17_adaptation_review.md) for the Android 17 build, memory-limiter, runtime, and evidence checklist.
  37. - See [Android 16 / API 36 Adaptation Review](./docs/en/android_16_adaptation_review.md) for the Android 16 and 16 KB page-size baseline.
  38. ### Installation
  39. ```bash
  40. git clone https://github.com/Gracker/Android-App-Memory-Analysis.git
  41. cd Android-App-Memory-Analysis
  42. ```
  43. ### Usage
  44. #### One-Click Live Dump & Analysis (Recommended)
  45. ```bash
  46. # List running apps on connected device
  47. python3 analyze.py live --list
  48. # Dump and analyze a specific app
  49. python3 analyze.py live --package com.example.app
  50. # Quick mode (skip hprof for faster results)
  51. python3 analyze.py live --package com.example.app --skip-hprof
  52. # Dump only (no analysis)
  53. python3 analyze.py live --package com.example.app --dump-only -o ./dumps
  54. ```
  55. #### Panorama Analysis (Multi-Source Correlation)
  56. ```bash
  57. # Analyze existing dump directory
  58. python3 analyze.py panorama -d ./dumps/com.example.app_20231225_120000
  59. # Analyze individual files
  60. python3 analyze.py panorama -m meminfo.txt -g gfxinfo.txt -H app.hprof -S smaps.txt
  61. # Analyze privileged process mappings only
  62. python3 analyze.py panorama -S smaps.txt --json -o smaps_panorama.json
  63. ```
  64. #### Individual File Analysis
  65. ```bash
  66. # Analyze Java heap (HPROF)
  67. python3 analyze.py hprof demo/hprof_sample/heapdump_latest.hprof.gz
  68. # Analyze native memory (smaps)
  69. python3 analyze.py smaps demo/smaps_sample/smaps
  70. # Analyze meminfo
  71. python3 analyze.py meminfo dump/meminfo.txt
  72. # Analyze gfxinfo
  73. python3 analyze.py gfxinfo dump/gfxinfo.txt
  74. # Traditional combined analysis (HPROF + smaps)
  75. python3 analyze.py combined -H demo/hprof_sample/heapdump_latest.hprof.gz -S demo/smaps_sample/smaps
  76. # Enhanced combined analysis (meminfo-aware, mtrack included)
  77. python3 analyze.py combined --modern --hprof demo/hprof_sample/heapdump_latest.hprof.gz --smaps demo/smaps_sample/smaps --meminfo demo/smaps_sample/meminfo.txt --json-output report.json
  78. # One-command demo shortcut (built-in hprof+smaps+meminfo)
  79. python3 analyze.py combined --demo --json-output demo_report.json
  80. ```
  81. Notes:
  82. - `combined` defaults to legacy mode (`combined_analyzer.py`) unless `--modern`, `--meminfo`, `--pid`, `--json-output`, or `--demo` is provided.
  83. - In modern mode with `-p/--pid`, the tool auto-collects `smaps` and tries to collect `dumpsys meminfo -d`.
  84. - The bundled demo HPROF is committed as `heapdump_latest.hprof.gz` to avoid large-file push limits. The unified `analyze.py` entry point reads `.hprof.gz` directly. If an old sample path ending in `.hprof` is missing but a sibling `.hprof.gz` exists, it automatically falls back to the packaged sample.
  85. ## AI Evidence Context and Skills
  86. The provider-neutral `ai-context` protocol validates artifacts, separates accounting domains, exposes missing/conflicting input, and selects versioned theory records with official sources before any AI interprets the case. It never uploads artifacts or calls an external model.
  87. New live dumps include a structured `manifest.json`, so skipped, unsupported, permission-denied, failed, and genuinely collected states remain distinguishable instead of becoming a generic “missing” file.
  88. The normal RD workflow is folder-first: download the complete QA handoff into one directory, then provide that directory plus the issue title or symptom. The context recursively inventories every regular file, treats names as hints rather than truth, classifies supported evidence by content, preserves multiple artifacts, and reports unclassified files and scan limits instead of silently ignoring them. Recognized evidence also augments intent routing, so a vague “memory increased” issue can evaluate the Java, native, graphics, or system-pressure branch actually present in the folder. It recognizes Android/logcat logs (plain text or gzip) and PNG/JPEG/WebP screenshots alongside dumps and reports.
  89. Plain, gzip, and bugreport ZIP logs receive a bounded scan for LeakCanary, resource-leak, OOM, GC, JNI, graphics/database/Binder, LMKD, and kernel-OOM signals, but no raw log lines or screenshot pixels are embedded. Signals carry line numbers/hashes (and ZIP member binding); screenshots carry dimensions/hashes and must be visually inspected before use.
  90. ```bash
  91. python3 analyze.py ai-context \
  92. -d ./qa-handoff/ANDROID-1234 \
  93. --question "Native memory keeps growing after the screen exits" \
  94. --format json \
  95. -o android-memory-context.json
  96. ```
  97. Importable Skills live under `skills/`:
  98. - `android-memory-evidence` validates partial or inaccurate inputs and gives exact capture guidance;
  99. - `android-memory-diagnose` combines artifact-bound facts with versioned theory;
  100. - `android-memory-remediate` changes code only after ownership and mechanism are supported, then verifies the matching scenario.
  101. Install the complete public package into the current AI project (Node.js 18+ and Python 3.8+):
  102. ```bash
  103. npx skills add Gracker/Android-App-Memory-Analysis \
  104. --skill '*'
  105. ```
  106. For a global Codex install, add `--agent codex --global`. The Evidence Skill includes its validated runtime and knowledge catalog, so installed copies can create contexts without cloning this repository or setting `ANDROID_MEMORY_ANALYSIS_ROOT`. The full analyzer checkout is only an optional enhancement for live capture, panorama, diff, and helper-driven Perfetto workflows.
  107. For a second pass, point the Skill at the same complete QA folder and describe whether the prior result should be challenged or extended. It rescans the whole tree, recognizes prior contexts/reports, compares added/changed/missing/unchanged evidence, and requires every material old claim to be confirmed, revised, retracted, or left unresolved. Prior material outside the folder can be supplied with repeatable `--previous-context` and `--previous-analysis` options.
  108. See [Android Memory AI Workflow](./docs/en/ai_workflow.md) for architecture, schema, installation, refresh, privacy boundaries, and verification.
  109. ## What Gets Analyzed?
  110. ### Panorama Analysis Output
  111. The panorama analysis starts from the familiar `dumpsys meminfo` table, preserves
  112. every row in source order, and uses `smaps` as drill-down evidence rather than a
  113. separate replacement summary:
  114. ```
  115. [ meminfo Primary Ledger + smaps Row Evidence ]
  116. Category Mem PSS PrivDirty SwapPss smaps PSS Delta Status
  117. Native Heap 80860 80824 25 80860 +0 aligned
  118. Dalvik Heap 59439 59420 69 59439 +0 aligned
  119. EGL mtrack 54432 54432 0 - - not-comparable
  120. ...
  121. TOTAL 337790 293788 162 - - see-total
  122. Row interpretation:
  123. - Native Heap: smaps identifies Scudo primary/secondary mappings without
  124. overwriting the meminfo Native Heap value.
  125. - EGL mtrack: driver/HAL attribution is preserved and is not subtracted from
  126. `/proc/<pid>/smaps`.
  127. 🖼️ Bitmap Deep Analysis:
  128. ------------------------------
  129. Bitmap (malloced): 27 objects 6.78 MB
  130. Bitmap (nonmalloced): 8 objects 11.59 MB
  131. GPU Cache: 15.34 MB
  132. GraphicBuffer: 12.45 MB
  133. 📈 Native Memory Tracking:
  134. ------------------------------
  135. Tracked Native: 28.45 MB (83.2%)
  136. Untracked Native: 5.76 MB (16.8%)
  137. ⚠️ Warning: Significant untracked Native memory detected
  138. 🎨 UI Resources:
  139. ------------------------------
  140. Views: 1,234
  141. ViewRootImpl: 3
  142. Activities: 5
  143. WebViews: 0
  144. ```
  145. ### Key Analysis Features
  146. 1. **meminfo-first row ledger**: Preserves every familiar meminfo category and field
  147. 2. **smaps row supplements**: Adds category PSS/SwapPSS, allocator subtypes, mappings, and explicit reconciliation
  148. 3. **Bitmap Correlation**: Links Java Bitmap objects to Native pixel memory
  149. 4. **Native Memory Tracking**: Identifies tracked vs untracked Native allocations
  150. 5. **GPU Memory Analysis**: GraphicBuffer and GPU cache usage
  151. 6. **UI Resource Counting**: View hierarchy and Activity leak detection
  152. 7. **Anomaly Detection**: Automatic warnings for potential issues
  153. ## Project Structure
  154. ```
  155. Android-App-Memory-Analysis/
  156. ├── analyze.py # Main entry point
  157. ├── tools/
  158. │ ├── hprof_parser.py # HPROF file parser
  159. │ ├── smaps_parser.py # smaps file parser
  160. │ ├── meminfo_parser.py # dumpsys meminfo parser
  161. │ ├── gfxinfo_parser.py # dumpsys gfxinfo parser
  162. │ ├── panorama_analyzer.py # Multi-source correlation analyzer
  163. │ ├── combined_analyzer.py # HPROF + smaps combined analyzer
  164. │ ├── memory_analyzer.py # Enhanced combined analyzer with meminfo/mtrack correlation
  165. │ ├── live_dumper.py # Live dump from device
  166. │ ├── hprof_dumper.py # HPROF dump utility
  167. │ └── adb # ADB binary (optional)
  168. ├── demo/
  169. │ ├── hprof_sample/ # Latest sample HPROF + analysis output
  170. │ ├── smaps_sample/ # Latest sample smaps/meminfo/showmap/gfxinfo + reports
  171. │ └── memory-lab/ # Demo APK project used to regenerate sample datasets
  172. ├── docs/
  173. │ ├── en/ # English documentation
  174. │ └── zh/ # Chinese documentation
  175. └── pic/ # Images for documentation
  176. ```
  177. ## Documentation
  178. For detailed guides on interpreting analysis results:
  179. - [English Learning Path](./docs/en/README.md)
  180. - [Analysis Results Guide](./docs/en/analysis_results_interpretation_guide.md)
  181. - [Meminfo Interpretation](./docs/en/meminfo_interpretation_guide.md)
  182. - [SMAPS Interpretation](./docs/en/smaps_interpretation_guide.md)
  183. - [Android 17 / API 37 Adaptation Review](./docs/en/android_17_adaptation_review.md)
  184. - [Android 16 / API 36 Adaptation Review](./docs/en/android_16_adaptation_review.md)
  185. - [Teaching Playbook](./docs/en/teaching_playbook.md)
  186. - [Chinese Learning Path](./docs/zh/README.md)
  187. - [分析结果解读指南](./docs/zh/analysis_results_interpretation_guide.md)
  188. - [meminfo 解读](./docs/zh/meminfo_interpretation_guide.md)
  189. - [smaps 解读](./docs/zh/smaps_interpretation_guide.md)
  190. - [Android 17 / API 37 适配 Review](./docs/zh/android_17_adaptation_review.md)
  191. - [教学实践手册](./docs/zh/teaching_playbook.md)
  192. - [Demo APK case study (Chinese)](./docs/zh/memory_lab_demo_case_study.md)
  193. ## Data Sources
  194. | Data Source | Command | Information Provided |
  195. |-------------|---------|---------------------|
  196. | smaps | `cat /proc/<pid>/smaps` | Detailed memory mapping |
  197. | hprof | `am dumpheap <pkg> <path>` | Java heap objects and references |
  198. | meminfo | `dumpsys meminfo <pkg>` | Summary + Native Allocations (Bitmap stats) |
  199. | gfxinfo | `dumpsys gfxinfo <pkg>` | GPU cache, GraphicBuffer, frame stats |
  200. ## Related Tools
  201. This toolkit complements these Android memory analysis tools:
  202. - **Android Studio Profiler**: Real-time memory monitoring
  203. - **LeakCanary**: Automatic memory leak detection
  204. - **MAT (Memory Analyzer Tool)**: Deep HPROF analysis
  205. - **Perfetto**: System-wide tracing
  206. ## Contributing
  207. Contributions are welcome! Please feel free to submit pull requests or open issues.
  208. ## License
  209. Licensed under the [Apache License 2.0](./LICENSE). Each independently installed Skill includes the same license text.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.