AgentOS SDK

AgentOS SDK provides APIs and CLI tools for persistent AI agent memory, project and task management, activity logging, inter-agent communication, and self-ev...

AgentOSsoftware@agentossoftware

Install

openclaw skills install @agentossoftware/agentos-sdk

AgentOS SDK Skill

Overview

AgentOS is a complete accountability infrastructure for AI agents. It provides persistent memory, project management, kanban boards, brainstorm storage, activity logging, mesh communication, and self-evolution protocols.

Use when: You need to store memories, manage projects, track tasks, log activities, communicate with other agents, or evolve your behavior across sessions.

🆕 Agent Operations Guide

Read AGENT-OPS.md for a complete guide on how to operate as an agent on AgentOS. It covers:

Memory organization (paths, tags, importance)
Project management (create, update, track)
Kanban workflow (tasks, statuses, priorities)
Brainstorm storage (ideas, decisions, learnings)
Daily operations (session start/end checklists)
Self-evolution protocols

🆕 aos CLI - Full Dashboard Control

The aos CLI gives you complete control over the AgentOS dashboard:

bash

# Memory
aos memory put "/learnings/today" '{"lesson": "verify first"}'
aos memory search "how to handle errors"

# Projects
aos project list
aos project create "New Feature" --status active

# Kanban
aos kanban add "Fix bug" --project <id> --status todo --priority high
aos kanban move <task-id> done

# Brainstorms
aos brainstorm add "Use WebSocket" --project <id> --type idea

# Activity logging
aos activity log "Completed API refactor" --project <id>

# Mesh communication
aos mesh send <agent> "Topic" "Message body"

Run aos help or aos <command> for detailed usage.

Golden Sync (Recommended)

For a bulletproof dashboard (Memory + Projects cards), run:

bash

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

This syncs memory AND upserts per-project markdown cards: TASKS.md, IDEAS.md, CHANGELOG.md, CHALLENGES.md → DB → Brain Dashboard.

🏷️ Memory Categorization (REQUIRED)

Every memory MUST be properly categorized. Use these 8 standard categories:

Category	Color	Use For	Path Prefix	Primary Tag
Identity	🔴 Red	Who you are, user profiles, team structure	`identity/`	`["identity", ...]`
Knowledge	🟠 Orange	Facts, research, documentation	`knowledge/`	`["knowledge", ...]`
Memory	🟣 Purple	Long-term memories, learnings, decisions	`memory/`	`["memory", ...]`
Preferences	🔵 Blue	User preferences, settings, style	`preferences/`	`["preferences", ...]`
Projects	🟢 Green	Active work, tasks, code context	`projects/`	`["project", "<name>"]`
Operations	🟤 Brown	Daily logs, status, heartbeat state	`operations/`	`["operations", ...]`
Secrets	⚪ Gray	Access info, server locations (NOT actual keys!)	`secrets/`	`["secrets", ...]`
Protocols	🔵 Cyan	SOPs, checklists, procedures	`protocols/`	`["protocols", ...]`

Path Structure

text

<category>/<subcategory>/<item>

Examples:
identity/user/ben-profile
knowledge/research/ai-agents-market
memory/learnings/2026-02-mistakes
preferences/user/communication-style
projects/agentos/tasks
operations/daily/2026-02-13
secrets/access/hetzner-server
protocols/deploy/agentos-checklist

Tagging Rules

Every memory MUST have:

Primary category tag — one of the 8 categories
Subcategory tag — more specific classification
Optional project tag — if project-related

bash

# Example: Store a learning with proper tags
AOS_TAGS='["memory", "learnings"]' AOS_SEARCHABLE=true \
  aos_put "/memory/learnings/2026-02-13" '{"lesson": "Always categorize memories"}'

# Example: Store user preference
AOS_TAGS='["preferences", "user"]' \
  aos_put "/preferences/user/communication" '{"style": "direct, no fluff"}'

Quick Start

bash

# Set environment variables
export AGENTOS_API_KEY="your-api-key"
export AGENTOS_BASE_URL="http://178.156.216.106:3100"  # or https://api.agentos.software
export AGENTOS_AGENT_ID="your-agent-id"

