SoulClaw

Soul-aware OpenClaw fork — enhanced memory, persona, and security for AI agents.

Forked from OpenClaw main branch at v2026.3.1 (MIT License).

SoulClaw is a fork of OpenClaw optimized for the ClawSouls ecosystem. It adds a 3-Tier long-term memory system, semantic memory search, persona drift detection, inline security scanning, and native swarm memory synchronization — all running locally.

What's new in 2026.7.1

• Rebased onto OpenClaw v2026.7.1 — brings four months of upstream work onto the new extensions/ plugin architecture (providers, channels, and memory now ship as extensions).
• /dreaming — idle-time memory synthesis (light → REM → deep sweeps) with a promotion policy that writes to MEMORY.md and keeps a DREAMS.md diary.
• Video & music generation — built-in video_generate tool (xAI grok-imagine-video / Alibaba Wan / Runway) plus music generation (Google Lyria / MiniMax).
• Soul Memory ported into the memory-core extension — the full 4-tier store (DAG lossless SQLite + FTS5, bge-m3 semantic search, T2→T1 promotion, tier stats, T2 compaction) is preserved on the new architecture.
• Compaction notification rewired into upstream agent-hooks; topic snapshots (/topic), inline SoulScan, Persona Engine, native Swarm Memory, tiered bootstrap, and soulclaw host all carried forward.
• New Node requirement — Node.js >=22.22.3 <23, >=24.15.0 <25, or >=25.9.0 (see Requirements).
• Installed from source for now — the soulclaw npm package still serves the previous stable 2026.3.x line until monorepo npm packaging lands (see Installation).

🧠 Soul Memory — 4-Tier Adaptive Memory Architecture

SoulClaw agents never forget while maintaining coherent identity. Soul Memory separates identity from experience through a 4-tier hierarchy with temporal decay and automatic promotion:

┌─────────────────────────────────────────────┐
│  T0: SOUL (Identity)                        │
│  SOUL.md, IDENTITY.md                       │
│  Immutable. Human-authorized changes only.  │
│  "Who I am"                                 │
├─────────────────────────────────────────────┤
│  T1: CORE MEMORY (Evergreen)                │
│  MEMORY.md, memory/roadmap.md, etc.         │
│  No decay. Curated knowledge.               │
│  "What I must never forget"                 │
├─────────────────────────────────────────────┤
│  T2: WORKING MEMORY (Temporal)              │
│  memory/2026-03-19.md (dated files)         │
│  Decay: half-life 23 days.                  │
│  "What happened recently"                   │
├─────────────────────────────────────────────┤
│  T3: SESSION MEMORY (Ephemeral)             │
│  Current conversation context.              │
│  Gone after session ends.                   │
│  "What we're talking about right now"       │
└─────────────────────────────────────────────┘

T0: Soul (Identity)

Your agent's SOUL.md and IDENTITY.md. These define who the agent is — personality, values, behavioral rules. They're loaded fresh every session, never modified by the agent, and never subject to search decay.

Defense against Memory-Identity Paradox: No matter how much experience accumulates, the identity anchor remains unchanged.

T1: Core Memory (Evergreen)

MEMORY.md and undated topic files (memory/roadmap.md, memory/legal.md). These store curated, long-term knowledge: decisions, architecture choices, key relationships, strategies.

No temporal decay. Core memories are always at full relevance, whether they were written today or a year ago.

T2: Working Memory (Temporal)

Date-stamped files like memory/2026-03-19.md. These are daily work logs, debug notes, meeting records, task progress.

Temporal decay with 23-day half-life: Today's working memory has full relevance. Last week's has 81%. Last month's has 41%. Three months ago? 7%.

Important working memories are automatically promoted to Core Memory (T1) based on:

• Rule-based detection (decisions, architecture, financial, legal terms)
• Access frequency (memories retrieved 3+ times across sessions)
• Weekly review with human approval

Configuration

Soul Memory activates with embedding provider + temporal decay:

// openclaw.json
{
  "agents": {
    "defaults": {
      "memorySearch": {
        "provider": "ollama", // "ollama" | "openai" | "gemini"
        "model": "bge-m3", // Recommended: multilingual
        "query": {
          "hybrid": {
            "temporalDecay": {
              "enabled": true,
              "halfLifeDays": 23, // 23-day half-life for T2
            },
          },
        },
      },
    },
  },
}

Memory Promotion CLI

Scan for promotion candidates:

