# 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 →](https://coryzibell.github.io/mx/)**
## Installation
```bash
cargo install mx
```
Or from source:
```bash
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](https://crates.io/crates/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`.
```bash
# 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.
```bash
# 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.
```bash
# 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.
```bash
# 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.
```bash
# 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]'
# 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 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
```bash
# 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.
```bash
# 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.
```bash
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](https://coryzibell.github.io/mx/paths.html)**.
## Documentation
For the complete command reference, configuration guide, and architecture docs, see the [full documentation](https://coryzibell.github.io/mx/).
## 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](https://github.com/coryzibell/tract/tree/fix/aarch64-msvc-asm); an upstream PR is pending.
## Status
Published on [crates.io](https://crates.io/crates/mx). The API surface is evolving.
Licensed under [Apache 2.0](LICENSE).