zeekk0/OpenAmikaPublic

OpenAmika

Hi! I'm Amika — MekaHime's AI companion, open source

Amika is a Live2D anime girl who talks with you by voice and text in real time, remembers you, and lives with you in your city. She runs on your own PC, with OpenRouter or fully local with Ollama. A hosted version runs at mekahime.com/amika.

简体中文 | 日本語 | English

💖 If Amika makes your day better, give us a ⭐ on GitHub — it helps more people find her! · Support the project: https://www.mekahime.com/donate

• Windows 10 or 11 and an NVIDIA graphics card (RTX 20-series or newer, 8 GB of video memory or more; her camera eyes need 16 GB), with a recent driver
• Python 3.11 (tick Add python.exe to PATH when you install it) and Git
• About 45 GB of free disk. Setting her up downloads about 15–20 GB and takes 30–60 minutes
• An OpenRouter key for her language model (recommended: a few dollars a month), or Ollama with a model of 27B or more and a graphics card big enough for it (see Which language model?)

Her ears, voice, memory and eyes always run on your PC. Her language model, the part that thinks and writes her replies, runs one of two ways:

• Semi-Local (recommended): through OpenRouter on your own key. In almost all cases this is the better choice: she uses the models she was tested with, answers fast, and it only costs a few dollars a month (about $1.50 if you talk 30 turns a day, about $5 at 100 turns a day).
• Fully Local: on your PC with Ollama. Use a model of 27B parameters or more; 70B or more gives the full, reliable experience. Models smaller than 27B may be really bad: she loses her character, forgets what you told her and breaks her reply format. A local model is also slower: all her thinking takes turns on it, so after you interrupt her, or while she saves a memory or reflects, a reply can take 5–50 s.

A local model needs its own video memory on top of the ~6 GB her ears, memory and voice use (~10 GB with her eyes): about 19 GB for a 27B model such as gemma3:27b, 24 GB for a 32B one such as qwen3:32b, and 50 GB for a 70B one such as qwen2.5:72b. So one 32 GB card (RTX 5090) holds a 27B model next to all of her (a 32B one only with her eyes off); a 24 GB card does not. A 70B model fits next to her only on a 72–96 GB workstation card. Otherwise run Ollama on a second PC (the Setup page takes its address), or stay Semi-Local. Whichever model you run, pick one that supports Chinese, since her prompts are written in it (llama3.3:70b, for one, does not). How to switch: Optional add-ons.

Open PowerShell (a normal window, not as administrator) and run these lines one at a time. They put her in C:\OpenAmika, a short folder that OneDrive does not sync:

cd C:\
git clone https://github.com/zeekk0/OpenAmika.git
cd OpenAmika
powershell -ExecutionPolicy Bypass -File scripts\setup_windows.ps1   # her brain, ears, memory and eyes
envs\brain\Scripts\python.exe scripts\setup_tts.py                   # her voice, her Live2D model, the paper doll: type yes
.\Start_OpenAmika.bat                                                # start her

Her voice, her Live2D model and the paper doll are free under MekaHime's personal-use license (see Licenses): the setup_tts.py line shows it first and downloads her files only after you type yes.

Both setup commands end with a summary, one line per part: OK when it is done, !! with the fix when it is not, and -- for information only (for example: no OpenRouter key yet, your first visit asks for it). Running a command again resumes and skips everything that is finished. When the setup_tts.py summary shows OK voice MekaHime_Amika and OK Live2D model Amika, she has her voice and her body; OK paper doll Host is the stand-in for her helpers (Her helpers).

Double-click Start_OpenAmika.bat in the OpenAmika folder (in PowerShell: .\Start_OpenAmika.bat). One console starts all of her, and your browser opens http://localhost:53000 when she is ready: about a minute, a few more the very first time. On your first visit she introduces herself and asks your name, your city and, if brain\.env has none yet, your OpenRouter key. Then press the power button and talk, or type. Click the page once so the browser lets her speak.

The light at the top right of every page is her health: green means everything works; click it to see what is not. Double-click Stop_OpenAmika.bat (or press Ctrl+C in her console) to stop her. To check everything without starting anything, run envs\brain\Scripts\python.exe launch.py --check: it ends with result: ready, or names what to fix.

To update her: stop her, run git stash, git pull and git stash pop in the OpenAmika folder (this keeps your name, your city and your edits), then run the two setup commands again (they fetch only what changed).

Every part writes a log in logs\. For anything else, ask on Discord or open an issue. Using an AI coding agent? Point it at README_IF_YOU_ARE_AI_AGENT.md.