openclaw memory promote --days 7          # Last 7 days
openclaw memory promote --frequency       # Show frequently accessed

Execute promotions:

openclaw memory promote --apply           # Auto-promote to MEMORY.md
openclaw memory promote --apply --target memory/legal.md  # Specific file

⚡ Tiered Bootstrap Loading

Save 40-60% tokens on every conversation.

OpenClaw loads ALL workspace files into every system prompt. SoulClaw introduces progressive disclosure:

# Typical savings (236 memory files):
# OpenClaw:  ~12,000 tokens/turn (all files loaded)
# SoulClaw:  ~4,500 tokens/turn (Tier 1 only on continuation)
# Savings:   ~62% fewer tokens per turn

Disable with SOULCLAW_TIERED_BOOTSTRAP=0 if you want upstream behavior.

Features

🔍 Semantic Memory Search

Vector-based memory retrieval using local Ollama embeddings.

• Ollama bge-m3 embeddings (1024d, 100+ languages)
• SQLite + sqlite-vec vector index
• Incremental updates (only re-embed changed chunks)
• Auto-fallback to text matching if Ollama unavailable
• Cross-lingual search (Korean/English/Japanese/etc.)

🎭 Persona Engine

Soul Spec-native persona management with drift detection and automatic recovery.

• Soul Spec v0.3 parsing
• Real-time persona drift scoring
• Automatic prompt reinforcement on drift

🛡️ Inline SoulScan

Built-in security scanning — no external CLI dependency.

• 4-stage scanning pipeline (Schema → File → Security → Quality)
• Auto-scan on soul apply
• Risk scoring (0-100)
• Dangerous soul blocking

🔄 Native Swarm Memory

Automatic agent memory synchronization via heartbeat.

• Auto pull/push on heartbeat cycle
• LLM-based conflict resolution
• Workspace auto-sync after merge

📦 Contained Runtime

Full runtime isolation for embedded environments (VSCode extensions, etc).

• OPENCLAW_STATE_DIR respected for all paths including workspace
• No pollution of user's ~/.openclaw/ directory
• Drop-in replacement for OpenClaw

Installation

npm (previous stable, 2026.3.x)

The soulclaw npm package currently serves the previous stable 2026.3.x line:

npm install -g soulclaw

From source (2026.7.1)

v2026.7.1 is installed from source until monorepo npm packaging lands:

git clone -b migrate/v2026.7.1 https://github.com/clawsouls/soulclaw.git
cd soulclaw
pnpm install
node scripts/build-all.mjs
node openclaw.mjs --version

Quick Start

# Start gateway
soulclaw gateway start

# With contained runtime (for extensions/embedding)
OPENCLAW_STATE_DIR=/path/to/state soulclaw gateway start

Security defaults (DM access)

OpenClaw connects to real messaging surfaces. Treat inbound DMs as untrusted input.

Full security guide: Security.
Before remote exposure, use the Gateway exposure runbook.

Default behavior on Telegram/WhatsApp/Signal/iMessage/Microsoft Teams/Discord/Google Chat/Slack:

• DM pairing (dmPolicy="pairing" / channels.discord.dmPolicy="pairing" / channels.slack.dmPolicy="pairing"; legacy: channels.discord.dm.policy, channels.slack.dm.policy): unknown senders receive a short pairing code and the bot does not process their message.
• Approve with: openclaw pairing approve <channel> <code> (then the sender is added to a local allowlist store).
• Public inbound DMs require an explicit opt-in: set dmPolicy="open" and include "*" in the channel allowlist (allowFrom / channels.discord.allowFrom / channels.slack.allowFrom; legacy: channels.discord.dm.allowFrom, channels.slack.dm.allowFrom).

Run openclaw doctor to surface risky/misconfigured DM policies.

Highlights

• Local-first Gateway — single control plane for sessions, channels, tools, and events.
• Multi-channel inbox — WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, iMessage, IRC, Microsoft Teams, Matrix, Feishu, LINE, Mattermost, Nextcloud Talk, Nostr, Synology Chat, Tlon, Twitch, Zalo, Zalo Personal, WeChat, QQ, WebChat, macOS, iOS/Android.
• Multi-agent routing — route inbound channels/accounts/peers to isolated agents (workspaces + per-agent sessions).
• Voice Wake + Talk Mode — wake words on macOS/iOS and continuous voice on Android (ElevenLabs + system TTS fallback).
• Live Canvas — agent-driven visual workspace with A2UI.
• First-class tools — browser, canvas, nodes, cron, sessions, and Discord/Slack actions.
• Companion apps — Windows Hub, macOS menu bar app, and iOS/Android nodes.
• Onboarding + skills — onboarding-driven setup with bundled/managed/workspace skills.

