README.md

---
license: mit
language:
  - en
tags:
  - local-ai
  - ai-companion
  - roleplay
  - llm
  - gguf
  - multi-agent
  - character-ai
  - storytelling
pretty_name: Dunoon Daemon
---

# 🐉 Dunoon Daemon

> **Your Personal, Persistent Local AI Companion & Story Engine**

Welcome to **Dunoon Daemon**, a local AI companion and roleplaying suite built for people who want characters that feel persistent, distinctive and fun to interact with.

Create original companions, recreate favourite fictional archetypes, build characters for tabletop games, or put two personalities together in the Arena and see what happens.

Dunoon Daemon runs locally on your own computer. Once your models are installed, your conversations and character data stay on your machine and the app does not require a cloud AI subscription.

---

## ✨ What Can It Do?

### 🧠 Persistent Character Memory

Each companion has its own memory.

Characters can remember useful details from previous conversations, ongoing tasks, established facts and important events without sharing everything indiscriminately between personalities.

Memory is automatically organised and maintained in the background.

### 🎭 Dynamic Personalities

Characters can have their own personalities, behaviours, backstories, goals and speaking styles.

Dunoon Daemon uses adjustable personality traits to influence how characters behave rather than forcing every companion into the same generic assistant personality.

You can create serious companions, fictional characters, tabletop NPCs, villains, oddballs or whatever else you can persuade a local language model to become.

### ⚔️ The Arena

Choose two characters and let them interact directly.

You can:

- Advance the conversation one turn at a time
- Let them continue automatically
- Interrupt whenever you want
- Introduce new situations or events
- Add files and images
- Change the direction of the encounter while it is running

The Arena can be used for debates, roleplaying, character testing, story experiments, tabletop inspiration or simply seeing what happens when two incompatible personalities are left alone together.

Results may vary spectacularly.

### 🌍 Scene Awareness

Dunoon Daemon keeps track of important details about the current situation so characters have a better chance of reacting sensibly to what is actually happening.

Characters are encouraged to respect established locations, objects, dangers, abilities and events rather than casually rewriting the world whenever the conversation changes direction.

It isn't a traditional game engine. Characters are still powered by language models and can surprise you, misunderstand things or occasionally do something completely ridiculous.

That's part of the fun.

### 👁️ Expressive Eyes

The interface includes animated digital eyes that react to the character's current tone and behaviour.

They provide a simple visual indication of how your companion is responding without interrupting the conversation.

### 🗣️ Character Voices

Dunoon Daemon can read character responses aloud using built-in speech options.

Different voices can be assigned to different companions, with adjustable speaking speeds and automatic audio handling.

### 🖼️ Images, Documents and Audio

Characters can work with more than ordinary text.

Depending on your setup, Dunoon Daemon can process:

- Images
- PDF documents
- Word documents
- Text and code files
- Audio files

Audio transcription is handled locally using Whisper-compatible models.

### 🎨 Customisable Interface

Choose different skins, fonts, text sizes and colours.

Optional Help tooltips explain controls throughout the main interface and Arena.

---

# 🚀 Getting Started

## Requirements

- **Windows 10 or Windows 11 (64-bit)**
- **Python 3.11 or newer** if running from source
- A local AI model

A modern NVIDIA, AMD or Intel GPU is recommended, although CPU operation is possible.

---

## 1. Start Dunoon Daemon

Launch:

`controller.py`

or use the standalone executable if you have a packaged build.

You can run models using either:

### Local GGUF Models

Click **📂 Load GGUF Model** and select a compatible GGUF model stored on your computer.

Dunoon Daemon will start the local model server and connect the interface to it.

### LM Studio

You can also use a model already running through LM Studio's local server.

Start the local server in LM Studio and Dunoon Daemon can connect to it.

---

## 2. Create a Companion

Click:

**➕ New Chat**

Give your companion a name.

Then open:

**🎭 Edit Persona**

You can create the character yourself or use the persona generator as a starting point.

Personality settings can then be adjusted to change how the character behaves.

---

## 3. Start Talking

Double-click a companion in the session list to open the conversation.

That's it.

Talk normally.

The companion's memory, personality and conversation history are handled automatically in the background.

---

# ⚔️ Using the Arena

Open the Arena and select two existing companions.

You can control the interaction using:

**⚔️ Step Turn**  
Advance the conversation by one character turn.

**▶️ Auto Loop**  
Allow the characters to continue talking automatically.

**💥 Send / Intervene**  
Interrupt the Arena and introduce your own dialogue, instructions or changes to the situation.

**⚡ Event**  
Introduce an unexpected event into the current scene.

**📁 Upload**  
Add a file or image to the interaction.

**⏩ Continue**  
Allow the current character to continue its previous response.

You remain free to intervene while the characters are interacting.

---

# ⚡ Useful Commands

Commands can be typed directly into a normal companion chat.

`/remember <text>`  
Ask the companion to permanently remember something.

`/memories` or `/vault`  
Show information about the companion's stored memories.

`/forget <n>`  
Remove recent conversational turns from the active context.

`/clear`  
Clear the visible conversation window without deleting stored memories.

`/character`  
Show the character's current personality settings.

`/baseline`  
Temporarily use a more neutral personality state.

`/ubaseline`  
Return to the character's normal dynamic personality.

`/status`  
Show information about the currently loaded model and voice system.

`/see` or `/upload`  
Open the file browser.

`/splash`  
Free unused system and graphics memory.

`/eject`  
Unload the currently loaded local model.

`/talk 1`  
Slow speech.

`/talk 2`  
Normal speech.

`/talk 3`  
Fast speech.

---

# 📁 Project Structure

The main files include:

`controller.py`  
Main application window, session controls and Arena.

`dunoon_daemon.py`  
Companion conversation interface.

`persona.py`  
Character and persona creation.

`character.py`  
Personality behaviour.

`overmind.py`  
Brings together the information a character needs for each response.

`ETO.py`  
Helps characters remain aware of the established situation and its consequences.

`memory_working.py`  
Maintains recent conversational memory.

`memory_deep.py`  
Stores longer-term memories.

`memory_router.py`  
Organises memories according to their purpose.

`memory_embeddings.py`  
Finds memories related to the current conversation.

`memory_integrity.py`  
Checks and repairs stored memories.

`memory_transfer.py`  
Controls optional information sharing between companions.

`state_engine.py`  
Maintains changing conversational state.

`eye_engine.py`  
Controls the animated eyes.

`tts_handler.py`  
Handles character speech.

`skin_manager.py`  
Controls interface themes.

`model_handler.py`  
Starts and stops local GGUF models.

`bridge.py`  
Connects Dunoon Daemon to LM Studio.

---

# 🛠️ Running From Source

Clone the repository:

git clone YOUR_REPOSITORY_ADDRESS

Open the project folder:

cd DunoonDaemonApp

Install the required packages:

pip install requests psutil pygame edge-tts pyttsx3 sentence-transformers numpy Pillow pypdf python-docx faster-whisper

Then run:

python controller.py

---

# 🔒 Local First

Dunoon Daemon is designed around local AI models.

Your companions, conversations, personalities and memory files are stored on your own computer.

Some optional features may require external services or downloads, but the core companion and roleplaying system is designed to operate locally.

---

# 📜 License

Distributed under the **MIT License**.

---

# ❤️ Dedication

Dedicated to the loyal companions who walk with us through every realm, and the code that keeps their echoes alive.

**For Kylo.**

---

## Credits

**Written with ChatGPT and Gemini.**