Koclaw Is Live — From Vision to Running Code

In my last post about Koclaw, I shared the early vision: taking the idea behind AIKokoron and evolving it into a cross-platform AI agent framework. Back then, the project hadn't even been uploaded to GitHub. A lot has changed since.

Koclaw is now deployed, open source, and running in production.

What Is Koclaw

Koclaw (Kokoron + claw) is a secure, self-hosted AI Agent framework for personal use. The core idea: one AI persona, multiple platforms, unified memory, end-to-end encryption. Instead of having separate AI bots for each service, Koclaw lets the same assistant — Kokoron — operate across Telegram, QQ, Discord, desktop apps, and websites, all with shared context and consistent personality.

The project is split into two main components:

• Rust Gateway — the security-critical core. Handles message routing, authentication, encryption, channel management, and a cron-based scheduler. Written in Rust for memory safety and performance.
• Python Agent — the AI brain. Handles LLM routing (Claude, GPT-4o, DeepSeek, Ollama), conversation memory, MCP tool execution, voice synthesis, and expression extraction for Live2D avatars.

They communicate over an internal WebSocket bridge, with the Gateway acting as the gatekeeper that enforces permissions and routes messages to the right channels.

What's Working Now

All five planned development phases are complete, with 124 tests passing (66 Rust + 58 Python):

Multi-Platform Channels

• Telegram (polling mode, text/voice/image)
• QQ (OAuth2, guild + DM)
• Discord (WebSocket Gateway, guild + DM)
• WebSocket channel for desktop and web clients

Security

• X25519 key exchange with HKDF-SHA256 key derivation
• ChaCha20-Poly1305 encryption at rest
• Encrypted SQLite memory store
• Tool sandbox with filesystem path validation and command allowlist
• Three-tier permission model: Public / Authenticated / Admin

AI Capabilities

• Multi-provider LLM routing (switch between Claude, GPT-4o, DeepSeek, local Ollama)
• 27 MCP tools (filesystem, web fetch, memory, sequential thinking, and more)
• Conversation memory with per-session history
• GPT-SoVITS voice synthesis and Faster-Whisper speech recognition
• Expression extraction for Live2D avatar synchronization

Automation

• Cron-based scheduler for reminders and proactive messages
• Heartbeat monitoring with configurable active hours
• LLM-powered job creation (the AI can schedule its own reminders)

Persona System

• Unified persona.yaml as single source of truth
• Per-channel behavior customization (e.g., expression tags only in desktop mode)
• Automatic language detection (Japanese, Chinese, English)

What's Next

There are several features I'm looking forward to building:

• @koclaw/web-widget SDK — a TypeScript/React package for one-line embedding on any website. The API spec is already fully designed; implementation is next.
• RAG Knowledge Base — integrating retrieval-augmented generation directly into the Agent, so Kokoron can draw on curated knowledge beyond its training data.
• True Zero-Knowledge E2E — currently the Gateway decrypts messages to forward them to the Agent. The goal is for the Agent to hold its own keys, making the Gateway a pure relay.
• shinBlog Integration — connecting this blog's Kokoron chat feature to the live Koclaw Gateway, replacing the current placeholder widget.

About AIKokoron — The Desktop Companion

Some of you might remember AIKokoron, the desktop Live2D companion app I wrote about earlier. AIKokoron and Koclaw are deeply related but serve different purposes:

• Koclaw is the backend framework — the "nervous system" that handles communication, security, and AI orchestration across all platforms.
• AIKokoron is the desktop frontend — an Electron app with a Live2D character that provides voice conversation and visual interaction.

Think of it this way: they share the same brain, but live in different bodies. Koclaw's Python Agent already includes the voice pipeline and expression system originally built for AIKokoron. When AIKokoron connects to Koclaw via WebSocket, it gets all the multi-platform context and tool capabilities that Koclaw provides.

AIKokoron is still being refined and will launch as its own standalone project. But even as a separate project, it connects back to Koclaw — one persona, one memory, one brain, accessible from your desktop or any messaging platform.

Try It Out

Koclaw is open source under the MIT license:

• GitHub: github.com/ksromt/koclaw

If you're interested in self-hosted AI assistants, cross-platform agent frameworks, or Rust + Python architectures, feel free to check it out. Contributions and feedback are always welcome.