Aetheel/openclaw-analysis.md

# OpenClaw Analysis & "My Own OpenClaw" Comparison

> **Date:** 2026-02-13  
> **Source Repo:** `inspiration/openclaw/` (local clone)  
> **Diagram Reference:** `inspiration/MyOwnOpenClaw.png`

---

## Table of Contents

1. [What Is OpenClaw?](#what-is-openclaw)
2. [OpenClaw Architecture Deep Dive](#openclaw-architecture-deep-dive)
3. [MyOwnOpenClaw — The Simplified Blueprint](#myownopenclaw--the-simplified-blueprint)
4. [Side-by-Side Comparison](#side-by-side-comparison)
5. [Key Takeaways for Building Our Own](#key-takeaways-for-building-our-own)
6. [Recommended Build Process for Aetheel](#recommended-build-process-for-aetheel)

---

## 1. What Is OpenClaw?

OpenClaw is an **open-source personal AI assistant** (MIT licensed, 176k+ stars, 443 contributors, 175k+ lines of TypeScript). It runs locally on your own devices and acts as a **gateway-centric control plane** that connects an AI agent to every messaging channel you already use.

**Core value proposition:** A single, always-on AI assistant that talks to you through WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Microsoft Teams, Google Chat, Matrix, WebChat, and more — while keeping everything local and under your control.

---

## 2. OpenClaw Architecture Deep Dive

### 2.1 The Four Pillars

Based on both the source code analysis and the `MyOwnOpenClaw.png` diagram, OpenClaw's architecture rests on **four core subsystems**:

---

### Pillar 1: Memory System — "How It Remembers You"

**Source files:** `src/memory/` (49 files, including `manager.ts` at 2,300+ lines)

**How it works:**

| Component | Details |
|-----------|---------|
| **Identity Files** | `SOUL.md` — personality & values; `USER.md` — who you are; `AGENTS.md` — agent behavior rules; `HEARTBEAT.md` — what to proactively check |
| **Long-term Memory** | `MEMORY.md` — persisted decisions, lessons, context |
| **Session Logs** | `daily/` — session logs organized by date |
| **Search** | **Hybrid search** = vector (embeddings) + keyword (BM25) via `sqlite-vec` or `pgvector` |
| **Embedding Providers** | OpenAI, Voyage AI, Gemini, or local via `node-llama-cpp` (ONNX) |
| **Storage** | SQLite database with `sqlite-vec` extension for vector similarity |
| **Sync** | File watcher (chokidar) monitors workspace for changes, auto-re-indexes |

**Key architectural details from the code:**
- `MemoryIndexManager` class (2,300 LOC) manages the full lifecycle: sync → chunk → embed → store → search
- Hybrid search weighting: configurable vector weight + keyword weight (default 0.7 × vector + 0.3 × keyword as shown in the diagram)
- Supports batch embedding with Voyage, OpenAI, and Gemini batch APIs
- FTS5 full-text search table for keyword matching
- Vector table via `sqlite-vec` for similarity search
- Automatic chunking with configurable token sizes and overlap

---

### Pillar 2: Heartbeat — "How It Acts Proactively"

**Source files:** `src/cron/` (37 files including service, scheduling, delivery)

**How it works:**

| Component | Details |
|-----------|---------|
| **Scheduling** | Cron-based scheduling using the `croner` library |
| **Service Architecture** | `src/cron/service/` — manages job lifecycle, timers, catch-up after restarts |
| **Normalization** | `normalize.ts` (13k) — normalizes cron expressions and job definitions |
| **Delivery** | `delivery.ts` — routes cron job output to the correct channel/session |
| **Run Logging** | `run-log.ts` — persists execution history |
| **Session Reaper** | `session-reaper.ts` — cleans up stale sessions |

**What happens on each heartbeat:**
1. Cron fires at scheduled intervals
2. Gateway processes the event
3. Checks all integrated services (Gmail, Calendar, Asana, Slack, etc.)
4. AI reasons over the data  
5. Sends notification if needed (e.g., "Meeting in 15 min — prep doc is empty")
6. Or returns `HEARTBEAT_OK` (nothing to report)

**Key detail:** Runs **without user prompting** — this is what makes it feel "proactive."

---

### Pillar 3: Channel Adapters — "How It Works Everywhere"

**Source files:** `src/channels/`, `src/whatsapp/`, `src/telegram/`, `src/discord/`, `src/slack/`, `src/signal/`, `src/imessage/`, `src/web/`, plus `extensions/` (35 extension directories)

**Built-in channels:**

| Channel | Library | Status |
|---------|---------|--------|
| WhatsApp | `@whiskeysockets/baileys` | Core |
| Telegram | `grammy` | Core |
| Slack | `@slack/bolt` | Core |
| Discord | `discord.js` / `@buape/carbon` | Core |
| Signal | `signal-cli` | Core |
| iMessage | BlueBubbles (recommended) or legacy `imsg` | Core |
| WebChat | Built into Gateway WS | Core |

**Extension channels** (via plugin system):
Microsoft Teams, Matrix, Zalo, Zalo Personal, Google Chat, IRC, Mattermost, Twitch, LINE, Feishu, Nextcloud Talk, Nostr, Tlon, voice calls

**Architecture:**
- **Gateway-centric** — all channels connect through a single WebSocket control plane (`ws://127.0.0.1:18789`)
- **Channel Dock** (`src/channels/dock.ts`, 17k) — unified registration and lifecycle management
- **Session isolation** — each channel/conversation gets its own session with isolated context
- **Group routing** — configurable mention gating, reply tags, per-channel chunking
- **DM security** — pairing codes for unknown senders, allowlists

---

### Pillar 4: Skills Registry — "How It Extends to Anything"

**Source files:** `skills/` (52 skill directories)

**How it works:**

| Component | Details |
|-----------|---------|
| **Structure** | Each skill is a directory with a `SKILL.md` file |
| **Installation** | Drop a file in `~/.openclaw/workspace/skills/<skill>/SKILL.md` — instantly available |
| **Registry** | ClawHub (5,700+ skills) — community-built extensions |
| **Types** | Bundled, managed, and workspace skills |
| **Scope** | Local files only — no public registry dependency, no supply chain attack surface |

**Built-in skill examples:**
`1password`, `apple-notes`, `apple-reminders`, `bear-notes`, `github`, `notion`, `obsidian`, `spotify-player`, `weather`, `canvas`, `coding-agent`, `discord`, `slack`, `openai-image-gen`, `openai-whisper`, `session-logs`, `summarize`, `video-frames`, `voice-call`, etc.

---

### 2.2 Gateway Architecture

The Gateway is the **central nervous system** of OpenClaw:

```
WhatsApp / Telegram / Slack / Discord / Signal / iMessage / Teams / WebChat
                │
                ▼
┌───────────────────────────────┐
│            Gateway            │
│       (WS control plane)      │
│     ws://127.0.0.1:18789      │
├───────────────────────────────┤
│  • Session management         │
│  • Channel routing            │
│  • Cron/heartbeat engine      │
│  • Tool registration          │
│  • Presence & typing          │
│  • Auth & pairing             │
│  • Plugin loading             │
│  • Memory manager             │
│  • Config hot-reload          │
└──────────────┬────────────────┘
               │
               ├─ Pi agent (RPC) — AI reasoning engine
               ├─ CLI (openclaw …)
               ├─ WebChat UI
               ├─ macOS app (menu bar)
               ├─ iOS / Android nodes
               └─ Browser control (CDP)
```

**Key source files:**
- `src/gateway/server.impl.ts` (22k) — main gateway server implementation
- `src/gateway/server-http.ts` (17k) — HTTP server
- `src/gateway/ws-log.ts` (14k) — WebSocket logging
- `src/gateway/session-utils.ts` (22k) — session management
- `src/gateway/config-reload.ts` (11k) — hot config reload

### 2.3 Configuration

- **File:** `~/.openclaw/openclaw.json` (JSON5 format)
- **Schema:** Massive TypeBox schema system (`src/config/schema.ts`, `schema.hints.ts` at 46k, `schema.field-metadata.ts` at 45k)
- **Validation:** Zod schemas (`src/config/zod-schema.ts`, 20k)
- **Hot Reload:** Config changes apply without restart

### 2.4 Tech Stack

| Category | Technology |
|----------|-----------|
| **Language** | TypeScript (ESM) |
| **Runtime** | Node.js ≥22 (Bun also supported) |
| **Package Manager** | pnpm (bun optional) |
| **Build** | `tsdown` (based on Rolldown) |
| **Testing** | Vitest with V8 coverage |
| **Linting** | Oxlint + Oxfmt |
| **AI Runtime** | Pi agent (`@mariozechner/pi-agent-core`) in RPC mode |
| **Database** | SQLite with `sqlite-vec` for vector search |
| **Embedding** | OpenAI, Voyage, Gemini, or local ONNX |
| **HTTP** | Express 5 |
| **WebSocket** | `ws` library |

---

## 3. MyOwnOpenClaw — The Simplified Blueprint

The `MyOwnOpenClaw.png` diagram presents a **dramatically simplified** version of the same architecture, built with:

**Tools:** Claude Code + Claude Agent SDK + SQLite + Markdown + Obsidian

### The 4 Custom Modules

#### ① My Memory (SQLite + Markdown + Obsidian)

| Feature | Implementation |
|---------|---------------|
| `SOUL.md` | Personality & values |
| `USER.md` | Who I am, preferences |
| `MEMORY.md` | Decisions & lessons |
| `daily/` | Session logs |
| **Hybrid Search** | 0.7 × vector + 0.3 × keyword (BM25) |
| **Embeddings** | SQLite (or Postgres) + FastEmbed (384-dim, ONNX) |
| **Key principle** | Fully local — zero API calls |
| **Storage philosophy** | "Markdown IS the database" — Obsidian syncs it everywhere |

#### ② My Heartbeat (Claude Agent SDK + Python APIs)

| Feature | Implementation |
|---------|---------------|
| **Frequency** | Every 30 minutes |
| **Action** | Python gathers data from sources: Gmail, Calendar, Asana, Slack |
| **Reasoning** | Claude reasons over the data, decides what's important |
| **Notification** | Sends notification if needed |
| **Example** | "Meeting in 15 min — prep doc is empty" |
| **Fallback** | `HEARTBEAT_OK (nothing to report)` |

#### ③ My Adapters (Slack + Terminal)

| Feature | Implementation |
|---------|---------------|
| **Slack** | Socket Mode — no public URL needed; each thread = persistent conversation |
| **Terminal** | Claude Code — direct interaction; full skill + hook access either way |
| **One-shot** | With Claude Code |
| **Future** | Discord, Teams — add when needed |

#### ④ My Skills (Local `.claude/skills/`)

| Feature | Implementation |
|---------|---------------|
| **Location** | Local `.claude/skills/` directory |
| **Examples** | `content-engine/`, `direct-integrations/`, `yt-script/`, `pptx-generator/`, `excalidraw-diagram/`, `...15+ more` |
| **Installation** | Drop in `SKILL.md` — instantly available |
| **Security** | Local files only — NO public registry, no supply chain attack surface |

### The Vision: "Your Ultra-Personalized AI Agent"

> - 🔵 Remembers your decisions, preferences, and context  
> - 🟣 Checks your email and calendar — before you ask  
> - 🟢 Talk to it from Slack, terminal, anywhere  
> - 🟡 Add any capability with a single file  
>
> **"Acts on your behalf. Anticipates what you need. Knows you better every day."**

### Build Stack

```
Claude Code ──→ Claude Agent SDK ──→ SQLite + Markdown ──→ Obsidian
(skills + hooks)  (heartbeat + background)  (hybrid search, fully local)  (your canvas, sync anywhere)
```

**~2,000 lines of Python + Markdown** — "You can build it in just a couple days."

---

## 4. Side-by-Side Comparison

| Feature | OpenClaw (Full) | MyOwnOpenClaw (Custom) |
|---------|----------------|----------------------|
| **Codebase Size** | 175k+ lines TypeScript | ~2,000 lines Python + Markdown |
| **Language** | TypeScript (ESM) | Python |
| **AI Provider** | Any (Anthropic, OpenAI, etc. via Pi) | Claude (via Claude Agent SDK) |
| **Memory System** | SQLite + sqlite-vec, multiple embedding providers | SQLite + FastEmbed (384-dim ONNX) |
| **Hybrid Search** | Vector + BM25 (configurable weights) | 0.7 vector + 0.3 keyword (BM25) |
| **Embeddings** | OpenAI, Voyage, Gemini, local ONNX | FastEmbed local ONNX only — zero API calls |
| **Prompt Files** | SOUL.md, USER.md, AGENTS.md, HEARTBEAT.md, TOOLS.md | SOUL.md, USER.md, MEMORY.md, daily/ |
| **Heartbeat** | Full cron system with croner library | Simple 30-minute Python script |
| **Data Sources** | Configurable via plugins/skills | Gmail, Calendar, Asana, Slack |
| **Channels** | 15+ (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Teams, Matrix, etc.) | Slack (Socket Mode) + Terminal (Claude Code) |
| **Gateway** | Full WS control plane with auth, routing, sessions | None — direct connection |
| **Skills** | 52 bundled + ClawHub registry (5,700+) | Local `.claude/skills/` directory (15+ custom) |
| **Skill Format** | `SKILL.md` file in directory | `SKILL.md` file in directory (same pattern!) |
| **Apps** | macOS, iOS, Android, WebChat | None — Slack + CLI |
| **Voice** | Voice Wake + Talk Mode (ElevenLabs) | Not included |
| **Browser** | Playwright-based CDP control | Not included |
| **Canvas** | Agent-driven visual workspace (A2UI) | Not included |
| **Config** | JSON5 with massive schema validation | Simple Markdown files |
| **Sync** | File watcher (chokidar) | Obsidian sync |
| **Storage Philosophy** | SQLite is the DB | "Markdown IS the database" — Obsidian syncs everywhere |
| **Installation** | `npm install -g openclaw` + wizard | Clone repo + point Claude Code at it |
| **Security** | DM pairing, allowlists, Docker sandboxing | Local only by default |
| **Multi-agent** | Session isolation, agent-to-agent messaging | Not included |
| **Complexity** | Enterprise-grade, production-ready | Personal, lightweight, hackable |

---

## 5. Key Takeaways for Building Our Own

### What OpenClaw Gets Right (and we should learn from):

1. **The Memory Architecture** — The combination of identity files (`SOUL.md`, `USER.md`) + long-term memory (`MEMORY.md`) + session logs (`daily/`) is the core pattern. Both systems use this.

2. **Hybrid Search** — Vector + keyword search is essential for good memory retrieval. The 0.7/0.3 weighting is a good starting point.

3. **Skill Drop-in Pattern** — Just put a `SKILL.md` file in a directory and it's instantly available. No compilation, no registry. OpenClaw invented this pattern and the custom version copies it directly.

4. **Proactive Heartbeat** — Running on a schedule, checking your data sources before you ask. This is what makes the agent feel like an assistant rather than a chatbot.

5. **The Separation of Concerns** — Memory, Heartbeat, Adapters, and Skills are clean, independent modules. Each can be built and tested separately.

### What MyOwnOpenClaw Simplifies:

1. **No Gateway** — Direct connections instead of a WS control plane. Much simpler but less flexible.

2. **Python over TypeScript** — More accessible for quick prototyping and data processing.

3. **Claude-only** — No model switching, no failover. Simpler but locked to one provider.

4. **Obsidian as sync** — Uses Obsidian's existing sync infrastructure instead of building custom file watching.

5. **Two adapters max** — Slack + Terminal vs. 15+ channels. Start small, add as needed.

### The Process (from the diagram):

> 1. Clone the OpenClaw repository (MIT licensed, 100% open source)
> 2. Point your coding agent at it — "Explain how the memory system works"
> 3. "Now build that into my own system here (optional: with customization XYZ)"
> 4. Repeat for heartbeat, adapters, skills. That's it.

**Use OpenClaw as your blueprint, not your dependency.**

---

## 6. Recommended Build Process for Aetheel

Based on this analysis, here's the recommended order for building a custom AI assistant inspired by OpenClaw:

### Phase 1: Memory System
- Create `SOUL.md`, `USER.md`, `MEMORY.md` files
- Implement SQLite database with `sqlite-vec` or FastEmbed for vector search
- Build hybrid search (vector + BM25 keyword)
- Set up file watching for automatic re-indexing
- Use Obsidian for cross-device sync

### Phase 2: Heartbeat
- Build a Python script using Claude Agent SDK
- Connect to Gmail, Calendar, Asana (start with most-used services)
- Set up 30-minute cron schedule
- Implement notification delivery (start with terminal notifications)

### Phase 3: Adapters
- Start with Terminal (Claude Code) for direct interaction
- Add Slack (Socket Mode) for messaging
- Build conversation threading support

### Phase 4: Skills
- Create `.claude/skills/` directory structure
- Port most-used skills from OpenClaw as inspiration
- Build custom skills specific to your workflow

---

## Appendix: OpenClaw File Structure Reference

```
openclaw/
├── src/                          # Core source code (175k+ LOC)
│   ├── memory/                   # Memory system (49 files)
│   │   ├── manager.ts            # Main memory manager (2,300 LOC)
│   │   ├── hybrid.ts             # Hybrid search (vector + keyword)
│   │   ├── embeddings.ts         # Embedding provider abstraction
│   │   ├── qmd-manager.ts        # Query+doc management (33k)
│   │   └── ...
│   ├── cron/                     # Heartbeat/cron system (37 files)
│   │   ├── service/              # Cron service lifecycle
│   │   ├── schedule.ts           # Scheduling logic
│   │   ├── delivery.ts           # Output delivery
│   │   └── ...
│   ├── channels/                 # Channel adapter framework (28 files)
│   │   ├── dock.ts               # Unified channel dock (17k)
│   │   ├── registry.ts           # Channel registration
│   │   └── ...
│   ├── gateway/                  # Gateway WS control plane (129+ files)
│   │   ├── server.impl.ts        # Main server (22k)
│   │   ├── server-http.ts        # HTTP layer (17k)
│   │   ├── session-utils.ts      # Session management (22k)
│   │   └── ...
│   ├── config/                   # Configuration system (130+ files)
│   ├── agents/                   # Agent runtime
│   ├── browser/                  # Browser control (Playwright)
│   └── ...
├── skills/                       # Built-in skills (52 directories)
│   ├── obsidian/
│   ├── github/
│   ├── notion/
│   ├── spotify-player/
│   └── ...
├── extensions/                   # Extension channels (35 directories)
│   ├── msteams/
│   ├── matrix/
│   ├── voice-call/
│   └── ...
├── apps/                         # Companion apps
│   ├── macos/
│   ├── ios/
│   └── android/
├── AGENTS.md                     # Agent behavior guidelines
├── openclaw.json                 # Configuration
└── package.json                  # Dependencies & scripts
```