From 3d5aa0b76b104c08fb141697f69b6076ed56d985 Mon Sep 17 00:00:00 2001
From: latte <latte@hiddenden.cafe>
Date: Mon, 12 Jan 2026 14:02:25 +0100
Subject: [PATCH] Update README with PostgreSQL memory system documentation

---
 README.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 50 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index e6896e3..a0d40d5 100644
--- a/README.md
+++ b/README.md
@@ -5,10 +5,12 @@ A customizable Discord bot that responds to @mentions with AI-generated response
 ## Features
 
 - **Multi-Provider AI**: Supports OpenAI, OpenRouter, Anthropic (Claude), and Google Gemini
+- **Persistent Memory**: PostgreSQL database for user and conversation storage
+- **User Recognition**: Set custom names so the bot knows "who is who"
+- **User Facts**: Bot remembers things about users (hobbies, preferences, etc.)
 - **Web Search**: Access current information via SearXNG integration
 - **Fully Customizable**: Configure bot name, personality, and behavior
-- **Conversation Memory**: Remembers context per user
-- **Easy Deployment**: Docker support included
+- **Easy Deployment**: Docker support with PostgreSQL included
 
 ## Quick Start
 
@@ -33,6 +35,12 @@ Edit `.env` with your settings (see [Configuration](#configuration) below).
 docker compose up -d
 ```
 
+This starts both the bot and PostgreSQL database. Run migrations on first start:
+
+```bash
+docker compose exec daemon-boyfriend alembic upgrade head
+```
+
 Or run locally:
 
 ```bash
@@ -76,6 +84,16 @@ All configuration is done via environment variables in `.env`.
 | `AI_TEMPERATURE` | `0.7` | Response creativity (0.0-2.0) |
 | `MAX_CONVERSATION_HISTORY` | `20` | Messages to remember per user |
 
+### Database (PostgreSQL)
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DATABASE_URL` | (none) | PostgreSQL connection string |
+| `POSTGRES_PASSWORD` | `daemon` | Password for docker-compose PostgreSQL |
+| `CONVERSATION_TIMEOUT_MINUTES` | `60` | Minutes before starting new conversation |
+
+When `DATABASE_URL` is set, the bot uses PostgreSQL for persistent storage. Without it, the bot falls back to in-memory storage (data lost on restart).
+
 ### Web Search (SearXNG)
 
 | Variable | Default | Description |
@@ -134,6 +152,25 @@ Mention the bot in any channel:
 @YourBot help me write a poem
 ```
 
+### Memory Commands
+
+Users can manage what the bot remembers about them:
+
+| Command | Description |
+|---------|-------------|
+| `!setname <name>` | Set your preferred name |
+| `!clearname` | Reset to Discord display name |
+| `!remember <fact>` | Tell the bot something about you |
+| `!whatdoyouknow` | See what the bot remembers |
+| `!forgetme` | Clear all facts about you |
+
+Admin commands:
+
+| Command | Description |
+|---------|-------------|
+| `!setusername @user <name>` | Set name for another user |
+| `!teachbot @user <fact>` | Add a fact about a user |
+
 ## AI Providers
 
 | Provider | Models | Notes |
@@ -150,12 +187,21 @@ src/daemon_boyfriend/
 ├── bot.py              # Main bot class
 ├── config.py           # Configuration
 ├── cogs/
-│   └── ai_chat.py      # Mention handler
+│   ├── ai_chat.py      # Mention handler
+│   ├── memory.py       # Memory commands
+│   └── status.py       # Health/status commands
+├── models/
+│   ├── user.py         # User, UserFact, UserPreference
+│   ├── conversation.py # Conversation, Message
+│   └── guild.py        # Guild, GuildMember
 └── services/
     ├── ai_service.py   # AI provider factory
+    ├── database.py     # PostgreSQL connection
+    ├── user_service.py # User management
+    ├── persistent_conversation.py  # DB-backed history
     ├── providers/      # AI providers
-    ├── conversation.py # Chat history
     └── searxng.py      # Web search service
+alembic/                # Database migrations
 ```
 
 ## License