mx

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

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.

Full documentation →

Installation

cargo install mx

Or from source:

cargo install --path .

Requires Rust 2024 edition. The binary is named mx.

Quick Start

Encoded Git 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.

# Stage all and commit with an encoded message
mx commit "fix session export crash on empty JSONL" -a

# Stage all, commit, and push
mx commit "add semantic search to memory" -a -p

# See what the encoding produces without committing
mx commit --encode-only --title "refactor store" --body "split surreal and sqlite backends"

Decoded Git Log

mx log has full parity with git log -- every display flag, format preset, and filter option works with transparent decoding.

# Last 10 commits, decoded (default)
mx log

# Last 3 commits (-N shorthand, like git log -3)
mx log -3

# One-line format with ref decorations
mx log --oneline

# Full details with diffstat
mx log -n 5 --full --stat

# Format presets: short, medium, full, fuller
mx log --format=fuller -3

# Filter by author, date, path
mx log --author="charlie" --since="1 week ago"
mx log -- src/handlers/

# Full patch output
mx log -p -3

Decoded Git Show

mx show is a drop-in replacement for git show that transparently decodes encoded commit messages. All git show flags work as expected.

# Show the latest commit, decoded
mx show

# Show a specific commit with diffstat
mx show abc1234 --stat

# Show just the commit message, no diff
mx show --no-patch

# View a file at a specific revision (passes through to git show)
mx show HEAD:src/main.rs

Knowledge / Memory

The memory system is a knowledge graph backed by SurrealDB (or embedded SurrealKV). Entries have categories, tags, resonance levels, embeddings, and relationships.

# Search knowledge entries
mx memory search "session bootstrap"

# Semantic (vector) search
mx memory search "how to handle state" --semantic

# Add a knowledge entry
mx memory add \
  --category pattern \
  --title "SurrealDB connection retry pattern" \
  --content "When the connection drops, use exponential backoff..." \
  --tags "surrealdb,reliability" \
  --source-agent smith

# Show a specific entry
mx memory show kn-abc123

# List entries filtered by category
mx memory list -c insight

# Statistics
mx memory stats

Default categories: pattern, technique, insight, gotcha, reference, decision, bloom, session. Categories are customizable per-deployment -- run mx memory categories list to see available categories.

KV Store

Fast local key-value state per agent. Counters, strings, lists, timestamped history, and structured state fields -- all backed by a TOML schema file and a JSON data file. No networking, no database.

# Basic operations
mx kv set session_goal "ship the docs"
mx kv inc builds
mx kv push decisions "chose Typst for docs"    # prints: kv-A3fB (1)
mx kv last decisions --count 5

# Batch set multiple state fields at once
mx kv set context goal="done" phase="writing"
mx kv set context --json '{"goal":"done","phase":"writing"}'
mx kv set mytensor --json '[0.4, 0.6, 0.5]'
echo '{"goal":"done"}' | mx kv set context --json -

# Auto-create a key in the schema and push in one step
mx kv push puns "the joke" --create history
mx kv push ideas "wild thought" --create list --max-entries 500

# Structured data on entries
mx kv push projects "palmtop DSI fix" \
  --data '{"tags":["palmtop","i915"],"status":"active"}'

# Query by structured data with --where
mx kv search projects --where status=active
mx kv search projects "DSI" --where status=active
mx kv search projects --where tags=palmtop --where status=active
mx kv last projects --where status=active --count 5
mx kv count projects --where status=active

# Time-range queries on history/list keys
mx kv last shipped --day 2026-04-25
mx kv last shipped --month 2026-04
mx kv last shipped --week 2026-W17
mx kv last shipped --from 2026-04-01 --to 2026-04-15
mx kv last shipped --since 1w
mx kv search shipped "feature" --month 2026-04
mx kv count shipped --day 2026-05-07

# Time range composes with --count (filter first, then limit)
mx kv last shipped --month 2026-04 --count 5

# Entry lookup by numeric index or entry ID
mx kv get shipped --id 35
mx kv get shipped --id kv-A3fB
mx kv get shipped --id 35-64
mx kv get shipped --id 1,kv-A3fB,12

# Remove by entry ID
mx kv remove shipped --id kv-A3fB

# Random sampling from history/list keys
mx kv random shipped --count 5
mx kv random ideas --count 1
mx kv random shipped --count 3 --since 30d

