If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/Tencent/MMKV shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Single-maintainer risk — review before adopting

• Last commit 2w ago
• 5 active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 93% of recent commits
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live Tencent/MMKV repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Tencent/MMKV.

What it runs against: a local clone of Tencent/MMKV — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in Tencent/MMKV | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 42 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Tencent/MMKV. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Tencent/MMKV.git
#   cd MMKV
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of Tencent/MMKV and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Tencent/MMKV(\\.git)?\\b" \\
  && ok "origin remote is Tencent/MMKV" \\
  || miss "origin remote is not Tencent/MMKV (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Android/MMKV/mmkv/src/main/java/com/tencent/mmkv/MMKV.java" \\
  && ok "Android/MMKV/mmkv/src/main/java/com/tencent/mmkv/MMKV.java" \\
  || miss "missing critical file: Android/MMKV/mmkv/src/main/java/com/tencent/mmkv/MMKV.java"
test -f "Android/MMKV/mmkv/src/main/cpp/native-bridge.cpp" \\
  && ok "Android/MMKV/mmkv/src/main/cpp/native-bridge.cpp" \\
  || miss "missing critical file: Android/MMKV/mmkv/src/main/cpp/native-bridge.cpp"
test -f "Android/MMKV/mmkv/CMakeLists.txt" \\
  && ok "Android/MMKV/mmkv/CMakeLists.txt" \\
  || miss "missing critical file: Android/MMKV/mmkv/CMakeLists.txt"
test -f "Android/MMKV/mmkv/build.gradle" \\
  && ok "Android/MMKV/mmkv/build.gradle" \\
  || miss "missing critical file: Android/MMKV/mmkv/build.gradle"
test -f "Android/MMKV/build.gradle" \\
  && ok "Android/MMKV/build.gradle" \\
  || miss "missing critical file: Android/MMKV/build.gradle"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 42 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~12d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/Tencent/MMKV"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

MMKV is an efficient, mmap-based key-value storage framework originally built by WeChat for high-performance mobile applications. It uses memory-mapped files and protobuf encoding to achieve zero-copy persistence with automatic syncing, eliminating the need for explicit sync() or apply() calls. Currently at v2.4.0, it supports Android (API 23+, 64-bit only since v2.0.0), iOS/macOS, Windows, POSIX, and HarmonyOS NEXT. Monorepo structure: Android/MMKV/mmkv/ contains the Android library with JNI bridges (src/main/cpp/native-bridge.cpp, flutter-bridge.cpp), Java wrapper (src/main/java/com/tencent/mmkv/MMKV.java), and AIDL definitions for inter-process communication (src/main/aidl/com/tencent/mmkv/ParcelableMMKV.aidl). Core C++ engine is shared across platforms, with language-specific bindings (Java, Dart, Go, etc.) layered on top.

Mobile app developers (primarily Android/iOS engineers) building performance-critical applications who need fast, persistent key-value storage with multi-process safety. WeChat and other high-scale apps use this to avoid SharedPreferences overhead and disk I/O stalls.

Production-ready and actively maintained. The codebase shows sophisticated architecture with multi-language bindings (C++, Java, Objective-C++, Dart, Go, Python, Ruby, Swift, Kotlin), comprehensive test suites in Android/MMKV/mmkv/src/androidTest/, and professional CI/GitHub Actions setup. Version 2.4.0 is stable; the LTS v1.3.x series still supports older API levels.

Low risk for production use but requires platform-specific testing: the codebase is polyglot (908KB C++, 251KB Java, 177KB Objective-C++) with tight mmap/protobuf coupling, so changes to serialization format can break compatibility. No explicit dependency management visible in the top-level config, but tight integration with Android NDK and iOS frameworks means environment setup is non-trivial. Single-vendor (Tencent/WeChat) governance, though publicly available.

Active maintenance at v2.4.0 with multi-platform support being expanded (HarmonyOS NEXT added recently). GitHub Actions workflows visible in .github/workflows/sponsor-priority.yml indicate CI/CD is operational. The repository supports both legacy (v1.3.x) and modern (v2.x) release branches, with ongoing deprecation of 32-bit and API <23 support.

Clone and set up Android locally: git clone https://github.com/Tencent/MMKV.git && cd Android/MMKV && ./gradlew build. For production use, add to your Android project via build.gradle: implementation 'com.tencent:mmkv:2.4.0'. Requires Android SDK 23+ (API level), Gradle 8.13.1, and Kotlin 2.2.20 (from root build.gradle).

