Mirix Documentation

MIRIX operates on a three-tier architecture designed for scalable multi-agent orchestration:

1. Client SDK (MirixClient): An external API wrapper used to interact with the system via HTTP/HTTPS.
2. REST API (FastAPI): Hosted on port 8531, it acts as the entry point for requests and provides a singleton get_server() instance.
3. AsyncServer: The core engine that handles method calls and orchestrates the MetaAgent and various specialized sub-agents (Core, Episodic, Semantic, etc.).

Use poetry run to execute the project's formatting, sorting, type checking, and linting tools to ensure your code adheres to the MIRIX standards. This ensures you are using the specific versions defined in the project's dependency management.

# Format code with Black
poetry run black .

# Sort imports with isort
poetry run isort .

# Type check with mypy
poetry run mypy mirix/

# Lint with Ruff
poetry run ruff check .

Use the clean_cache.py script to remove Python bytecode, testing artifacts, type checking caches, and distribution files. This is the recommended method as it is cross-platform (Windows, macOS, and Linux) and provides detailed statistics.

Run the script from the project root using python3 or make it executable to run it directly.

# From project root
python3 scripts/clean_cache.py

# Or make it executable and run directly
chmod +x scripts/clean_cache.py
./scripts/clean_cache.py

Mirix is distributed as two separate PyPI packages: mirix-client (a lightweight library) and mirix-server (the full server with agents, database, and LLM integrations). You can build both packages simultaneously using the automated build script, or build them individually using specific setup scripts.

Build both packages

Run the automated script from the project root or the packaging directory.

Build individual packages

Use setup_client.py for the client-only package or setup_server.py for the server-only package. Pass sdist bdist_wheel as arguments to generate distribution files.

The REST API supports two authentication methods:

1. API Key: Pass the key in the X-API-Key: <key> header. Best for programmatic client access.
2. Bearer JWT: Pass the token in the Authorization: Bearer <token> header. Used for dashboard sessions.

To identify specific clients or organizations, include the following headers:

• x-client-id: Identifies the client.
• x-org-id: Identifies the organization.

Execute the evaluation script using main_eval.py. You must specify a limit, enable LLM running, provide a configuration path, and define an output path.

Arguments:

• --limit: Number of evaluations to run.
• --run-llm: Flag to enable LLM execution.
• --mirix_config_path: Path to the MIRIX configuration YAML file.
• --output_path: Directory where results will be stored.

uv run python main_eval.py --limit 1 --run-llm --mirix_config_path ./configs/0201c.yaml --output_path results/0201c

To produce a lean mirix_client wheel, follow these steps from the repository root. Note that the version is fixed at 0.1.0 in mirix/__init__.py and scripts/packaging/setup_client.py, and client-only dependencies are defined in scripts/packaging/requirements_client.txt.

1. (Optional) Move the project-level pyproject.toml to prevent PEP 621 metadata from overriding the client setup script: Move-Item pyproject.toml pyproject.toml.backup_client
2. Clean previous build artifacts: Remove-Item -Recurse -Force build, dist, mirix_client.egg-info
3. Build the client package: python scripts/packaging/setup_client.py sdist bdist_wheel
4. Restore pyproject.toml if it was moved: Move-Item pyproject.toml.backup_client pyproject.toml

Output artifacts (the .whl and .tar.gz files) will be located in the dist/ directory.

After the evaluation is complete, use organize_results.py to process the output directory. This will generate a metrics.json file within the specified output path containing all evaluation metrics.

uv run organize_results.py results/0201c

To integrate with a production Event Bus requiring JSON messages and mTLS authentication, export the following environment variables, providing the paths to your SSL certificates:

export QUEUE_TYPE=kafka
export KAFKA_BOOTSTRAP_SERVERS=broker1:9094,broker2:9094
export KAFKA_SERIALIZATION_FORMAT=json
export KAFKA_SECURITY_PROTOCOL=SSL
export KAFKA_SSL_CAFILE=/tmp/ca.pem
export KAFKA_SSL_CERTFILE=/tmp/cert.pem
export KAFKA_SSL_KEYFILE=/tmp/key.pem

For Unix-like systems (Linux, macOS), you can use the clean_cache.sh script for fast execution. Run it from the project root using bash or execute it directly if permissions allow.

# From project root
./scripts/clean_cache.sh

# Or
bash scripts/clean_cache.sh

To prepare the environment for running MIRIX evaluations, install uv using Homebrew, create a virtual environment, and install the required dependencies.

1. Install uv: brew install uv
2. Create and activate the virtual environment.
3. Upgrade pip and install requirements from requirements.txt.

brew install uv
uv venv
source .venv/bin/activate # on windows, use `.\.venv\Scripts\Activate.ps1`
python -m ensurepip --upgrade
python -m pip install -r requirements.txt

To ensure no cache files are accidentally committed, you can automate the cleanup by adding it to your .git/hooks/pre-commit file.

# .git/hooks/pre-commit
#!/bin/bash
python3 scripts/clean_cache.py