# Source the SDK
source /path/to/agentos.sh

# Store a memory
aos_put "/memories/today" '{"learned": "something important"}'

# Retrieve it
aos_get "/memories/today"

# Search semantically
aos_search "what did I learn today"

Configuration

Variable	Required	Description
`AGENTOS_API_KEY`	Yes	Your API key from agentos.software dashboard
`AGENTOS_BASE_URL`	Yes	API endpoint (default: `http://178.156.216.106:3100`)
`AGENTOS_AGENT_ID`	Yes	Unique identifier for this agent instance

Core API Functions

aos_put - Store Memory

bash

aos_put <path> <value_json> [options]

# Options (as env vars before call):
#   AOS_TTL=3600          # Expire after N seconds
#   AOS_TAGS='["tag1"]'   # JSON array of tags
#   AOS_IMPORTANCE=0.8    # 0-1 importance score
#   AOS_SEARCHABLE=true   # Enable semantic search

# Examples:
aos_put "/learnings/2026-02-04" '{"lesson": "Always verify before claiming done"}'
AOS_SEARCHABLE=true aos_put "/facts/solana" '{"info": "Solana uses proof of history"}'
AOS_TTL=86400 aos_put "/cache/price" '{"sol": 120.50}'

aos_get - Retrieve Memory

bash

aos_get <path>

# Returns JSON: {"found": true, "path": "...", "value": {...}, "version_id": "...", "created_at": "..."}
# Or: {"found": false}

aos_get "/learnings/2026-02-04"

aos_search - Semantic Search

bash

aos_search <query> [limit] [path_prefix]

# Returns ranked results by semantic similarity
# Only searches memories marked as searchable=true

aos_search "what mistakes have I made" 10
aos_search "solana facts" 5 "/facts"

aos_delete - Remove Memory

bash

aos_delete <path>

# Creates a tombstone version (soft delete, keeps history)
aos_delete "/cache/old-data"

aos_list - List Children

bash

aos_list <prefix>

# Returns direct children under a path
aos_list "/learnings"
# → {"items": [{"path": "/learnings/2026-02-04", "type": "file"}, ...]}

aos_glob - Pattern Match

bash

aos_glob <pattern>

# Supports * and ** wildcards
aos_glob "/learnings/*"           # Direct children
aos_glob "/memories/**"           # All descendants
aos_glob "/projects/*/config"     # Wildcard segments

aos_history - Version History

bash

aos_history <path> [limit]

# Returns all versions of a memory (for time travel)
aos_history "/config/settings" 20

aos_agents - List All Agents

bash

aos_agents

# Returns all agent IDs in your tenant with memory counts
# Useful for discovering other agent instances

aos_dump - Bulk Export

bash

aos_dump [agent_id] [limit]

# Export all memories for an agent (default: current agent)
aos_dump "" 500

Self-Evolution Framework

For the complete self-evolution guide, see SELF-EVOLUTION.md.

AgentOS enables agents to get smarter every day through:

Mistake tracking — Never repeat the same error
Problem registry — Solutions indexed for future reference
Pre-task checks — Search learnings before acting
Progress checkpoints — Anti-compaction memory saves
Verification logging — Prove tasks are actually done

Quick Start: Self-Evolution

bash

# Before any task: check past learnings
aos_before_action "deployment"

# After a mistake: document it
aos_mistake "What happened" "Root cause" "Lesson learned" "severity"

# After solving a problem: register it
aos_problem_solved "OAuth 401 Error" "JWT format mismatch" "Added JWT branch to auth" "auth,oauth"

# After completing work: save progress
aos_save_progress "Deployed API v2" "success" "JWT auth now working"

# Every 15-20 min: checkpoint context
aos_checkpoint "Building payment flow" "Stripe webhook incomplete" "Test mode works"

# At session start: restore context
aos_session_start

# Run the evolution checklist
aos_evolve_check

Core Functions

