MateClaw

[Website] [Live Demo] [Documentation] [中文]

Latest stable: v2.2.0 — a pluggable, recoverable Agent Runtime. Digital employees can now run on MateClaw's native StateGraph engine or the managed DeepSeek Harness (DSH) runtime while keeping one conversation, policy, tool, persistence, and observability plane. Persistent Goals survive bounded turns and backend restarts, and A2A connects governed employees across systems. Read the v2.2.0 release notes.

Other personal AI agents are built for one person. MateClaw is the one your IT department can actually sign off on.

Multi-user workspaces. Approval-gated sensitive actions. Full audit trail. Spring Boot Actuator health monitoring. Per-channel error isolation so one chat platform's outage doesn't take down the rest. One JAR in your environment; you control persisted data, and task content is sent only to model, channel, or tool services you explicitly configure.

And underneath, a real Agent Runtime. An employee is no longer welded to one reasoning loop. Choose the native StateGraph runtime for ReAct, Plan-and-Execute, Goals, and Team Runs, or run DeepSeek Harness as a managed external loop over authenticated JSON-RPC. Both paths converge on the same conversations, workspace boundaries, Tool Guard, event projection, and lifecycle controls.

Most AI tools die when their vendor has a bad day. Most forget you the moment the tab closes. Most give you a chatbox and call it a product.

MateClaw is the whole widget. One deployment. Reasoning, knowledge, memory, tools, channels — built together, not bolted on. And when your primary model is unavailable, the next healthy provider retries the current request.

Three things that make it different

1 · Your AI doesn't die when a model does

Primary key expired. Vendor returns 401. Network blip. Quota drained.

Other tools hand you a red error card. MateClaw tries the next healthy provider in configured order — including built-in and OpenAI-compatible options such as DashScope, OpenAI, Anthropic, Gemini, DeepSeek, Kimi, Ollama, LM Studio, and MLX — and attempts to recover the current request. It returns an error only when the available chain is exhausted. A provider health tracker parks bad vendors in a cooldown window so they don't waste seconds on every turn.

You don't write a retry script. You drag providers into priority order in Settings → Models and watch the health dashboard fill with green dots as requests route around failures in real time.

2 · Knowledge that links itself

Upload a PDF, a batch of markdown, a scraped page — raw material in.

MateClaw's LLM Wiki digests it into structured pages, builds [[links]] between them, and preserves traceable citations for generated content. Open the citation drawer to inspect the corresponding source chunk and verify page or answer references.

This is the difference between a warehouse and a library.

3 · One product, five surfaces

Same brain. Same memory. Same tools. Different doors.

What's in the box

Digital employees, not chatbots

You hire coworkers, not chat boxes. Each one has a Role, a Goal, a Backstory, a runtime, a pixel-art avatar, and a color of their own — six built-in templates ship ready (General Assistant · Product Assistant · Research Analyst · Customer Support · Data Analyst · Code Reviewer). Employee identity and governance stay stable even when the execution engine changes.

Agent Runtime: native or DSH (2.2.0+)

The AgentRuntimeProvider contract separates an employee from the engine that runs its turn. The native runtime keeps ReAct, Plan-and-Execute, persistent Goals, and Team Runs inside MateClaw. The DSH runtime manages dsh-jsonrpc-agent as an authenticated child process and streams thinking, text, tool calls, usage, completion, and cancellation back as normalized runtime events. DSH owns the external Agent loop; MateClaw still owns the session, workspace, credentials, tools, approvals, messages, and UI projection. Runtime availability and capabilities are validated before startup, and DSH can be installed, verified, connection-tested, enabled, or disabled from the console. Configure DeepSeek Harness →

Durable long tasks: checkpoint, restart, continue (2.2.0+)

Persistent Goals turn work that takes hours into bounded, recoverable segments. The database preserves the goal checklist, continuation state, attempts, cooldowns, leases, and user input accepted while the worker is busy. After a single backend instance restarts, the supervisor reconciles the interrupted attempt, reads persisted checkpoints and artifacts, and schedules the next safe segment instead of asking you to repeat the task.

For file-producing work, ask the employee to keep a progress ledger, append small verifiable units, inspect the existing tail after recovery, and complete the Goal only after reproducible acceptance checks pass. The runtime does not promise exactly-once behavior for arbitrary external side effects; payments, sends, publishes, and destructive calls still need provider idempotency or review. Run and verify durable Goals →

Prompt pattern: “Create a persistent Goal first. Save the plan and progress in the workspace, write in small checkpoints, resume from existing evidence after errors or restart, and call completeGoal only after every criterion has verifiable evidence.”

Team Runs (2.1.0+)

One request, one durable Team Run. A stable runId links the user's objective, task DAG, worker executions, final synthesis, and deliverables. Chat is the outcome surface, Agents Live groups the workers for real-time observation, and Teams owns history and governance — all three consume the same server projection. Worker conversations no longer flood the normal sidebar; summaries and files lead, while tasks, evidence, approvals, and read-only worker records drill down on demand. Underneath, the 2.0 shared board still provides dependency orchestration, parallel dispatch, prerequisite hand-off, execution leases, cancel-interrupt, and human approval gates.

Knowledge & memory

• LLM Wiki — raw materials digest into linked pages with citations; the hot cache auto-injects into every employee's system prompt. Transformations engine (1.3.0+) turns the Wiki from a search index into a processing pipeline
• Workspace memory — AGENTS.md, SOUL.md, PROFILE.md, MEMORY.md, daily notes
• Memory lifecycle — post-conversation extraction, scheduled consolidation, Dreaming workflows. Workflows can also write directly into an employee's MEMORY.md via the write_memory step

Skills · MCP · ACP — three ways to extend capability

• SKILL.md packages — manifest + prompt + tool list + LESSONS.md. In 2.1, reflection and cross-session recurring-request mining can produce reusable improvements; routine promotion, constrained auto-binding, curator handover/governance, origin policy, snapshots, and restore points keep evolution observable, workspace-scoped, and reversible. Eight starter templates plus a five-step creation wizard, with Pre-flight checks before install
• MCP — stdio / SSE / Streamable HTTP, plug into any external tool server. Per-employee binding (1.3.0+) means a tool you install for one employee doesn't bleed into another's toolbox
• ACP — bring top-tier coding agents like Claude Code and Codex in as employees, auto-bridged to skill cards with wrapper tools
• Tool Guard — RBAC + approval flow + path protection. Capability needs boundaries

Business orchestration (1.3.0+)

• Workflow — compose multip