A personal AI assistant system built with Java + Vue 3, powered by Spring AI Alibaba. Features multi-agent orchestration, a flexible tool/skill system with MCP protocol support, multi-layer memory, and multi-channel adapters.

Core capabilities:

Multi-Agent Orchestration — ReAct (Thought → Action → Observation loop) and Plan-and-Execute (auto-decompose complex tasks into ordered sub-steps). Create multiple independent agents, each with their own personality and tools.

Tool & Skill System — Built-in tools (web search, date/time) + MCP protocol for external tool integration. Pre-configured GitHub and Filesystem MCP servers — enable and go. Install skill packages from ClawHub marketplace or custom sources.

Multi-Layer Memory — Short-term context window with auto-compression, event-driven post-conversation memory extraction, workspace files (PROFILE.md / MEMORY.md / daily notes), and scheduled memory consolidation.

Every Channel — Web console, DingTalk, Feishu, WeChat Work, Telegram, Discord, QQ. One MateClaw, connect as needed.

Multi-Provider Models — 20+ providers: DashScope, OpenAI, Anthropic, Google Gemini, DeepSeek, Kimi, MiniMax, Zhipu AI, Volcano Engine, OpenRouter, Ollama, LM Studio, llama.cpp, MLX, and more. Configure in the web UI.

Desktop App — Electron-based desktop application with auto-update support. Download and double-click to run.

Table of Contents

• Quick Start
• Screenshots
• Architecture
• Tech Stack
• Features
• Documentation
• Roadmap
• Contributing
• Contact Us
• License

Quick Start

Prerequisites

• Java 17+
• Node.js 18+ & pnpm
• Maven 3.9+ (or use mvnw)
• At least one LLM API Key (e.g., DashScope)

Option 1: Local Development

1. Start the backend

cd mateclaw-server
export DASHSCOPE_API_KEY=your-key-here
mvn spring-boot:run
# Backend runs at http://localhost:18088
# H2 Console: http://localhost:18088/h2-console
# API Docs (SpringDoc OpenAPI): http://localhost:18088/swagger-ui.html

2. Start the frontend

cd mateclaw-ui
pnpm install
pnpm dev
# Frontend runs at http://localhost:5173 (proxies /api to :18088)

3. Log in

Open http://localhost:5173 and log in with admin / admin123.

Option 2: Docker

cp .env.example .env
# Edit .env — fill in DASHSCOPE_API_KEY and other variables

docker compose up -d
# Service runs at http://localhost:18080 (MySQL + backend)

Option 3: Desktop Application

Download the installer from GitHub Releases:

Double-click to run. The app bundles JRE 21 + the Spring Boot backend, no Java installation needed. Supports auto-update via GitHub Releases.

macOS users: If macOS blocks the app, right-click → Open → Open again, or go to System Settings → Privacy & Security → Open Anyway.

Screenshots

Architecture

mateclaw/
├── mateclaw-server/          # Spring Boot backend
│   ├── src/main/java/vip/mate/
│   │   ├── agent/            # Agent engine (ReAct, Plan-and-Execute, StateGraph)
│   │   ├── planning/         # Task planning (Plan / SubPlan models)
│   │   ├── tool/             # Tool system (built-in + MCP adapters)
│   │   ├── skill/            # Skill management (workspace + ClawHub)
│   │   ├── channel/          # Channel adapters (Web, DingTalk, Feishu, etc.)
│   │   ├── workspace/        # Conversations, messages, workspace files
│   │   ├── memory/           # Memory extraction & consolidation
│   │   ├── llm/              # Multi-provider model configs
│   │   ├── cron/             # Scheduled tasks (CronJob)
│   │   ├── auth/             # Spring Security + JWT
│   │   └── config/           # Spring bean configurations
│   └── src/main/resources/
│       ├── application.yml   # Main config (H2 for dev)
│       ├── prompts/          # Prompt templates
│       └── db/               # Schema & seed data (schema.sql, data.sql)
├── mateclaw-ui/              # Vue 3 SPA frontend
│   └── src/
│       ├── views/            # Pages (ChatConsole, AgentWorkspace, SkillMarket, etc.)
│       ├── components/       # Reusable components
│       ├── stores/           # Pinia stores (domain-driven)
│       ├── api/              # Axios HTTP client
│       ├── router/           # Vue Router
│       ├── types/            # TypeScript types
│       └── i18n/             # Internationalization (zh-CN, en-US)
├── mateclaw-desktop/         # Electron desktop app
├── docs/                     # VitePress documentation (zh + en)
├── docker-compose.yml
└── .env.example

