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/objectbox/objectbox-java 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.

GO — Healthy across all four use cases

• Last commit 2d ago
• 3 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Small team — 3 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 95% of recent commits

_{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 objectbox/objectbox-java repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/objectbox/objectbox-java.

What it runs against: a local clone of objectbox/objectbox-java — 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 objectbox/objectbox-java | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of objectbox/objectbox-java. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/objectbox/objectbox-java.git
#   cd objectbox-java
#
# 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 objectbox/objectbox-java and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "objectbox-java-api/src/main/java/io/objectbox/annotation/Entity.java" \\
  && ok "objectbox-java-api/src/main/java/io/objectbox/annotation/Entity.java" \\
  || miss "missing critical file: objectbox-java-api/src/main/java/io/objectbox/annotation/Entity.java"
test -f "objectbox-android/src/main/java/io/objectbox/android/AndroidPlatform.java" \\
  && ok "objectbox-android/src/main/java/io/objectbox/android/AndroidPlatform.java" \\
  || miss "missing critical file: objectbox-android/src/main/java/io/objectbox/android/AndroidPlatform.java"
test -f "build.gradle.kts" \\
  && ok "build.gradle.kts" \\
  || miss "missing critical file: build.gradle.kts"
test -f "gradle/libs.versions.toml" \\
  && ok "gradle/libs.versions.toml" \\
  || miss "missing critical file: gradle/libs.versions.toml"
test -f "objectbox-android/build.gradle.kts" \\
  && ok "objectbox-android/build.gradle.kts" \\
  || miss "missing critical file: objectbox-android/build.gradle.kts"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
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/objectbox/objectbox-java"
  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).

ObjectBox Java is a lightweight, on-device embedded database for Android and JVM applications that combines object persistence with vector search capabilities. It provides a Box-based API for CRUD operations on annotated entities and enables fast, battery-efficient vector similarity search for RAG AI and generative AI workloads, all without requiring a server. Monorepo structure: objectbox-android/ contains Android-specific bindings and Admin tools (with adminIncluded/adminExcluded variants), while core database logic is in the root. Build logic is isolated in build-logic/ with Gradle conventions plugins. Annotation processing generates MyObjectBox classes at compile time. ProGuard rules (consumer-proguard-rules.pro, proguard-rules.pro) protect obfuscation of the database layer.

Android and Java/Kotlin developers building mobile and desktop applications who need fast local data persistence and vector search without the overhead of traditional SQL databases or network-dependent services. Specifically targets developers implementing AI features (RAG, similarity search) and those prioritizing battery efficiency and offline-first architectures.

Production-ready and actively maintained. The repository shows 1.7M+ lines of Java code, established CI/CD pipelines (GitHub Actions, GitLab CI, Jenkinsfile for Windows builds), comprehensive test coverage, and regular releases. Recent activity visible in build configs and workflow automation indicates active development, making it suitable for production deployments.

Low risk for a mature database library. The monorepo structure (objectbox-android, objectbox-java core modules) is well-organized with separate build logic. Primary risks are: native binary dependencies (C++ core) requiring platform-specific maintenance, the Android-specific Admin console build variants adding complexity, and the reliance on code generation (indicated by MyObjectBox builder pattern) which can break on gradle/annotation processor changes.

Active development on vector search features and Gradle build modernization. Recent changes include refactored build configuration using Gradle 8+ conventions (build-logic/), Dependabot integration for dependency updates, and CI pipeline expansion (Windows support via ci/Jenkinsfile-Windows). The focus is on consolidating Java/Kotlin support and improving the vector database capabilities.

git clone https://github.com/objectbox/objectbox-java.git
cd objectbox-java
./gradlew build

For Android development, import into Android Studio. For JVM-only, ensure Java 11+ is installed. Run ./gradlew test to verify the build. Consult objectbox-android/README.md and root README.md for Android-specific setup.

Daily commands: For local testing: ./gradlew test (JVM unit tests), ./gradlew connectedAndroidTest (Android integration tests on device/emulator). To build the library: ./gradlew build. For publishing locally: ./gradlew publishToMavenLocal. Gradle wrapper handles JVM bootstrap; no separate package manager setup needed.

