convez.ai
PluginUtilidadesIntermediário
Sakushi-Dev

PersonaUI

Sakushi-Dev/PersonaUI

Crie companheiros IA com personalidade e memória — tudo local e privado

Ver no GitHub
BomPluginScore · de 0 a 100

Aplicação desktop local para criar e interagir com companheiros IA com personalidades distintas, profundidade emocional e memória persistente. Todos os dados são armazenados localmente, garantindo privacidade, e se integra à API Claude da Anthropic para gerar respostas contextualizadas.

Instalação

$npx convez-ai Sakushi-Dev/PersonaUI

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
12
Forks
0
Acompanhando
0
Saúde
100%
Último commit
há 7 meses
Versão
—
Issues abertas
0
Contribuidores
2

Casos de uso

  • Criar personagens IA para exploração criativa e narrativa
  • Desenvolver assistentes virtuais personalizados com histórico e contexto
  • Prototipagem de interações conversacionais com estado persistente

Veredito

Ferramenta inovadora para quem quer criar companheiros IA com personalidade real e memória duradoura, rodando 100% local. Ideal para criadores, pesquisadores e exploradores de IA interessados em sistemas conversacionais mais sofisticados e humanizados.

README

A tradução para o português deste README ainda está na fila.


What Is PersonaUI?

PersonaUI is a local desktop application that lets you create and talk to AI characters — called Personas. Unlike typical chatbots, these personas remember previous conversations, develop their own emotional states, and grow over time. Every persona stores its data exclusively on your computer. Nothing is sent to external servers beyond the AI model requests themselves.

The application runs as a native desktop window (via PyWebView) with a modern React frontend. It connects to Anthropic's Claude API for generating responses, while all conversation data, memories, and settings remain local.


Installation

There are two ways to get PersonaUI running on your machine: a one-click installer for Windows, or a manual setup for developers and Linux/macOS users.

Prerequisites

  • An Anthropic API key — You can create one at console.anthropic.com. The onboarding wizard will ask for it on first launch.
  • Git (optional) — Needed if you want to clone the repository. You can also download the project as a ZIP file directly from GitHub.

Python is required to run the application, but on Windows PersonaUI can install it for you automatically (see Option A below).

Step 1 — Get the Project

There are two ways to download the project files onto your computer:

With Git (recommended if you want easy updates later):

  1. Press Win + R, type cmd, and hit Enter. This opens the Windows command prompt.
  2. Check if Git is installed by typing:
    git --version
    
    If you see a version number (e.g. git version 2.43.0), Git is ready. If you get an error like 'git' is not recognized, install Git first:
    • Go to git-scm.com/downloads and download the Windows installer.
    • Run the installer. You can keep all default settings — just click Next until the installation finishes.
    • Close the command prompt and open a new one (Win + R → cmd → Enter), so that the new Git installation is recognized.
  3. Navigate to the folder where you want the project to live. For example, to put it on your Desktop:
    cd %USERPROFILE%\Desktop
    
  4. Download the project:
    git clone https://github.com/Sakushi-Dev/PersonaUI.git
    
    This creates a new folder called PersonaUI containing all project files.

Without Git: Go to github.com/Sakushi-Dev/PersonaUI, click the green Code button, select Download ZIP, and extract the archive to a folder of your choice.

Step 2 — Start the Application

Option A: Windows — Double-click to start

The project includes a PersonaUI.exe in the project root (or bin/start.bat as the equivalent batch file). This is not a traditional installer — it is a lightweight batch script converted to an EXE using Bat To Exe Converter. When you run it, the script:

  1. Looks for an existing Python installation (virtual environment, system Python, or py launcher).
  2. If no Python is found, it automatically downloads and installs Python 3.12 for you.
  3. Creates a virtual environment (.venv) and installs all pip dependencies.
  4. Downloads Node.js v22 if it is not present and installs the frontend npm packages.
  5. Builds the React frontend and launches the application.

You can also run bin/start.bat directly — it behaves identically.

Additional scripts in bin/: update.bat (pulls the latest version via Git), reset.bat (factory reset with confirmation dialog), prompt_editor.bat (launches the standalone prompt editor).

Option B: Manual Setup (All Platforms)

If you prefer full control, or you are on Linux/macOS:

cd PersonaUI
python -m venv .venv

# Windows
.venv\Scripts\activate

# Linux / macOS
source .venv/bin/activate

pip install -r requirements.txt
python src/init.py

The init script takes care of everything from here: downloading Node.js if needed, installing npm packages, building the frontend, and starting the app.

Launch Options

You can customize startup behavior by editing config/launch_options.txt:

OptionEffect
--no-guiRuns without the desktop window. The app becomes accessible in your browser at http://localhost:PORT.
--devStarts the Vite development server for live frontend changes at http://localhost:5173.