• Fully Local: install Ollama, run ollama pull gemma3:27b (17 GB; or another model of 27B or more, see Which language model?), then on the Setup page choose Brain → Ollama → Detect models → Use this model. No key needed. For Ollama on another PC, type its address there before Detect models.
• Her helpers: Hermes Agent or nanoMuse run errands for her, with the paper doll beside her on stage (below). Any other MCP server works too, on the Tools page (docs/TOOLS.md).
• Smart home: Zigbee plugs she can switch (IoT/README.md). It stays off until you read and accept the IoT safety statement (docs/IOT_DISCLAIMER.md) on the Tools page. She runs on language models and can make mistakes: never connect heaters, locks, valves or anything that could cause harm.
• Text her on Discord or Telegram (docs/MESSENGERS.md).
• Your phone: Tailscale_Serve_OpenAmika.bat makes her reachable on your own devices over Tailscale.

She can hand errands to a helper program on your PC, Hermes Agent or nanoMuse: it searches the web, uses a browser and works with files. She decides whether to help, gives the helper the task after she has answered you, relays its questions, and tells you the result in her own words. While a helper is switched on, MekaHime's paper doll stands at the bottom right of her stage and plays the helper's side. Each helper runs its own model on OpenRouter, and the key she uses works for it.

Hermes Agent: install it from a PowerShell window. This form of its installer asks no questions; the lines after it do the setup OpenAmika needs:

& ([scriptblock]::Create((irm https://hermes-agent.nousresearch.com/install.ps1))) -NonInteractive

Then, in a new PowerShell window:

hermes model                                    # choose OpenRouter, paste your key, then "Enter custom model name": z-ai/glm-5
$key = [guid]::NewGuid().ToString('N')          # a random key for its API server
hermes config set API_SERVER_ENABLED true
hermes config set API_SERVER_KEY $key
hermes gateway stop                             # a Hermes already running reads the key only when it starts again

nanoMuse: clone it into the Nanomuse folder, give it a config.toml and put your key in its own vault; the commands and the file are in docs/TOOLS.md.

Connect them. In the OpenAmika folder, run Copy-Item config\tools.example.json config\tools.json (only if there is no config\tools.json yet) and notepad config\tools.json. Set "enabled": true at the top and in the helper's entry. For nanoMuse, "NANOMUSE_LANGUAGE" is the language it answers in ("en"; or "ja", "zh-CN"). For Hermes, copy its key with this line and paste it (Ctrl+V) as "HERMES_API_KEY":

(Select-String -Path "$env:LOCALAPPDATA\hermes\.env" -Pattern '^API_SERVER_KEY=(.+)').Matches[0].Groups[1].Value | Set-Clipboard

Save and start her (.\Start_OpenAmika.bat): she starts her helpers herself. On the Tools page the helper's card turns green (agent online).

Meet the paper doll. Open the Use page: the doll slides onto her stage. Ask her, for example, "Can you have Hermes check tomorrow's weather?". She answers, types the task in her speech bubble, and the doll takes over: it thinks while the helper works, speaks the helper's steps in its own bubble, looks surprised when the helper has a question or needs your OK (say yes or no, or click Approve on the Use page), and is happy when the result comes, which she then tells you. The doll comes with setup_tts.py (OK paper doll Host in its summary).

Every step in detail, and what each message means: docs/TOOLS.md.

• OpenAmika's code is MIT (LICENSE). Third-party parts keep their own licenses (THIRD_PARTY_NOTICES.md); the Live2D Cubism Core in ui/vendor/ is not MIT.
• Amika herself is not MIT. Her character, art, voice, Live2D model and their weights, and the paper doll that stands in for her helpers (MekaHime/MekaHime_Amika), belong to MekaHime Inc. and are free under a personal-use license: personal use only, 18+, no redistribution or re-hosting, and no training other models on them. Two creator rules: earn on social media (videos, streams, ads, memberships, sponsorships) with no limit, crediting MekaHime.AI visibly; and fan merch up to US$1,000 in total, as an individual, made from fan art you recreated yourself (never an original image MekaHime published on its website or social media), with "MekaHime.AI" on the visible side and a small "Fan Art" label. Any other commercial use needs a license from MekaHime ([email protected]). The LICENSE on Hugging Face governs.
• Hermes Agent (MIT) and nanoMuse (GPL-3.0-or-later) are separate programs you install yourself; OpenAmika only talks to them.
• Built on SenseVoice, GPT-SoVITS, bge-m3, Qwen3-VL, pixi-live2d-display with the Live2D Cubism SDK, OpenRouter, Ollama and the Model Context Protocol. Thank you.

Questions and bugs: GitHub issues, [email protected], or Discord. Support the project: https://www.mekahime.com/donate