WIP — Work in Progress. Under active development. APIs and data formats may change without notice.
Local-first AI roleplay framework for persistent characters with hierarchical memory, multi-NPC conversations, and safety guardrails. Designed for solo TTRPG-style play and creative writing with AI-powered NPCs.
- Persistent characters — name, race, class, alignment, personality profiles
- Hierarchical memory — episodic / semantic / procedural memory with importance scoring and vector retrieval
- Scene management — full lifecycle (create → start → end), multi-character scenes
- Multi-NPC conversations — agent router detects name mentions, targets specific NPCs, falls back to last speaker
- Guardrails — intent classification (6 classes), DM commands (10 commands), response validation with safe fallbacks
- Message persistence — conversations survive restarts (SQLite)
- Model-agnostic — local inference via koboldcpp by default, with Ollama, OpenAI, and Anthropic adapters
- React frontend — dark mode, responsive layout, chat bubbles, TTS/STT voice support
# One-command launcher (installs deps, starts backend + frontend)
.\scripts\start-chatpg.ps1
# Or with koboldcpp LLM server
.\scripts\start-chatpg.ps1 -KoboldCpp .\koboldcpp.exe -Model .\gemma-3-4b-it-Q4_K_M.gguf# Terminal 1 — Backend (port 8000)
cd backend
python -m uvicorn app.main:app --port 8000 --reload
# Terminal 2 — Frontend (port 5173)
cd frontend
npx vite --port 5173 --host 127.0.0.1
# Terminal 3 — LLM (optional)
.\koboldcpp.exe --model .\gemma-3-4b-it-Q4_K_M.gguf --port 5001Open http://127.0.0.1:5173 in your browser.
The default provider is koboldcpp at http://127.0.0.1:5001.
Set LLM_PROVIDER to ollama, openai, or anthropic to use another provider.
| Layer | Technology |
|---|---|
| Backend | Python 3.13, FastAPI |
| Database | SQLite |
| Embeddings | sentence-transformers (all-MiniLM-L6-v2) |
| Frontend | React + TypeScript + Vite |
| UI Library | Tailwind v4 + shadcn/ui v4 |
| State | TanStack Router + TanStack Query |
| LLM | koboldcpp (default), Ollama / OpenAI / Anthropic (optional) |
Active development. Milestone progress:
- M1 — Core engine (inference, character CRUD, working memory) ✓
- M2 — Memory persistence (scenes, messages, vector store) ✓
- M3 — Guardrails & multi-NPC ✓
- M4 — Voice (TTS/STT) — implemented; model download/inference requires the runtime dependencies
- M5 — UI polish & memory tools ✓ (migrated from Streamlit to React + Vite)
MIT