What Makes PersonaUI Different

Most AI chatbots forget everything once the conversation ends. PersonaUI gives each persona three files that represent its inner world:

  • Memory — Recollections of past conversations and shared moments
  • Soul — Evolving self-understanding, values, and personal growth
  • Relationship — How the persona perceives and relates to you over time

Written from the persona's own perspective and updated autonomously via tool use at configurable context thresholds (50 %, 75 %, 95 %). Viewable and editable through the in-app Cortex Overlay.

After sending a response, the AI may decide it has something to add — a follow-up message sent on its own, without any input from you.

  • Independent follow-up messages with a 10-second timer, cancelable at any time
  • Mood shifts naturally during conversation — excitement, concern, playfulness, frustration
  • Emotional states carry over across messages, just as in a real interaction
  • Makes conversations feel noticeably more human

Each persona is defined by a set of properties you choose during creation:

  • Species — Human, Transcendent Being, Elf, Robot, Alien, or Demon
  • Personality — Friendly, protective, curious, wise, mysterious, or custom combinations
  • Expression style — Normal speech, expressive actions, or casual texting
  • Knowledge areas — Cooking, gaming, art, science, philosophy, or anything you define
  • Scenario — The setting in which conversations take place

Every persona operates in its own isolated environment with dedicated Cortex files, chat history, and emotional state.

All data lives exclusively on your machine — nothing is stored in the cloud. Despite full local privacy, you can still share access over your local network:

  • IP-based access control with whitelist and blacklist
  • QR code for quick mobile device connection
  • Per-persona SQLite databases, easy to back up or delete
  • No data leaves your computer except the API requests to Anthropic

Features

FeatureDescription
Cortex Memory SystemThree-file memory architecture (Memory, Soul, Relationship), updated autonomously via tool use
Afterthought SystemThe AI independently decides whether to send a follow-up message (10-second timer, cancelable)
8-Step OnboardingGuided first-launch setup: profile, API key, context settings, Cortex config, UI preferences
Slash CommandsType / in the chat to access commands with autocomplete — extensible for both frontend and backend
36 Prompt TemplatesJSON-based personality templates with three-phase placeholder resolution
Prompt EditorA standalone visual tool for inspecting and editing how prompt components combine
19 Overlay DialogsIn-app panels for API settings, Cortex editing, avatar management, persona configuration, and more
Custom SpecificationsFive specification categories to fine-tune persona behavior beyond the defaults
Network SharingShare access over your local network with IP-based access control and QR code for mobile devices
InternationalizationFull i18n support — currently available in English and German

Technology Stack

LayerTechnologyPurpose
AI EngineAnthropic Claude (SDK 0.34+)Response generation with tool-use support
BackendPython 3.12+ with Flask 3.0+Application server and API
DesktopPyWebView 5.xNative desktop window without Electron overhead
FrontendReact 19, Vite 7, React Router 7Single-page application with hot module replacement
StorageSQLite (one database per persona)Local-only storage, easy to back up or delete
StreamingServer-Sent Events (SSE)Real-time message streaming from the AI
LocalizationCustom useLanguage hookFeature-scoped locale files for EN and DE

Architecture

+-------------------------------------------------------+
|                      PyWebView                        |
|                                                       |
|  +-----------+  +------------+  +-----------------+   |
|  |  Splash   |  |    Chat    |  |  Prompt Editor  |   |
|  |  Screen   |  |   (React)  |  |  (Standalone)   |   |
|  +-----+-----+  +-----+------+  +-------+---------+   |
|        |              |                  |            |
|   startup.py    Flask Routes        EditorApi         |
|        |              |                  |            |
|        +--------------+------------------+            |
|                       |                               |
|              +--------+--------+                      |
|              |    Services     |                      |
|              | Chat - Cortex   |                      |
|              +--------+--------+                      |
|                       |                               |
|         +-------------+-------------+                 |
|         |             |             |                 |
|    PromptEngine   ApiClient    Database               |
|    (36 Templates) (Anthropic)  (SQLite)               |
+-------------------------------------------------------+

Backend — 15 Flask blueprints: access, api, avatar, character, chat, commands, cortex, custom_specs, emoji, main, onboarding, react_frontend, sessions, settings, user_profile (~84 REST endpoints).

Frontend — A React 19 single-page application with three pages (Chat, Onboarding, Waiting), 20 reusable UI components, 21 overlay dialogs, 5 context providers, 8 custom hooks, and 13 API service modules. Includes a slash command system with autocomplete and keyboard navigation.


Documentation

The .github/docs/ directory contains detailed guides for every part of the system:

