# sol

a virtual librarian for Matrix. sol lives in your chat rooms, archives conversations in OpenSearch, and responds with the help of Mistral AI — with end-to-end encryption, tool use, and per-user memory.

sol is built by [sunbeam studios](https://sunbeam.pt) as part of our self-hosted collaboration stack.

## what sol does

- **Matrix presence** — joins rooms, reads the vibe, decides when to speak. direct messages always get a response; in group rooms, sol evaluates relevance before jumping in.
- **message archive** — every message is indexed in OpenSearch with full-text and semantic search. sol can search its own archive via tools.
- **tool use** — mistral calls tools mid-conversation: archive search, room context retrieval, and a sandboxed TypeScript/JavaScript runtime (deno_core) for computation.
- **per-user memory** — sol remembers things about the people it talks to. memories are extracted automatically after conversations (via ministral-3b), injected into the system prompt before responding, and accessible from scripts via `sol.memory.get/set`. user isolation is enforced at the rust level.
- **reactions** — sol can react to messages with emoji when it has something to express but not enough to say.
- **E2EE** — full end-to-end encryption via matrix-sdk with sqlite state store.

## architecture

```
src/
├── main.rs              entrypoint, Matrix client setup, backfill
├── sync.rs              event loop — messages, reactions, redactions, invites
├── config.rs            TOML config with serde defaults
├── context.rs           ResponseContext — per-message sender identity
├── matrix_utils.rs      message extraction, reply detection, room info
├── archive/
│   ├── schema.rs        ArchiveDocument, OpenSearch index mapping
│   └── indexer.rs       batched indexing, reactions, edits, redactions
├── brain/
│   ├── conversation.rs  sliding-window context per room
│   ├── evaluator.rs     engagement decision (must/maybe/react/ignore)
│   ├── personality.rs   system prompt templating
│   └── responder.rs     Mistral chat loop with tool iterations + memory
├── memory/
│   ├── schema.rs        MemoryDocument, index mapping
│   ├── store.rs         query, get_recent, set — OpenSearch operations
│   └── extractor.rs     post-response fact extraction via ministral-3b
└── tools/
    ├── mod.rs           ToolRegistry, tool definitions, dispatch
    ├── search.rs        archive search (keyword + semantic)
    ├── room_history.rs  context around a timestamp or event
    ├── room_info.rs     room listing, member queries
    └── script.rs        deno_core sandbox with sol.* API
```

## dependencies

sol talks to three external services:

- **Matrix homeserver** — [tuwunel](https://github.com/tulir/tuwunel) (or any Matrix server)
- **OpenSearch** — message archive + user memory indices
- **Mistral AI** — response generation, engagement evaluation, memory extraction

## configuration

sol reads config from `SOL_CONFIG` (default: `/etc/sol/sol.toml`) and the system prompt from `SOL_SYSTEM_PROMPT` (default: `/etc/sol/system_prompt.md`).

secrets via environment:

| Variable | Description |
|----------|-------------|
| `SOL_MATRIX_ACCESS_TOKEN` | Matrix access token |
| `SOL_MATRIX_DEVICE_ID` | Matrix device ID (for E2EE) |
| `SOL_MISTRAL_API_KEY` | Mistral API key |

see `config/sol.toml` for the full config reference with defaults.

## building

```sh
cargo build --release
```

docker (cross-compile to x86_64 linux):

```sh
docker build -t sol .
```

## running

```sh
export SOL_MATRIX_ACCESS_TOKEN="..."
export SOL_MATRIX_DEVICE_ID="..."
export SOL_MISTRAL_API_KEY="..."
export SOL_CONFIG="config/sol.toml"
export SOL_SYSTEM_PROMPT="config/system_prompt.md"

cargo run --release
```

## tests

```sh
cargo test
```

80 unit tests covering config parsing, conversation windowing, engagement rules, personality templating, memory schema/store/extraction, search query building, TypeScript transpilation, and sandbox path isolation.

## license

[MIT](LICENSE)