# Merovingian: Exploiting cause and effect in the matrix.org protocol

> You see, there is only one constant, one universal.  It is the only real
> truth.  Causality.  Action, reaction.  Cause and effect.
>
> \- The Merovingian, *The Matrix Reloaded*

Merovingian is a protocol for connecting bots together via Matrix rooms so that
they can communicate with each other to produce useful results.  By defining a
common protocol, users are able to combine different bots together easily and
flexibly to produce their desired result.

```{warning}
Merovingian is a work in progress, and is subject to change.
```

Four types of actors, represented by Matrix accounts, interact in Merovingian:

<dl>
<dt>causes</dt><dd>represent something that happens</dd>
<dt>effects</dt><dd>represent a result of, or response to, a cause</dd>
<dt>filters</dt><dd>extend the matching capabilities of effects</dd>
<!--dt>adapters</dt><dd>allow Matrix events that do not fit the expected format to
still be used</dd-->
</dl>

For example, a cause could be an RSS feed, a web hook, a git hook, sensor data,
system monitoring, etc.  An effect could be making an HTTP call, running a
program, sending an email, turning a device on or off, etc.

A single Matrix account can also take on more than one of these roles at the
same time.  For example, an effect may send a file in response to a message
from a cause.  If another effect reacts to that file, then the original effect
is also a cause.

Merovingian defines how events sent from causes should be formatted, and how
effects determine which events they should react to, using a pattern-matching
mechanism.  Since there may be situations in which a simple pattern may not be
sufficient to give the criteria for matching events, filters may be used to
extend the expressiveness of the matching arbitrarily.  Filters can encapsulate
the complexity of event matching so that effects do not need to be modified in
order to react to complex conditions.

```{toctree}
---
maxdepth: 2
caption: "Contents:"
---
cause
effect
filter
config
```


## Indices and tables

* {ref}`genindex`
* {ref}`modindex`
* {ref}`search`