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

# 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.

Status

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

Licensed under Apache 2.0.