Tech Stack

Features

Agent System

• ReAct Agent — Thought → Action → Observation reasoning loop with tool calling
• Plan-and-Execute — Auto-decompose complex tasks into ordered sub-steps with progress tracking
• Dynamic Agent — Load agent configs from database at runtime
• Multi-Agent — Create multiple independent agents, each with their own system prompt, tools, and personality

Tool & Skill System

• Built-in Tools — Web search (Serper/Tavily), date/time, workspace memory read/write
• MCP Protocol — Connect external tools via Model Context Protocol (stdio, SSE, and Streamable HTTP transports). Full lifecycle management in the web UI — add, edit, enable/disable, and test connections
• Pre-configured MCP Servers — GitHub (@modelcontextprotocol/server-github) and Filesystem ship out-of-the-box. Enable from the MCP management page and fill in your token — no code changes needed
• Skill Packages — Install/uninstall skill packages with SKILL.md manifests
• ClawHub Marketplace — Browse and install skills from the ClawHub registry
• Workspace Skills — Convention-based skill directory at ~/.mateclaw/skills/{name}/

Memory System

• Short-Term — Conversation context window with auto-compression when token budget exceeded
• Post-Conversation Extraction — Event-driven async LLM analysis, writes to PROFILE.md / MEMORY.md / daily notes
• Memory Consolidation — Scheduled daily emergence (CronJob at 2:00 AM) merges daily notes into long-term memory
• Workspace Files — Per-agent AGENTS.md, SOUL.md, PROFILE.md, MEMORY.md, memory/*.md
• Agent Memory Tool — Agents can read/write their own workspace files during conversations

Multi-Channel

• Web Console — SSE streaming with rich message rendering (Markdown, code, plans)
• DingTalk — Webhook + event subscription
• Feishu (Lark) — Webhook + event subscription
• WeChat Work — Callback API
• Telegram — Bot API with webhook
• Discord — Bot with slash commands
• QQ — QQ Bot API

Model Providers

Configure in the web UI (Settings → Models). Supported providers:

Security

• Spring Security + JWT — Token-based authentication
• Tool Guard — Approval rules for sensitive tool operations
• File Validation — Path traversal prevention for workspace files
• Skill Security — Validation during skill installation

Scheduled Tasks

• CronJob System — Create scheduled tasks with 5-field cron expressions
• Memory Consolidation — Auto-triggered daily for each agent
• Custom Tasks — Schedule any prompt to run periodically

Documentation

Roadmap

Status: In Progress — actively being worked on; Planned — queued or under design.

Contributing

MateClaw is open to contributions! Whether it's bug fixes, new features, documentation improvements, or new channel/tool integrations — all contributions are welcome.

# Clone the repository
git clone https://github.com/matevip/mateclaw.git
cd mateclaw

# Backend
cd mateclaw-server
mvn clean compile

# Frontend
cd ../mateclaw-ui
pnpm install
pnpm dev

Please read CONTRIBUTING.md (if available) before submitting a PR.

Contact Us

Why MateClaw?

Mate — a companion, always by your side. Claw — sharp, capable, ready to grab any task. MateClaw is your personal AI mate that lends a claw whenever you need it. Built as a monolith with modular design, it's easy to deploy, extend, and customize.

License

MateClaw is released under the Apache License 2.0.