miaowunya/rikkahub-sillytavern-android

A deeply customized fork of RikkaHub (merged with upstream v2.5.6, plus 2150+ commits of additions), natively implemented in Kotlin + Jetpack Compose.

• Just want a good AI chat app: plug in any API and start talking — multi-provider, streaming, voice calls, plugin tools, memory, cache savings. No “tavern” concepts required.
• Migrating from desktop SillyTavern: character cards, lorebooks, presets, regex and themes import losslessly with official semantics — no Termux, no Node.js.

Both routes share the same client and don’t interfere with each other.

Website & docs: rikkahub.luoca.cn · Documentation (installation, configuration, tavern imports, plugin development)

---

Tavern compatibility

Memory & caching

This fork’s exclusives

---

✨ Fork features

---

🚀 Quick start

1. Grab the latest APK from Releases (arm64-v8a, Android 8.0+)
2. Settings → Models & Services → Providers, add your API; then Default models & prompts to pick models for chat / title / compression
3. Start chatting. Want more:
   • Import a character card (Assistants page → import, PNG / V2 / V3 JSON; lorebooks and presets come along automatically)
   • Import lorebooks / presets / regex / QR (Settings → Extensions)
   • Try a SillyTavern theme (Settings → Preferences → Chat appearance → import theme)
   • Add plugins (Settings → Plugins → import ZIP; bundled plugins work out of the box)

In-app update: Settings → About → Check for updates (GitHub Releases API, with an auto-fallback mirror for mainland China)

---

💬 Chat features (this fork’s core enhancements)

⚡ Prompt Prefix Cache Optimization

Major providers (DeepSeek / Kimi / Claude, etc.) offer automatic prefix caching: a byte-identical prefix to the previous request is a cache hit, billed far below the normal rate. But in chat, plenty of content changes every turn (timestamps, recent chats, memories, random numbers, rolling summaries) — one divergence kills the whole cache.

Drawing on the DeepSeek Harness prefix-stability design, this fork eliminates those divergence points one by one:

Diagnostics: a built-in prefix divergence view compares consecutive requests item by item, shows the common prefix and estimated hit rate, and supports character-level diff location — you can always see exactly why a cache missed. A prompt viewer also shows the exact prompt sent this turn.

Actual results vary by conversation shape: in steady, append-only chats the hit rate improves noticeably; the exact gain depends on how often content changes and on each provider’s pricing.

🧠 Memory & Long Conversations

• Semantic memory RAG (ported from Rikkahub-Revised): memories split into FACT / EPISODIC, embedded with the vector model and retrieved via cosine similarity (with a lexical fallback of word terms + CJK bigrams); episodic memories get recency weighting; results are injected within a budget
• Three-layer memory (from orangechat/Tumin): a fixed-memory section (independently editable without touching the character card) + a recent-life stream (cross-conversation memory of the current chat; unread events from other conversations auto-injected) + long-term recall via lexical-overlap scoring; the stream is auto-summarized in the background past a threshold
• Enhanced memory_tool: a list read operation plus fact / episodic distinction — the model can review existing memories before writing or updating
• Memory management page: view / edit / delete entries per assistant
• Rolling context compression: past a threshold (auto-computed from the model’s context window or set manually), a compression model rolls earlier turns into a summary (originals preserved, replaced only at request time), injected as a system message — staying in-window without losing persona or foreshadowing
• Recent chats reference: optionally inject the assistant’s recent conversation list for cross-session continuity
• Transient-content pruning: web-search results / images / audio / video older than two turns are dropped from requests (with the message ID so the AI can retrieve the original via read_history_message)
• First-turn auto memory: the first turn injects the most recent memories (no relevance query exists yet), later turns recall by relevance — the AI knows you from the first message

Memory features (memory tool / RAG / three-layer memory / cross-window life stream) are on by default — memory helps the AI know you better and isn’t sacrificed to save context. Existing assistants keep their settings and can opt out per assistant.

🧿 Jev decisioning (TypeSafe System One)

Settings → HuaDeng Settings → Jev decisioning. Jev is a dedicated small model that only judges — it never generates text (~100ms end to end, output tokens free). It mounts as an invisible decision layer inside the client: paste an API key and it works. Two takeover switches:

Silence is a hard requirement: whenever Jev is unavailable (no key, network failure, low confidence), memory and tools fall back to the original logic — no error dialogs, no blocking.

🧩 Plugin System

QuickJS-sandboxed plugins. A plugin is a ZIP package (manifest.json + main.js); import it in Settings → Plugins.

The plugin system originated in orangechat / Tumin; this fork added the sandbox capabilities tool-style plugins need (session-aware HTTP, image decoding, detail-page cards).

What it can do