Daily commands: Android Dev Build: cd Android/MMKV && ./gradlew clean build (incremental builds with ./gradlew build). Run Tests: ./gradlew connectedAndroidTest (requires attached device/emulator). Integration: Import as AAR or use Maven Central (dependency mechanism in build.gradle). No local dev server; this is a library, not an app.

• Android/MMKV/mmkv/src/main/java/com/tencent/mmkv/MMKV.java — Core entry point for MMKV API; all contributors must understand the public interface and mmap-based storage architecture
• Android/MMKV/mmkv/src/main/cpp/native-bridge.cpp — JNI bridge between Java and native C++ implementation; critical for understanding performance characteristics and multi-process concurrency
• Android/MMKV/mmkv/CMakeLists.txt — Build configuration for native libraries; necessary for setting up the compilation pipeline and understanding native dependencies
• Android/MMKV/mmkv/build.gradle — Android module build configuration; defines compilation target, native library integration, and artifact publishing
• Android/MMKV/build.gradle — Root-level build configuration with dependency management and version definitions shared across all modules
• Android/MMKV/mmkv/src/main/aidl/com/tencent/mmkv/ParcelableMMKV.aidl — AIDL definition for inter-process communication; essential for understanding multi-process access patterns and serialization
• Android/MMKV/mmkv/src/main/java/com/tencent/mmkv/MMKVContentProvider.java — ContentProvider implementation enabling cross-process data access; required for multi-process concurrency support

Add a new configuration option

1. Add the option constant to MMKVConfig.java with getter/setter methods (Android/MMKV/mmkv/src/main/java/com/tencent/mmkv/MMKVConfig.java)
2. Update the native-bridge.cpp JNI bindings to pass the configuration to native code (Android/MMKV/mmkv/src/main/cpp/native-bridge.cpp)
3. Add a test case in MMKVTest.java to verify the new configuration works correctly (Android/MMKV/mmkv/src/androidTest/java/com/tencent/mmkv/MMKVTest.java)

Add a new data type encoding support

1. Add encode/decode methods in MMKV.java following the pattern of existing put/get methods (Android/MMKV/mmkv/src/main/java/com/tencent/mmkv/MMKV.java)
2. Implement corresponding JNI bindings in native-bridge.cpp for protobuf serialization (Android/MMKV/mmkv/src/main/cpp/native-bridge.cpp)
3. Add comprehensive test cases covering encode/decode and edge cases (Android/MMKV/mmkv/src/androidTest/java/com/tencent/mmkv/MMKVTest.java)

Add multi-process IPC support for a new feature

1. Define the new IPC method in ParcelableMMKV.aidl interface (Android/MMKV/mmkv/src/main/aidl/com/tencent/mmkv/ParcelableMMKV.aidl)
2. Implement the AIDL method in MMKVContentProvider.java with proper access controls (Android/MMKV/mmkv/src/main/java/com/tencent/mmkv/MMKVContentProvider.java)
3. Update ParcelableMMKV.java to handle serialization of new data structures (Android/MMKV/mmkv/src/main/java/com/tencent/mmkv/ParcelableMMKV.java)
4. Add inter-process test cases in MMKVTestService.java (Android/MMKV/mmkv/src/androidTest/java/com/tencent/mmkv/MMKVTestService.java)

Integrate MMKV into a new Android application

1. Add the mmkv dependency to your app's build.gradle (specify version matching release notes) (Android/MMKV/mmkv/build.gradle)
2. Initialize MMKV in your Application class using MMKV.initialize() following the demo pattern (Android/MMKV/mmkvdemo/src/main/java/com/tencent/mmkvdemo/MyApplication.java)
3. Reference MainActivity.java for basic put/get operations and configuration examples (Android/MMKV/mmkvdemo/src/main/java/com/tencent/mmkvdemo/MainActivity.java)

• mmap (memory-mapped I/O) — Provides efficient, zero-copy synchronization between memory and disk; eliminates need for explicit flush operations and reduces latency for both reads and writes
• Protocol Buffers (protobuf) — Compact binary serialization format reduces storage footprint and encoding/decoding overhead compared to JSON or XML alternatives
• undefined — undefined

No 32-bit support since v2.0.0: If targeting armv7 or x86, must use v1.3.x LTS. MinSdkVersion = 23: Code assumes Android 6.0+; targeting API <23 will fail at build time. NDK requirement: C++ code requires Android NDK to be configured in local.properties or ANDROID_NDK_HOME environment variable; Gradle will error cryptically without it. Protobuf format locked in: Changing serialization format breaks compatibility across versions; no migration tooling provided. Process locks: Multi-process mode uses file-based locks in the mmap file; concurrent writes from multiple processes will serialize, not parallelize.

