Mazu
A local coding agent with persistent project memory, rollback, cost limits, and a built-in way to measure itself.
Mazu is alpha software. It runs entirely on your machine, works with Anthropic, OpenAI, DeepSeek, Gemini, or a local OpenAI-compatible server, and keeps its own state in a .mazu/ folder inside your project. This README tries to say plainly what works, what has been measured, and what has not — see Measured so far and Known limitations.
███╗ ███╗
████╗ ████║ A Z U
██╔████╔██║ ══════════════════════════════
██║╚██╔╝██║ memory-augmented coding agent
██║ ╚═╝ ██║ persistent memory · checkpoints · skills · multi-model
╚═╝ ╚═╝
What Mazu does
- Chat or run unattended.
mazu chatis an interactive agent that can read and edit files and run shell commands, asking before anything destructive.mazu run "task"does the same in a loop without you, with step and cost limits. - Remembers a project across sessions. Decisions, conventions, and mistakes are stored in a local SQLite database, ranked against your current task with local BM25 (optionally blended with embeddings), and injected back into context. Facts about you live in a separate global store that follows you into every project.
- Checkpoints code, memory, and conversation together. Each step of a run snapshots a git commit, a consistent copy of the memory database, the skill library, and the transcript.
mazu rollbackrestores them;mazu timelineandmazu checkpoint diffshow what changed first. - Bounds spend.
--max-costonmazu chatandmazu runcounts the whole session's estimated spend — the main loop, context compaction, and memory extraction — andmazu usagetotals it across projects. - Measures itself.
mazu benchreplays a fixed task suite several times under different configurations and reports pass rate with confidence intervals and cost per solved task, so a change to the agent can be judged on numbers instead of impressions. - Tries more than one way.
mazu exploreruns the same task on several models in parallel in isolated git worktrees and ranks the results (optionally by your test suite);mazu councilasks several models the same read-only question and has a lead model synthesize an answer.
Mazu is not an IDE and does not try to out-polish editor-integrated agents. Its focus is the layer around the model: what the agent remembers, what it did, whether you can undo it, and what it cost.
Measured so far
Mazu ships with a benchmark built from its own history, in bench/mazu_history: five real bugs that were fixed in this repository, each checked out at the commit before its fix, described to the agent by symptom only, and judged by the regression tests the real fix added. Those tests are kept outside the clone and copied in only after the agent finishes, so the agent cannot see or edit them. --check proves every task is fair without calling a model: the unfixed commit must fail its test and the real fix must pass it.
First baseline, deepseek:deepseek-chat, 3 repeats per task (15 trials), judged only by the hidden tests:
| Result | |
|---|---|
| Pass rate | 10 / 15 = 67% (95% Wilson interval 42%–85%) |
| Mean cost per trial | about $0.035 |
| Cost per solved task | about $0.052 |
Per task, three tasks passed 3/3, one passed 1/3 (in the failing runs the agent changed an existing test to fit its own fix), and one passed 0/3. Most runs used the whole 25-step budget even when they passed.
What this does not show: it is a small suite from one repository, and Mazu has not been compared head-to-head with any other coding agent or with a more expensive model on the same tasks. Treat the numbers as a baseline for measuring changes, not as a ranking.
Install
Requires Python 3.11+ and git (used for checkpoints).
pip install mazu
pip install "mazu[openai]" # openai:* and deepseek:* models
pip install "mazu[gemini]" # gemini:* models
pip install "mazu[ui]" # terminal UI (mazu ui)
pip install "mazu[documents]" # .docx/.pdf/.xlsx/.pptx extraction (used by mazu-web)
From source: git clone https://github.com/turgutino/Mazu.git && cd Mazu && pip install -e ".[openai]".
Set at least one provider key (Mazu uses whichever is present), or run the wizard:
export DEEPSEEK_API_KEY=... # or ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY
mazu setup # guided: pick a provider, store the key in ~/.mazu/config.toml
mazu doctor # diagnose setup problems (add --live to test keys, --fix for safe fixes)
Quick start
cd your-project/
mazu init
mazu chat
> we use PostgreSQL for this project, not SQLite. remember that.
[remember] saved (decision): use PostgreSQL, not SQLite
> /checkpoint
[checkpoint] cp_000001 saved (commit 4f2a91c)
In a later session the agent already has that decision in context. For an end-to-end example — an agent breaks a test, mazu timeline and mazu checkpoint diff show what, mazu rollback undoes it — see docs/demo.md.
In mazu chat: /checkpoint snapshots now, /rollback [id] restores, /compact compacts the conversation, /auto toggles auto-approval of destructive tools.
Commands
Agent
| Command | Purpose |
|---|---|
mazu chat |
Interactive session. --model, --max-cost USD, --shell-allowlist, --auto-approve, --resume ID, --list, --delete ID |
mazu run "task" |
Unattended multi-step run. --max-steps (default 15), --max-cost USD, --allow-shell, --shell-allowlist, --dry-run, --checkpoint-every, --keep-checkpoints, --model, --auto-commit-baseline |
mazu run --resume ID |
Continue a stopped run from its last checkpoint |
mazu run --from-checkpoint CP --branch NAME "task" |
Start a divergent run on a new git branch from a checkpoint |
mazu runs |
List recent runs: status, stop reason, steps |
mazu explore "task" |
Same task on N models in parallel git worktrees, ranked (--models or --auto-models, --test-command, --max-cost shared across branches). Never auto-merges. |
mazu council "question" |
Ask several models the same read-only question; a lead model synthesizes |
mazu run refuses to start on a dirty working tree (unless --auto-commit-baseline or --dry-run) so the first checkpoint is a clean baseline. --dry-run runs the model for real but reports file writes and shell commands instead of executing them.
Checkpoints
mazu checkpoint # snapshot now
mazu checkpoint list | show ID | diff ID | inspect ID --memory | compare A B | prune --keep 20
mazu checkpoint compare-branches RUN_A RUN_B
mazu timeline # what changed at each checkpoint
mazu rollback [ID] # restore code + memory + skills + conversation
mazu branch-from ID NAME # new git branch at a checkpoint, nothing else touched
A checkpoint is a git commit, an online-backup copy of memory.db, a copy of the skills folder, and the conversation. See Known limitations for how restore behaves if it is interrupted.
Memory
mazu memory list [--category C] [--global]
mazu memory why "query" # what would be retrieved for this query, and why
mazu memory pin ID | unpin ID | edit ID | forget ID | supersede OLD NEW
mazu memory consolidate --dry-run # preview near-duplicate merging, then run without --dry-run
mazu memory stale [--auto] # find (or archive) memories that look stale
mazu memory stats
Categories: decision, convention, mistake, task_outcome, fact (project) and user_preference (global). Memories are written two ways: explicitly when the agent calls remember, and by a cheap end-of-session extraction pass (at most 5 per session, de-duplicated against existing entries by title and word overlap). At most 15 memories and about 8,000 characters are injected per session; pinned memories and the three most recent mistakes are always included.
Optional semantic search (MAZU_SEMANTIC_MEMORY=1, needs an OpenAI key for embeddings) blends BM25 with cosine similarity 50/50; off by default.
mazu memory-belief stats | review exposes an observation-only log of memory-contradiction decisions. It never changes memory.
Skills, router, curator
- Skills (
mazu skills list | forget | unarchive): the agent can save a reusable Python function and run it later without a model call. See the safety notes below before relying on this. - Router (
mazu router stats): aftermazu exploreruns, Mazu can print a passive model suggestion based on your own project's results. It never changes which model runs. Disable withmazu config set router_suggestions false. - Curator (
mazu curator setup | run | status | log | undo | enable | disable): an opt-in maintenance pass over Mazu's own memory and skills using its own separate API key. Inert until configured; every change is logged and reversible.
Cost, logs, diagnostics
mazu usage [--since-days 7] # estimated spend by model, all projects (~/.mazu/usage.db)
mazu models # known models: streaming, tools, context window, approximate price
mazu log | log show SESSION # every tool call the agent made, including blocked and declined ones
mazu doctor [--live] [--fix]
mazu config set|unset|list # ~/.mazu/config.toml; environment variables always win
mazu ui # terminal UI over checkpoints, memory, and the action log
mazu timeline, memory list, log, runs, and models accept --json. Costs are estimates from a built-in price table (mazu/llm/pricing.py) that can lag behind provider pricing; a model without a known price is reported as unpriced rather than counted as free, and --max-cost cannot be enforced for it.
Benchmarking your own changes
python bench/mazu_history/build_suite.py --out ./bench-work/mazu-history --check # no model calls
mazu bench run --suite bench-work/mazu-history/suite.json --configs configs.json --repeats 3 --out results.jsonl
mazu bench report results.jsonl
configs.json is a list such as [{"name": "baseline", "model": "deepseek:deepseek-chat", "extra_args": ["--max-cost", "0.60"]}]. Each trial runs in a fresh git clone with a throwaway home directory (your real ~/.mazu is untouched; API-key config is copied in), the agent runs with shell commands allowed inside that clone, and pass/fail comes from the task's verify command, never from the agent's own claim. mazu bench run makes real, billed model calls. Results are an append-only file, so an interrupted run resumes. Configs are interleaved per task so provider drift affects all of them alike. The report shows pass rate with a Wilson 95% interval and says when intervals overlap — with few repeats an apparent gap is usually not evidence of a real difference.
A second, easier suite of eight seeded bugs is in bench/seeded_bugs.
Models
Models are named provider:model, for example deepseek:deepseek-chat, openai:gpt-5, anthropic:claude-sonnet-5, gemini:gemini-2.0-flash. Without --model, Mazu uses MAZU_MODEL, then default_model from mazu config, then whichever provider key is set. mazu models lists what Mazu knows about; names and prices there can go stale, and models newer than the table appear as unpriced.
local:<model-name> points at any OpenAI-compatible server on your machine (LM Studio by default at http://localhost:1234/v1; set local_base_url for Ollama or others). It is never auto-selected. Smaller local models are noticeably weaker on multi-file tasks.
mazu config set reasoning_effort low|medium|high controls reasoning effort for providers that support it; others accept and ignore it.
Safety model
What Mazu does:
- File tools are confined to the project root, including through symlinks.
- Destructive tool calls ask for confirmation in
mazu chat. Inmazu run, shell commands ask unless--allow-shellis passed; file edits proceed because checkpoints make them recoverable. - A hardcoded denylist blocks a short list of patterns:
rm -rf /,git push --force, paths under.ssh/,sudo, andformat X:. Every block says why. --dry-runpreviews a task without writing or executing.- API keys are read from the environment or
~/.mazu/config.toml(in your home folder, outside any project) and shown masked. Mazu adds.mazu/to your project's.gitignore; it does not touch.envfiles, so keep those out of version control yourself.
What it does not do — read this before using --allow-shell or unattended runs:
- The denylist is a backstop, not a sandbox. It matches a few exact patterns and is easily bypassed by equivalent commands (for example
rm -rf ~,git push -f,su, PowerShell deletes, or a Python one-liner). Run unattended agents in a disposable directory or container. --shell-allowlistonly checks how a command starts. A compound command such asgit status; something-elsepasses an allowlist ofgit.- Skills are arbitrary Python run as a subprocess with Mazu's privileges and environment, with no isolation. In
mazu run,--allow-shellgovernsrun_shellonly; saved skills are executed without a confirmation prompt (inmazu chatthey do ask). This is a known gap. - Checkpoints undo file and memory changes. They cannot undo an external action such as a push or a network request.
See SECURITY.md for the policy and how to report a vulnerability.
Known limitations
- No verification step. The agent decides for itself when it is done, and nothing re-runs your tests before it stops. In the baseline above, an agent twice edited an existing test to fit its change.
- Rollback is not atomic.
restoreresets git, then restores memory, skills, and the index in sequence. If it is interrupted midway, code may be rolled back while memory or the index is not. There is no fault-injection test for this yet. - Memory is not verified. Auto-extracted memories are injected into the prompt as established context, with no trust level. Contradictions between memories are detected in shadow mode only (logged, never acted on), so a wrong remembered fact can persist until you edit or forget it. Auto-extraction keeps short summaries, not the raw conversation. Memory quality has not been benchmarked.
- Memory growth is manual to clean up. At most 5 memories are added per session and the prompt block is bounded, but the database itself only shrinks through
consolidate,stale,forget, or Curator. - Small evidence base. The benchmark covers five bugs from one repository, with one model, and no comparison against other agents. Context compaction and memory extraction are not exercised by those short tasks.
- Platforms. Live testing has mostly been on Windows. CI runs the test suite (about 1,100 tests, no API cost by default) on Linux, Windows, and macOS across Python 3.11–3.13. Gemini is implemented but has not been exercised in recent live tests and does not stream.
- Rollback is linear; branching exists (
--from-checkpoint,compare-branches) but there is no merge or graph view.
The build plan is in ROADMAP.md, version history in CHANGELOG.md, and module-level design in ARCHITECTURE.md.
Web UI
mazu-web is a separate companion package with the same operations in a browser (chat, run, explore, council, checkpoints, memory, skills, usage, doctor, config), plus image and document attachments.
pip install mazu-web
cd your-project && mazu-web # http://127.0.0.1:8765
Its chat tab keeps its own copy of the chat loop, so it does not yet have mazu chat --max-cost or the final session total described above; its Run, Explore, and Council tabs share the same code as the terminal.
Contributing
Issues and pull requests are welcome — see CONTRIBUTING.md.
License
MIT — see LICENSE. Copyright (c) 2026 Turgut Sofuyev.
Metadata
Release files for mazu 0.25.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mazu-0.25.2.tar.gz | 381.2 kB | Without provenance | Details for mazu-0.25.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mazu-0.25.2-py3-none-any.whl | Python 3 | none | any | Details for mazu-0.25.2-py3-none-any.whl |
Total release size: 621.5 kB
Release files / mazu-0.25.2.tar.gz
| Download URL | mazu-0.25.2.tar.gz |
|---|---|
| Size | 381.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
41a072f7055101d000e6d240c9b077bb408fcef5ac774d32502e3d2e1f6aaee4
|
|
BLAKE2b-256 checksum How to use checksums |
ee28f78bb2e769afa27476c99e3fdd962ebff84711767b7baf10141d885fdb69
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.5
|
Release files / mazu-0.25.2-py3-none-any.whl
| Download URL | mazu-0.25.2-py3-none-any.whl |
|---|---|
| Size | 240.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
19035d1406ed2031e836bf61495b124e36ac61bb2d92a205d5a73f2f1e77f8fd
|
|
BLAKE2b-256 checksum How to use checksums |
b2209163249ac73c579c9566ffa64fcaeed964eab6b72d2cf41053216e6ee7ae
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.5
|
Security for mazu 0.25.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.