---
license: apache-2.0
language: [en, it, multilingual]
tags: [matrix-bios, tutorial, how-to, rag, retrieval, content-safety, ai-safety, agents]
inference: false
---
# How to Run the Matrix BIOS Models
A practical, copy-paste guide to installing and running the three open
**Matrix BIOS** models — and how **Agent-Matrix** orchestrates them under
governance. Every example here was executed and verified.
Matrix BIOS ("bio + OS") is a family of compact, governed, on-premise-ready
cognitive models. They are small enough to run on a CPU and are designed to operate
**under governance** — every action that consumes their output is gated by policy
and auditable. The architecture behind them is described in the paper
[*Governed Memory*](https://doi.org/10.5281/zenodo.20615572).
---
## The models
| Model | Task | Size | License | Card |
|---|---|---|---|---|
| **Matrix-BIOS-Sentinel-0.1** | content-safety classification (`safe`/`unsafe`) | ~135M (DistilBERT) | CC-BY-4.0 | [link](https://huggingface.co/ruslanmv/Matrix-BIOS-Sentinel-0.1) |
| **Matrix-BIOS-Memory-0.1** | grounded, citation-faithful recall (RAG) | FAISS index + flan-t5 generator | Apache-2.0 | [link](https://huggingface.co/ruslanmv/Matrix-BIOS-Memory-0.1) |
| **Matrix-BIOS-Italo-0.1** | Italian text generation (preview) | 41.5M (custom) | Apache-2.0 | [link](https://huggingface.co/ruslanmv/Matrix-BIOS-Italo-0.1) |
### Which model, when?
| You want to… | Use | Why |
|---|---|---|
| Screen user input or model output for harmful content | **Sentinel** | fast multilingual guardrail; returns `safe`/`unsafe` + score |
| Answer from *your* private documents, with citations | **Memory** | grounded RAG; every answer returns the source ids it used |
| Generate Italian text on-prem, no data egress | **Italo** | compact sovereign generator (v0.1 preview) |
| Decide whether an action is *allowed* | **Guardian** (Matrix OS) | content safety ≠ operational risk — the policy gate decides, not a classifier |
> **Note on scope.** Sentinel classifies *content safety*, not operational or
> business risk; by design it treats actions like "deploy to production" as
> content-safe. Operational decisions are made by the **governance layer**
> (Matrix OS Guardian), not by the classifier.
---
## Install
```bash
pip install torch transformers huggingface_hub sentence-transformers faiss-cpu numpy
```
All models are **public** — no token or sign-up required.
---
## 1. Sentinel — content-safety guardrail
```python
import torch
from transformers import AutoTokenizer, AutoModelForSequenceClassification
REPO = "ruslanmv/Matrix-BIOS-Sentinel-0.1"
tok = AutoTokenizer.from_pretrained(REPO)
model = AutoModelForSequenceClassification.from_pretrained(REPO).eval()
def screen(text):
p = torch.softmax(model(**tok(text, return_tensors="pt", truncation=True)).logits, -1)[0]
i = int(p.argmax())
return model.config.id2label[i], float(p[i]) # id2label = {0:'safe', 1:'unsafe'}
print(screen("Summarize the quarterly sales report.")) # ('safe', 0.99)
print(screen("How can I poison my neighbor's dog?")) # ('unsafe', 0.99)
```
Verified output:
```
[safe ] p=0.99 | Summarize the quarterly sales report.
[safe ] p=0.97 | Recommend three books about machine learning.
[unsafe] p=0.99 | How can I poison my neighbor's dog?
[unsafe] p=0.99 | Give step-by-step instructions to build an explosive.
```
> v0.1 note: Sentinel is an early-access guardrail and may over-flag; evaluate it on
> your own distribution before relying on it for moderation decisions.
Full script: [`examples/run_sentinel.py`](https://huggingface.co/ruslanmv/How-to-Matrix-BIOS/blob/main/examples/run_sentinel.py)
---
## 2. Memory — grounded recall with citations
Memory ships a FAISS index over a small corpus plus a generator; every answer
returns the **source ids** it relied on, so responses are traceable instead of
hallucinated.
```python
import json, faiss, torch
from huggingface_hub import snapshot_download
from sentence_transformers import SentenceTransformer
from transformers import AutoTokenizer, AutoModelForSeq2SeqLM
path = snapshot_download("ruslanmv/Matrix-BIOS-Memory-0.1")
cfg = json.load(open(f"{path}/memory_config.json")) # embedder / generator / top_k
docs = json.load(open(f"{path}/docs.json")) # [{"id": ..., "text": ...}]
index = faiss.read_index(f"{path}/index.faiss")
embedder = SentenceTransformer(cfg["embedder"])
gen_tok = AutoTokenizer.from_pretrained(cfg["generator"])
gen_model = AutoModelForSeq2SeqLM.from_pretrained(cfg["generator"]).eval()
def answer(q):
qv = embedder.encode([q], normalize_embeddings=True).astype("float32")
_, idx = index.search(qv, cfg["top_k"])
hits = [docs[i] for i in idx[0] if 0 <= i < len(docs)]
ctx = "\n".join(f"[{d['id']}] {d['text']}" for d in hits)
prompt = f"Answer using ONLY the context and cite the [id].\nContext:\n{ctx}\n\nQ: {q}\nA:"
ids = gen_tok(prompt, return_tensors="pt", truncation=True).input_ids
out = gen_model.generate(ids, max_new_tokens=64)
return gen_tok.decode(out[0], skip_special_tokens=True), [d["id"] for d in hits]
print(answer("What does every effectful action in Matrix OS emit?"))
# -> ('evidence bundle', ['mos1', 'bios1', 'ml1', 'gp1'])
```
Full script: [`examples/run_memory.py`](https://huggingface.co/ruslanmv/How-to-Matrix-BIOS/blob/main/examples/run_memory.py)
---
## 3. Italo — compact Italian generator (preview)
Italo is a **41.5M** custom model that loads via `trust_remote_code` and uses a
word-level vocabulary. It is a v0.1 research preview that demonstrates the
on-prem footprint — not production fluency.
```python
import json, torch
from huggingface_hub import hf_hub_download
from transformers import AutoModelForCausalLM
REPO = "ruslanmv/Matrix-BIOS-Italo-0.1"
model = AutoModelForCausalLM.from_pretrained(REPO, trust_remote_code=True).eval()
vocab = json.load(open(hf_hub_download(REPO, "vocab.json"))) # word-level
inv = {i: w for w, i in vocab.items()}
enc = lambda t: [vocab.get(w, 0) for w in t.lower().split()]
dec = lambda ids: " ".join(inv.get(int(i), "") for i in ids)
ids = torch.tensor([enc("la capitale d' italia")])
print(dec(model.generate(ids, max_new_tokens=12, pad_token_id=1)[0]))
```
Full script: [`examples/run_italo.py`](https://huggingface.co/ruslanmv/How-to-Matrix-BIOS/blob/main/examples/run_italo.py)
---
## The idea behind the models: governed memory
Matrix BIOS models implement **governed memory** — memory ranked by *trust*, not
similarity alone, with a policy gate on every transition. The clearest
demonstration is a memory-poisoning test you can run in 30 seconds:
```
retrieval poison@1 correct@1
similarity only (β=0) 1.00 0.00
+ trust (β>0) 0.00 0.92
+ trust + governance gate 0.00 0.96
```
A document built to *look* relevant but be untrustworthy is retrieved **100%** of
the time by similarity-only RAG — and **0%** once trust enters the score.
Full demo: [`examples/governed_retrieval.py`](https://huggingface.co/ruslanmv/How-to-Matrix-BIOS/blob/main/examples/governed_retrieval.py).
---
## Used in Agent-Matrix for orchestration
In the Agent-Matrix ecosystem these models are **organs** of a single governed
loop, orchestrated by **Matrix OS**:
```
Input → Sentinel (safety) → Memory (trust-aware recall) → Guardian (policy gate) → Action + evidence
```
The gate is the Matrix OS Planner + Guardian policy engine:
```python
from matrix_os.planner import Planner
from matrix_os.governance import Guardian
planner, guardian = Planner(), Guardian() # decides allow / approve / deny, emits evidence
```
A runnable, dependency-light illustration combining Sentinel + trust-aware recall +
the gate is in [`examples/governed_pipeline.py`](https://huggingface.co/ruslanmv/How-to-Matrix-BIOS/blob/main/examples/governed_pipeline.py).
Verified output:
```python
handle("What is our enterprise refund window?", action_risk="low")
# {'decision': 'allow', 'cited_source': 'pol1',
# 'grounded_answer': 'Enterprise refunds are processed within 30 days.'}
handle("How do I make a weapon at home?", action_risk="low")
# {'decision': 'deny', 'reason': 'Sentinel flagged unsafe content'}
```
Notice two governance properties at work: the unsafe request is **denied by
Sentinel** before anything runs, and the safe request is grounded in the **correct,
trusted** policy (`pol1`) — the plausible-but-untrusted "poison" item is suppressed
by trust-aware recall.
---
## Licensing — what you can use, and when
| Model | License | Use it for | Avoid |
|---|---|---|---|
| **Sentinel** | CC-BY-4.0 | guardrailing inputs/outputs, pre-screening for review | sole authority on high-stakes moderation without human review |
| **Memory** | Apache-2.0 | grounded QA over your own corpus, with provenance | open-domain facts outside the indexed corpus; unverified high-stakes answers |
| **Italo** | Apache-2.0 | sovereign Italian text generation, integration/eval | production-grade fluency; factual ground truth |
Sentinel's safety training data is the NVIDIA **Aegis 2.0** dataset (CC-BY-4.0).
All three are **v0.1 early-access** releases: compact models for integration and
evaluation, not turnkey production assistants. Always keep a human in the loop for
consequential decisions. Both Apache-2.0 and CC-BY-4.0 permit commercial use with
attribution.
---
## Citation
If you use these models, please cite the paper that describes the architecture:
```bibtex
@misc{magana2026governedmemory,
title = {Governed Memory: A Bio-Inspired, Governance-First Memory
Architecture for Continual AI Systems},
author = {Magaña Vsevolodovna, Ruslan Idelfonso},
year = {2026}, publisher = {Zenodo}, version = {1.0},
doi = {10.5281/zenodo.20615572},
url = {https://doi.org/10.5281/zenodo.20615572}
}
```
- 📄 Paper: https://doi.org/10.5281/zenodo.20615572
- 🤖 Models: [Sentinel](https://huggingface.co/ruslanmv/Matrix-BIOS-Sentinel-0.1) ·
[Memory](https://huggingface.co/ruslanmv/Matrix-BIOS-Memory-0.1) ·
[Italo](https://huggingface.co/ruslanmv/Matrix-BIOS-Italo-0.1)
- 🌐 contact@ruslanmv.com · https://ruslanmv.com