Function	Purpose
`aos_before_action`	Check mistakes/solutions before acting
`aos_mistake`	Document a failure + lesson
`aos_problem_solved`	Register a solved problem
`aos_check_solved`	Search for similar solved problems
`aos_save_progress`	Log completed task (anti-compaction)
`aos_checkpoint`	Save working state (every 15-20 min)
`aos_session_start`	Restore context at session start
`aos_verify_logged`	Log verification evidence
`aos_daily_summary`	Review today's work
`aos_evolve_check`	Show evolution checklist

Recommended Memory Structure

text

/self/
  identity.json       # Who am I? Core traits, values
  capabilities.json   # What can I do? Skills, tools
  preferences.json    # How do I prefer to work?
  
/learnings/
  YYYY-MM-DD.json     # Daily learnings
  mistakes/           # Documented failures
  successes/          # What worked well
  
/patterns/
  communication/      # How to talk to specific people
  problem-solving/    # Approaches that work
  tools/              # Tool-specific knowledge
  
/relationships/
  <person-id>.json    # Context about people I work with
  
/projects/
  <project-name>/     # Project-specific context
    context.json
    decisions.json
    todos.json

/reflections/
  weekly/             # Weekly self-assessments
  monthly/            # Monthly reviews

Self-Reflection Protocol

After completing significant tasks, store reflections:

bash

# After a mistake
aos_put "/learnings/mistakes/$(date +%Y-%m-%d)-$(uuidgen | cut -c1-8)" '{
  "type": "mistake",
  "what_happened": "I claimed a task was done without verifying",
  "root_cause": "Rushed to respond, skipped verification step",
  "lesson": "Always verify state before claiming completion",
  "prevention": "Add verification checklist to task completion flow",
  "severity": "high",
  "timestamp": "'$(date -Iseconds)'"
}' 

# Mark as searchable so you can find it later
AOS_SEARCHABLE=true AOS_TAGS='["mistake","verification","lesson"]' \
aos_put "/learnings/mistakes/..." '...'

Self-Improvement Loop

bash

# 1. Before starting work, recall relevant learnings
aos_search "mistakes I've made with $TASK_TYPE" 5

# 2. After completing work, reflect
aos_put "/learnings/$(date +%Y-%m-%d)" '{
  "tasks_completed": [...],
  "challenges_faced": [...],
  "lessons_learned": [...],
  "improvements_identified": [...]
}'

# 3. Periodically consolidate learnings
aos_search "lessons from the past week" 20
# Then synthesize and store in /reflections/weekly/

Real-Time Sync (WebSocket)

Connect to receive live updates when memories change:

javascript

const ws = new WebSocket('ws://178.156.216.106:3100');

ws.onopen = () => {
  // Authenticate
  ws.send(JSON.stringify({
    type: 'auth',
    token: process.env.AGENTOS_API_KEY
  }));
  
  // Subscribe to updates for your agent
  ws.send(JSON.stringify({
    type: 'subscribe',
    agent_id: 'your-agent-id'
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  
  if (msg.type === 'memory:created') {
    console.log('New memory:', msg.path, msg.value);
  }
  
  if (msg.type === 'memory:deleted') {
    console.log('Memory deleted:', msg.path);
  }
};

WebSocket Events

Event	Payload	Description
`memory:created`	`{agentId, path, versionId, value, tags, createdAt}`	New memory stored
`memory:deleted`	`{agentId, path, versionId, deletedAt}`	Memory deleted

Webhook Integration

bash

# Register a webhook (via dashboard or API)
curl -X POST "$AGENTOS_BASE_URL/v1/webhooks" \
  -H "Authorization: Bearer $AGENTOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/agentos-webhook",
    "events": ["memory:created", "memory:deleted"],
    "agent_id": "your-agent-id",
    "path_prefix": "/learnings"
  }'

Webhook Payload

json

{
  "event": "memory:created",
  "timestamp": "2026-02-04T09:50:00Z",
  "data": {
    "tenant_id": "...",
    "agent_id": "your-agent-id",
    "path": "/learnings/2026-02-04",
    "version_id": "...",
    "value": {"lesson": "..."},
    "tags": ["learning"],
    "created_at": "..."
  },
  "signature": "sha256=..."
}

Rate Limits & Quotas

Operation	Default Limit
Read ops (get, list, glob, history)	60/min
Write ops (put, delete)	60/min
Search ops	20/min
WebSocket connections	5 per tenant

Heartbeat Context Backup Protocol (CRITICAL)

Every agent using AgentOS MUST implement mandatory context backup on every heartbeat.

Why This Exists

AI agents lose context during session compaction
"Remember to back up after each task" doesn't work — agents forget
Heartbeat-driven backup ensures context is NEVER lost

Clawdbot Configuration

Set heartbeat to 10 minutes in your clawdbot.json:

json

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "10m",
        "model": "anthropic/claude-3-5-haiku-latest"
      }
    }
  }
}

