Personal AI coding agent that runs securely in containers. Small, focused, and built for daily use.
Mozi is not a "build for fun" project, and not a "cover every scenario" platform.
It is built around one practical goal: a personal coding agent you can run every day, safely, with predictable behavior and low maintenance overhead.
Core logic:
- Small core, stable runtime: keep the host process simple and reliable instead of building a giant orchestration platform.
- Session continuity without context chaos: use lifecycle-based session segmentation/rotation so long-running usage stays manageable.
- Memory as a system behavior: memory file creation/sync/indexing are runtime responsibilities, not manual user chores.
- Sandbox-first execution: code/tool execution should be isolated by default, so autonomy does not mean host risk.
Anti-goals:
- Not trying to be an enterprise multi-tenant agent platform.
- Not trying to automate every workflow blindly.
- Not adding features that increase complexity without clear daily value.
Mozi can borrow ideas from projects like OpenClaw, but the product target is different: smaller surface area, clearer control, and better day-to-day operability for a personal setup.
git clone https://github.com/royzhu/mozi.git
cd mozi
pnpm install# pnpm
pnpm add -g @royisme/mozi-bot
# bun
bun add -g @royisme/mozi-bot
# npm
npm i -g @royisme/mozi-botThen run:
mozi --version
mozi runtime startCreate ~/.mozi/config.jsonc:
Model config note:
- User-facing model keys are
agents.defaults.modeland optionalagents.defaults.imageModel(or per-agent overrides). - Multi-format inputs are handled by the multimodal ingestion + media-understanding pipeline with model capability routing.
Session lifecycle behavior:
/newperforms a hard segment rotation (new segment id, old segment archived)- Temporal auto-rotation runs by default (12h window and day-boundary rollover)
- Semantic rotation can run in background with debounce and reversible rollback
Memory lifecycle behavior:
- Builtin memory syncs local
.mdfiles into a SQLite index automatically. - Reindexing triggers on session warmup, before search, or via filesystem watcher.
- Session history can be auto-archived to memory files on context overflow or
/new.
Set your environment variables:
OPENAI_API_KEY=sk-...
TELEGRAM_BOT_TOKEN=...Mozi includes built-in diagnostic commands for config and ACP setup.
# top-level config doctor
mozi doctor
mozi doctor --json
mozi doctor --verbose
mozi doctor --fix
# config doctor via config surface
mozi config --doctor
mozi config --doctor --json
mozi config --doctor --fix
# ACP-specific doctor
mozi acp doctor
mozi acp doctor --json
mozi acp doctor --verboseWhat they help with:
- config consistency and missing required values
- unresolved env placeholders and redacted secrets
- agent/model/provider wiring problems
- ACP backend/defaultAgent/allowedAgents/installCommand consistency
- machine-readable JSON output for scripting and CI
Current limitation:
- these doctor commands focus on static configuration and setup validation
- they do not yet diagnose all runtime causes of
(no response)failures such as upstream provider/runtime/reply-rendering probe failures
In local development, build first, then run the compiled CLI from dist/:
pnpm run build
bun dist/mozi.mjs runtime startIf mozi is globally installed or linked to your PATH, this is equivalent:
mozi runtime startMozi uses repo-local git hooks to enforce validation before code leaves your machine:
pre-commitrunspnpm run checkpre-pushrunspnpm run test
You can also run them manually:
pnpm run check
pnpm run testList configured skill directories and loaded skills:
mozi skillsShow eligibility, missing requirements, and install hints:
mozi skills --statusMozi supports WeChat via the ilink bot API (long-poll based, Phase 1: text DMs only, no media).
Run the login command to scan a QR code and get your ilink bot token:
mozi wechat loginThe command will:
- Fetch a QR code and render it in your terminal
- Wait for you to scan it with the WeChat bot account
- Print the token and a ready-to-paste config snippet
If the QR expires before you scan, it automatically refreshes up to 3 times.
Add the token to your config file:
"channels": {
"wechat": {
"enabled": true,
"token": "${WECHAT_ILINK_TOKEN}",
// "allowFrom": ["<wechat-user-id>"], // optional allowlist
// "baseUrl": "https://ilinkai.weixin.qq.com", // optional
// "pollingTimeoutSeconds": 35 // optional
}
}Set the token as an environment variable:
WECHAT_ILINK_TOKEN=your_ilink_bot_token_here- Text DMs only (Phase 1 — no images, files, or voice)
- Typing indicator while Mozi is composing a response
allowFromfield restricts incoming messages to specific WeChat user IDs- Long-poll cursor is persisted to Mozi's data directory automatically
- If the session expires (errcode -14), the monitor pauses for 30 minutes before retrying
Mozi uses a modular architecture with a deliberately compact scope:
- Runtime Host: The main process that manages channels, queue scheduling, and session runtime.
- Channel Adapters: Integration with messaging platforms (Telegram, Discord, WeChat).
- Agents: LLM-powered entities that execute tasks.
- LLM: Provider abstraction (OpenAI, Anthropic).
- Runner: Executes agents in isolated environments.
- Skills: Capabilities like web search or code execution.
- Tools: Low-level interfaces for agents.
- Storage: Persistent state using SQLite and local filesystem.
- docs/GETTING_STARTED.md - Required baseline setup to run Mozi locally
- docs/SYSTEM.md - System overview and architecture
- docs/API.md - API reference and interfaces
- docs/CONTRIBUTING.md - How to contribute
- docs/MODULES/memory.md - Memory sync and persistence details
- dev-docs/ARCHITECTURE.md - Internal architecture details
- dev-docs/TECH_STACK.md - Technology choices
- dev-docs/PROGRESS.md - Development status
MIT
{ "paths": { "baseDir": "~/.mozi", }, "models": { "providers": { "openai": { "apiKey": "${OPENAI_API_KEY}", "api": "openai-responses", "models": [{ "id": "gpt-4o" }], }, }, }, "memory": { "backend": "builtin", "builtin": { "sync": { "onSessionStart": true, "onSearch": true, "watch": true, "intervalMinutes": 0, }, }, "persistence": { "enabled": true, "onOverflowCompaction": true, "onNewReset": true, }, }, "agents": { "defaults": { "model": "openai/gpt-4o", "imageModel": "openai/gpt-4o", "lifecycle": { "control": { "model": "openai/gpt-4o-mini", "fallback": ["openai/gpt-4o"], }, "temporal": { "enabled": true, "activeWindowHours": 12, "dayBoundaryRollover": true, }, "semantic": { "enabled": true, "threshold": 0.8, "debounceSeconds": 60, "reversible": true, }, }, }, "mozi": { "main": true, "name": "Mozi", "skills": [], }, }, "channels": { "routing": { "dmAgentId": "mozi" }, "telegram": { "enabled": true, "botToken": "${TELEGRAM_BOT_TOKEN}", "agentId": "mozi", }, "wechat": { "enabled": true, "token": "${WECHAT_ILINK_TOKEN}", // "allowFrom": ["<wechat-user-id>"], // optional, leave out to allow all // "baseUrl": "https://ilinkai.weixin.qq.com", // optional, default shown // "pollingTimeoutSeconds": 35, // optional }, }, }