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.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ollamarama_matrix-1.6.1.tar.gz (65.4 kB view details)

Uploaded Jul 6, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

ollamarama_matrix-1.6.1-py3-none-any.whl (62.4 kB view details)

Uploaded Jul 6, 2026 Python 3

File details

Details for the file ollamarama_matrix-1.6.1.tar.gz.

File metadata

Download URL: ollamarama_matrix-1.6.1.tar.gz
Upload date: Jul 6, 2026
Size: 65.4 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for ollamarama_matrix-1.6.1.tar.gz
Algorithm	Hash digest
SHA256	`95040d552842da762a4cbe2ce3ad089fc8cb0cc5ca30e4d318875e7033844614`
MD5	`a815c003a62d0125d86332c77ac1eaac`
BLAKE2b-256	`8851227a3164693bfadd7b4131532594c593d4551ae35d8bbe9548c6b8ac675b`

See more details on using hashes here.

Provenance

The following attestation bundles were made for ollamarama_matrix-1.6.1.tar.gz:

Publisher: pypi-publish.yml on h1ddenpr0cess20/ollamarama-matrix

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: ollamarama_matrix-1.6.1.tar.gz
- Subject digest: 95040d552842da762a4cbe2ce3ad089fc8cb0cc5ca30e4d318875e7033844614
- Sigstore transparency entry: 2084916581
- Sigstore integration time: Jul 6, 2026
Source repository:
- Permalink: h1ddenpr0cess20/ollamarama-matrix@c3dc71f8667c90bb3e2706973130a7d6d65e1a50
- Branch / Tag: refs/tags/v1.6.1
- Owner: https://github.com/h1ddenpr0cess20
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: pypi-publish.yml@c3dc71f8667c90bb3e2706973130a7d6d65e1a50
- Trigger Event: release