https://github.com/h1ddenpr0cess20/ollamarama-matrix
AI chatbot for Matrix with infinite personalties, using ollama
https://github.com/h1ddenpr0cess20/ollamarama-matrix
ai chatbot matrix matrix-nio ollama
Last synced: 11 months ago
JSON representation
AI chatbot for Matrix with infinite personalties, using ollama
- Host: GitHub
- URL: https://github.com/h1ddenpr0cess20/ollamarama-matrix
- Owner: h1ddenpr0cess20
- License: agpl-3.0
- Created: 2023-12-15T05:55:33.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-07-10T05:49:24.000Z (12 months ago)
- Last Synced: 2025-07-10T08:48:37.716Z (12 months ago)
- Topics: ai, chatbot, matrix, matrix-nio, ollama
- Language: Python
- Homepage:
- Size: 137 KB
- Stars: 48
- Watchers: 1
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ollamarama-matrix
[](https://www.gnu.org/licenses/agpl-3.0)
[](https://www.python.org/downloads/)
[](https://matrix.org/)
[](https://ollama.com/)
[](https://github.com/h1ddenpr0cess20/ollamarama-matrix)
Ollamarama is a powerful AI chatbot for the [Matrix](https://matrix.org/) chat protocol powered by [Ollama](https://ollama.com/). Transform your Matrix channels with an AI that can roleplay as virtually anything you can imagine.
## ✨ Features
- 🎭 **Dynamic Personalities**: Switch between different AI personalities on the fly
- 👥 **Per-User Chat History**: Each user maintains their own conversation context
- 🔒 **Channel Isolation**: Conversations are separated by channel and user
- 🤝 **Collaborative Mode**: Users can interact with each other's chat histories
- 🛠️ **Admin Controls**: Model switching and global reset capabilities
- 🎯 **Custom Prompts**: Use your own system prompts for specialized interactions
## 🌟 Related Projects
- 💬 **IRC Version**: [ollamarama-irc](https://github.com/h1ddenpr0cess20/ollamarama-irc)
- 🖥️ **Terminal Version**: [ollamarama](https://github.com/h1ddenpr0cess20/ollamarama)
## 🚀 Quick Start
### Prerequisites
Install and familiarize yourself with [Ollama](https://ollama.com/) to run local LLMs.
```bash
curl https://ollama.com/install.sh | sh
```
### 1. Install AI Models
Download the models you want to use from the [Ollama library](https://ollama.com/library).
**🎯 Recommended model:**
```bash
ollama pull qwen3
```
### 2. Install Dependencies
```bash
pip install -r requirements.txt
```
This installs `matrix-nio` with encryption support so the bot can work in encrypted rooms.
### 3. Configure Matrix Bot
1. Set up a [Matrix account](https://app.element.io/) for your bot
2. Get your server URL, username, and password
3. Update the `config.json` file with your credentials:
```json
{
"matrix": {
"server": "https://matrix.org",
"username": "@your_bot:matrix.org",
"password": "your_password",
"channels": ["#your-channel:matrix.org"],
"store_path": "store"
}
}
```
### 4. Run the Bot
```bash
python ollamarama.py
```
## 📖 Usage Guide
### Basic Commands
| Command | Description | Example |
|---------|-------------|---------|
| `.ai ` or `botname: ` | Basic chat with the AI | `.ai Hello there!` |
| `.x ` | Talk to another user's chat history | `.x Alice What did we discuss?` |
| `.persona ` | Change AI personality | `.persona helpful librarian` |
| `.custom ` | Use custom system prompt | `.custom You are a coding expert` |
| `.reset` | Clear history, reset to default personality | `.reset` |
| `.stock` | Clear history, use without system prompt | `.stock` |
### 👑 Admin Commands
| Command | Description | Example |
|---------|-------------|---------|
| `.model [model_name]` | Show/change current model | `.model qwen3` |
| `.clear` | Reset bot for all users | `.clear` |
### 💡 Pro Tips
- **Personality Examples**: Try `detective`, `pirate`, `shakespeare`, `helpful assistant`, `sarcastic critic`
- **Collaborative Mode**: Use `.x username` to continue someone else's conversation
- **Custom Prompts**: Perfect for specialized tasks like code review or creative writing
## Encryption Support
- This bot supports end-to-end encryption (E2E) in Matrix rooms using `matrix-nio[e2e]` and a built-in device verification system.
- You must have `libolm` installed and available to Python for E2E to work.
- On Windows, you need to build and install `libolm` from source for encryption support. If you do not need encrypted rooms or have issues with `libolm`, use the files in the `no-e2e/` folder, or run it using Windows Subsystem for Linux (WSL).
## ⚖️ License
This project is licensed under the **GNU Affero General Public License v3.0 (AGPL-3.0)**. See the [LICENSE](LICENSE) file for details.
## 🤝 Contributing
Contributions are welcome! Feel free to:
- 🐛 Report bugs
- 💡 Suggest features
- 🔧 Submit pull requests
## ⭐ Show Your Support
If you find this project useful, please consider giving it a star on GitHub!