Android Memory AI Workflow

This workflow connects the repository's practical collectors/parsers with the proof boundaries maintained in the private Gracker/android-memory theory repository. It does not delegate truth to a model: the repository first creates a validated, provider-neutral context, then Codex, Claude, or another Skills-capable agent interprets that context.

Architecture

Layer	Components	Stable boundary
User and AI project	android-memory-evidence android-memory-diagnose android-memory-remediate	User question, evidence state, separated facts/hypotheses/advice
AI protocol	bundled Skill runtime analyze.py ai-context android_memory_ai.context	android-memory-ai-context schema 1.2 plus generator version
Evidence and knowledge	artifact validators intent coverage QA log/screenshot observations android_memory_catalog.json	Hashes, provenance, accounting domains, versions, gaps, conflicts
Practical tools	meminfo/smaps/HPROF/gfxinfo/DMA-BUF/ZRAM/Perfetto/logcat/panorama/diff	Raw artifacts and backward-compatible derived reports
Android / Linux	ART, Scudo, memtrack, LMKD, PSI, ZRAM, VMAs, process exits	API/kernel/ROM/permission/device variance

Privacy, collection perturbation, package/PID/phase identity, Android version, accounting compatibility, and raw-versus-derived provenance cross every layer.

New live dumps also write manifest.json with per-artifact ok, empty, permission_denied, not_supported, command_failed, skipped, not_applicable, or not_collected state plus command, domain, perturbation, and reason. not_collected never means the memory category is absent.

Create an AI context

The default input is the complete folder downloaded from QA plus the issue title or symptom. Do not require the user to classify or enumerate files first:

python3 analyze.py ai-context \
  -d ./qa-handoff/ANDROID-1234 \
  --question "Native memory keeps growing after the screen exits" \
  --format json \
  -o android-memory-context.json

Create a human-readable report:

python3 analyze.py ai-context \
  -d ./dumps/com.example.app_20260721_120000 \
  --intent native-memory \
  --format markdown \
  --lang en \
  -o android-memory-context.md

Artifact and subject overrides keep partial evidence useful:

python3 analyze.py ai-context \
  -d ./case \
  --meminfo /evidence/meminfo.txt \
  --smaps /evidence/smaps.txt \
  --analysis-report /evidence/panorama.json \
  --package com.example.app \
  --android-sdk 37 \
  --phase after-exit-30s \
  --question "Does this prove a JNI leak?"

Use --strict only for automation. An incomplete context is still written, but the command exits 2.

Follow-up analysis and new evidence

Every follow-up starts by rescanning the complete current folder. If a prior android-memory-ai-context or recognizable analysis report is stored in that folder, the runtime indexes it as analysis history rather than treating it as new memory evidence. It compares the newest prior context snapshot with the current rescan and reports added, changed, missing-since-previous, and unchanged-by-fingerprint artifacts.

The usual interaction needs only the same folder and the user's new request:

python3 analyze.py ai-context \
  -d ./qa-handoff/ANDROID-1234 \
  --question "I disagree with the prior conclusion; QA added logs. Reanalyze the case." \
  --format json \
  -o android-memory-context-v2.json

If the old material lives outside the QA folder, pass repeatable explicit overrides:

python3 analyze.py ai-context \
  -d ./qa-handoff/ANDROID-1234 \
  --previous-context /reviews/android-memory-context-v1.json \
  --previous-analysis /reviews/android-memory-analysis-v1.md \
  --analysis-mode reanalysis-with-new-evidence \
  --question "Recheck the old owner conclusion against the new logs" \
  -o android-memory-context-v2.json

Keep --analysis-mode auto unless the user has explicitly selected the workflow. The runtime distinguishes:

• initial: no prior analysis applies;
• reanalysis: rebuild the current claim ledger independently because the old reasoning is challenged;
• supplement: preserve only still-valid claims and propagate new, changed, or missing evidence;
• reanalysis-with-new-evidence: perform both;
• clarification-required: prior analysis exists, the evidence is unchanged, and the request does not say whether to redo or extend. The folder may still be inventoried, but the agent must clarify the mode before presenting a final diagnosis.

