# Lisa

Lisa is a Rust Matrix bot. It durably ingests allowed-room mentions and
replies, sends a bounded recent context to an OpenAI-compatible self-hosted
LLM, and persists the exact rich reply before Matrix delivery. It can search
through a fixed SearXNG endpoint, fetch bounded HTTP(S) pages, convert HTML
using Pandoc, and append only host-validated source links.

## Run

1. Copy `config.example.toml` to a protected location and set the Matrix
   identifiers and allowed room IDs.
2. Copy `persona.example.md` to the configured `persona.path` and edit it.
3. Set `LISA_MATRIX_PASSWORD` and `LISA_LLM_API_KEY` in the service
   environment. Lisa requests and refreshes its own Matrix access tokens.
4. Create the parent directories for `database_path` and `matrix_store_path`
   with read/write access for the service account.
5. Run `cargo run -- --config /etc/lisa/config.toml`.

On first startup Lisa records a Matrix sync baseline and ignores its timeline.
Later sync events are recorded in SQLite before the sync cursor advances.
Persisted replies are retried with the same transaction ID after a restart.
Lisa keeps room work serial while allowing configured cross-room concurrency,
and displays a refreshed Matrix typing notice while an LLM response is pending.

`pandoc` must be installed on the host. Page content is held only in memory for
the current invocation; it never receives Matrix, LLM, or search credentials.

See [operations guidance](docs/operations.md) for systemd, health checks,
shutdown, backup, and upgrade procedures.