From ae49591735d70d8573f6e01e4959c0cca3388ce1 Mon Sep 17 00:00:00 2001
From: Cole <colemanswenson@gmail.com>
Date: Wed, 25 Mar 2026 14:50:51 -0700
Subject: [PATCH] Add README

Co-Authored-By: DadBot <dadbot@localhost>
---
 README.md | 85 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 85 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..248462b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,85 @@
+# DadBot
+
+A Discord bot with a persistent personality, long-term memory, and a simulated inner life. Runs through LiteLLM so you can point it at any model.
+
+## Features
+
+- **Persistent personality** — DadBot can rewrite his own personality prompt via a tool call. Changes persist to `personality.txt` and are logged to `personality_changelog.txt`.
+- **User dossiers** — Automatically builds and maintains a per-user fact file (`dossiers.json`) from conversation history.
+- **Self-reflection** — When idle, DadBot runs a private reflection session: explores a topic from `topics.txt`, updates his reflection notes, and may refine his personality.
+- **Life simulation** — Alternates with reflection sessions to run scripted life events (`life_events.json`) as a two-LLM dialogue. Outcomes are summarised into `life_history.txt` and can influence personality.
+- **Web search** — Connected to a SearXNG MCP server for live web search during conversations and reflections.
+- **Image support** — Handles image attachments in messages (base64-encoded, passed to the model as vision input).
+- **Multi-message replies** — Use `[SPLIT]` in model output to send multiple Discord messages with natural word-count-based pacing.
+- **Rolling context** — Per-channel message history with a configurable window (`MAX_CONTEXT`).
+
+## Requirements
+
+- Python 3.11+
+- A running [LiteLLM](https://github.com/BerriAI/litellm) proxy
+- A running [SearXNG MCP](https://github.com/ihor-sokoliuk/mcp-searxng) instance (optional but expected)
+- A Discord bot token
+
+## Setup
+
+1. Copy `.env.example` to `.env` and fill in your values:
+
+```env
+DISCORD_TOKEN=your_discord_bot_token
+LITELLM_BASE_URL=http://your-litellm-host:4000/v1
+LITELLM_API_KEY=your_key
+MODEL=your-chat-model
+BACKGROUND_MODEL=your-background-model   # defaults to MODEL if unset
+SYSTEM_PROMPT=...
+MAX_CONTEXT=20
+MCP_URL=http://mcp-searxng:4001/mcp
+```
+
+2. Install dependencies:
+
+```bash
+pip install -r requirements.txt
+```
+
+3. Run:
+
+```bash
+python bot.py
+```
+
+## Docker
+
+```bash
+docker compose up -d
+```
+
+The compose file expects an external Docker network named `aiplayground_litellm_internal` and mounts all persistent data files from the project directory.
+
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `MODEL` | `gpt-4` | Model for chat and reflection |
+| `BACKGROUND_MODEL` | `MODEL` | Model for background tasks (life sim, reflection) |
+| `MAX_CONTEXT` | `20` | Rolling message history per channel |
+| `SYSTEM_PROMPT` | `You are a helpful assistant.` | Base system prompt |
+| `MCP_URL` | `http://mcp-searxng:4001/mcp` | SearXNG MCP endpoint |
+| `REFLECTION_IDLE_MIN` | (see bot.py) | Minutes of inactivity before background task fires |
+| `REFLECTION_MAX_TURNS` | `5` | Max LLM turns per reflection session |
+| `LIFE_SIM_MAX_TURNS` | `6` | Max turns per life simulation event |
+
+## Data Files
+
+| File | Purpose |
+|---|---|
+| `personality.txt` | DadBot's current personality prompt (editable by the bot) |
+| `dossiers.json` | Per-user and self fact store |
+| `reflection_notes.txt` | Notes DadBot saves for future reflection sessions |
+| `reflection_log.txt` | Full transcripts of past reflection sessions |
+| `personality_changelog.txt` | Log of every personality change with reasoning |
+| `topics.txt` | One topic per line — exploration pool for reflection sessions |
+| `used_topics.json` | Tracks which topics have been used |
+| `life_events.json` | Ordered list of life events to simulate |
+| `used_life_events.json` | Tracks which life events have been played |
+| `life_history.txt` | Summaries of completed life events |
+| `life_sim_log.txt` | Full transcripts of life simulation sessions |