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 (or embedded SurrealKV). 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.