npm package: @royisme/mozi-bot
Description: Personal AI coding agent that runs securely in containers
Latest version: 2.2.1

# Mozi (墨子)

<p align="center">
  <img src="docs/assets/logo.png" alt="Mozi" width="200">
</p>

<p align="center">
  Personal AI coding agent that runs securely in containers. Small, focused, and built for daily use.
</p>

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

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

### Install from npm (Global CLI)

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

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

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

Then run:

```bash
mozi --version
mozi runtime start
```

### Configuration

Create `~/.mozi/config.jsonc`:

```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:

```env
OPENAI_API_KEY=sk-...
TELEGRAM_BOT_TOKEN=...
```

### Doctor Commands

Mozi includes built-in diagnostic commands for config and ACP setup.

```bash
# 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/`:

```bash
pnpm run build
bun dist/mozi.mjs runtime start
```

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

```bash
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:

```bash
pnpm run check
pnpm run test
```

### Skills

List configured skill directories and loaded skills:

```bash
mozi skills
```

Show eligibility, missing requirements, and install hints:

```bash
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:

```bash
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:

```jsonc
"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:

```env
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](docs/GETTING_STARTED.md) - Required baseline setup to run Mozi locally
- [docs/SYSTEM.md](docs/SYSTEM.md) - System overview and architecture
- [docs/API.md](docs/API.md) - API reference and interfaces
- [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) - How to contribute
- [docs/MODULES/memory.md](docs/MODULES/memory.md) - Memory sync and persistence details

## Development Docs

- [dev-docs/ARCHITECTURE.md](dev-docs/ARCHITECTURE.md) - Internal architecture details
- [dev-docs/TECH_STACK.md](dev-docs/TECH_STACK.md) - Technology choices
- [dev-docs/PROGRESS.md](dev-docs/PROGRESS.md) - Development status

## Requirements

- Node.js >= 22.12.0
- [pnpm](https://pnpm.io) (via Corepack recommended)
- [Docker](https://docker.com) (only if sandbox exec is enabled)

## License

MIT