• Memory-Mapped I/O (mmap) — MMKV's core efficiency technique: mmap synchronizes an in-memory buffer with a file automatically, eliminating explicit write() syscalls and enabling zero-copy reads; understanding mmap semantics is essential to debug data corruption or durability issues
• Protocol Buffers (protobuf) — MMKV encodes all values as protobuf messages to achieve compact binary representation; extending MMKV with new data types requires modifying the .proto schema and serialization logic
• JNI (Java Native Interface) — The Android layer calls C++ mmap engine via JNI; bugs in native-bridge.cpp (memory leaks, incorrect type marshaling) directly impact app stability
• Inter-Process Communication (IPC) via AIDL — MMKV's multi-process mode uses AIDL (Android Interface Definition Language) to serialize and pass MMKVContent across process boundaries; the ParcelableMMKV.aidl contract defines how data moves between processes
• Process-Level File Locking — MMKV implements reader-writer locks at the mmap file level to prevent corruption during concurrent multi-process access; understanding lock contention and deadlock risks is crucial for high-concurrency apps
• Android NDK (Native Development Kit) — MMKV's C++ engine is compiled via NDK; CMakeLists.txt and build.gradle orchestrate NDK toolchain configuration, ABI selection, and linking; misconfigured NDK is the most common build failure
• Durability & Write-Ahead Logging (implicit) — MMKV leverages mmap's fsync semantics to guarantee durability without explicit journaling; understanding when mmap flushes to disk (system-dependent) is critical for consistency in crash scenarios

• google/protobuf — MMKV's serialization format; understanding protobuf wire format is essential to extend data type support
• android/ndk-samples — Reference implementations for JNI and NDK best practices used throughout MMKV's native-bridge.cpp
• realm/realm-java — Alternative object-relational mobile storage with similar mmap internals but different API (SQL-like vs key-value)
• facebook/rocksdb — Similar embedded key-value store used on Android; heavier but with more sophisticated compaction and transaction support
• Tencent/MMKV-Swift — Official Swift binding for MMKV, enabling use in iOS/macOS apps; maintained alongside the main repo

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive CI/CD workflow for Windows and POSIX platforms

The repo supports Windows, POSIX, macOS, and HarmonyOS NEXT platforms, but .github/workflows only shows sponsor-priority.yml. There are no visible build/test workflows for non-Android platforms. Adding platform-specific CI would catch regressions early across all supported architectures.

• [ ] Create .github/workflows/windows-build.yml to compile and test Windows native code
• [ ] Create .github/workflows/posix-build.yml for POSIX/Linux platform validation
• [ ] Create .github/workflows/macos-build.yml for macOS/iOS platform validation
• [ ] Each workflow should run CMake builds and execute platform-specific unit tests from Android/MMKV/mmkv/src/androidTest

Add inter-process communication (IPC) tests for Android

The codebase has ParcelableMMKV.aidl, MMKVContentProvider.java, and MMKVContentChangeNotification.java which indicate IPC support, but Android/MMKV/mmkv/src/androidTest/java/com/tencent/mmkv only contains MMKVTest.java and MMKVTestService.java. There appear to be no dedicated tests for cross-process data sharing, notifications, or content provider operations.

• [ ] Create Android/MMKV/mmkv/src/androidTest/java/com/tencent/mmkv/MMKVContentProviderTest.java to test MMKVContentProvider queries, updates, and notifications
• [ ] Create Android/MMKV/mmkv/src/androidTest/java/com/tencent/mmkv/MMKVParcelableTest.java to verify ParcelableMMKV serialization across processes
• [ ] Add test cases for MMKVContentChangeNotification subscription and broadcast scenarios

Add proguard mapping tests and obfuscation validation for Android release builds

Android/MMKV/mmkv/proguard-rules.pro exists but there are no visible tests validating that ProGuard rules correctly preserve public APIs or prevent crashes in obfuscated builds. This is critical for a library consumed by production apps.

• [ ] Create Android/MMKV/mmkv/src/androidTest/java/com/tencent/mmkv/MMKVProguardTest.java with reflection-based API validation tests
• [ ] Add gradle task in Android/MMKV/mmkv/build.gradle to run tests against minified/obfuscated release builds
• [ ] Document expected public API surface that must survive obfuscation (MMKV, MMKVConfig, NameSpace classes and their key public methods)

