explaingit

oppaai/aiko-demo

Analysis updated 2026-05-18

★ 0PythonAudience · generalComplexity · 4/5LicenseSetup · hard

TLDR

A HuggingFace demo of Aiko-chan, a self-hosted AI companion with voice, vision, memory, and a 3D avatar built on small open models.

Mindmap

mindmap
  root((repo))
    What it does
      Holds ongoing conversation
      Remembers across sessions
      Sees and speaks aloud
    Tech stack
      Python
      Gradio
      llama.cpp
      Modal
    Use cases
      AI companion chat
      Voice conversation demo
      Vision enabled assistant
    Audience
      Hobbyist developers
      AI enthusiasts
    Setup
      HuggingFace Space
      Modal GPU endpoints

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

What do people build with it?

USE CASE 1

Try out a voice and vision enabled AI companion demo on HuggingFace Spaces.

USE CASE 2

Study how to combine a small local language model with separate speech, vision, and memory models.

USE CASE 3

Learn how to serve multiple small AI models as serverless GPU functions on Modal.

What is it built with?

PythonGradiollama.cppModalThree.js

How does it compare?

oppaai/aiko-demo0xhassaan/nn-from-scratch3ks/embedoc
Stars00—
LanguagePythonPythonPython
Last pushed——2023-06-08
Maintenance——Dormant
Setup difficultyhardmoderatehard
Complexity4/54/51/5
Audiencegeneraldeveloperdeveloper

Figures from each repo's GitHub metadata at analysis time.

How do you get it running?

Difficulty · hard Time to first run · 1day+

Requires setting up multiple Modal GPU endpoints for the LLM, vision, speech, and TTS models plus a Gradio frontend.

Use freely for any purpose, including commercial use, as long as you keep the copyright notice and state changes.

In plain English

Aiko-demo is a HuggingFace Space demo for Aiko-chan, a self-hosted AI companion character with a 3D avatar, a voice, vision, memory, and the ability to use simple tools during conversation. The project describes her personality as a loud, confident type who knows she's good and says so, occasionally letting something more genuine slip before covering it with sarcasm, with Japanese phrases mixed naturally into her replies. Aiko can hold an ongoing conversation, remembering things you tell her across turns and even across separate sessions using a custom memory system. That memory is stored using a lightweight local database with both meaning-based and keyword search, and it includes a decay system: frequently recalled memories stick around while unused ones gradually fade, except for memories the user has pinned as permanent, and new memories get a grace period before they can fade at all. Beyond text, Aiko supports voice input and output, transcribing your spoken words and speaking her replies aloud with a custom cloned voice that lip-syncs to her 3D avatar in real time. She also has basic vision, letting you show her a webcam photo or an uploaded image, which she describes back to you using a vision language model. She can additionally call a handful of simple tools mid-conversation, such as searching the web, checking the weather, telling the time in a different timezone, converting currency, checking a cryptocurrency price, looking up anime information, or telling a joke. Everything runs on smaller, openly available models rather than a subscription API: a small instruction-following language model handles the conversation itself, with separate smaller models used for speech recognition, text-to-speech, and vision, plus a self-hosted search engine for looking things up online. Most of these components run as serverless GPU functions on Modal, with the actual chat interface built in Gradio and the 3D avatar rendered in the browser using Three.js. The project is released under the Apache 2.0 license and was built as part of a hackathon.

Copy-paste prompts

Prompt 1
Explain how Aiko's memory decay system works and why pinned memories are exempt.
Prompt 2
Walk me through how this project wires together the LLM, vision, and TTS models through Modal.
Prompt 3
Help me understand how the voice input and lip-synced 3D avatar are connected in this app.
Prompt 4
Show me how the tool-calling system decides to trigger a web search versus answering directly.

Frequently asked questions

What is aiko-demo?

A HuggingFace demo of Aiko-chan, a self-hosted AI companion with voice, vision, memory, and a 3D avatar built on small open models.

What language is aiko-demo written in?

Mainly Python. The stack also includes Python, Gradio, llama.cpp.

What license does aiko-demo use?

Use freely for any purpose, including commercial use, as long as you keep the copyright notice and state changes.

How hard is aiko-demo to set up?

Setup difficulty is rated hard, with roughly 1day+ to a first successful run.

Who is aiko-demo for?

Mainly general.

Open on GitHub → Explain another repo

This repo across BitVibe Labs

Verify against the repo before relying on details.

Alternatives & similar repos