The agent must also inspect the current conversation/task for the previous answer; a context JSON records the earlier evidence snapshot, not necessarily the earlier prose conclusion. Every material old claim must be marked confirmed, revised, retracted, or unresolved, with genuinely new claims listed separately. An unchanged hash does not prove that an old interpretation was correct, and a missing path is not proof of deletion when the scan was truncated or a file was renamed.

QA logs and screenshots

The runtime recursively inventories the QA directory before building context. It does not rely on QA naming conventions: known names and extensions are discovery hints, while content signatures classify supported artifacts. Multiple files of the same type remain distinct. Every indexed regular file is represented either as a recognized artifact or unclassified_file; skipped symlinks, unreadable entries, index truncation, per-type overflow, and hash-budget omissions are explicit limitations. Recognized HPROF, high-specificity log signals, native profiles, and comparisons augment question-based intent routing; generic supporting artifacts do not open unrelated branches. request.intent_source records whether routing came from the question, evidence, both, or an explicit choice.

The directory may contain nested plain/gzip Android logs, bugreport ZIPs, targeted logcat/LeakCanary/bugreport/tombstone/ANR text, PNG/JPEG/WebP screenshots, dumps, traces, reports, or unrelated attachments. The default bounds are 2,048 indexed files, 64 processed artifacts per type, 32 MiB decoded per log/archive, 256 ZIP members, 512 MiB per-file hashing, and 1 GiB total hashing. Use repeatable overrides only for files outside the QA directory:

python3 analyze.py ai-context \
  -d ./case \
  --android-log /qa/logcat-main.log \
  --android-log /qa/system.log.gz \
  --qa-screenshot /qa/leakcanary.png \
  --qa-screenshot /qa/memory-chart.jpg \
  --question "QA saw a retained Activity and an OOM after five loops"

Each log or bugreport ZIP is scanned independently up to 32 MiB of decoded text; ZIP samples also bind the archive member and use a 256-member ceiling. evidence.qa_observations contains signal type/strength/count, one-based line numbers, SHA-256 for matched lines, available threadtime timestamps/tags, and scan truncation. It never contains raw lines. Signals cover complete LeakCanary-path candidates, Android component/StrictMode cleanup warnings, Java/native allocation failures, GC pressure, JNI reference overflow, Binder/database/graphics pressure, LMKD, and kernel OOM events.

A complete LeakCanary GC-root/reference path can satisfy the managed owner-path branch when the original report, target/build/phase, expected lifecycle, and suspect edge are verified. A notification screenshot, retained count, OOM throw site, GC line, or keyword match cannot. Growth/regression still requires comparable phases.

Screenshots are validated only for format, dimensions, size, and hash. No OCR or pixel content is placed in the context. The consuming AI must inspect the authorized image and bind every visible claim to its screenshot artifact ID and region, while recording cropped, hidden, unreadable, or inferred content.

Artifact paths are relative or redacted by default, which is appropriate for a context sent to an external AI. Add --include-local-paths only for an authorized AI running on the same machine; it adds the absolute evidence root and artifact paths so the agent can open raw evidence. Do not forward that context without a separate privacy review.

Context contract

The schema records the request, subject candidates, recursive folder_inventory, validated artifacts, accounting domains, hashes, intent-specific coverage, QA observations, conflicts, bounded derived-report summaries, evidence.analysis_history, relevant knowledge records, analysis rules, privacy policy, limitations, and executable next-evidence guidance. With one valid meminfo containing a complete main table and at most one valid smaps, evidence.accounting_ledger preserves every meminfo main/Dalvik-detail row and attaches category-level smaps PSS/SwapPss without embedding VMA paths. A summary-only meminfo remains explicitly unavailable, while multiple candidates remain ambiguous instead of being paired by filename. analysis_history identifies prior contexts/reports, the selected mode, the bounded evidence delta, limitations, and the mandatory claim-review contract; it does not embed old report text. An automatic mixed question such as “Native memory keeps growing” evaluates both the native branch and regression claim; the overall support level is the weakest contract, while primary_intent_support_level preserves the branch-only result.

Support levels describe evidence-set coverage, not probability:

• insufficient: explain current evidence and collect discriminators; do not select a root cause or code fix;
• limited: identify direction while preserving alternatives;
• supported: core and some ownership/timeline evidence is available;
• strong: the intent-defined evidence set is complete, but every claim still needs artifact binding.

