Content
# AndroidMiniMem
A **lightweight** Android remote memory debugging tool, refactored from two existing projects:
- Backend engine `android_mem_engine` (Android ARM64, Cheat Engine protocol server)
- Frontend GUI `AMem` (Windows + Dear ImGui, built-in IPC + Python MCP bridge)
MiniMem retains only the most basic capabilities, removing heavy features like data search, pointer scan, and freeze list, primarily for **facilitating AI-assisted memory debugging via MCP**.
QQ交流群: 1065266874
## Directory Structure (Monorepo)
```
AndroidMiniMem/
├── engine/ Android ARM64 backend (device-side resident socket service)
├── gui/ Windows frontend (connection display + log + Lua + embedded IPC service)
└── mcp/ Python MCP service (exposing IPC capabilities to external AI assistants)
```
## Data Flow
```
External AI Assistant ──(MCP/stdio)──▶ mcp/ (Python)
│ HTTP JSON
▼
gui/ Embedded IpcServer (127.0.0.1:28100)
│ Call socket/client_singleton.h protocol layer
▼
gui/ WinSocketClientMgr ──(TCP)──▶ engine/ socket_server (Android device)
│
▼
Memory read/write / breakpoints / symbols (kernel or syscall)
```
The free functions in `socket/client_singleton.h` are the **single source of truth** for the device protocol; GUI, IPC (MCP) all communicate through it.
## Retained / Removed Capabilities
| Capability | Status | Description |
|------|------|------|
| Process list / module list | ✅ Retained | `list_processes` / `list_modules` / `get_module_base` |
| Memory read / write / batch read | ✅ Retained | `read_memory` / `write_memory` / `read_batch` |
| Hardware breakpoints (set/remove/pause/resume/read hit) | ✅ Retained | `set/remove/suspend/resume_breakpoint` / `read_bp_info` |
| Kernel switching | ✅ Retained | `init_driver` loads/connects kernel driver and hot-swaps `g_memIO` (IO/Syscall/Kernel/SysHook) |
| ELF symbol parsing | ✅ Retained | `symbol_init` / `symbol_list` / `symbol_find` |
| Pointer offset chain resolution | ✅ Retained | `resolve_offset_chain` |
| Lua script engine | ✅ Retained | For complex analysis (`execute_lua` + GUI script window) |
| Data search (initial/secondary/fuzzy/grouping/HEX) | ❌ Removed | — |
| Pointer scan | ❌ Removed | — |
| Freeze list | ❌ Removed | — |
| SO injection / remote mmap | ❌ Removed | — |
| GUI value scan/memory viewer/breakpoint display window | ❌ Removed | Breakpoints no longer displayed on the frontend |
| Built-in AI chat (gui/ai) | ❌ Removed | Replaced with MCP path |
The frontend only retains: main control panel, server connection, module list, log, Lua script manager.
## Build
> **Initial Clone**: `gui/imgui` is a git submodule (Dear ImGui, docking branch), needs initialization:
> ```bash
> git clone https://github.com/niqiuqiux/AndroidMiniMem.git
> cd AndroidMiniMem
> git submodule update --init --recursive
> # or clone with submodules in one step: git clone --recurse-submodules <url>
> ```
### 1. Backend Engine `engine/` (Android ARM64)
Requires Android NDK (r27c/r28c). Produces device-side executable file `bin/socket_server`.
```bash
cd engine
./build.sh # Linux
# or build.bat # Windows
# or directly:
cmake -S . -B build -DANDROID_NDK=<ndk_path> -DCMAKE_BUILD_TYPE=Release
cmake --build build -j
```
Push `socket_server` (and kernel driver `Mem.ko`/`CFI.ko`, if using kernel mode) to the device and run as root, listening on port (default 52736).
### 2. Frontend GUI `gui/` (Windows x64)
Requires Visual Studio 2022 / Clang, CMake, DirectX 12 SDK, and `third_party/LuaJIT` (mandatory). Capstone/Keystone optional (enabling Lua disassembly/assembly).
```bash
cd gui
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build
```
Produces `bin/MiniMemClient.exe`, which automatically starts IPC service on `127.0.0.1:28100` after launch.
### 3. MCP Service `mcp/` (Python 3.10+)
```bash
cd mcp
pip install -e . # Register amem-mcp command
amem-mcp # Start stdio MCP, bridging GUI's IPC service
```
The root directory's `.mcp.json` is configured for Claude Code (`python -m amem_mcp`, `PYTHONPATH` points to `mcp/`). GUI and device connection required before use.
## MCP Tool Overview
Process/module: `list_processes` `open_process` `list_modules` `get_module_base` `resolve_offset_chain`
Memory: `read_memory` `write_memory` `read_batch`
Breakpoints: `set_breakpoint` `remove_breakpoint` `suspend_breakpoint` `resume_breakpoint` `read_bp_info`
Symbols: `symbol_init` `symbol_list` `symbol_find`
Script: `execute_lua`
Status: `get_status` `get_version` `get_architecture` `init_driver`
## Documentation
- [engine/ceserver/cmd.md](engine/ceserver/cmd.md) — Socket binary protocol: command words, wire format, memory read/write "continuous prefix" semantics
- [docs/api_design.md](docs/api_design.md) — API design contract and decisions: continuous prefix read/write three-state, batch read, return value/error convention, module base address/breakpoints/symbols/pointer chain essentials, new API specifications
- Each submodule has its own `CLAUDE.md` (`engine/`, `gui/`) explaining build and architecture.
MCP Store