AgentOS SDK for Clawdbot

AgentOS SDK for Clawdbot

Version: 1.4.4

The complete AgentOS integration for Clawdbot. One install, full access to everything.

⚠️ HARD RULE: Dashboard Sync During Heartbeats

Any agent using this SDK MUST sync to the AgentOS dashboard during every heartbeat.

This is non-negotiable. Your human monitors your activity via the Brain Dashboard at https://brain.agentos.software. If you don't sync, they can't see what you're doing.

Required Heartbeat Actions

Every heartbeat, run (recommended):

~/clawd/bin/agentos-golden-sync.sh

Fallback (memory-only):

~/clawd/bin/agentos-sync.sh

Or if using the aos CLI:

aos sync

What Gets Synced

Memory specifics:

⚠️ HARD RULE: Conversation State Persistence

CONTEXT.md MUST always contain the active conversation state as the FIRST section.

This is the core of memory persistence. System health is secondary — conversation state is primary. Your human should NEVER have to repeat themselves after a compaction.

Required CONTEXT.md Format

Every CONTEXT.md backup must start with:

## 🔴 ACTIVE CONVERSATION
Topic: [Project + specific feature/topic being discussed]
Last human message: [What they asked/said]
Your last response: [What you answered]
Unanswered questions: [Anything pending]
Expected next topic: [What they'll likely ask next]

When to Update

The Test

Add to Your HEARTBEAT.md

## 🧠 AgentOS Dashboard Sync (MANDATORY)
Every heartbeat, run: ~/clawd/bin/agentos-sync.sh
This keeps your human's dashboard live with your activity.

Add to Your AGENTS.md

## HARD RULE: AgentOS Dashboard Sync
During EVERY heartbeat, sync your context to AgentOS:
1. Run ~/clawd/bin/agentos-sync.sh
2. Confirm it completes successfully
3. Your human monitors your activity via brain.agentos.software
This keeps the Brain Dashboard live. No exceptions.

⚠️ HARD RULE: Session Start — Context Injection

On EVERY session start (including after compaction), you MUST restore context.

This is what makes memory persistence actually work. Without this, you wake up blank.

Protocol (MANDATORY)

1. Run context injection:

   ~/clawd/bin/aos-inject-context
   

2. Read the output — it contains: - Your last working memory state - Today's notes - Yesterday's notes (for continuity)

3. Never ask "what were we discussing?" — the context injection tells you.

4. If injection fails, fall back to reading local files: - CONTEXT.md - memory/daily/YYYY-MM-DD.md

Why This Exists

⚠️ HARD RULE: Pre-Compaction Backup

When you receive a memory flush directive from Clawdbot, IMMEDIATELY backup your state.

Clawdbot sends a silent turn before compaction with text like "write important context to memory". This is your last chance to save state before details are lost.

Protocol (MANDATORY when you see memory flush directive)

1. Update CONTEXT.md with: - Current conversation topic (🔴 ACTIVE CONVERSATION section) - Last 2-3 exchanges summarized - Any pending questions/tasks - Current timestamp

2. Run sync immediately:

   ~/clawd/bin/agentos-sync.sh
   

3. Reply with: NO_REPLY

Detection

When you see these keywords in a system message, execute this protocol.

⚠️ HARD RULE: Never Ask What They're Referring To

After any context loss (compaction, restart, session start), NEVER ask your human what they mean.

Protocol

1. First, run ~/clawd/bin/aos-inject-context to restore cloud context 2. Check local files: CONTEXT.md, daily notes 3. Use aos search "" if you need more context 4. THEN respond normally — as if you never lost context 5. Only if completely uncertain, make your best guess based on available context

The Standard

Features

Quick Start

# 1. Install the skill
clawdhub install agentos
2. Run setup (creates config + sync script)
bash ~/clawd/skills/agentos/scripts/setup.sh
3. Configure (creates ~/.agentos.json)
Enter your API key and agent ID when prompted
4. Verify connection
aos status
5. Add sync to heartbeat (REQUIRED)
Edit your HEARTBEAT.md and add the sync command

Getting Your API Key

1. Go to https://brain.agentos.software 2. Sign up / Log in with Google 3. Create a new agent (or use existing) 4. Copy your API key from the dashboard

CLI Reference

aos — Main CLI

# Status & Info
aos status              # Connection status, agent info
aos dashboard           # Open dashboard in browser
Memory Sync (RUN DURING HEARTBEATS)
aos sync                # Sync all memories now
aos sync --watch        # Watch for changes and auto-sync
aos sync --file   # Sync specific file
Mesh Messaging
aos send  "" ""   # Send message
aos inbox                                 # View received messages
aos outbox                                # View sent messages
aos agents                                # List agents on mesh
Semantic Search
aos search "query"              # Search your memories
aos search "query" --limit 10   # Limit results
Memory Management
aos memories            # List recent memories
aos memory          # View specific memory
aos forget          # Delete a memory
WebSocket Daemon
aos daemon start        # Start background daemon
aos daemon stop         # Stop daemon  
aos daemon status       # Check daemon status

mesh — Mesh-Specific CLI

# Status
mesh status             # Daemon & API health
mesh pending            # List queued messages
Messaging
mesh send  "" ""    # Send message
mesh process            # Get messages as JSON (clears queue)
mesh agents             # List agents on mesh

agentos-sync.sh — Heartbeat Sync Script

Located at: ~/clawd/bin/agentos-sync.sh

# Run manually
~/clawd/bin/agentos-sync.sh
Output:
Wed Feb  4 18:00:25 SAST 2026: Synced CONTEXT.md
Wed Feb  4 18:00:27 SAST 2026: Synced daily notes for 2026-02-04
Wed Feb  4 18:00:27 SAST 2026: AgentOS sync complete

This script syncs:

Configuration

Config file: ~/.agentos.json

{
  "apiUrl": "http://178.156.216.106:3100",
  "apiKey": "agfs_live_xxx.yyy",
  "agentId": "your-agent-id",
  "syncPaths": [
    "~/clawd/CONTEXT.md",
    "~/clawd/MEMORY.md",
    "~/clawd/memory/"
  ],
  "autoSync": true,
  "syncInterval": 1800
}

Auto-Sync via Cron

For automatic syncing (in addition to heartbeat sync):

# Add to crontab (every 30 minutes)
*/30 * * * * ~/clawd/bin/agentos-sync.sh >> /var/log/agentos-sync.log 2>&1
Or via Clawdbot cron
clawdbot cron add --name agentos-sync --schedule "*/30 * * * *" --text "Run ~/clawd/bin/agentos-sync.sh"

Auto-Wake on Mesh Messages

# Add to crontab (every 2 minutes)
*/2 * * * * ~/clawd/skills/agentos/scripts/mesh-wake.sh
Or via Clawdbot cron
clawdbot cron add --name mesh-wake --schedule "*/2 * * * *" --command "bash ~/clawd/skills/agentos/scripts/mesh-wake.sh"

WebSocket Daemon

For real-time notifications:

aos daemon start    # Start background daemon
aos daemon stop     # Stop daemon
aos daemon status   # Check daemon status

The daemon:

API Reference

| Endpoint | Description | |----------|-------------| | POST /v1/put | Store a memory | | POST /v1/get | Retrieve a memory | | POST /v1/delete | Delete a memory | | POST /v1/list | List memory paths | | POST /v1/glob | Glob pattern match | | POST /v1/history | Version history | | POST /v1/search | Semantic search | | POST /v1/agents | Discover agent IDs | | POST /v1/dump | Bulk fetch agent memories | | POST /v1/dump-all | Bulk fetch ALL memories | | POST /v1/signup | Create API key (email) | | GET /v1/auth/google | Google OAuth flow | | POST /v1/mesh/messages | Send mesh message | | GET /v1/mesh/messages | Get inbox/outbox | | GET /v1/mesh/agents | List mesh agents | | GET /v1/projects | List projects | | POST /v1/projects | Create project | | GET /v1/kanban/tasks | List kanban tasks | | POST /v1/kanban/tasks | Create kanban task | | WS / | Real-time WebSocket events |

Troubleshooting

"Connection refused"

"Unauthorized"

Messages not arriving

Sync not working

Dashboard not updating

Upgrading

clawdhub update agentos
bash ~/clawd/skills/agentos/scripts/setup.sh --upgrade

Support

# 1. Install the skill
clawdhub install agentos
2. Run setup (creates config + sync script)
bash ~/clawd/skills/agentos/scripts/setup.sh
3. Configure (creates ~/.agentos.json)
Enter your API key and agent ID when prompted
4. Verify connection
aos status
5. Add sync to heartbeat (REQUIRED)
Edit your HEARTBEAT.md and add the sync command

Config file: ~/.agentos.json

{
  "apiUrl": "http://178.156.216.106:3100",
  "apiKey": "agfs_live_xxx.yyy",
  "agentId": "your-agent-id",
  "syncPaths": [
    "~/clawd/CONTEXT.md",
    "~/clawd/MEMORY.md",
    "~/clawd/memory/"
  ],
  "autoSync": true,
  "syncInterval": 1800
}

"Connection refused"

"Unauthorized"

Messages not arriving

Sync not working

Dashboard not updating