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, locally, and fast.

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

• 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

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

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.

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.

pip install -r requirements.txt

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

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

Validate only (no network login):

ollamarama-matrix --dry-run -v

Alternatively, run as a module:

python -m ollamarama --config config.json

• 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

Common commands (see Commands for the full list):

• 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.

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

AGPL‑3.0 — see LICENSE for details.