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 the rooms listed in matrix.channels
• Send .ai hello or BotName: hello in a joined room
• The bot replies and maintains per‑user history
• Invites to other rooms are declined automatically (the bot replies and leaves)

Usage Guide

Common commands (see Commands for the full list):

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

Apache-2.0 — see LICENSE for details.