From Spring Boot 3.5 to an AI OS: One JAR Powers Agents, Knowledge Base, and Toolchain

Overview

MateClaw is an open‑source AI platform built with Java 17, Spring Boot 3.5 and Spring AI Alibaba. It is delivered as a single JAR that runs on the user’s own machine, keeping all data local while providing multi‑agent collaboration, a structured knowledge base, a four‑layer memory system, tool integration, and access through multiple channels.

Problems addressed

Single‑vendor model unavailability – MateClaw can configure more than 14 providers (DashScope, OpenAI, Anthropic, DeepSeek, Kimi, Ollama, etc.) and automatically routes requests based on priority, health checks, and cooldown periods.

High knowledge‑base maintenance cost – PDFs, Markdown and plain text are ingested and transformed into bidirectional Wiki pages where every sentence links back to its source.

Data privacy – All conversations, logs and files reside on the user’s server; API keys are managed locally and billing is calculated by the user.

Core features

Multi‑Agent system

Each Agent has its own name, system prompt, tool list, bound knowledge base and memory file. Version 1.1.0 adds task delegation, allowing a primary Agent to assign sub‑tasks to multiple Agents in parallel (e.g., a code Agent handles a Jira ticket while a research Agent gathers competitor data).

Two reasoning modes are available:

ReAct – default mode; the Agent iterates: think → act (tool call) → observe → decide.

Plan‑and‑Execute – generates an ordered plan of 2‑6 steps, executes them sequentially, and displays progress beside the conversation.

Both modes share the same system prompt and can be switched on the fly. Depth of thinking can be set from off to max, supporting Anthropic extended thinking, DashScope qwq, and OpenAI o1.

Memory system

Short‑term context – current dialogue; when the window fills, early turns are summarized instead of truncated.

Post‑dialog extraction – after each session, three files are written asynchronously: PROFILE.md (user info), MEMORY.md (important items), and a daily diary.

Integration & Dreaming – a nightly job (2 am) scans the past seven days of diaries, extracts patterns, updates MEMORY.md, discards stale entries, and writes DREAMS.md to show memory evolution.

System‑prompt injection – the four files are automatically injected into the system prompt at the start of each conversation.

LLM Wiki knowledge base

Unlike vector‑only stores that return fragments, MateClaw’s Wiki creates structured pages with titles, summaries, bodies and bidirectional links ( [[like this]]). Each sentence retains a reference to its original paragraph.

Two ingestion modes exist:

Eager – processes the document immediately, generating pages at the cost of LLM calls.

Lazy – only slices and vectorizes; pages are generated on demand, enabling instant search without LLM usage.

When an Agent is bound to a knowledge base, the top‑level page summary is injected into the system prompt, and full pages are fetched only when needed, saving tokens.

Tool system and MCP

Built‑in tools include web search, file I/O, shell execution, time, image generation, music, video, speech‑to‑text and text‑to‑speech. All tools pass through a Tool Guard that supports RBAC, path protection, and optional human approval for high‑risk actions.

The platform also supports the MCP protocol (stdio, SSE, or streamable HTTP) for third‑party services.

Multi‑channel integration

Web console – full management UI for agents, models, tools, knowledge bases, permissions and scheduled tasks.

Desktop – Electron app with embedded JRE 21; double‑click to start, no separate Java or Node installation.

Webchat component – embed a <script> tag into any website.

IM channels – DingTalk, Feishu, Enterprise WeChat, WeChat, Telegram, Discord, QQ, Slack.

Plugin SDK – Java module for third‑party capability extensions.

Quick start

Download the desktop client from GitHub Releases ( .exe for Windows, .dmg for macOS, .AppImage for Linux). The package includes JRE 21, so no extra runtime is needed.

Run the app; the first launch takes 10‑30 seconds while the backend starts. Default credentials are admin / admin123; change the password in Settings → Security.

Add a model provider under Settings → Model → Add Supplier. Supply keys for DashScope, OpenAI, Anthropic, or point to a local Ollama endpoint ( localhost:11434), or use ChatGPT OAuth for GPT‑4o, o3, o4‑mini.

After configuration, query “Search the latest Spring Boot version and summarize breaking changes”. The ReAct mode will automatically invoke the search tool, process results, and respond.

Optionally bind a knowledge base (e.g., company design docs) to an Agent, add an IM channel, and the same Agent will continue the conversation across all endpoints.

Other deployment options

Docker Compose – copy .env.example to .env, fill required values, then run:

cp .env.example .env
# Fill required values (DB password, etc.)

docker compose up -d
# Access http://localhost:18080

The compose file is 18 lines and bundles the entire Spring Boot process.

Source launch – suitable for developers who want to modify code.

# Backend
cd mateclaw-server
mvn spring-boot:run   # http://localhost:18088

# Frontend
cd mateclaw-ui
pnpm install && pnpm dev   # http://localhost:5173

Production uses MySQL 8.0+; development uses embedded H2 with Flyway migrations.

Technology stack

Backend – Spring Boot 3.5, Spring AI Alibaba 1.1, MyBatis Plus, Flyway.

Agent runtime – StateGraph, ReAct + Plan‑Execute.

Database – H2 (dev) / MySQL 8.0+ (prod).

Auth – Spring Security + JWT.

Frontend – Vue 3, TypeScript, Vite, Element Plus, TailwindCSS 4.

Desktop – Electron with embedded JRE 21.

Embedded component – Vite library mode, output UMD + ES bundles.

Suitable scenarios

Java/Spring Boot developers who want to read and contribute to source code without switching ecosystems.

Teams needing multi‑model redundancy (five or more providers) to avoid single‑point failures.

Strict data‑privacy requirements where on‑premises deployment is mandatory.

Organizations requiring fine‑grained permission management and audit logs for Agent operations.

Repository

Source code: https://github.com/matevip/mateclaw (Apache 2.0 license)

Documentation: https://claw.mate.vip/docs/zh