Files

T

darman 797fc74e11 Add project documentation and reference materials

Include Luna AI Assistant design docs covering channels, configuration,
core architecture, memory, scheduler, and skills. Add reference docs
from OpenClaw and ZeroClaw projects, plus Mistral and OpenAI API specs.

2026-04-04 04:14:06 +02:00

4.3 KiB

Raw Blame History

OpenClaw

Overview

OpenClaw is a mature TypeScript/Node.js AI assistant platform (~342k stars, ~24k commits). Local-first gateway control plane with plugin-SDK architecture. Monorepo with packages. Repo: https://github.com/openclaw/openclaw

Architecture

Local-first WebSocket gateway as central control plane
Plugin-SDK architecture — features are installable packages, not inline code
Monorepo: src/ for core, packages/ for SDKs

Agent Runtime

Pi agent runtime with RPC mode
Tool streaming and block streaming
Multi-agent routing
Agent compaction for long conversations

Providers

Multiple AI providers via plugin-sdk
OAuth subscription auth (OpenAI Codex, Claude Code)

Channels

24+ messaging platforms via plugin-per-platform pattern with shared registry/helpers: WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Teams, LINE, Nostr, WeChat, and more. Each channel plugin: channel-specific auth, message normalization, allowlist-based access control.

Memory

memory-host-sdk package with three engines:
- engine-embeddings (vector embedding computation/storage)
- engine-foundation (core memory primitives)
- engine-storage (pluggable storage backends)
Pluggable vector DB support for semantic search

Tools

Rich tool ecosystem:

Browser: Managed Chromium via CDP
Canvas: A2UI visual workspace
Cron: Scheduled tasks
Nodes: Device-local (camera, screen, notifications)
Sessions: Session management tools
Web Fetch: HTTP with SSRF guards and visibility rules
PDF, TTS, Image tools

Sessions

JSON-persisted session store
Pruning, capping, rotation, archiving
Per-session sandbox policies
Activation modes, group routing
Session lifecycle events

Security

DM Pairing: 6-digit codes + per-channel allowlists
Per-session Sandboxing: Docker/SSH backends
Tool Allow/Deny Lists
SSRF Guards on web fetch
Web Fetch Visibility Rules

Skills & Plugins

Full plugin lifecycle:

Manifest Registry with capability declarations
Install/enable/disable/uninstall lifecycle
Workspace Skills via AGENTS.md and SKILL.md conventions
Bundled plugins + external ClawHub package registry

Voice & Apps

Wake word detection, Talk Mode, TTS (ElevenLabs + system fallback)
macOS menu bar app, iOS/Android nodes, WebChat browser client

In-Depth Reference Pages

Session Management — SessionEntry type, store maintenance (pruning/capping/rotation), atomic writes, lifecycle events
Plugin Architecture — Plugin type system, 40+ provider hooks, tool factories, config schemas, channel handlers
Channel System — Plugin-per-platform pattern, shared registry, message normalization, access control
Security — DM/group access decisions, pairing, allowlists, per-session sandboxing, SSRF guards
Memory SDK — Composable engine architecture (storage, embeddings, QMD), SQLite + sqlite-vec, 6 embedding providers
Compaction Strategy — Token-budget gating, staged summarization, quality guards, identifier preservation, session truncation

Relevance to Luna

Patterns Worth Adopting

Session Management: Pruning/capping/rotation is much more mature than Luna's basic SessionManager. Configurable max message counts, session lifecycle events, group routing. See Session Management for details. Link to Core.
Plugin Architecture: Manifest-based registry with install/enable/disable lifecycle is a good reference for Luna's Skills module. See Plugin Architecture for the hook system.
Channel Normalization: Plugin-per-platform with shared registry validates Luna's Channels design. Key lesson: establish a rich normalized message type before adding the second channel. See Channel System.
Security Layers: DM pairing and per-session sandboxing are practical patterns Luna should adopt before exposing tool execution. See Security for the access decision system.
Compaction: Token-budget driven summarization with quality guards and structured output sections. Far more sophisticated than Luna's basic LibrarianAgent compaction. See Compaction Strategy.

Key Differences from Luna

OpenClaw is a platform for third-party plugin development; Luna is a standalone assistant
TypeScript vs .NET/C#
Features are installable packages vs compiled modules
Mature multi-app distribution (macOS, iOS, Android, WebChat) vs CLI only

4.3 KiB Raw Blame History