Security model (important)

• Default: tools run on the host for the main session, so the agent has full access when it is just you.
• Group/channel safety: set agents.defaults.sandbox.mode: "non-main" to run non-main sessions inside sandboxes. Docker is the default sandbox backend; SSH and OpenShell backends are also available.
• Typical sandbox default: allow bash, process, read, write, edit, sessions_list, sessions_history, sessions_send, sessions_spawn; deny browser, canvas, nodes, cron, discord, gateway.
• Before exposing anything remotely, read Security, Gateway exposure runbook, Sandboxing, and Configuration.

Operator quick refs

• Chat commands: /status, /new, /reset, /compact, /think <level>, /verbose on|off, /trace on|off, /usage off|tokens|full, /restart, /activation mention|always
• Session tools: sessions_list, sessions_history, sessions_send
• Skills registry: ClawHub
• Architecture overview: Architecture

Docs by goal

• New here: Getting started, Onboarding, Updating
• Channel setup: Channels index, WhatsApp, Telegram, Discord, Slack
• Apps + nodes: Windows Hub, macOS, iOS, Android, Nodes
• Config + security: Configuration, Security, Exposure runbook, Sandboxing
• Remote + web: Gateway, Remote access, Tailscale, Web surfaces
• Tools + automation: Tools, Skills, Cron jobs, Webhooks, Gmail Pub/Sub
• Internals: Architecture, Agent, Session model, Gateway protocol
• Troubleshooting: Channel troubleshooting, Logging, Docs home

Apps (optional)

The Gateway alone delivers a great experience. All apps are optional and add extra features.

If you plan to build/run companion apps, follow the platform runbooks below.

macOS (OpenClaw.app) (optional)

• Menu bar control for the Gateway and health.
• Voice Wake + push-to-talk overlay.
• WebChat + debug tools.
• Remote gateway control over SSH.

Note: signed builds required for macOS permissions to stick across rebuilds (see macOS Permissions).

iOS node (optional)

• Pairs as a node over the Gateway WebSocket (device pairing).
• Voice trigger forwarding + Canvas surface.
• Controlled via openclaw nodes ….

Android node (optional)

• Pairs as a WS node via device pairing (openclaw devices ...).
• Exposes Connect/Chat/Voice tabs plus Canvas, Camera, Screen capture, and Android device command families.
• Runbook: Android connect.

Setting Up Ollama for Memory Search

SoulClaw uses Ollama for local embedding generation. No API keys needed.

1. Install Ollama

# macOS / Linux
curl -fsSL https://ollama.com/install.sh | sh

2. Pull the embedding model

ollama pull bge-m3

Why bge-m3? Multilingual embedding model (100+ languages) that handles mixed-language content accurately.

3. Verify

ollama list  # Should show bge-m3

SoulClaw auto-detects Ollama on startup and begins indexing memory files.

Hardware Compatibility

Using a different embedding model

// openclaw.json
{
  "agents": {
    "defaults": {
      "memorySearch": {
        "provider": "local",
        "embedding": {
          "model": "nomic-embed-text",
          "ollamaUrl": "http://localhost:11434",
        },
      },
    },
  },
}

Without Ollama

SoulClaw works without Ollama — it falls back to keyword-based text matching. Ollama makes search significantly more accurate.

Roadmap

Upstream Compatibility

All OpenClaw features, plugins, and configurations work as-is. SoulClaw adds functionality — it doesn't remove or break anything.

The openclaw/main branch tracks upstream for migration purposes.

Requirements

• Node.js >=22.22.3 <23, >=24.15.0 <25, or >=25.9.0 (upstream requirement)
• Ollama (optional but recommended)
  • bge-m3 — memory search embeddings (default)

Ecosystem

SoulClaw is part of the ClawSouls ecosystem:

• ClawSouls — AI agent persona platform
• Soul Spec — Open specification for agent identity
• SoulClaw CLI Guide — Detailed usage guide (SoulScan, Persona Engine, Swarm Memory)
• ClawSouls CLI — Soul management, SoulScan, checkpoints

License

MIT — same as OpenClaw.

Credits

Built on OpenClaw by the OpenClaw team.
Enhanced by ClawSouls for the soul-aware agent ecosystem.