# Update an entry's value or structured data in-place
mx kv update projects "palmtop DSI fix (v2)" --id kv-A3fB
mx kv update projects --id 42 --data '{"status":"done"}'
mx kv update projects --id 42 --data '{"obsolete_field":null}'

# Migrate entries to match current schema data definitions
mx kv migrate projects --dry-run
mx kv migrate projects --prune

# Rename a key (preserves all entries, IDs, and data)
mx kv rename old_decisions archived_decisions

# Per-entry memory links (bridge KV entries to the knowledge graph)
mx kv push decisions "adopted memory links" --memory kn-abc123
mx kv set decisions --id 17 --memory kn-abc123
mx kv last decisions --count 3 --memory

# JSON output for scripting and jq piping
mx kv last projects --count 5 --json | jq '.[].data.status'
mx kv search projects --where status=active --json | jq 'map(.value)'
mx kv count shipped --json | jq '.count'

Every entry gets a stable entry ID (e.g. kv-A3fB) alongside its numeric index. Push prints both: kv-A3fB (42). Anywhere a numeric index works, an entry ID also works -- --id kv-A3fB, mixed comma lists, remove. Ranges remain numeric only. Old data files are back-filled on first load.

Entries can carry structured JSON data via --data on push or update. Query entries by data fields with --where key=value (available on search, last, random, count). Multiple --where flags are ANDed. Supports exact string match, array-contains, and numeric/boolean comparison on top-level fields.

Individual entries can link to the memory graph via --memory kn-xxx on push (at creation) or set --id --memory (on existing entries). Per-entry memory wins over key-level fallback. Pass --memory on read commands (get, last, since, search, random, dump) to resolve linked knowledge entries.

Time-range flags (--day, --month, --week, --since, --from/--to) are available on last, search, count, and random. All dates are UTC. The --since flag accepts relative times (30d, 1w, 2h, 30m) and ISO-8601 timestamps. For a standalone relative-time query on history keys, use mx kv since.

PR Merge

# Squash merge (default) with encoded commit message
mx pr merge 42

# Rebase merge
mx pr merge 42 --rebase

# Standard merge commit
mx pr merge 42 --merge-commit

Session Archival (Codex)

Archives Claude session JSONL files to permanent storage with transcripts, extracted images, and manifests.

# Archive the current session
mx codex archive

# Archive with clean markdown transcript only (no raw JSONL)
mx codex archive --clean

# Archive all unarchived sessions
mx codex archive --all

# List archived sessions
mx codex list

# Read an archived session
mx codex read <archive-id> --clean

# Search across all archives
mx codex search "memory migration"

GitHub Sync

Pull and push issues/discussions as local YAML files.

mx sync pull owner/repo
mx sync push owner/repo --dry-run
mx sync labels owner/repo

Configuration

Everything mx writes lives under a single base directory: $MX_HOME, default ~/.mx/. Each subsystem owns a subdirectory (kv/, state/, memory/, codex/, ...). Move the whole tree by setting MX_HOME, or override one subsystem at a time with vars like MX_SURREAL_ROOT, MX_CODEX_PATH, MX_KV_SCHEMA, MX_KV_DATA, MX_ISOLATE_MODELS.

Two env vars were removed in the path-alignment refactor (#259):

• MX_MEMORY_PATH -- use MX_SURREAL_ROOT instead. Setting the old name now emits a one-line stderr note and is otherwise ignored.
• MX_STATE_SCHEMA (deprecated) -- replaced by the mx state ... --schema {id|path} CLI flag. The default schema ID is now tensor (was crewu). Note: mx state itself is deprecated; use mx kv with structured data instead.

For the full layout, the complete env-var reference (including SurrealDB connection vars, GitHub App auth, and tuning), legacy-fallback behavior, and worked examples, see the filesystem layout.

Documentation

For the complete command reference, configuration guide, and architecture docs, see the full documentation.

Build Notes

tract-linalg and tract-data are patched via [patch.crates-io] in Cargo.toml to fix ARM64 NEON assembly compilation on aarch64-pc-windows-msvc. MSVC's cl.exe silently ignores GAS-syntax .S files (D9024/D9027, exit 0), producing no object files. The patch forces clang as the assembler for this target and excludes it from x86 MASM template transformations. The patch lives in coryzibell/tract; an upstream PR is pending.

Status

Published on crates.io. The API surface is evolving.

Licensed under Apache 2.0.