Soul-aware OpenClaw fork — enhanced memory, persona, and security for AI agents.
Forked from OpenClaw (MIT License). Current base: upstream
v2026.8.1(tagupstream-v2026.8.1); the fork started atv2026.3.1.
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.
v2026.8.1) — the SoulClaw layer was re-applied on top of the upstream release instead of being merged forward from 2026.7.x, which had fallen ~21k commits behind. You get every 2.0 change: simplified install, SQLite-backed sessions, browser/computer control, shared sessions, the new security model.memory-wiki plugin). SoulClaw no longer bundles the 2026.7.x memory engine; it will return as a plugin on top of upstream memory in a follow-up release. The tiered bootstrap loading rules below are unchanged./topic snapshots, the bundled session hooks and soulclaw host.session-start-index hook had been failing silently since 2026.7.x (it imported a path that did not exist in the built bundle); it is wired to the 2.0 memory runtime again.~/.openclaw before upgrading from 2026.7.x; sessions created after the migration are not visible to older releases.>=22.22.3 <23, >=24.15.0 <25, or >=25.9.0 (see Requirements).OpenClaw 2.0 introduced a built-in memory system that covers most of what SoulClaw's
2026.7.x 4-tier engine did: plain files plus one SQLite index, trust-tiered writes,
per-turn recall with an escalating deep-recall lane (Active Memory), and a compiled
knowledge vault (memory-wiki). Rather than run two memory engines side by side,
this release uses upstream memory unchanged and retires the bundled 7.x engine.
What stays SoulClaw-specific — and is unchanged in this release:
The SoulClaw memory layer returns as a plugin on top of upstream memory in a
follow-up release. Until then, memory_search and the upstream CLI (openclaw memory)
are the tools to use.
Save 40-60% tokens on every conversation.
OpenClaw loads ALL workspace files into every system prompt. SoulClaw introduces progressive disclosure:
| Tier | Files | When |
|---|---|---|
| Tier 1 (Always) | SOUL.md, IDENTITY.md, AGENTS.md | Every turn — core identity |
| Tier 2 (First turn) | TOOLS.md, USER.md, BOOTSTRAP.md | New session only — session context |
| Tier 3 (On demand) | MEMORY.md, memory/*.md | Never injected — use memory_search tool |
# 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.
Vector-based memory retrieval using local Ollama embeddings.
bge-m3 embeddings (1024d, 100+ languages)Soul Spec-native persona management with drift detection and automatic recovery.
Built-in security scanning — no external CLI dependency.
Automatic agent memory synchronization via heartbeat.
Full runtime isolation for embedded environments (VSCode extensions, etc).
OPENCLAW_STATE_DIR respected for all paths including workspace~/.openclaw/ directorynpm install -g soulclaw
This installs SoulClaw 2026.8.1 (rebased onto OpenClaw v2026.8.1). Requires Node.js >=22.22.3 <23, >=24.15.0 <25, or >=25.9.0.
git clone https://github.com/clawsouls/soulclaw.git
cd soulclaw
pnpm install
node scripts/build-all.mjs
node openclaw.mjs --version
# Start gateway
soulclaw gateway start
# With contained runtime (for extensions/embedding)
OPENCLAW_STATE_DIR=/path/to/state soulclaw gateway start
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:
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.openclaw pairing approve <channel> <code> (then the sender is added to a local allowlist store).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.
main session, so the agent has full access when it is just you.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.bash, process, read, write, edit, sessions_list, sessions_history, sessions_send, sessions_spawn; deny browser, canvas, nodes, cron, discord, gateway./status, /new, /reset, /compact, /think <level>, /verbose on|off, /trace on|off, /usage off|tokens|full, /restart, /activation mention|alwayssessions_list, sessions_history, sessions_sendThe 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.
Note: signed builds required for macOS permissions to stick across rebuilds (see macOS Permissions).
openclaw nodes ….openclaw devices ...).SoulClaw uses Ollama for local embedding generation. No API keys needed.
# macOS / Linux
curl -fsSL https://ollama.com/install.sh | sh
ollama pull bge-m3
Why bge-m3? Multilingual embedding model (100+ languages) that handles mixed-language content accurately.
| Model | Dimensions | Multilingual | RAM | Recommended |
|---|---|---|---|---|
bge-m3 | 1024 | ✅ 100+ languages | ~1.3GB | ✅ Default |
nomic-embed-text | 768 | ❌ English only | ~0.3GB | English-only workspaces |
ollama list # Should show bge-m3
SoulClaw auto-detects Ollama on startup and begins indexing memory files.
| Environment | Speed (per query) |
|---|---|
| Apple Silicon (M1-M4) | ~50ms (Metal GPU) |
| NVIDIA GPU (CUDA) | ~30ms |
| CPU only | ~500ms |
// openclaw.json
{
"agents": {
"defaults": {
"memorySearch": {
"provider": "local",
"embedding": {
"model": "nomic-embed-text",
"ollamaUrl": "http://localhost:11434",
},
},
},
},
}
SoulClaw works without Ollama — it falls back to keyword-based text matching. Ollama makes search significantly more accurate.
| Tag | Status | Description |
|---|---|---|
soulclaw/v2026.8.1 | 🚧 Publishing | Rebuilt on OpenClaw 2.0 (v2026.8.1); upstream memory used as-is, 7.x engine retired |
soulclaw/v2026.3.3 | ✅ Released | Contained runtime (OPENCLAW_STATE_DIR workspace fix) |
soulclaw/v2026.3.4 | ✅ Released | Semantic memory search (bge-m3 vector embeddings) |
soulclaw/v2026.3.5 | ✅ Released | Persona engine + Inline SoulScan + Native Swarm Memory |
soulclaw/v2026.3.6 | ✅ Released | Tiered bootstrap loading (40-60% token savings) |
soulclaw/v2026.3.12 | ✅ Released | Stability improvements + upstream sync |
soulclaw/v2026.3.17 | ✅ Released | Passive memory auto-extraction |
soulclaw/v2026.3.18 | ✅ Released | DAG lossless memory store (SQLite + FTS5) |
soulclaw/v2026.3.19 | ✅ Released | DAG FTS5 → memory_search pipeline integration |
soulclaw/v2026.3.20 | ✅ Released | Network stability fix (IPv6 auto-fallback) |
soulclaw/v2026.3.21–v2026.3.37 | ✅ Released | Topic snapshots, compaction notify, session hooks, soulclaw host, stability |
soulclaw/v2026.8.1 | 🔄 Tagging | Rebase onto OpenClaw v2026.8.1 — extensions architecture, dreaming, video/music, memory-core port |
| Version | |
|---|---|
| Fork base | OpenClaw v2026.3.1 (main branch) |
| Current SoulClaw | 2026.8.1 |
| License | MIT (same as OpenClaw) |
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.
>=22.22.3 <23, >=24.15.0 <25, or >=25.9.0 (upstream requirement)bge-m3 — memory search embeddings (default)SoulClaw is part of the ClawSouls ecosystem:
MIT — same as OpenClaw.
Built on OpenClaw by the OpenClaw team. Enhanced by ClawSouls for the soul-aware agent ecosystem.
FAQs
Soul-aware OpenClaw fork — enhanced memory search and contained runtime
The npm package soulclaw receives a total of 6 weekly downloads. As such, soulclaw popularity was classified as not popular.
We found that soulclaw demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Company News
Socket is joining the OpenJS Security Stewardship Program to fund Node.js vulnerability research, maintainer remediation, and security releases.
Security News
Two compromised GitHub Actions were re-enabled with malicious tags intact, exposing thousands of downstream repositories to Mini Shai-Hulud.
Research
/Security News
A malicious Firefox extension fetches its payload after installation to evade detection, steal Google session cookies, and automate account takeover.