Getting started

mnesio is a Rust workspace. The fastest way to see it running is Docker (no toolchain) or a single make target; building from source is the third option. Every path lands you on the same live dashboard at http://localhost:7777.

Fastest — no Rust toolchain (Docker)

Builds and runs the server in a container and serves the live dashboard with zero external downloads on first boot (mock embedder + synthetic writer):

git clone https://github.com/mnesio/mnesio.git && cd mnesio
docker compose up --build

Open http://localhost:7777. For real, persistent use, set MNESIO_DEMO=0 and MNESIO_EMBEDDER=fastembed in docker-compose.yml (fastembed downloads bge-small-en-v1.5 on first run; the log persists in the mnesio-data volume).

With Rust installed — one word

git clone https://github.com/mnesio/mnesio.git && cd mnesio
make demo     # instant demo: live dashboard, zero downloads (mock embedder + learning curve)

Other targets (make on its own lists them all):

Target	What it does
make demo	Instant demo — mock embedder, synthetic writer, live procedural learning curve
make run	Real server — persistent log + fastembed embeddings
make test	The workspace test suite
make lint	Exactly what CI enforces (fmt --check + clippy -D warnings)
make mcp	Install the MCP binary for Claude Desktop / Cursor / any MCP client
make docker	The Docker path above

From source

1. Prerequisites: Rust (stable, 1.75+, via rustup) and a C toolchain (for native deps like tantivy and hnsw_rs).

2. Clone and build the workspace:

   git clone https://github.com/mnesio/mnesio.git
   cd mnesio
   cargo build --release

3. Run the tests and lint exactly as CI does:

   cargo test
   cargo fmt --check
   cargo clippy -- -D warnings

Run the server + dashboard

The host process (mnesio-server, binary name mnesio) exposes an HTTP API and a live dashboard.

# Real embeddings (fastembed, 384-d) — downloads bge-small on first run:
cargo run --release -p mnesio-server

# Or offline/instant with the deterministic mock embedder (no download):
MNESIO_EMBEDDER=mock cargo run --release -p mnesio-server

Open http://localhost:7777. The dashboard surfaces live panels for retrieval metrics, memory evolution, the procedural learning curve, and each frontier phase (causal, probe, KV, exchange, dream, provenance).

Tip

Add MNESIO_DEMO=1 for a fresh temp data dir plus a synthetic writer, and MNESIO_PROCEDURAL=on to spawn the procedural compiler worker. The default build uses deterministic stand-ins so everything runs offline; point the LLM-backed features at a running Ollama with MNESIO_EVOLVE_LLM=ollama.

Key environment variables

Env var	Default	Meaning
MNESIO_PORT	7777	HTTP listen port
MNESIO_HOST	127.0.0.1	Bind address; the Docker image sets 0.0.0.0
MNESIO_DATA	./mnesio-data	Path to the fjall keyspace
MNESIO_EMBEDDER	fastembed	mock for the 32-d deterministic embedder (no download)
MNESIO_DEMO	0	1 → temp data dir + synthetic writer
MNESIO_PROCEDURAL	off	on → spawn the procedural compiler worker

Storage layout

mnesio persists to a single append-only event log (fjall-backed) plus its materialized views. By default it lives under ./mnesio-data. Because the log is the single system of record, every index is rebuildable by replaying events — deleting a view directory and restarting reconstructs it.

Optional: heavier feature flags

Local LLM

# route evolution / procedural / qaeval through a local Ollama model
cargo run --release -p mnesio-server --features ollama

Real crypto

# ChaCha20-Poly1305 keyring + ed25519 skill certificates
cargo run --release -p mnesio-server --features aead,ed25519

GPU KV

# candle/Metal GPU backend for KV cartridges (also needs MNESIO_KV_GPU=1)
MNESIO_KV_GPU=1 cargo run --release -p mnesio-server --features candle-kv,metal

Next: wire it into an agent with the MCP quickstart.