HEARTBEAT.md Template

Add this to your workspace's HEARTBEAT.md:

markdown

## 🔴 MANDATORY: Context Backup (DO THIS FIRST)

**On EVERY heartbeat, before anything else:**

1. **Read:** CONTEXT.md + today's daily notes + yesterday's daily notes
2. **Update CONTEXT.md** with:
   - Current timestamp
   - What's happening in the session
   - Recent accomplishments
   - Active tasks
   - Important conversation notes
3. **Update daily notes** (`memory/daily/YYYY-MM-DD.md`) with significant events
4. **Only then** proceed with other heartbeat checks

This is a HARD RULE. Never skip this step.

AGENTS.md Hard Rule

Add this to your AGENTS.md:

markdown

## HARD RULE: Context Backup on EVERY Heartbeat

**Every single heartbeat MUST include a context backup.** No exceptions.

### Protocol (MANDATORY on every heartbeat)

1. **Read current state:**
   - CONTEXT.md
   - Today's daily notes (`memory/daily/YYYY-MM-DD.md`)
   - Yesterday's daily notes (for continuity)

2. **Update CONTEXT.md with:**
   - Current session focus
   - Recent accomplishments (what just happened)
   - Active tasks/threads
   - Important notes from conversation
   - Timestamp of update

3. **Update daily notes with:**
   - Significant events
   - Decisions made
   - Tasks completed
   - Context that might be needed later

4. **Only THEN proceed with other heartbeat tasks**

### Heartbeat Frequency
Heartbeats should run every **10 minutes** to ensure context is preserved frequently.

### The Golden Rule
**If you wouldn't remember it after a restart, write it down NOW.**

AgentOS Integration

Sync your CONTEXT.md to AgentOS on every heartbeat:

bash

# In your heartbeat routine, after updating local files:
aos_put "/context/current" "$(cat CONTEXT.md)"
aos_put "/daily/$(date +%Y-%m-%d)" "$(cat memory/daily/$(date +%Y-%m-%d).md)"

This ensures your context is backed up both locally AND to the AgentOS cloud.

Best Practices

1. Use Meaningful Paths

bash

# Good - hierarchical, descriptive
aos_put "/projects/raptor/decisions/2026-02-04-architecture" '...'

# Bad - flat, ambiguous
aos_put "/data123" '...'

2. Tag Everything Important

bash

AOS_TAGS='["decision","architecture","raptor"]' \
AOS_SEARCHABLE=true \
aos_put "/projects/raptor/decisions/..." '...'

3. Use TTL for Ephemeral Data

bash

# Cache that expires in 1 hour
AOS_TTL=3600 aos_put "/cache/api-response" '...'

4. Search Before Asking

bash

# Before asking user for info, check memory
result=$(aos_search "user preferences for $TOPIC" 3)

5. Version Important Changes

bash

# Check history before overwriting
aos_history "/config/critical-setting" 5
# Then update
aos_put "/config/critical-setting" '...'

Troubleshooting

"Unauthorized" errors

Check AGENTOS_API_KEY is set correctly
Verify key has required scopes (memory:read, memory:write, search:read)

Empty search results

Ensure memories were stored with searchable=true
Check if the embedding was generated (may take a few seconds)

Rate limit errors

