{"skill":{"slug":"agentos-sdk","displayName":"AgentOS SDK","summary":"AgentOS SDK provides APIs and CLI tools for persistent AI agent memory, project and task management, activity logging, inter-agent communication, and self-ev...","description":"# AgentOS SDK Skill\n\n## Overview\nAgentOS 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.\n\n**Use when:** You need to store memories, manage projects, track tasks, log activities, communicate with other agents, or evolve your behavior across sessions.\n\n## 🆕 Agent Operations Guide\n**Read `AGENT-OPS.md` for a complete guide on how to operate as an agent on AgentOS.** It covers:\n- Memory organization (paths, tags, importance)\n- Project management (create, update, track)\n- Kanban workflow (tasks, statuses, priorities)\n- Brainstorm storage (ideas, decisions, learnings)\n- Daily operations (session start/end checklists)\n- Self-evolution protocols\n\n## 🆕 aos CLI - Full Dashboard Control\nThe `aos` CLI gives you complete control over the AgentOS dashboard:\n\n```bash\n# Memory\naos memory put \"/learnings/today\" '{\"lesson\": \"verify first\"}'\naos memory search \"how to handle errors\"\n\n# Projects\naos project list\naos project create \"New Feature\" --status active\n\n# Kanban\naos kanban add \"Fix bug\" --project <id> --status todo --priority high\naos kanban move <task-id> done\n\n# Brainstorms\naos brainstorm add \"Use WebSocket\" --project <id> --type idea\n\n# Activity logging\naos activity log \"Completed API refactor\" --project <id>\n\n# Mesh communication\naos mesh send <agent> \"Topic\" \"Message body\"\n```\n\nRun `aos help` or `aos <command>` for detailed usage.\n\n## Golden Sync (Recommended)\nFor a bulletproof dashboard (Memory + Projects cards), run:\n```bash\n~/clawd/bin/agentos-golden-sync.sh\n```\n\nThis syncs memory AND upserts per-project markdown cards:\n`TASKS.md`, `IDEAS.md`, `CHANGELOG.md`, `CHALLENGES.md` → DB → Brain Dashboard.\n\n## 🏷️ Memory Categorization (REQUIRED)\n\n**Every memory MUST be properly categorized.** Use these 8 standard categories:\n\n| Category | Color | Use For | Path Prefix | Primary Tag |\n|----------|-------|---------|-------------|-------------|\n| **Identity** | 🔴 Red | Who you are, user profiles, team structure | `identity/` | `[\"identity\", ...]` |\n| **Knowledge** | 🟠 Orange | Facts, research, documentation | `knowledge/` | `[\"knowledge\", ...]` |\n| **Memory** | 🟣 Purple | Long-term memories, learnings, decisions | `memory/` | `[\"memory\", ...]` |\n| **Preferences** | 🔵 Blue | User preferences, settings, style | `preferences/` | `[\"preferences\", ...]` |\n| **Projects** | 🟢 Green | Active work, tasks, code context | `projects/` | `[\"project\", \"<name>\"]` |\n| **Operations** | 🟤 Brown | Daily logs, status, heartbeat state | `operations/` | `[\"operations\", ...]` |\n| **Secrets** | ⚪ Gray | Access info, server locations (NOT actual keys!) | `secrets/` | `[\"secrets\", ...]` |\n| **Protocols** | 🔵 Cyan | SOPs, checklists, procedures | `protocols/` | `[\"protocols\", ...]` |\n\n### Path Structure\n```\n<category>/<subcategory>/<item>\n\nExamples:\nidentity/user/ben-profile\nknowledge/research/ai-agents-market\nmemory/learnings/2026-02-mistakes\npreferences/user/communication-style\nprojects/agentos/tasks\noperations/daily/2026-02-13\nsecrets/access/hetzner-server\nprotocols/deploy/agentos-checklist\n```\n\n### Tagging Rules\nEvery memory MUST have:\n1. **Primary category tag** — one of the 8 categories\n2. **Subcategory tag** — more specific classification\n3. **Optional project tag** — if project-related\n\n```bash\n# Example: Store a learning with proper tags\nAOS_TAGS='[\"memory\", \"learnings\"]' AOS_SEARCHABLE=true \\\n  aos_put \"/memory/learnings/2026-02-13\" '{\"lesson\": \"Always categorize memories\"}'\n\n# Example: Store user preference\nAOS_TAGS='[\"preferences\", \"user\"]' \\\n  aos_put \"/preferences/user/communication\" '{\"style\": \"direct, no fluff\"}'\n```\n\n---\n\n## Quick Start\n\n```bash\n# Set environment variables\nexport AGENTOS_API_KEY=\"your-api-key\"\nexport AGENTOS_BASE_URL=\"http://178.156.216.106:3100\"  # or https://api.agentos.software\nexport AGENTOS_AGENT_ID=\"your-agent-id\"\n\n# Source the SDK\nsource /path/to/agentos.sh\n\n# Store a memory\naos_put \"/memories/today\" '{\"learned\": \"something important\"}'\n\n# Retrieve it\naos_get \"/memories/today\"\n\n# Search semantically\naos_search \"what did I learn today\"\n```\n\n## Configuration\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `AGENTOS_API_KEY` | Yes | Your API key from agentos.software dashboard |\n| `AGENTOS_BASE_URL` | Yes | API endpoint (default: `http://178.156.216.106:3100`) |\n| `AGENTOS_AGENT_ID` | Yes | Unique identifier for this agent instance |\n\n## Core API Functions\n\n### aos_put - Store Memory\n```bash\naos_put <path> <value_json> [options]\n\n# Options (as env vars before call):\n#   AOS_TTL=3600          # Expire after N seconds\n#   AOS_TAGS='[\"tag1\"]'   # JSON array of tags\n#   AOS_IMPORTANCE=0.8    # 0-1 importance score\n#   AOS_SEARCHABLE=true   # Enable semantic search\n\n# Examples:\naos_put \"/learnings/2026-02-04\" '{\"lesson\": \"Always verify before claiming done\"}'\nAOS_SEARCHABLE=true aos_put \"/facts/solana\" '{\"info\": \"Solana uses proof of history\"}'\nAOS_TTL=86400 aos_put \"/cache/price\" '{\"sol\": 120.50}'\n```\n\n### aos_get - Retrieve Memory\n```bash\naos_get <path>\n\n# Returns JSON: {\"found\": true, \"path\": \"...\", \"value\": {...}, \"version_id\": \"...\", \"created_at\": \"...\"}\n# Or: {\"found\": false}\n\naos_get \"/learnings/2026-02-04\"\n```\n\n### aos_search - Semantic Search\n```bash\naos_search <query> [limit] [path_prefix]\n\n# Returns ranked results by semantic similarity\n# Only searches memories marked as searchable=true\n\naos_search \"what mistakes have I made\" 10\naos_search \"solana facts\" 5 \"/facts\"\n```\n\n### aos_delete - Remove Memory\n```bash\naos_delete <path>\n\n# Creates a tombstone version (soft delete, keeps history)\naos_delete \"/cache/old-data\"\n```\n\n### aos_list - List Children\n```bash\naos_list <prefix>\n\n# Returns direct children under a path\naos_list \"/learnings\"\n# → {\"items\": [{\"path\": \"/learnings/2026-02-04\", \"type\": \"file\"}, ...]}\n```\n\n### aos_glob - Pattern Match\n```bash\naos_glob <pattern>\n\n# Supports * and ** wildcards\naos_glob \"/learnings/*\"           # Direct children\naos_glob \"/memories/**\"           # All descendants\naos_glob \"/projects/*/config\"     # Wildcard segments\n```\n\n### aos_history - Version History\n```bash\naos_history <path> [limit]\n\n# Returns all versions of a memory (for time travel)\naos_history \"/config/settings\" 20\n```\n\n### aos_agents - List All Agents\n```bash\naos_agents\n\n# Returns all agent IDs in your tenant with memory counts\n# Useful for discovering other agent instances\n```\n\n### aos_dump - Bulk Export\n```bash\naos_dump [agent_id] [limit]\n\n# Export all memories for an agent (default: current agent)\naos_dump \"\" 500\n```\n\n## Self-Evolution Framework\n\n**For the complete self-evolution guide, see [SELF-EVOLUTION.md](./SELF-EVOLUTION.md).**\n\nAgentOS enables agents to get smarter every day through:\n- **Mistake tracking** — Never repeat the same error\n- **Problem registry** — Solutions indexed for future reference\n- **Pre-task checks** — Search learnings before acting\n- **Progress checkpoints** — Anti-compaction memory saves\n- **Verification logging** — Prove tasks are actually done\n\n### Quick Start: Self-Evolution\n\n```bash\n# Before any task: check past learnings\naos_before_action \"deployment\"\n\n# After a mistake: document it\naos_mistake \"What happened\" \"Root cause\" \"Lesson learned\" \"severity\"\n\n# After solving a problem: register it\naos_problem_solved \"OAuth 401 Error\" \"JWT format mismatch\" \"Added JWT branch to auth\" \"auth,oauth\"\n\n# After completing work: save progress\naos_save_progress \"Deployed API v2\" \"success\" \"JWT auth now working\"\n\n# Every 15-20 min: checkpoint context\naos_checkpoint \"Building payment flow\" \"Stripe webhook incomplete\" \"Test mode works\"\n\n# At session start: restore context\naos_session_start\n\n# Run the evolution checklist\naos_evolve_check\n```\n\n### Core Functions\n\n| Function | Purpose |\n|----------|---------|\n| `aos_before_action` | Check mistakes/solutions before acting |\n| `aos_mistake` | Document a failure + lesson |\n| `aos_problem_solved` | Register a solved problem |\n| `aos_check_solved` | Search for similar solved problems |\n| `aos_save_progress` | Log completed task (anti-compaction) |\n| `aos_checkpoint` | Save working state (every 15-20 min) |\n| `aos_session_start` | Restore context at session start |\n| `aos_verify_logged` | Log verification evidence |\n| `aos_daily_summary` | Review today's work |\n| `aos_evolve_check` | Show evolution checklist |\n\n### Recommended Memory Structure\n\n```\n/self/\n  identity.json       # Who am I? Core traits, values\n  capabilities.json   # What can I do? Skills, tools\n  preferences.json    # How do I prefer to work?\n  \n/learnings/\n  YYYY-MM-DD.json     # Daily learnings\n  mistakes/           # Documented failures\n  successes/          # What worked well\n  \n/patterns/\n  communication/      # How to talk to specific people\n  problem-solving/    # Approaches that work\n  tools/              # Tool-specific knowledge\n  \n/relationships/\n  <person-id>.json    # Context about people I work with\n  \n/projects/\n  <project-name>/     # Project-specific context\n    context.json\n    decisions.json\n    todos.json\n\n/reflections/\n  weekly/             # Weekly self-assessments\n  monthly/            # Monthly reviews\n```\n\n### Self-Reflection Protocol\n\nAfter completing significant tasks, store reflections:\n\n```bash\n# After a mistake\naos_put \"/learnings/mistakes/$(date +%Y-%m-%d)-$(uuidgen | cut -c1-8)\" '{\n  \"type\": \"mistake\",\n  \"what_happened\": \"I claimed a task was done without verifying\",\n  \"root_cause\": \"Rushed to respond, skipped verification step\",\n  \"lesson\": \"Always verify state before claiming completion\",\n  \"prevention\": \"Add verification checklist to task completion flow\",\n  \"severity\": \"high\",\n  \"timestamp\": \"'$(date -Iseconds)'\"\n}' \n\n# Mark as searchable so you can find it later\nAOS_SEARCHABLE=true AOS_TAGS='[\"mistake\",\"verification\",\"lesson\"]' \\\naos_put \"/learnings/mistakes/...\" '...'\n```\n\n### Self-Improvement Loop\n\n```bash\n# 1. Before starting work, recall relevant learnings\naos_search \"mistakes I've made with $TASK_TYPE\" 5\n\n# 2. After completing work, reflect\naos_put \"/learnings/$(date +%Y-%m-%d)\" '{\n  \"tasks_completed\": [...],\n  \"challenges_faced\": [...],\n  \"lessons_learned\": [...],\n  \"improvements_identified\": [...]\n}'\n\n# 3. Periodically consolidate learnings\naos_search \"lessons from the past week\" 20\n# Then synthesize and store in /reflections/weekly/\n```\n\n## Real-Time Sync (WebSocket)\n\nConnect to receive live updates when memories change:\n\n```javascript\nconst ws = new WebSocket('ws://178.156.216.106:3100');\n\nws.onopen = () => {\n  // Authenticate\n  ws.send(JSON.stringify({\n    type: 'auth',\n    token: process.env.AGENTOS_API_KEY\n  }));\n  \n  // Subscribe to updates for your agent\n  ws.send(JSON.stringify({\n    type: 'subscribe',\n    agent_id: 'your-agent-id'\n  }));\n};\n\nws.onmessage = (event) => {\n  const msg = JSON.parse(event.data);\n  \n  if (msg.type === 'memory:created') {\n    console.log('New memory:', msg.path, msg.value);\n  }\n  \n  if (msg.type === 'memory:deleted') {\n    console.log('Memory deleted:', msg.path);\n  }\n};\n```\n\n### WebSocket Events\n\n| Event | Payload | Description |\n|-------|---------|-------------|\n| `memory:created` | `{agentId, path, versionId, value, tags, createdAt}` | New memory stored |\n| `memory:deleted` | `{agentId, path, versionId, deletedAt}` | Memory deleted |\n\n## Webhook Integration\n\nRegister webhooks to receive HTTP callbacks when memories change:\n\n```bash\n# Register a webhook (via dashboard or API)\ncurl -X POST \"$AGENTOS_BASE_URL/v1/webhooks\" \\\n  -H \"Authorization: Bearer $AGENTOS_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"url\": \"https://your-server.com/agentos-webhook\",\n    \"events\": [\"memory:created\", \"memory:deleted\"],\n    \"agent_id\": \"your-agent-id\",\n    \"path_prefix\": \"/learnings\"\n  }'\n```\n\n### Webhook Payload\n\n```json\n{\n  \"event\": \"memory:created\",\n  \"timestamp\": \"2026-02-04T09:50:00Z\",\n  \"data\": {\n    \"tenant_id\": \"...\",\n    \"agent_id\": \"your-agent-id\",\n    \"path\": \"/learnings/2026-02-04\",\n    \"version_id\": \"...\",\n    \"value\": {\"lesson\": \"...\"},\n    \"tags\": [\"learning\"],\n    \"created_at\": \"...\"\n  },\n  \"signature\": \"sha256=...\"\n}\n```\n\n## Rate Limits & Quotas\n\n| Operation | Default Limit |\n|-----------|---------------|\n| Read ops (get, list, glob, history) | 60/min |\n| Write ops (put, delete) | 60/min |\n| Search ops | 20/min |\n| WebSocket connections | 5 per tenant |\n\n## Heartbeat Context Backup Protocol (CRITICAL)\n\n**Every agent using AgentOS MUST implement mandatory context backup on every heartbeat.**\n\n### Why This Exists\n- AI agents lose context during session compaction\n- \"Remember to back up after each task\" doesn't work — agents forget\n- Heartbeat-driven backup ensures context is NEVER lost\n\n### Clawdbot Configuration\n\nSet heartbeat to 10 minutes in your `clawdbot.json`:\n\n```json\n{\n  \"agents\": {\n    \"defaults\": {\n      \"heartbeat\": {\n        \"every\": \"10m\",\n        \"model\": \"anthropic/claude-3-5-haiku-latest\"\n      }\n    }\n  }\n}\n```\n\n### HEARTBEAT.md Template\n\nAdd this to your workspace's `HEARTBEAT.md`:\n\n```markdown\n## 🔴 MANDATORY: Context Backup (DO THIS FIRST)\n\n**On EVERY heartbeat, before anything else:**\n\n1. **Read:** CONTEXT.md + today's daily notes + yesterday's daily notes\n2. **Update CONTEXT.md** with:\n   - Current timestamp\n   - What's happening in the session\n   - Recent accomplishments\n   - Active tasks\n   - Important conversation notes\n3. **Update daily notes** (`memory/daily/YYYY-MM-DD.md`) with significant events\n4. **Only then** proceed with other heartbeat checks\n\nThis is a HARD RULE. Never skip this step.\n```\n\n### AGENTS.md Hard Rule\n\nAdd this to your `AGENTS.md`:\n\n```markdown\n## HARD RULE: Context Backup on EVERY Heartbeat\n\n**Every single heartbeat MUST include a context backup.** No exceptions.\n\n### Protocol (MANDATORY on every heartbeat)\n\n1. **Read current state:**\n   - CONTEXT.md\n   - Today's daily notes (`memory/daily/YYYY-MM-DD.md`)\n   - Yesterday's daily notes (for continuity)\n\n2. **Update CONTEXT.md with:**\n   - Current session focus\n   - Recent accomplishments (what just happened)\n   - Active tasks/threads\n   - Important notes from conversation\n   - Timestamp of update\n\n3. **Update daily notes with:**\n   - Significant events\n   - Decisions made\n   - Tasks completed\n   - Context that might be needed later\n\n4. **Only THEN proceed with other heartbeat tasks**\n\n### Heartbeat Frequency\nHeartbeats should run every **10 minutes** to ensure context is preserved frequently.\n\n### The Golden Rule\n**If you wouldn't remember it after a restart, write it down NOW.**\n```\n\n### AgentOS Integration\n\nSync your CONTEXT.md to AgentOS on every heartbeat:\n\n```bash\n# In your heartbeat routine, after updating local files:\naos_put \"/context/current\" \"$(cat CONTEXT.md)\"\naos_put \"/daily/$(date +%Y-%m-%d)\" \"$(cat memory/daily/$(date +%Y-%m-%d).md)\"\n```\n\nThis ensures your context is backed up both locally AND to the AgentOS cloud.\n\n---\n\n## Best Practices\n\n### 1. Use Meaningful Paths\n```bash\n# Good - hierarchical, descriptive\naos_put \"/projects/raptor/decisions/2026-02-04-architecture\" '...'\n\n# Bad - flat, ambiguous\naos_put \"/data123\" '...'\n```\n\n### 2. Tag Everything Important\n```bash\nAOS_TAGS='[\"decision\",\"architecture\",\"raptor\"]' \\\nAOS_SEARCHABLE=true \\\naos_put \"/projects/raptor/decisions/...\" '...'\n```\n\n### 3. Use TTL for Ephemeral Data\n```bash\n# Cache that expires in 1 hour\nAOS_TTL=3600 aos_put \"/cache/api-response\" '...'\n```\n\n### 4. Search Before Asking\n```bash\n# Before asking user for info, check memory\nresult=$(aos_search \"user preferences for $TOPIC\" 3)\n```\n\n### 5. Version Important Changes\n```bash\n# Check history before overwriting\naos_history \"/config/critical-setting\" 5\n# Then update\naos_put \"/config/critical-setting\" '...'\n```\n\n## Troubleshooting\n\n### \"Unauthorized\" errors\n- Check `AGENTOS_API_KEY` is set correctly\n- Verify key has required scopes (`memory:read`, `memory:write`, `search:read`)\n\n### Empty search results\n- Ensure memories were stored with `searchable=true`\n- Check if the embedding was generated (may take a few seconds)\n\n### Rate limit errors\n- Implement exponential backoff\n- Batch operations where possible\n- Check `X-PreAuth-RateLimit-Remaining` header\n\n## Mesh Communication (Agent-to-Agent)\n\nAgentOS Mesh enables real-time communication between AI agents.\n\n### Mesh Functions\n\n```bash\n# Send a message to another agent\naos_mesh_send <to_agent> <topic> <body>\n\n# Get inbox messages (sent to you)\naos_mesh_inbox [limit]\n\n# Get outbox messages (sent by you)\naos_mesh_outbox [limit]\n\n# Check for locally queued messages (from daemon)\naos_mesh_pending\n\n# Process queued messages (returns JSON, clears queue)\naos_mesh_process\n\n# List all agents on the mesh\naos_mesh_agents\n\n# Create a task for another agent\naos_mesh_task <assigned_to> <title> [description]\n\n# List tasks assigned to you\naos_mesh_tasks [status]\n\n# Get mesh overview stats\naos_mesh_stats\n\n# Get recent activity feed\naos_mesh_activity [limit]\n\n# Check mesh connection status\naos_mesh_status\n```\n\n### Example: Sending Messages\n\n```bash\n# Send a message to another agent\naos_mesh_send \"kai\" \"Project Update\" \"Finished the API integration, ready for review\"\n\n# Send with context\naos_mesh_send \"icarus\" \"Research Request\" \"Please analyze the latest DeFi trends on Solana\"\n```\n\n### Example: Processing Incoming Messages\n\n```bash\n# Check if there are pending messages\naos_mesh_pending\n\n# Process and respond to messages\nmessages=$(aos_mesh_process)\necho \"$messages\" | jq -r '.[] | \"From: \\(.from) - \\(.topic)\"'\n\n# Respond to each message\naos_mesh_send \"kai\" \"Re: Project Update\" \"Thanks for the update, looks good!\"\n```\n\n### Real-Time Mesh Daemon\n\nFor real-time message reception, run the mesh daemon:\n\n```bash\nnode ~/clawd/bin/mesh-daemon.mjs\n```\n\nThe daemon connects via WebSocket and queues incoming messages for processing.\n\n### Mesh Events (WebSocket)\n\n| Event | Payload | Description |\n|-------|---------|-------------|\n| `mesh:message` | `{fromAgent, toAgent, topic, body, messageId}` | New message received |\n| `mesh:task_update` | `{taskId, assignedTo, title, status}` | Task status changed |\n\n### CLI Shortcut\n\nA standalone CLI is also available:\n\n```bash\n~/clawd/bin/mesh status    # Connection status\n~/clawd/bin/mesh pending   # List pending messages\n~/clawd/bin/mesh send <to> \"<topic>\" \"<body>\"\n~/clawd/bin/mesh agents    # List agents\n```\n\n## API Reference\n\nFull OpenAPI spec available at: `$AGENTOS_BASE_URL/docs`\n\n---\n\n*AgentOS - Persistent memory and mesh communication for evolving AI agents*\n","tags":{"latest":"3.7.0"},"stats":{"comments":0,"downloads":2817,"installsAllTime":5,"installsCurrent":5,"stars":0,"versions":9},"createdAt":1770210308682,"updatedAt":1779076689358},"latestVersion":{"version":"3.7.0","createdAt":1770990573904,"changelog":"AgentOS SDK 3.7.0 introduces required memory categorization and tagging.\n\n- Every memory must now use one of 8 standard categories with color labels, path prefixes, and tags.\n- Documentation adds a table of memory categories, path structures, and strict tagging rules.\n- Example code updated to demonstrate compliant storage and retrieval.\n- No API changes; this update enforces documentation and usage discipline for better organization and dashboard clarity.","license":null},"metadata":null,"owner":{"handle":"agentossoftware","userId":"s173ne9xwn8crfvhx6mt6022hn8412z7","displayName":"AgentOSsoftware","image":"https://avatars.githubusercontent.com/u/257728256?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1779947669376}}