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

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):

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`
`.history [on,off,toggle]`	Enable or disable your conversation history	`.history off`
`.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`
`.thinking [on,off,toggle]` (admin)	Show or hide the thinking placeholder while generating	`.thinking off`

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

License

Apache-2.0 — see LICENSE for details.