mx docs
GitHub

mx

A Swiss army knife for Claude Code and multi-agent toolkits.

mx is a Rust CLI providing encoded git operations, a SurrealDB-backed knowledge graph, session archival, GitHub sync, and emotional state tensors. Designed for use with Claude Code, but works with any multi-agent workflow that needs persistent memory, encoded commits, or session management.

Quick links

  • Getting Started – install mx and make your first encoded commit

  • Commit – encoded git commits

  • Log – decoded git log

  • Memory – knowledge graph operations

  • Codex – session archival

  • KV – local key-value store

  • State – emotional state tensors (deprecated)

  • Sync – GitHub sync

  • PR – pull request merge

  • GitHub – GitHub operations

  • Convert – conversion utilities

Features

Encoded commits

mx commit wraps git commit but encodes the message using base-d. The commit title is hashed and the body is compressed, each encoded through a randomly selected dictionary. The result looks like hieroglyphs in git log but decodes cleanly with mx log.

mx commit "fix session export crash on empty JSONL" -a
mx log

Knowledge graph

The memory system is a knowledge graph backed by SurrealDB (embedded SurrealKV or network WebSocket). The schema is applied automatically on every connection in both modes. Entries have categories, tags, resonance levels, embeddings, and relationships.

mx memory search "session bootstrap"
mx memory search "how to handle state" --semantic
mx memory add --category pattern --title "Retry pattern" \
  --content "Use exponential backoff..." --tags "reliability"

Session archival

The codex archives Claude session JSONL files to permanent storage with transcripts, extracted images, and manifests.

mx codex archive
mx codex list
mx codex read <archive-id> --clean

Local key-value store

KV provides fast per-agent state: counters, strings, lists, and history with time-based queries and structured data filtering.

mx kv set session.goal "ship the docs"
mx kv get session.goal
mx kv push decisions "chose Typst over markdown"  # prints: kv-A3fB (1)
mx kv get shipped --id kv-A3fB
mx kv get shipped --id 35-64
mx kv push puns "the joke" --create history        # auto-adds key to schema
mx kv push projects "palmtop DSI fix" \
  --data '{"tags":["palmtop","i915"],"status":"active"}'
mx kv search projects --where status=active
mx kv push decisions "adopted memory links" --memory kn-abc123
mx kv set decisions --id 17 --memory kn-abc123
mx kv last projects --count 5 --json | jq '.[].data.status'

Installation

From crates.io:

cargo install mx

Or from source:

git clone https://github.com/coryzibell/mx.git
cd mx
cargo install --path .

Requires Rust 2024 edition.

Configuration

Everything mx writes lives under a single base directory: $MX_HOME, which defaults to ~/.mx/. See Filesystem Layout for the full reference.

Start here

New to mx? Start with Getting Started for a hands-on walkthrough of installation, your first encoded commit, and a tour of the subsystems.