ollamarama-matrix

Ollamarama is a powerful AI chatbot for the Matrix chat protocol powered by the Ollama Chat API. Transform your Matrix rooms with an AI that can roleplay as virtually anything you can imagine — privately and locally.

Documentation

• Overview
• Getting Started
• Ollama Setup
• Configuration
• Commands
• Tools & MCP
• Docker
• CLI Reference
• Operations & E2E
• Architecture
• Development
• Migration
• Legacy Map
• Security
• AI Output Disclaimer

Features

• Dynamic personalities with quick switching
• Per‑user history, isolated per room and user
• Collaborative mode to talk across histories
• Admin controls for model switching and resets
• Custom system prompts for specialized tasks

Related Projects

• IRC version: https://github.com/h1ddenpr0cess20/ollamarama-irc
• CLI version: https://github.com/h1ddenpr0cess20/ollamarama

Installation

Options depending on how you prefer to run it:

• From source (installs CLI):
  • Clone this repo, then run: pip install .
  • Or use pipx for isolation: pipx install .
• From source without installing the package:
  • pip install -r requirements.txt
  • Run with: python -m ollamarama --config config.json

After installation, use the ollamarama-matrix command. For E2E encryption, ensure libolm is installed; see Operations & E2E.

Quick Start

Prerequisites

Install and familiarize yourself with Ollama to run local LLMs.

curl -fsSL https://ollama.com/install.sh | sh

Pull at least one model (recommended):

ollama pull qwen3

For deeper setup and verification steps, see Ollama Setup.

1) Install dependencies

pip install -r requirements.txt

2) Configure

Create or edit config.json at the repo root. See Configuration for a minimal example, full schema, and validation guidance.

3) Run

Preferred (installed command):

ollamarama-matrix --config config.json

Fetch models from the server (ignores ollama.models in config):

ollamarama-matrix --config config.json --server-models

Short form:

ollamarama-matrix -S --config config.json

Alternatively, run as a module:

python -m ollamarama --config config.json

4) Try It

• The bot logs in and joins configured rooms
• Send .ai hello or BotName: hello in a joined room
• The bot replies and maintains per‑user history

Usage Guide

Common commands (see Commands for the full list):

Command	Description	Example
.ai <message> or botname: <message>	Chat with the AI	.ai Hello there!
.x <user> <message>	Continue another user's conversation	.x Alice What did we discuss?
.persona <text>	Change your personality	.persona helpful librarian
.custom <prompt>	Use a custom system prompt	.custom You are a coding expert
.reset / .stock	Clear history (default/stock prompt)	.reset
.model [name] (admin)	Show/change model	.model qwen3
.clear (admin)	Reset globally for all users	.clear
.help	Show inline help	.help
.verbose [on,off,toggle] (admin)	Control inclusion of brevity clause for new conversations	.verbose on

Encryption Support

• Works in encrypted Matrix rooms using matrix-nio[e2e] with device verification.
• Requires libolm available to Python for E2E. If unavailable, you can run without E2E; see Getting Started (Install Dependencies).
• Persist the store/ directory to retain device keys and encryption state.

Community & Policies

• Code of Conduct
• Contributing
• Security Policy
• Security
• Not a Companion
• AI Output Disclaimer

License

AGPL‑3.0 — see LICENSE for details.