Skip to content
Memtru
Documentation menu
Getting started

Quickstart

Memtru runs reproducible tests against the memory system behind an AI agent: cross-user and cross-tenant isolation, deletion visibility, stale memory, session boundaries and update integrity. This guide gets you from nothing to a report in a few minutes. No account is needed.

Requirements

  • Python 3.11 or newer
  • A clone of this repository (the package is not published to PyPI yet)

Install

python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

pip install memtru
memtru version

Create a configuration

memtru init --project my-agent

This writes memtru.yaml, validated before it is saved. It uses the built-in in_memory adapter, a correct reference store, so the first run should pass.

Check the setup

memtru doctor

doctor checks the Python version, the configuration, whether the adapter can be built, its capabilities, and whether the report directory is writable. It never prints secrets.

Run the tests

memtru test

You get one line per scenario, a summary, and two report files:

  • .memtru/reports/<run-id>.json: machine-readable, schema 1.0
  • .memtru/reports/<run-id>.html: a self-contained report you can open in any browser

latest.json and latest.html always point at the most recent run.

See a failure

The built-in store can simulate specific bugs. Edit memtru.yaml:

adapter:
  type: in_memory
  faults: [ignore_user_scope]

Run memtru test again. MT-ISO-001 Cross-user isolation now fails, the command exits with code 1, and the HTML report shows the finding with its evidence, reproduction steps and suggested remediation.

Or run both stores back to back:

memtru demo

Understand the output

Every scenario ends in exactly one status:

Status Meaning
PASS Every required assertion held for this adapter and configuration.
FAIL A defined assertion was violated. A finding is created.
INCONCLUSIVE Not enough evidence for a verdict, usually because the positive control failed.
ERROR The scenario could not complete (provider error, timeout).
SKIPPED The adapter lacks a required capability. Never counted as a pass.

A PASS means the listed assertions held in this configuration. It is not a guarantee that the system is secure.

Next steps