• objectbox-java-api/src/main/java/io/objectbox/annotation/Entity.java — Core annotation that marks classes as persistable database entities; all schema definitions start here.
• objectbox-android/src/main/java/io/objectbox/android/AndroidPlatform.java — Android platform abstraction layer; essential for understanding how ObjectBox adapts to Android's lifecycle and threading model.
• build.gradle.kts — Root build configuration; defines multi-module setup, dependency management, and publishing conventions.
• gradle/libs.versions.toml — Centralized dependency version catalog; required for understanding external library versions and upgrade paths.
• objectbox-android/build.gradle.kts — Android module build config; controls native library integration, ProGuard rules, and flavor management.
• README.md — Project overview and onboarding; establishes ObjectBox's core mission as a lightweight vector database for Android/JVM.
• .github/workflows — CI/CD pipeline definitions; shows how tests, builds, and releases are automated across platforms.

Add a Custom Property Converter

1. Create a class implementing ObjectBox's converter interface in your app code (objectbox-java-api/src/main/java/io/objectbox/annotation/Convert.java)
2. Annotate the property in your entity with @Convert(converter = YourConverter.class) (objectbox-java-api/src/main/java/io/objectbox/annotation/Entity.java)
3. Rebuild the project to trigger annotation processing and code generation

Create a New Entity with Relationships

1. Define a new class and annotate it with @Entity (objectbox-java-api/src/main/java/io/objectbox/annotation/Entity.java)
2. Add properties including ToOne relations, optionally with @Backlink for reverse navigation (objectbox-java-api/src/main/java/io/objectbox/annotation/Backlink.java)
3. Build the project; ObjectBox code generation creates accessors and query code
4. On Android, use AndroidObjectBrowser to visualize the new schema in debug builds (objectbox-android/src/adminIncluded/java/io/objectbox/android/AndroidObjectBrowser.java)

Integrate ObjectBox LiveData into Android Fragment

1. Import ObjectBoxLiveData from the android module (objectbox-android/src/main/java/io/objectbox/android/ObjectBoxLiveData.java)
2. Wrap a Query object: LiveData<List<Entity>> = ObjectBoxLiveData.query(box.query(...).build()) (objectbox-android/src/main/java/io/objectbox/android/ObjectBoxLiveData.java)
3. Observe the LiveData in your Fragment/Activity UI code; changes trigger recomposition automatically

Enable Admin Browser in Android Debug Build

1. Check objectbox-android build.gradle.kts to ensure admin flavor is enabled (objectbox-android/build.gradle.kts)
2. Initialize Admin in your debug Application class; it runs as a foreground service (objectbox-android/src/adminIncluded/java/io/objectbox/android/Admin.java)
3. In a debug-only Activity or menu, call Admin.startBrowser() to launch the in-app inspector

• Native C++ Library (JNI bindings) — Provides sub-millisecond query latency and minimal memory overhead for embedded mobile and IoT devices.
• Annotation-based schema definition (@Entity, @Convert, @Backlink) — Enables compile-time code generation via annotation processors; eliminates boilerplate and catches errors early.
• Gradle multi-module setup (objectbox-java-api, objectbox-android) — Decouples core API from Android-specific features; supports JVM-only deployments while keeping Android integrations optional.
• ProGuard/R8 rules — Protects generated entity accessors from obfuscation in release builds; essential for reflection-based serialization.
• LiveData integration (AndroidObjectBrowser, ObjectBoxLiveData) — Bridges ObjectBox queries to Androidx reactive patterns; simplifies data-driven UI updates.

• JNI native library dependency instead of pure Java implementation

  • Why: Achieves <1ms latency for vector similarity search and B-tree operations; essential for mobile performance.
  • Consequence: Increases APK size (~5–15 MB per architecture), requires native library distribution, complicates cross-platform testing.

• Admin browser as optional debug-only feature (separate build flavor)

  • Why: Reduces release build footprint and hides introspection from production users.
  • Consequence: Developers must use debug flavor for in-app database inspection; adds build variant complexity.

• Annotation processor-based code generation at compile time

  • Why: Eliminates runtime reflection overhead; enables type-safe query builders and property access.
  • Consequence: Slower incremental builds; generated code must be kept in sync with schema changes.

• Single-store-per-app design (not multi-database)

  • Why: Simplifies transaction semantics and avoids cross-database consistency issues.
  • Consequence: Applications requiring multiple schemas must use workarounds (nested entities, custom serialization).