• tools declared in the manifest become AI-callable tools (unified plugin_ prefix)
• System-prompt injection: systemPrompt injected directly, or sections each gated by a config switch (supports file: external files and enc: AES-256-GCM encrypted files)
• Detail-page data cards: declare detailCard and the plugin page calls that exported function and renders a live status card (e.g. calorie “today’s intake”)
• Folders, enable/disable, per-plugin config forms (text / password / boolean / select / model picker)
• Per-plugin dataStore key-value storage under plugin_data_

Sandbox capabilities

Single-threaded; 30s tool timeout, 8s detail-card timeout. ES5 only (async/await are preprocessed into synchronous calls).

Security

• Two-stage import: parse and preview the manifest, then commit
• SHA-256 integrity check (.integrity) in the plugin directory — a modified plugin is disabled automatically
• Zip-Slip protection: every entry’s canonical path is verified on extraction
• Empty allowedHosts = all network requests denied
• Plugins reach only the explicitly injected bridge objects, never host capabilities

⚠️ Plugins are third-party code. Only import sources you trust.

Bundled plugins

All packages (source included) are in docs/plugins/; see docs/PLUGINS_GUIDE.md for the development guide.

🗼 Proxy-Station Compatibility & Anti-Empty-Reply

Classic pathologies when Gemini is accessed through OpenAI-compatible proxy stations (newapi etc.), fixed automatically:

• Body swallowed by reasoning_content: some proxies put the actual reply into the reasoning field, leaving artifacts in content — after the stream ends, if the body is empty while reasoning has substance, the reasoning is promoted to the body (no false positives during the thinking phase)
• response prefix artifacts: stray response / Response: leftovers at the start of the body — stripped on both streaming and non-streaming paths, even when split across deltas; boundary checks avoid mangling words like responses
• Truncation: promotion + stripping present the reply in full instead of “answer in the thinking block, half a reply in the body”

Anti-empty-reply (global):

• System prompt into the conversation flow: SYSTEM messages convert in place to user turns (with an acknowledgment turn after the first); lorebook / persona / rolling-summary positions and content stay untouched — bypassing Gemini’s safety blocking of systemInstruction
• Auto-perturb retry: on a reply with no text and no tool calls, the last user message is perturbed (add/remove periods, add space — 4 rotating variants) and retried up to 3 times

Both are off by default; enable in HuaDeng Settings or per assistant.

🔊 Doubao Voice (Volcengine Agent Plan)

• Doubao TTS: Doubao speech-synthesis large model 2.0
  • seed-tts-2.0 resource with 14 built-in 2.0 voice presets (default Cancan 2.0, plus Kuaile Xiaodong, Tianmei Taozi, Gaoleng Yujie, …); any voice ID can be typed manually
  • Speech-rate control; audio format (mp3/wav/pcm/ogg/opus) and sample rate selectable
  • Fully parses Volcengine’s concatenated-JSON chunked streaming responses; long-audio synthesis verified
  • The Agent Plan dedicated endpoint is built in as the default; standard-console users can switch back
• Volcengine ASR: Agent Plan ark-xxx keys are only valid on the dedicated /api/v3/plan/ path — the default URL now points there; standard-console users can change it back in settings
• One Agent Plan API key drives both voice input and voice output

Pairs with voice / video calls: one tap on the chat top bar enters the call screen (shown only when both TTS and ASR are configured) — local voice-activity detection → ASR incremental transcription → auto-send → streaming TTS of the reply, interruptible at any time; on hang-up the call folds into an archive card in the conversation.

📱 On-Device Augmentation

Device toolbox (30 tools)

Enable it on an assistant and the AI can call phone system capabilities:

torch · vibrate · volume read/write · brightness read/write · toast · battery · storage · Wi-Fi / audio / telephony / sensor info · share · wallpaper · notifications · alarm / timer · music control · SMS reading · contacts · call log · location · app launching · open URL · media scanning · file download · open file

To save tokens it uses a lazy-discovery meta-tool: only one device_toolbox slot is registered in context. The AI calls action=list to fetch the catalog (parameter schemas + permission status), then action=run to invoke a specific tool.

WeChat Bot / QQ Bot

Connect an existing assistant to a messaging channel (AI, memories, and tools all reused from that assistant):

• WeChat Bot: QR-login with your own WeChat account (iLink protocol); HTTP long-polling receives messages → auto reply; an expired token stops the service with a notification
• QQ Bot: official QQ Open Platform API — enter AppID + AppSecret; WebSocket gateway for real-time send/receive with automatic token refresh

Both are off by default with a privacy risk-confirmation dialog before enabling.

AI proactive messaging

AlarmManager exact alarms + WorkManager fallback; the assistant reaches out at random intervals (configurable range). Generation injects context (time since last chat, current time, battery) and politely skips a trigger while a generation is running. Off by default.