• Add missing test coverage for MMKVContentChangeNotification.java and MMKVContentProvider.java in src/androidTest/; these inter-process notification mechanisms have no visible unit tests despite being in the public API.
• Document the exact memory layout of protobuf encoding for each data type (bool, int, string, bytes, array) in a code comment block at the top of the C++ encoder; current code in native-bridge.cpp lacks inline explanation of wire format choices.
• Add Kotlin extension functions to MMKV.java for idiomatic usage (e.g., kv["key"] = value and val v = kv<Int>("key")) in a new src/main/java/com/tencent/mmkv/MMKVKotlin.kt file; increases adoption in modern Android projects.

MMKV demonstrates a generally secure architecture for a key-value storage framework, but has several moderate security concerns primarily related to outdated dependencies and incomplete security disclosure practices. The main risks are: (1) Legacy Android support library versions (25.4.0) that likely contain multiple known vulnerabilities, (2) Low minimum SDK version (23) extending the attack surface, (3) Outdated Gradle tools lacking recent security patches, and (4) Incomplete vulnerability disclosure policy. The presence of debug keystores and gradle wrapper JARs in version control

• High · Outdated Gradle Plugin Dependency — build.gradle (Android/MMKV/build.gradle). The Gradle build configuration uses gradle:8.13.1, which may contain known vulnerabilities. Regular security updates for build tools are critical to prevent supply chain attacks and exploitation of known CVEs in the build system. Fix: Update to the latest stable version of Gradle (8.7.0 or newer). Review Gradle release notes for security patches and maintain a policy of timely updates.
• Medium · Outdated Support Library Version — build.gradle (Android/MMKV/build.gradle). The supportLibVersion is pinned to '25.4.0', which is significantly outdated (released in 2016). This version likely contains multiple known security vulnerabilities and lacks modern security features. Using AndroidX is strongly recommended. Fix: Migrate from the legacy Support Library (version 25.x) to AndroidX (androidx libraries). Update all support library dependencies to current versions (minimum 1.x for AndroidX compatibility libraries).
• Medium · Weak Minimum SDK Version — build.gradle (Android/MMKV/build.gradle). minSdkVersion is set to 23 (Android 6.0, released 2015), which is over 8 years old. This exposes the application to unpatched security vulnerabilities in older Android versions and prevents use of modern security APIs. Fix: Consider raising minSdkVersion to at least 24-26 to reduce the attack surface. Review target market requirements and gradually increase minimum version as legacy device support can be deprecated.
• Medium · Missing SECURITY.md Disclosure Details — SECURITY.md. The SECURITY.md file lacks detailed vulnerability disclosure procedures, no specific security contact email is provided, and no maximum response time for security issues is defined. This makes responsible disclosure difficult. Fix: Enhance SECURITY.md with: (1) A dedicated security contact email address, (2) Expected response timeframes for vulnerability reports, (3) Clear instructions for responsible disclosure, (4) CVE assignment process details, (5) Security patch release timeline expectations.
• Low · Debug Keystore Committed to Repository — Android/MMKV/debug.keystore. A debug.keystore file is present in the Android build directory. While debug keystores are intended for development, their presence in the repository could be misused if the repository is compromised or if development builds are accidentally distributed. Fix: Remove debug.keystore from version control. Add it to .gitignore and document that developers should generate their own debug keystores locally using 'keytool'. Use only release keystores for production builds in CI/CD pipelines.
• Low · Gradle Wrapper JAR in Repository — Android/MMKV/gradle/wrapper/gradle-wrapper.jar. The gradle-wrapper.jar is committed to the repository. While convenient, this can make the repository size larger and presents a supply chain risk if the JAR is compromised. Fix: While gradle-wrapper.jar is generally accepted practice, ensure gradle-wrapper.properties verifies the checksum. Regularly audit wrapper versions for security updates and consider using gradle-wrapper validation in CI/CD pipelines.
• Low · Docker Multistage Build without Security Scanning — Dockerfile. The Dockerfile builds from gcc:11.5.0 without explicit security scanning, vulnerability checks, or non-root user execution. The image is not hardened against container-based attacks. Fix: Add security hardening: (1) Implement image scanning with tools like Trivy or Snyk, (2) Create a non-root user for runtime execution, (3) Use minimal base images when possible, (4) Add security labels and metadata, (5) Implement least-privilege permissions for build processes.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.