An artifact can be format-valid yet inadequate for the selected intent. In particular, a single live snapshot has a valid phase, but Java/native leak and regression claims still require timestamp, process role, user/profile, scenario, loops, cooldown, collection mode, perturbation, and comparable phases. Such artifacts appear in evidence.coverage.inadequate and remain in next_evidence.

Install the public Skills

The public package contains three Skills and a self-contained stdlib-only evidence runtime. Context generation requires Python 3.8 or later, but it does not require cloning this repository or setting ANDROID_MEMORY_ANALYSIS_ROOT.

Install all three into the current project with the open Skills CLI (Node.js 18+):

npx skills add Gracker/Android-App-Memory-Analysis \
  --skill '*'

Project scope is recommended for a team because the generated skills-lock.json records the source and installed hashes. For a global Codex install:

npx skills add Gracker/Android-App-Memory-Analysis \
  --skill '*' \
  --agent codex \
  --global \
  --yes

Replace codex with the target agent identifier when needed, and restart or reload the agent after installation or update.

Refresh an existing global installation by rerunning the same source command; the CLI replaces the managed copies and refreshes their hashes:

npx skills add Gracker/Android-App-Memory-Analysis \
  --skill '*' \
  --agent codex \
  --global \
  --yes

Omit --global and the explicit agent for an interactive project-scoped refresh. The Evidence Skill's runtime/runtime-manifest.json pins the runtime, context schema, catalog version, and file hashes. Repository maintainers regenerate the bundle from canonical sources; users should not edit generated runtime files.

The full repository remains an optional enhancement for live capture, panorama, diff, and helper-driven Perfetto collection. Use --repo /path/to/Android-App-Memory-Analysis only when deliberately selecting such a checkout. Some generated advanced-collection commands use ANDROID_MEMORY_ANALYSIS_ROOT to reference that optional checkout, but the installed-Skill context runtime never discovers or depends on the variable.

Recommended sequence:

1. $android-memory-evidence validates partial/malformed inputs and creates the context.
2. $android-memory-diagnose combines artifact-bound facts with versioned theory and official sources.
3. $android-memory-remediate changes code only after ownership/mechanism evidence exists and then verifies the same scenario/domain.

Incomplete or inaccurate user input

Do not ask vaguely for more logs. State what is observed, what it supports, what it cannot prove, remaining hypotheses, and the smallest artifact that distinguishes them. Include the exact command, placeholder substitutions, prerequisites, permissions, Android-version gate, perturbation, and expected discriminator. Preserve user/tool conflicts instead of silently choosing one source.

Theory and publication boundary

android_memory_catalog.json contains original condensed operational knowledge, private source revision provenance, official public links, evidence requirements, non-claims, version scope, and practical tool mappings. It does not copy the private articles or treat review history as runtime truth.

Current audited theory revision: 2feca977830e99ddfb191022e9ba02409e7f0e19.

Privacy and cost

The context does not embed raw HPROF, trace, log lines, screenshot pixels, or arbitrary file bodies, and it redacts external absolute paths by default. Files up to 512 MiB are eligible for hashing within the default 1 GiB total budget; --hash-large-files opts into hashing larger files and removes the total budget. Review authorization, privacy, access control, processing location, and retention before sharing raw artifacts with an external model. Context generation never starts heavy HPROF or panorama analysis implicitly.

Verification

The repository-defined gate for this AI/Skills surface is:

python3 scripts/sync_skill_runtime.py --write  # only after canonical runtime/catalog changes
./scripts/verify.sh
./scripts/verify_npx_skill_install.sh

Commit the regenerated runtime with its canonical source change. verify.sh never regenerates it: stale or missing bundle files fail the build. The gates run stdlib tests, bundle drift validation, isolated copied-Skill execution, catalog/Skills validation, a real demo CLI smoke test, strict incomplete-evidence exit-code checks, and cloned-git npx skills install/reinstall execution. Run Skill Creator quick_validate.py separately for every Skill.

The AI Knowledge and Skills GitHub Actions workflow runs the same gate on Python 3.8 and 3.12. A separate job installs and reinstalls all three Skills through a pinned real npx skills CLI into a clean project, removes repository/environment discovery, and proves the copied runtime can create a context both times. CI adds no hosted-model credentials and never uploads dump artifacts.