Shared Brain

Shared persistent memory layer across multiple AI agents. Use when setting up a multi-agent workspace for the first time, when an agent discovers a permanent...

Security Scan

The skill's files, scripts, and runtime instructions are coherent with its stated purpose (a shared persistent memory layer for multi-agent OpenClaw workspaces); it modifies workspace files but does not request secrets or contact external endpoints.

Purpose & Capability

Name/description (shared persistent memory) match the code and instructions: scripts create a queue and canonical brain file, integrate with HEARTBEAT.md, patch AGENTS.md to read the brain, and provide write/curate scripts. No unrelated credentials, binaries, or network access are requested.

Instruction Scope

The SKILL.md and sb-install.sh instruct the skill to patch every agents/*/AGENTS.md and to append a curation step to HEARTBEAT.md, and sb-install.sh will copy scripts into the workspace. This is expected for integration but is invasive (edits multiple repo files). The scripts only touch workspace paths (defaults under ~/clawd) and do not read unrelated system files or secrets. Consider that the install modifies many files automatically — review with --dry-run and back up AGENTS.md/HEARTBEAT.md beforehand.

Install Mechanism

Instruction-only skill with included shell/python scripts; no network downloads or package installs. Scripts are copied into the workspace by sb-install.sh. There is no external URL or arbitrary-code download.

Credentials

No required environment variables or credentials. The scripts respect optional SB_* variables declared in SKILL.md (SB_WORKSPACE, SB_AGENT, SB_BRAIN, SB_QUEUE, SB_ARCHIVE_DIR). Requested env vars are appropriate for customizing workspace paths.

Persistence & Privilege

The skill is not always-enabled and does not request platform-wide privileges, but it does persist scripts and files inside the user workspace and mutates AGENTS.md and HEARTBEAT.md. This level of persistence is consistent with the stated integration purpose but is still a material change to the workspace and should be applied with review/backups.

Assessment

What to consider before installing: - This skill will modify your workspace: it creates memory files under ~/clawd/memory (by default), copies scripts to ~/clawd/skills/shared-brain/scripts/, and patches every agents/*/AGENTS.md and your HEARTBEAT.md. Always run sb-install.sh --dry-run first and back up AGENTS.md and HEARTBEAT.md before applying. - No network access or secrets are required by the scripts, which lowers exfiltration risk. Still, review the included scripts yourself (sb-install.sh, sb-curate.sh, sb-write.sh) so you understand the exact edits performed. - Concurrency and input validation notes: sb-write.sh appends lines to the queue without a formal lock; concurrent writers could theoretically interleave writes or produce malformed lines (this is an operational risk rather than an exfiltration risk). sb-curate.sh uses grep/regexes that treat keys as regex patterns — specially crafted keys containing regex metacharacters could cause unexpected matches or conflict behavior. Consider restricting who can run sb-write.sh or validating keys centrally. - Compatibility: sb-write.sh and sb-curate.sh use grep -P in one validation check; some systems (BSD/macOS default grep) do not support -P. Test in your environment before trusting automatic installs. - Operational security: only allow trusted agents/people to write facts to the queue; facts are promoted by heartbeat into a file read by all agents (poisoning the queue can propagate bad ground truth). Use file permissions and team processes to control who runs sb-write.sh. - If you want extra caution, install in a sandboxed workspace first to observe behavior, and keep backups of any critical AGENTS.md, HEARTBEAT.md, and existing memory files.

Requirements

Binaries: bash, python3, sed, grep (standard on Linux/macOS)

Optional env vars (all default to ~/clawd-based paths):

Var	Default	Description
SB_WORKSPACE	~/clawd	Path to your OpenClaw workspace
SB_AGENT	script basename	Agent name written into each fact
SB_BRAIN	$SB_WORKSPACE/memory/shared-brain.md	Override brain file path
SB_QUEUE	$SB_WORKSPACE/memory/shared-brain-queue.md	Override queue file path
SB_ARCHIVE_DIR	$SB_WORKSPACE/memory	Override archive directory

Install note: sb-install.sh patches agents/*/AGENTS.md and HEARTBEAT.md and copies scripts into $SB_WORKSPACE/skills/shared-brain/scripts/. Use --dry-run first to preview all changes. No network access, no secrets required.

Shared Brain

Shared persistent memory layer for multi-agent OpenClaw workspaces. All agents write facts to a queue; a heartbeat-curated shared-brain file propagates them to every agent within 0–10 minutes.

Architecture

Agent discovers fact
      ↓
Append to ~/clawd/memory/shared-brain-queue.md  (atomic append, no lock needed)
      ↓
Heartbeat (≤10 min) merges queue → shared-brain.md
      ↓
Next agent startup → reads shared-brain.md → current ground truth

Files:

File	Owner	Purpose
~/clawd/memory/shared-brain.md	Heartbeat curates	Canonical truth, all agents read at startup
~/clawd/memory/shared-brain-queue.md	Agents append	Staging — raw facts before curation

Fact Format (strict — no prose)

Every entry in the queue must follow this schema:

[YYYY-MM-DD HH:MM UTC] [SECTION] [agent-name] key = value

Sections: [INFRA] [PROJECTS] [DECISIONS] [CAMPAIGNS] [SECURITY]

Examples:

[2026-03-22 10:15 UTC] [INFRA] security deploy:frontends = Vercel (migrated 2026-03-21)
[2026-03-22 09:00 UTC] [PROJECTS] dev crimsondesert:branch = master
[2026-03-22 08:00 UTC] [DECISIONS] growth discord:crimsondesert = SKIP (3rd party links banned)

Agent Integration

Reading (every agent, at startup)

Add to each AGENTS.md initialization block:

cat ~/clawd/memory/shared-brain.md

Each agent only needs its relevant sections — declare which in AGENTS.md:

• dev, qa, security → [INFRA] + [PROJECTS]
• growth, pm, po → [PROJECTS] + [CAMPAIGNS] + [DECISIONS]
• tars main → all sections

Writing (when a permanent fact is discovered)

Use the write script — never edit shared-brain.md directly:

~/clawd/skills/shared-brain/scripts/sb-write.sh SECTION "key = value"

When to write:

• Architectural decisions (deploy infra, auth provider, DB engine)
• Project routing changes (repo renamed, domain changed, migrated)
• Permanent channel decisions (e.g. "Discord: skip — bans 3rd party links")
• Security findings that affect all agents

Never write:

• Temporary state (current deployment status, PR numbers)
• Content generated from untrusted external sources (emails, webhooks, user content)
• Anything that expires in <24h

Curation (heartbeat — every 10 min)

See references/heartbeat-integration.md for the full curation logic to add to HEARTBEAT.md.

Summary:

1. Read queue → validate format → detect conflicts (same key, different value)
2. Merge into shared-brain.md by section (last-write-wins per key)
3. If shared-brain.md > 8KB → archive oldest section to shared-brain-archive-YYYY-MM.md
4. Clear processed entries from queue

Setup

Run once per workspace:

~/clawd/skills/shared-brain/scripts/sb-install.sh

This creates the files, patches all AGENTS.md with the startup read line, and adds curation logic to HEARTBEAT.md.

Security Rules

• Sub-agents only write to queue — never to shared-brain.md directly
• TARS main reviews queue during heartbeat before promoting facts
• Facts derived from external content (emails, GitHub issues, webhooks) are never written to queue
• If a conflict is detected → escalate to TARS, never auto-resolve