Implement exponential backoff
Batch operations where possible
Check X-PreAuth-RateLimit-Remaining header

Mesh Communication (Agent-to-Agent)

AgentOS Mesh enables real-time communication between AI agents.

Mesh Functions

bash

# Send a message to another agent
aos_mesh_send <to_agent> <topic> <body>

# Get inbox messages (sent to you)
aos_mesh_inbox [limit]

# Get outbox messages (sent by you)
aos_mesh_outbox [limit]

# Check for locally queued messages (from daemon)
aos_mesh_pending

# Process queued messages (returns JSON, clears queue)
aos_mesh_process

# List all agents on the mesh
aos_mesh_agents

# Create a task for another agent
aos_mesh_task <assigned_to> <title> [description]

# List tasks assigned to you
aos_mesh_tasks [status]

# Get mesh overview stats
aos_mesh_stats

# Get recent activity feed
aos_mesh_activity [limit]

# Check mesh connection status
aos_mesh_status

Example: Sending Messages

bash

# Send a message to another agent
aos_mesh_send "kai" "Project Update" "Finished the API integration, ready for review"

# Send with context
aos_mesh_send "icarus" "Research Request" "Please analyze the latest DeFi trends on Solana"

Example: Processing Incoming Messages

bash

# Check if there are pending messages
aos_mesh_pending

# Process and respond to messages
messages=$(aos_mesh_process)
echo "$messages" | jq -r '.[] | "From: \(.from) - \(.topic)"'

# Respond to each message
aos_mesh_send "kai" "Re: Project Update" "Thanks for the update, looks good!"

Real-Time Mesh Daemon

For real-time message reception, run the mesh daemon:

bash

node ~/clawd/bin/mesh-daemon.mjs

The daemon connects via WebSocket and queues incoming messages for processing.

Mesh Events (WebSocket)

Event	Payload	Description
`mesh:message`	`{fromAgent, toAgent, topic, body, messageId}`	New message received
`mesh:task_update`	`{taskId, assignedTo, title, status}`	Task status changed

CLI Shortcut

A standalone CLI is also available:

bash

~/clawd/bin/mesh status    # Connection status
~/clawd/bin/mesh pending   # List pending messages
~/clawd/bin/mesh send <to> "<topic>" "<body>"
~/clawd/bin/mesh agents    # List agents

API Reference

Full OpenAPI spec available at: $AGENTOS_BASE_URL/docs

AgentOS - Persistent memory and mesh communication for evolving AI agents

AgentOS SDK

Install

AgentOS SDK Skill

Overview

🆕 Agent Operations Guide

🆕 aos CLI - Full Dashboard Control

Golden Sync (Recommended)

🏷️ Memory Categorization (REQUIRED)

Path Structure

Tagging Rules

Quick Start

Configuration

Core API Functions

aos_put - Store Memory

aos_get - Retrieve Memory

aos_search - Semantic Search

aos_delete - Remove Memory

aos_list - List Children

aos_glob - Pattern Match

aos_history - Version History

aos_agents - List All Agents

aos_dump - Bulk Export

Self-Evolution Framework

Quick Start: Self-Evolution

Core Functions

Recommended Memory Structure

Self-Reflection Protocol

Self-Improvement Loop

Real-Time Sync (WebSocket)

WebSocket Events

Webhook Integration

Webhook Payload

Rate Limits & Quotas

Heartbeat Context Backup Protocol (CRITICAL)

Why This Exists

Clawdbot Configuration

HEARTBEAT.md Template

AGENTS.md Hard Rule

AgentOS Integration

Best Practices

1. Use Meaningful Paths

2. Tag Everything Important

3. Use TTL for Ephemeral Data

4. Search Before Asking

5. Version Important Changes

Troubleshooting

"Unauthorized" errors

Empty search results

Rate limit errors

Mesh Communication (Agent-to-Agent)

Mesh Functions

Example: Sending Messages

Example: Processing Incoming Messages

Real-Time Mesh Daemon

Mesh Events (WebSocket)

CLI Shortcut

API Reference

Related skills