Mozi (墨子)

Why Mozi Exists

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.

Quick Start

git clone https://github.com/royzhu/mozi.git
cd mozi
pnpm install

Install from npm (Global CLI)

# pnpm
pnpm add -g @royisme/mozi-bot

# bun
bun add -g @royisme/mozi-bot

# npm
npm i -g @royisme/mozi-bot

Then run:

mozi --version
mozi runtime start

Configuration

Create ~/.mozi/config.jsonc:

{
  "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
    },
  },
}

Model config note:

• User-facing model keys are agents.defaults.model and optional agents.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:

• /new performs 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 .md files 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=...

Doctor Commands

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 --verbose

What 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

Running (Dev / Local)

In local development, build first, then run the compiled CLI from dist/:

pnpm run build
bun dist/mozi.mjs runtime start

If mozi is globally installed or linked to your PATH, this is equivalent:

mozi runtime start

Development Workflow

Mozi uses repo-local git hooks to enforce validation before code leaves your machine:

• pre-commit runs pnpm run check
• pre-push runs pnpm run test

You can also run them manually:

pnpm run check
pnpm run test

Skills

List configured skill directories and loaded skills:

mozi skills

Show eligibility, missing requirements, and install hints:

mozi skills --status

WeChat Channel

Mozi supports WeChat via the ilink bot API (long-poll based, Phase 1: text DMs only, no media).

Obtain a Token

Run the login command to scan a QR code and get your ilink bot token:

mozi wechat login

The command will:

1. Fetch a QR code and render it in your terminal
2. Wait for you to scan it with the WeChat bot account
3. Print the token and a ready-to-paste config snippet

If the QR expires before you scan, it automatically refreshes up to 3 times.

Configuration

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

Capabilities and Limits

• Text DMs only (Phase 1 — no images, files, or voice)
• Typing indicator while Mozi is composing a response
• allowFrom field 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

Architecture

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.

Documentation

• 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

Development Docs

• dev-docs/ARCHITECTURE.md - Internal architecture details
• dev-docs/TECH_STACK.md - Technology choices
• dev-docs/PROGRESS.md - Development status

Requirements

• Node.js >= 22.12.0
• pnpm (via Corepack recommended)
• Docker (only if sandbox exec is enabled)

License

MIT