back
loading skill details...
AgentOS SDK provides APIs and CLI tools for persistent AI agent memory, project and task management, activity logging, inter-agent communication, and self-ev...
# 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
```
<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:
1. **Primary category tag** — one of the 8 categories
2. **Subcategory tag** — more specific classification
3. **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](./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
```
/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
Register webhooks to receive HTTP callbacks when memories change:
```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*
don't have the plugin yet? install it then click "run inline in claude" again.