Fala · Escuta · Lembra · Age E nada sai da sua máquina.
"Toda IA esquece você quando fecha a aba. Esta não."
Você baixa. Roda. E ela te conhece — porque a memória dela é um arquivo no seu disco, não uma conta num servidor de alguém.
Apagar a memória dá amnésia, não lobotomia: ela continua sendo ela, só não te conhece mais.
- 🚀 Primeira instalação
- 🧠 As três memórias
- 🛠️ O que ela sabe fazer
- 🗂️ As quatro pastas
- 🎛️ Providers
- 🔒 Segurança — leia isto
- 🧪 Testes
- 🩹 Quando der ruim
- 📚 Documentação
- ⚖️ Licença
git clone https://github.com/NakamuraIA/HanaNakamura-VTuber-OSS.git hana
cd hanaNo Windows, dê duplo clique em Hana-First-Run.cmd. Pelo terminal, o
comando equivalente é:
.\Hana-First-Run.cmdEle verifica Python, Node e npm; prepara backend, frontend, banco e catálogos
públicos. Depois, abra o .env criado e ponha uma chave de LLM. Só uma já
basta.
Passo a passo e instalação manual: FIRST_RUN.md.
Depois da primeira instalação, é sempre assim:
Ela liga sozinha. Sem terminal, sem comando.
Pra desligar: Desligar-Hana.cmd.
Dois terminais. Um pro back, um pro front.
# terminal 1 — backend
cd backend
.venv\Scripts\activate
uvicorn main:app --reload --port 8042# terminal 2 — frontend
cd frontend
npm run devAbre em http://localhost:1425.
A regra que evita 90% da confusão: Python roda de
backend/. Node roda defrontend/.npmna raiz dáENOENT: package.json.
cd frontend
npm run tauri dev # abre com live-reload (dev)
npm run tauri build # gera o .exe em src-tauri/target/release/O executável fica em frontend/src-tauri/target/release/hana-control-center.exe.
Aqui é onde este projeto é diferente. Não é "histórico de chat" — são três memórias com propósitos diferentes, e a divisão importa:
| O que guarda | Quem escreve | Como entra no prompt | |
|---|---|---|---|
| 💬 Curta | a conversa recente | automático | as últimas N falas, isoladas por canal |
| 🧠 Longa | fatos destilados | ela mesma | só o que combina com a pergunta (RAG) |
| 📌 Fixa | suas regras | só você | sempre, inteira |
Curta guarda conversa. Longa guarda fato. A diferença:
CURTA (crua): LONGA (destilado):
você: nossa, odeio texto longo
hana: desculpa! → "Nakamura não gosta
você: sério, escreve curto de respostas longas"
hana: ok
Quatro mensagens viram uma frase. É por isso que a busca funciona numa e não na outra — você não acha significado num monte de "pera" e "kkkk".
É a continuação do system prompt — mas em banco, editável pela tela:
[REGRAS FIXAS — valem sempre, em todo turno]
- (regra) responda sempre curto
- (giria) me chama de Naka
- (tarefa) o projeto X está na fase de testes
Só você escreve. Ela não tem ferramenta que grave ali — é leitura pura. Desligar uma regra tira do prompt sem apagar, ótimo pra descobrir qual está causando algum comportamento estranho.
runtime/hana_memory.sqlite3
├── messages curta — conversa, por canal → prompt ✅
├── facts longa — RAG com FTS5/BM25 → prompt ✅
├── pinned fixa — suas regras → prompt ✅
├── chat_log histórico da tela → prompt ❌ nunca
├── settings configuração do app → prompt ❌
└── skills os manuais que ela lê e escreve → só o índice
Essa divisão é a coisa mais importante do projeto. As três primeiras custam token toda mensagem. As outras são de graça.
As travas ficam no banco, não no código:
role CHECK (role IN ('user','assistant'))
channel CHECK (channel IN ('chat','discord','terminal','voice'))
content CHECK (length(content) BETWEEN 1 AND 8000)Trava no código depende de todo mundo lembrar. Trava no banco não esquece — um bug em qualquer caller não consegue sujar a tabela.
O isolamento por canal não é enfeite: sem ele, o Discord enxerga a conversa de voz. Já aconteceu, e tem teste pra nunca mais.
Detalhes: backend/docs/MEMORIA.md
33 ferramentas. As que importam:
| 🖐️ Mãos | 🧠 Cabeça | 🎨 Criação |
|---|---|---|
| roda comando no terminal | busca na web (Tavily) | gera e edita imagem |
| lê e escreve arquivo | salva e corrige memória | fala (TTS) e escuta (STT) |
| digita e clica por você | lê e escreve as próprias skills | avatar VTuber |
| vê a tela | agenda lembretes | responde no Discord |
Skill = o manual (quando/como fazer, as pegadinhas). Script = o código que executa.
Quando ela descobre um truque usando uma skill, anota nela:
## Notas da Hana (aprendidas em uso)
- [2026-07-27] usar --audio-format mp3, senão vem opusNa próxima vez ela já sabe. Sem você ensinar de novo.
hana/
├── backend/ 🐍 Python — a Hana de verdade
├── frontend/ ⚛️ React + Tauri — a telinha
├── data/ 📚 skills, scripts e imagens
└── runtime/ 💾 memória e mídia ← a ÚNICA pasta que ela escreve
Copie a pasta inteira, não só o
.sqlite3. O banco usa WAL, então as escritas mais recentes podem estar num arquivo-walao lado. Ou desligue a Hana antes — no desligamento limpo o WAL é aplicado no banco.
Se ela escrever fora de runtime/, é bug. Regra fácil de checar.
Escolha na tela, troque quando quiser. Uma chave já basta pra começar.
| 🧠 Cérebro | 🎙️ Voz | 🔍 Busca |
|---|---|---|
| DeepSeek · Gemini · Groq | Edge (grátis, sem chave) | Tavily |
| OpenRouter · Qwen · Maritaca | Google Cloud · ElevenLabs · Fish | via MCP |
Sugestão pra começar: DeepSeek (barato e rápido) + Edge TTS (grátis).
🎚️ Controle de raciocínio unificado (clique)
Cada provider chama "pensar antes de responder" de um jeito diferente. A Hana unifica isso num knob só na tela:
| Provider | O que ele expõe de verdade |
|---|---|
| Gemini 3.x | thinking_level: low / high |
| Gemini 2.5.x | thinking_budget: -1 dinâmico, 0 desliga |
| DeepSeek | 2 níveis reais + desligado |
| OpenRouter | escala contínua: none → max |
| Groq / Qwen | liga/desliga |
Detalhes: backend/docs/
Este projeto entrega uma IA que roda comando no seu PC. Três coisas que você precisa saber:
| 1 | A API não tem senha. Ela só escuta em 127.0.0.1 — mantenha assim |
| 2 | O bot do Discord obedece ninguém até você pôr seu ID no .env |
| 3 | O .env tem chave de verdade. Nunca commite |
Não troque HANA_BACKEND_HOST pra 0.0.0.0. Parece inofensivo ("quero
acessar do celular"), mas entrega shell sem senha pra qualquer aparelho da rede.
O CORS só aceita localhost e o app Tauri — de propósito. Com ele aberto,
qualquer aba do navegador poderia mandar a Hana rodar comando. Tem teste
travando isso.
python -m pytest backend/tests/ -qpython -m backend.memory.coreOs testes daqui não são enfeite — cada um trava um bug que já aconteceu e que não dá erro nenhum quando volta:
| 🧪 | O que ele impede |
|---|---|
test_vazamento_canal |
o Discord ler a conversa de voz |
test_ferramentas_expostas |
o prompt prometer ferramenta que ela não pode chamar |
test_persona_publica |
dado pessoal voltar pro código que vai pro GitHub |
test_limpar_memoria |
o "apagar tudo" mentir e deixar conversa pra trás |
test_prompt_fixas |
o relógio voltar pro meio do prompt e matar o cache |
test_cors |
o CORS voltar a aceitar qualquer origem |
| Erro | Causa |
|---|---|
ENOENT: package.json |
rodou npm na raiz — vá pra frontend/ |
No module named 'backend' |
rodou Python dentro de backend/ — use uvicorn main:app de dentro de backend/ |
address already in use |
já tem algo na 8042 ou 1425 |
| Tela branca no app | o backend não subiu — rode o Hana.cmd |
| Ela não responde no Discord | falta HANA_OWNER_ID no .env |
fts5: syntax error |
atualize — foi corrigido |
| 📄 | |
|---|---|
| MEMORIA.md | 🧠 as três memórias, por dentro |
| ARCHITECTURE.md | visão geral |
| MODULE_CONTRACT.md | como escrever um módulo |
| Swagger | http://localhost:8042/docs — em português |
AGPL-3.0-only. Veja LICENSE.
Em português claro: use, modifique e distribua à vontade — mas se rodar isto como serviço na web, tem que abrir o código. É a licença que impede alguém de pegar este projeto, vender como SaaS e fechar.
A identidade Hana Nakamura, a marca e os assets do personagem são protegidos separadamente. Veja NOTICE e TRADEMARK.md.