#DocumentFocus Area
00Project SummaryArchitecture, tech stack, design decisions
01App Core & StartupBootstrap chain, init.py, app.py, PyWebView
02Configuration & SettingsJSON settings, defaults, .env, config loading
03Utils & HelpersLogger, provider, access control, SQL loader, helpers
04Routes & API15 blueprints, ~84 REST endpoints
05Chat SystemSSE streaming, afterthought, message assembly
06Prompt EngineJSON templates, manifests, placeholder resolution
07Database LayerPer-persona SQLite, schema, migrations, SQL loader
09Persona & InstructionsPersona spec, config, CRUD, AI autofill
10Cortex Memory SystemLong-term memory, tool_use, tier system
11Services LayerApiClient, ChatService, CortexService, Provider
12Frontend — React SPAReact architecture, components, services, hooks
13Prompt EditorStandalone editor app, CRUD, preview
14Onboarding, Splash & ResetFirst-run wizard, splash screen, factory reset
15Tests & QualityTest architecture, fixtures, coverage
16Slash CommandsCommand system, registry, built-in commands

Troubleshooting

  • Make sure Python 3.12+ is installed and added to your PATH. Verify with python --version in a terminal.
  • On Windows, the start.bat / PersonaUI.exe script tries to detect Python automatically. If it fails, install Python manually from python.org and check "Add Python to PATH" during installation.
  • If you use a virtual environment, make sure it is activated before running any commands:
    # Windows
    .venv\Scripts\activate
    
    # Linux / macOS
    source .venv/bin/activate
    
  • PyWebView relies on the system's WebView2 runtime on Windows. If you see a blank or white window, install the Microsoft Edge WebView2 Runtime.
  • Make sure the frontend was built successfully. Check that the frontend/dist/ folder exists and contains files. If not, rebuild it:
    cd frontend
    npm install
    npm run build
    
  • Try launching with --no-gui in config/launch_options.txt to open the app in your browser instead. This helps isolate whether the issue is PyWebView or the app itself.
  • After changing your monitor setup (disconnecting a display, changing resolution), the app window may open off-screen because it restores the last saved position.
  • Fix: Delete src/settings/window_settings.json and restart PersonaUI. The window will open centered with default dimensions.
  • Verify your Anthropic API key is correct and active at console.anthropic.com.
  • Re-enter your API key through the in-app settings (API overlay). The key is stored in the src/.env file and can also be edited manually if needed.
  • The key format must start with sk-ant-api. If the onboarding wizard rejects your key, double-check for leading/trailing spaces.
  • Ensure your API key has sufficient credits. You can check your usage and billing at the Anthropic console. If you see a credit_balance_exhausted error, you need to add credits to your Anthropic account.
  • After changing the key via the in-app settings, it takes effect immediately — no restart required.
  • The default port is 5000 (configurable via src/settings/server_settings.json). If you see an error like Address already in use or OSError: [Errno 98], another process is occupying the port.
  • On Windows, find and kill the blocking process:
    netstat -ano | findstr :5000
    taskkill /PID <PID> /F
    
  • On Linux/macOS:
    lsof -i :5000
    kill -9 <PID>
    
  • This commonly happens when a previous PersonaUI instance didn't shut down cleanly.
  • The init script downloads Node.js v22 automatically. If this fails (e.g. due to network restrictions or firewall blocks), install Node.js manually from nodejs.org.
  • Delete frontend/node_modules/ and frontend/package-lock.json, then retry:
    cd frontend
    rm -rf node_modules package-lock.json
    npm install
    npm run build
    
  • On Windows, long file paths in node_modules can cause issues. Enable long paths:
    git config --system core.longpaths true
    
  • Each persona has its own SQLite database (src/data/main.db for the default persona, src/data/persona_<uuid>.db for custom ones). If a specific persona's chat is broken, try deleting its database file and restarting the app. The database will be recreated automatically (note: chat history for that persona will be lost).
  • If you see migration errors after an update, make sure you are running the latest version — database migrations are applied automatically on startup.
  • Orphaned database files: If you deleted a persona's JSON definition manually but its database file still exists, it will not be cleaned up automatically. You can safely delete any .db file in src/data/ that no longer corresponds to an existing persona.
  • The Cortex system updates persona memory (Memory, Soul, Relationship files) via background API calls triggered at configurable context thresholds (50 %, 75 %, 95 %). If memory seems stale:
    • Check that Cortex is enabled in the Cortex settings overlay.
    • Cortex updates have a 30-second cooldown between triggers — rapid messages may skip updates.
    • Background cortex updates fail silently if the API call errors out (e.g. insufficient credits, network issue). Check src/logs/personaui.log for warnings.
    • Each Cortex file is capped at 8,000 characters. Excess content is silently truncated.
  • Cortex update calls use additional API credits — one extra API request per update cycle.
  • If src/settings/cycle_state.json becomes corrupt, delete it. It will be recreated with default values, which may trigger an immediate cortex update on the next conversation.
  • The onboarding wizard is controlled by src/settings/onboarding.json. If this file is missing, empty, or corrupt (e.g. due to a crash during write), the onboarding will re-trigger on the next launch.
  • Fix: Create or fix the file manually:
    {"completed": true, "disclaimer_accepted": true}
    
  • This also applies after a factory reset — the onboarding is intentionally shown again.
  • PersonaUI stores settings as JSON files in src/settings/. If any of these files become malformed (e.g. crash during write, accidental manual edit), the app may fail to start or behave unexpectedly.
  • Fix: Delete the corrupt settings file. PersonaUI recreates most settings files with defaults on the next launch. Key files:
    • user_settings.json — User preferences
    • cortex_settings.json — Cortex system configuration
    • window_settings.json — Window position and size
    • onboarding.json — Onboarding completion state
    • cycle_state.json — Cortex trigger tracking
    • user_profile.json — User name, avatar, language
  • The defaults.json file contains static defaults shipped with the app — do not modify or delete it.
  • Avatar uploads require Pillow (included in requirements.txt). If Pillow is not installed, the upload will fail. Reinstall dependencies with pip install -r requirements.txt.
  • Maximum upload size is 10 MB. Images are automatically cropped and resized to 1024×1024 JPEG.
  • Custom avatars are stored in frontend/public/avatar/costum/. If this directory is missing, create it manually.
  • Custom avatars are deleted by a factory reset. Back them up before resetting if needed.
  • Make sure both devices are on the same local network (same Wi-Fi / LAN).
  • Check your firewall settings — the port PersonaUI uses (default: 5000) must be allowed for incoming connections.
  • On Windows, you may need to allow Python (or the specific port) through Windows Defender Firewall:
    • Open Windows Security → Firewall & network protection → Allow an app through firewall
    • Add python.exe (from your .venv/Scripts/ folder) or allow the port manually.
  • Verify the correct local IP is displayed. You can check with ipconfig (Windows) or ifconfig / ip addr (Linux/macOS).
  • If you are locked out by the IP whitelist/blacklist, edit or delete src/settings/server_settings.json and restart.
  • PersonaUI uses Server-Sent Events (SSE) for real-time message streaming. Long responses can be interrupted by:
    • Proxies or firewalls with idle-connection timeouts — if you're behind a corporate proxy, try connecting directly.
    • Unstable network connections — the stream will error out and the partial response is shown.
  • If streaming frequently breaks, try switching to --no-gui mode and using a modern browser, which tends to handle SSE more reliably.
  • Check src/logs/personaui.log for detailed error messages from the streaming endpoint.
  • The PersonaUI.exe is a batch script converted with Bat To Exe Converter. Some antivirus tools flag this as suspicious — it is a false positive.
  • You can add an exception for the PersonaUI folder in your antivirus settings, or simply use bin/start.bat directly instead of the EXE.
  • If bin/update.bat or git pull fails with merge conflicts, you likely have local changes that conflict with the update.
  • Important: bin/update.bat uses git reset --hard origin/main internally — this discards all local code changes. Settings and persona data in .gitignored directories are not affected.
  • To update manually while preserving local changes:
    git stash
    git pull
    git stash pop   # re-apply your changes (may need manual conflict resolution)
    
  • Settings and persona data are never overwritten by Git updates — they live in directories that are .gitignored.
  • When running with --dev, the Vite dev server runs on http://localhost:5173 while the Flask backend runs on a different port. CORS is pre-configured for this setup.
  • If you still see CORS errors, make sure you're accessing the frontend through http://localhost:5173 (not through the Flask port).
  • Clear your browser cache or try an incognito window — stale service workers can cause unexpected CORS issues.
  • PersonaUI writes detailed logs to src/logs/personaui.log (rotating file, 5 MB max, 3 backups).
  • When reporting a bug or debugging an issue, check this log file first — it contains stack traces, API errors, and background task failures that are not visible in the UI.
  • Console output (when running from a terminal) also shows INFO-level messages and above.
  • If nothing else helps, you can perform a full factory reset using bin/reset.bat (or python src/reset.py).
  • This deletes all personas, databases, settings, chat history, custom avatars, Cortex memory, logs, and caches — effectively returning PersonaUI to its first-launch state.
  • Back up any data you want to keep before resetting:
    • src/data/ — Databases (chat history)
    • src/settings/ — All settings
    • src/instructions/created_personas/ — Custom persona definitions
    • frontend/public/avatar/costum/ — Custom avatars

Contributing

Contributions are welcome. The dev branch is the main working branch for new features and improvements.

  • The documentation covers the full codebase, making it straightforward to get oriented.
  • Automated tests protect against regressions.
  • Current priorities: Cortex system refinement, React frontend polish, additional language support, performance optimization for large conversation histories.

License

PersonaUI is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).


Ver o original no GitHub

Bom para

Relacionados