简体中文

Oriona

An Android-native execution agent with local memory, governed tools, automation, and multi-channel delivery.

What Oriona Is

Oriona runs an AI agent directly on Android. The app accepts requests from its Compose UI, connected chat channels, scheduled jobs, and heartbeat events; sends structured context to a configured model provider; executes policy-controlled capabilities on the device; and records observable task progress locally.

Oriona is designed around execution rather than chat alone:

• One runtime path for foreground, Always-on, channel, cron, and heartbeat work.
• Capability governance with schemas, permissions, confirmation, timeouts, cancellation, and structured results.
• Durable task history with lifecycle states, bounded event storage, interruption recovery, and reviewed retry.
• On-device memory with current, short-term, and long-term tiers; bundled semantic retrieval; embedding refresh; conflict detection; scheduled compaction; and sensitivity controls.
• Android capabilities for files, device state, media, personal data, Bluetooth, notifications, and sharing.
• Embedded terminal backed by a packaged PRoot + Alpine runtime for isolated, session-scoped command execution on arm64-v8a and x86_64 devices.
• Extensible skills from built-in assets, local packages, and the ClawHub skill market.
• Multiple providers and protocols, including OpenAI-compatible, Responses-compatible, and Anthropic-compatible endpoints.
• Multiple channels, including Telegram, Discord, Slack, Feishu, WeCom, and email.

Project Scope

Oriona is currently maintained as a source-first open-source engineering project, not as a packaged consumer product. The supported path is cloning the repository, building it locally, and running the automated verification suite.

• README.md is the primary public project guide.
• CI signing is temporary and exists only to verify that a Release APK can be signed, installed, and launched; no production signing key or official binary distribution is planned at this stage.
• API 24 and API 35 emulators are the compatibility baseline. Vendor-specific physical-device behavior is not part of the current acceptance scope.
• The next measurement priority is reproducible MemoryVault evaluation: retrieval quality, semantic paraphrase recall, conflict/recency handling, forgetting and privacy invariants, restart consistency, latency, and storage cost.

Architecture

The main execution flow is:

UI / Channel / Cron / Heartbeat
              ↓
RuntimeApplicationService → GatewayRuntime → SessionTurnCoordinator
              ↓
TurnEngine → AgentLoop (stable) ↔ Model Provider
              ↓
CapabilityKernel → governed Android capabilities
              ↓
Room / TaskJournal / MemoryVault / session workspace
              ↓
Compose UI or bound-channel delivery

Detailed design documents:

• System architecture
• CapabilityKernel
• Turn engine boundary and Pi prototype
• TaskJournal
• LightMem-lite
• Testing and QA
• Project status

Quick Start

Requirements

• Android Studio with Android SDK 35
• JDK 17 or newer
• Android 7.0 / API 24 or newer device or emulator

Build

git clone https://github.com/Huang-404-Q/Oriona.git
cd Oriona
./gradlew :app:assembleDebug

On Windows PowerShell:

git clone https://github.com/Huang-404-Q/Oriona.git
cd Oriona
.\gradlew.bat :app:assembleDebug

The debug APK is generated at:

app/build/outputs/apk/debug/app-debug.apk

First Run

1. Install the APK and open Oriona.
2. Choose the UI language and configure a model provider.
3. Grant only the Android permissions needed by the capabilities you plan to use.
4. Create a session and send a request.
5. Optionally enable channels, automation, MCP servers, memory, or additional skills.

Provider credentials are supplied by the user. Oriona does not bundle hosted model access.

Major Subsystems

Area	Main responsibility
Agent runtime	Model/tool loop, context construction, cancellation, and terminal outcomes
CapabilityKernel	Capability discovery, schema validation, policy, confirmation, timeout, and execution events
TaskJournal	Durable runs, steps, events, progress cards, interruption recovery, and retry policy
MemoryVault	Local long-term memory, hybrid recall, sensitivity, forgetting, and governance
Embedded terminal	Session-scoped PRoot/Alpine commands, persistent shell sessions, timeouts, and workspace sharing
Channels	Inbound/outbound messaging, bindings, delivery, deduplication, and runtime status
Automation	Cron jobs, heartbeat wakeups, background restoration, and Always-on execution
Skills	Built-in and installed instructions, package inspection, compatibility review, and ClawHub discovery
Workspace	Per-session files, attachments, bounded file operations, and cleanup
Providers	Normalized model messages, streaming, tool calls, usage, and provider-specific protocols

Security Model

Oriona treats device actions as governed capabilities:

• Inputs are validated against explicit JSON schemas.
• Risky operations can require user confirmation.
• Android runtime permissions remain enforced by the platform.
• File operations stay inside defined workspace boundaries.
• Tool output, task events, and summaries are bounded before persistence or display.
• Credential-shaped values are redacted from TaskJournal summaries.
• Remote channels use explicit session bindings and configuration.

Report security issues using SECURITY.md.

Verification

Run the local quality gate:

./gradlew :app:verifyTextEncoding :app:testDebugUnitTest \
  :app:koverVerifyDebug :app:lintDebug \
  :app:assembleDebug :app:assembleRelease
cd experiments/pi-runtime && npm ci && npm test

Run connected Android tests when a device or emulator is available:

./gradlew :app:connectedDebugAndroidTest

The current verified baseline is 452 JVM tests (0 failures, 1 skipped), 7 Pi companion tests, 24 shared Android connected tests on API 24, and 29 connected tests on API 35. The API 35 lane adds virtual-hardware coverage for notifications, injected location, microphone recording, camera frames, and Bluetooth/BLE behavior. Kover enforces at least 20% line coverage, Android Lint gates new findings, and the CI release smoke signs, verifies, installs, and cold-launches the Release APK on API 35. That APK is a CI verification artifact, not an official product release.

Repository Layout

Oriona/
├── app/
│   ├── src/main/java/ai/oriona/   # application and runtime source
│   ├── src/main/assets/           # templates and built-in skills
│   ├── src/test/                  # JVM tests
│   ├── src/androidTest/           # device/emulator tests
│   └── schemas/                   # exported Room schemas
├── docs/
│   ├── architecture/              # subsystem design documents
│   ├── engineering/               # architecture, roadmap, and QA
│   └── index.html                 # project website
├── PROJECT_STATUS.md              # milestone source of truth
└── README.md

Contributing

Read CONTRIBUTING.md and CLA.md before opening a pull request. Keep changes focused, add the smallest useful verification, and update relevant documentation with behavior changes.

License

Oriona uses a dual-license model:

• GNU AGPL v3 for open-source use.
• Commercial license for proprietary integration.

Bundled model provenance is recorded in THIRD_PARTY_MODELS.md. Bundled terminal runtime provenance and hashes are recorded in THIRD_PARTY_RUNTIME.md.