• does not provide server-side database functionality; on-device only
• not a real-time collaborative database (eventual consistency not guaranteed across devices without explicit sync)
• does not handle full-text search natively (vectors only; text search via external library)
• not thread-safe by default; transactions are required for concurrent writes from multiple threads

1. Annotation processor dependency: The MyObjectBox builder is generated at compile time; missing or misconfigured annotation processors cause runtime crashes. 2. Native binary distribution: The actual C++ database core is not in this repo; it's distributed as precompiled binaries. Build failures on unsupported architectures (ARM, exotic Linux distros) won't be obvious from Java code. 3. Admin console variants: objectbox-android has conditional admin UI compilation (adminIncluded vs adminExcluded); including the admin variant adds significant APK size and permissions—understand which variant you're using. 4. ProGuard/R8 config required: Apps using ObjectBox must respect the consumer-proguard-rules.pro; wrong ProGuard config will strip critical reflection-based ORM code at runtime. 5. Gradle 8+ requirement: The build-logic/ module uses Gradle conventions plugins; older Gradle versions will fail silently.

• HNSW (Hierarchical Navigable Small World) — ObjectBox's vector search relies on HNSW indexing for fast approximate nearest-neighbor queries; understanding this algorithm is essential for tuning vector search performance and understanding query time/memory tradeoffs
• Memory-mapped I/O — ObjectBox's C++ core uses memory-mapped file access for zero-copy reads and efficient on-device storage; this is why ObjectBox is battery-efficient compared to traditional SQLite-style buffering
• Java Annotation Processing — Entity classes are processed at compile time to generate MyObjectBox and Box implementations; understanding the annotation processor lifecycle is crucial for extending ObjectBox or debugging generation issues
• ProGuard/R8 Bytecode Obfuscation — ObjectBox relies on reflection for ORM and requires explicit ProGuard keep rules; incorrect obfuscation will break field mapping and entity instantiation at runtime
• Monorepo Gradle Conventions Plugins — build-logic/ defines shared Gradle conventions used across all modules; understanding this pattern is key to maintaining consistent builds and adding new modules to ObjectBox
• Build Variants (Android) — objectbox-android uses conditional build variants (adminIncluded/adminExcluded) to swap Admin UI code at compile time; this pattern allows shipping different APK versions without code duplication
• Embedded Vector Database — Unlike cloud vector databases (Pinecone, Weaviate), ObjectBox embeds the entire vector index on-device, enabling offline-first RAG and generative AI without network calls; this is the core differentiator for AI features

• realm/realm-java — Direct competitor: another on-device Java/Android database with object persistence, lacking vector search but mature and widely used
• greenrobot/greenDAO — Alternative lightweight Android ORM with annotation-based entity definition; smaller and simpler but without vector or AI features
• objectbox/objectbox-examples — Official example apps and tutorials demonstrating ObjectBox usage patterns for Android and JVM projects
• objectbox/objectbox-swift — Companion repository: ObjectBox for iOS/Swift, sharing the same underlying C++ core and similar API design across ecosystems
• weaviate/weaviate — Vector database ecosystem reference; ObjectBox vector search aligns with Weaviate's HNSW indexing patterns for similarity search

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 GitHub Actions CI workflow for Windows builds

The repo has a Jenkinsfile and ci/Jenkinsfile-Windows for Windows builds, but no GitHub Actions workflow. Given the project supports both Android and JVM on Windows, adding a GitHub Actions workflow would provide faster feedback on PRs and reduce CI/CD fragmentation. This is especially important since objectbox-android and core modules need Windows validation.

• [ ] Create .github/workflows/windows-build.yml that runs gradle build on Windows runners
• [ ] Test compilation of objectbox-android and objectbox-java-core modules
• [ ] Add native library handling for Windows (check gradle.properties and build.gradle.kts for platform-specific logic)
• [ ] Ensure ProGuard rules in objectbox-android/proguard-rules.pro are validated
• [ ] Reference ci/Jenkinsfile-Windows to replicate critical build steps

Add integration tests for Android Admin feature variants

The objectbox-android module has conditional compilation with adminIncluded and adminExcluded variants (seen in src structure), but there's no clear test coverage validating both builds. A new integration test suite would ensure both Admin.java variants and AdminKeepAliveService/AdminNotificationReceiver work correctly when enabled/disabled.