🎨 Appearance & Themes

• Color overrides: 7 custom colors (primary, global text, user / AI / thinking bubbles, chat background, input field; ARGB)
• Bubble beautification: user / AI bubble background images + corner radius + theme-color overlay; drawer background image and chat background image (tinted with the chat background color)
• Fine-grained text colors: separate body / quote / italics colors, with Tavern-orange, warm-gold, rose, coral, lavender, sky-blue and mint presets
• SillyTavern theme import: one-tap import of SillyTavern beautification theme JSONs, bulk-verified against 537 real themes (537/537 parse successfully):
  • Layered color compositing: theme tints (blur_tint → chat_tint → message bubble tints → background image) are composited source-over into opaque approximations following SillyTavern’s render stack, so transparent-bubble themes no longer collapse into flat color blocks; 8-digit hex parsed per CSS spec as #RRGGBBAA
  • Background image: background-image on #bg1 / body / #chat detected from custom_css (URLs auto-downloaded, data URIs decoded)
  • Bubble styling: border-radius on .mes / #chat maps to bubble corner radius; chat_display=1 (bubble mode) enables assistant bubbles automatically
  • Theme fonts: ttf/otf from @font-face are auto-downloaded and set as the chat font (woff/woff2 ignored)
  • Also: main_text_color → global text, quote/italics_text_color → quote/italics colors, font_scale → font scale
• Preset palettes + HCT custom themes + dynamic color remain unchanged

🛠 Skills & Tools

Skills

• Automatic triggering: matching keywords inject SKILL.md without relying on the model
• Public skills directory /Rikkahub/skills: add or remove via any file manager
• GitHub one-click install / batch download / update detection: subdirectories and multi-skill repos supported, with source + directory-hash tracking

Tools

New on top of upstream:

There is also a system-prompt assembler (tool-selection guide / work ethics).

Tool-calling compatibility

• DSML text tool-call compat: when a model writes tool calls into the message body instead of using function calling, they are parsed and executed, and the markers are stripped from the body
• Tool alias mapping: DSML-idiomatic names like web_search are mapped to the actually-registered name (search_web)
• Chinese tool display names: tool calls always show a Chinese name in the UI (web_search → 联网搜索, execute_python → 灵枢演算)

💞 Companionship

Hidable in one tap via HuaDeng Settings → Clean simple mode, which also stops registering the related tools.

• Couples space: bind a partner to unlock the “Rabbit’s Burrow” feed (both sides post, and the AI genuinely replies in the comments), “Our Diary”, and “Anniversaries”
• Life hub: six panels — Today / Cycle & Body / Memos / Calendar reminders / Listen together / Shared reading shelf — which the AI can participate in via tools

---

🍺 SillyTavern compatibility (aligned with official semantics)

Existing tavern assets migrate directly — parsed with official SillyTavern semantics rather than an approximate conversion:

The prompt pipeline follows the official structure too: main prompt, standalone character-field messages, example messages split on `` into real user/assistant turns, PHI appended after history, depth prompts injected at their configured depth and role.

Differences from other Android tavern projects

Searching “Android SillyTavern” surfaces mostly containers or launchers — projects that bundle Node.js with SillyTavern and run it (their descriptions typically use terms such as runner, launcher, container, installer, local Node.js server).

This project is a native implementation: a complete Kotlin + Jetpack Compose client in which the tavern compatibility layer is core code rather than an external wrapper. The differences:

• No Node service to run — no background process holding memory, faster cold start
• Tavern features interoperate with client features: a card’s lorebook can drive plugin tools, the memory system, TTS read-aloud, and the device toolbox
• A complete mobile experience: Material You theming, gestures, notifications, the share sheet

It also addresses two common tavern pain points

• ⚡ Long chats get expensive → Prompt prefix cache optimization removes per-turn divergence points
• 🧠 The AI forgets / the context blows up → Memory & long conversations: semantic RAG + three-layer memory + rolling compression

The tavern core (character-card structure, lorebook engine, Macro Engine 2.0, slash commands, group chats) comes from the mingli2 branch of the intermediate fork heikeyangle-code/rikkahub-plus. This branch (huadeng) adds on top: HTML card rendering, multiple-greetings import, preset & regex import, QR import, lorebook editor field completion + token-budget fallback, Vector Storage semantic entries, a prompt viewer, regex depth limits & caching, and greeting macro substitution.

Switching from Chatbox or another general-purpose AI client?

If you currently use Chatbox (or any other general AI chat client) to talk to APIs, this app is a worthwhile upgrade — the fundamentals are fully covered (multi-provider access, streaming, Markdown / LaTeX / syntax highlighting, chat export, data backup), plus an entire layer Chatbox doesn’t have:

No “tavern” concepts required as a pure chat client — both routes coexist. Start with it as a plain AI client and import a character card whenever you want.

---

🔍 Common needs and where they map

Search keywords: AI chat app, Android AI client, AI assistant, AI memory, prompt cache, Android SillyTavern, SillyTavern Android client, mobile SillyTavern, tavern client, character card import, lorebook, world info, roleplay AI, AI roleplay, RP client, Android LLM chat, AI chat client, RAG memory, OpenAI-compatible proxy, Chatbox for Android, Chatbox alternative, Chatbox with memory, Chatbox roleplay, Kotlin Jetpack Compose AI app, local AI chat.

---

🏮 HuaDeng Settings (fork-exclusive)

Settings → HuaDeng Settings collects this fork’s compatibility and helper features on one page. Global switches apply to all assistants (per-assistant switches can override).

Compatibility & helpers

Access & automation

Five entries: WeChat Bot, QQ Bot, AI proactive messaging, Security settings, and Author’s note.

Security settings (Settings → Security): the global tool-call approval policy — force-confirm all tool calls (confirm before every execution) or auto-approve all tool calls (skip approval; use with caution). They are mutually exclusive. The former is off by default; the latter is on by default.

Jev decisioning

The configuration page for the TypeSafe System One judge model: API base URL / key / model name, a confidence-threshold slider, and the two takeover switches (automatic memory screening, judge tool). See Jev decisioning.

---

🛡 Privacy & Stability

Privacy hardening

• Sanitized request logging: request-header allowlist, prompt / schema / binary / credential redaction, secret masking and size caps on error messages
• Tool approval boundaries: clipboard / screen-time / shell require approval on every execution; file tools require it for writes; screen-time queries are scope-limited and never expose package names
• Backup-restore resource budget: entry counts and per-entry / total decompression sizes are capped against malicious archives
• Daily file cleanup: chat attachments and generated images can auto-expire by retention days (off by default)
• Firebase telemetry off by default: Google services and Crashlytics only activate with a build property
• Plugin sandbox: see Plugins → Security

Stability

• Foreground-service keep-alive: generation survives app switching
• SSE long-connection hardening: OkHttp 30s PING keep-alive; event-stream requests disable caching and compression so proxies no longer buffer streaming output
• Smooth database upgrades: every schema change ships as an explicit migration — existing data upgrades losslessly; migrations are idempotent
• Consistent-snapshot backup import with safe startup recovery, PickVisualMedia image picking, and many fixes

---

📦 Download

Only a single arm64-v8a APK is published, supporting Android 8.0 (API 26) and above.

---

✅ Relationship to upstream

• Everything preserved: Material You theming, multi-provider support, streaming, conversation forking & regeneration, message edit / delete / translate, full-text search (jieba), favorites, image generation, TTS / ASR, MCP, workspace sandbox (multi-tab terminal + shell compatibility mode), backup (S3 / WebDAV), web chat endpoint, and chat export all work as before
• Already merged with upstream: rikkahub/rikkahub master v2.5.6 (2026-10, includes the provider advanced-settings tab with custom request headers, memory copying when duplicating an assistant, the MCP OAuth callback moving to localhost to dodge WAF 403s, $ref inlining for MCP tool input schemas, Gemini Interactions API support, Claude Opus/Sonnet 5.5 and Gemini 4 model registry entries, per-provider model-list collapsing, the chart_display local tool, and an export option that omits reasoning)
• Versus the intermediate mingli2 branch: beyond tavern enhancements, this branch adds prompt prefix caching, semantic memory RAG & rolling compression, Jev decisioning, proxy-station compatibility & anti-empty-reply, Doubao voice, and privacy hardening
• New since v2.5.6: the academic system moved out of the app into a plugin, the calories & protein plugin, session-aware HTTP and image decoding in the plugin sandbox, detail-page data cards, the update check moving to the GitHub Releases API, Jev decisioning, and a fix for the proactive-message foreground service crashing on startup
• Merging upstream: see the conflict handbook in DIVERGENCE.md

---

🤝 Contributions welcome

Contributions are always welcome! Bug reports, suggestions, and code are all appreciated:

• Bug reports / suggestions: Issues
• Code: just Fork + PR — no permission needed

---

🙏 Credits

This project stands on the shoulders of others:

This repository and its upstreams are all AGPL-3.0 licensed; this fork continues under the same license. Copyright of each upstream project belongs to its authors — thank you for open-sourcing.

中文介绍：README_CN.md —— 安卓上的 AI 聊天客户端，兼为 SillyTavern（酒馆）安卓兼容端：角色卡 / 世界书 / 预设 / 正则 / 美化主题按官方语义一键导入，无需 Termux 或 Node.js。搜「安卓 酒馆」「SillyTavern 安卓」即可找到本项目。

---