• [ ] Create objectbox-android/src/test or objectbox-android/src/androidTest directory structure
• [ ] Write tests for adminIncluded variant: verify Admin.java, AdminKeepAliveService, and AdminNotificationReceiver are present
• [ ] Write tests for adminExcluded variant: verify Admin.java stub implementation works
• [ ] Add Gradle test configuration in objectbox-android/build.gradle.kts to run both variants
• [ ] Document test execution in objectbox-android/README.md

Create dependency vulnerability scanning workflow

The repo uses gradle/libs.versions.toml for dependency management and has dependabot.yml configured, but there's no GitHub Actions workflow actively scanning and reporting vulnerabilities. Adding a dedicated workflow using gradle-dependency-check or similar would proactively surface security issues in PRs and releases.

• [ ] Create .github/workflows/security-scan.yml that runs on PR and main branch pushes
• [ ] Integrate gradle-dependency-check plugin or OWASP Dependency-Check into build.gradle.kts
• [ ] Configure the workflow to check objectbox-android, objectbox-java-core, and build-logic modules
• [ ] Set up failure conditions for HIGH/CRITICAL vulnerabilities and warnings for MEDIUM
• [ ] Add security scan badge and results to README.md with link to detailed reports

• Add integration tests for the vector search API in objectbox-android/src/test/; currently no visible test files for HnswIndex or vector similarity queries.
• Document the MyObjectBox code generation process with an example in a new docs/ folder showing the before/after of annotation processing—helps onboard contributors unfamiliar with annotation processors.
• Create a GitHub Actions workflow for platform-specific binary validation; the Windows CI (ci/Jenkinsfile-Windows) is isolated and could benefit from a GitHub Actions mirror to catch Windows-specific build regressions earlier.

The ObjectBox-Java codebase demonstrates generally good security practices as a database library. No critical vulnerabilities were identified in the visible file structure. The main concerns are: (1) conditional admin interface code that must be strictly controlled during builds to prevent production exposure, (2) ProGuard rules that should be reviewed for information leakage, and (3) minor HTTP/HTTPS and dependency management improvements. The project appears to follow modern Android development practices with proper build configuration separation. Recommend implementing strict CI/CD controls for build variant selection and conducting regular security audits of the native database layer components.

• Medium · ProGuard Rules Exposure — objectbox-android/proguard-rules.pro, objectbox-android/consumer-proguard-rules.pro. ProGuard rules files (proguard-rules.pro and consumer-proguard-rules.pro) are included in the repository. While this is common practice, ensure these rules don't expose sensitive information about the application's internal structure or contain hardcoded sensitive data that could aid reverse engineering. Fix: Review ProGuard rules to ensure they don't expose sensitive information. Consider documenting what should and should not be obfuscated. Implement additional security measures beyond obfuscation for sensitive operations.
• Medium · Admin Interface Conditional Compilation — objectbox-android/src/adminIncluded, objectbox-android/src/adminExcluded. The codebase uses conditional compilation with adminIncluded and adminExcluded variants for the Admin/Object Browser feature. If the admin variant is accidentally bundled in production builds, it could expose database inspection capabilities to attackers. Fix: Implement strict build configuration to ensure admin variants are only included in debug/testing builds. Add CI/CD checks to prevent admin builds from reaching production. Document the build variants clearly.
• Low · Missing HTTPS in Documentation Link — README.md. The logo URL in README.md uses HTTP instead of HTTPS for raw.githubusercontent.com, which could be vulnerable to MITM attacks. Fix: Change 'http://raw.githubusercontent.com' to 'https://raw.githubusercontent.com' to ensure secure asset delivery.
• Low · Gradle Wrapper Security — gradle/wrapper/gradle-wrapper.jar. The gradle-wrapper.jar is committed to the repository. While this is a common practice, ensure the wrapper is from an official release and regularly updated to patch security vulnerabilities in the Gradle build system. Fix: Verify the gradle-wrapper.jar checksum against official Gradle releases. Keep it updated to the latest secure version. Consider implementing gradle wrapper validation in CI/CD pipelines.
• Low · No Dependency Lock File Visible — gradle configuration. While gradle/libs.versions.toml is present, no lock file (gradle.lockfile or similar) is visible in the provided structure. This could allow supply chain attacks through dependency version variations. Fix: Implement dependency locking using gradle.lockfile or similar mechanism to ensure reproducible builds and detect unexpected dependency changes.

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.