{ "schemaVersion": "1.0", "item": { "slug": "agentos-sdk", "name": "AgentOS SDK", "source": "tencent", "type": "skill", "category": "开发工具", "sourceUrl": "https://clawhub.ai/AgentOSsoftware/agentos-sdk", "canonicalUrl": "https://clawhub.ai/AgentOSsoftware/agentos-sdk", "targetPlatform": "OpenClaw" }, "install": { "downloadMode": "redirect", "downloadUrl": "/downloads/agentos-sdk", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=agentos-sdk", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "installMethod": "Manual import", "extraction": "Extract archive", "prerequisites": [ "OpenClaw" ], "packageFormat": "ZIP package", "includedAssets": [ "AGENT-OPS.md", "DOCS.md", "SELF-EVOLUTION.md", "SKILL.md", "agentos.sh", "examples/clawdbot-integration.md" ], "primaryDoc": "SKILL.md", "quickSetup": [ "Download the package from Yavira.", "Extract the archive and review SKILL.md first.", "Import or place the package into your OpenClaw setup." ], "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "sourceHealth": { "source": "tencent", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-04-23T16:43:11.935Z", "expiresAt": "2026-04-30T16:43:11.935Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=4claw-imageboard", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=4claw-imageboard", "contentDisposition": "attachment; filename=\"4claw-imageboard-1.0.1.zip\"", "redirectLocation": null, "bodySnippet": null }, "scope": "source", "summary": "Source download looks usable.", "detail": "Yavira can redirect you to the upstream package for this source.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/agentos-sdk" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] }, "downloadPageUrl": "https://openagent3.xyz/downloads/agentos-sdk", "agentPageUrl": "https://openagent3.xyz/skills/agentos-sdk/agent", "manifestUrl": "https://openagent3.xyz/skills/agentos-sdk/agent.json", "briefUrl": "https://openagent3.xyz/skills/agentos-sdk/agent.md" }, "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "documentation": { "source": "clawhub", "primaryDoc": "SKILL.md", "sections": [ { "title": "Overview", "body": "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.\n\nUse when: You need to store memories, manage projects, track tasks, log activities, communicate with other agents, or evolve your behavior across sessions." }, { "title": "🆕 Agent Operations Guide", "body": "Read AGENT-OPS.md for a complete guide on how to operate as an agent on AgentOS. It covers:\n\nMemory organization (paths, tags, importance)\nProject management (create, update, track)\nKanban workflow (tasks, statuses, priorities)\nBrainstorm storage (ideas, decisions, learnings)\nDaily operations (session start/end checklists)\nSelf-evolution protocols" }, { "title": "🆕 aos CLI - Full Dashboard Control", "body": "The aos CLI gives you complete control over the AgentOS dashboard:\n\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 --status todo --priority high\naos kanban move done\n\n# Brainstorms\naos brainstorm add \"Use WebSocket\" --project --type idea\n\n# Activity logging\naos activity log \"Completed API refactor\" --project \n\n# Mesh communication\naos mesh send \"Topic\" \"Message body\"\n\nRun aos help or aos for detailed usage." }, { "title": "Golden Sync (Recommended)", "body": "For a bulletproof dashboard (Memory + Projects cards), run:\n\n~/clawd/bin/agentos-golden-sync.sh\n\nThis syncs memory AND upserts per-project markdown cards:\nTASKS.md, IDEAS.md, CHANGELOG.md, CHALLENGES.md → DB → Brain Dashboard." }, { "title": "🏷️ Memory Categorization (REQUIRED)", "body": "Every memory MUST be properly categorized. Use these 8 standard categories:\n\nCategoryColorUse ForPath PrefixPrimary TagIdentity🔴 RedWho you are, user profiles, team structureidentity/[\"identity\", ...]Knowledge🟠 OrangeFacts, research, documentationknowledge/[\"knowledge\", ...]Memory🟣 PurpleLong-term memories, learnings, decisionsmemory/[\"memory\", ...]Preferences🔵 BlueUser preferences, settings, stylepreferences/[\"preferences\", ...]Projects🟢 GreenActive work, tasks, code contextprojects/[\"project\", \"\"]Operations🟤 BrownDaily logs, status, heartbeat stateoperations/[\"operations\", ...]Secrets⚪ GrayAccess info, server locations (NOT actual keys!)secrets/[\"secrets\", ...]Protocols🔵 CyanSOPs, checklists, proceduresprotocols/[\"protocols\", ...]" }, { "title": "Path Structure", "body": "//\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" }, { "title": "Tagging Rules", "body": "Every memory MUST have:\n\nPrimary category tag — one of the 8 categories\nSubcategory tag — more specific classification\nOptional project tag — if project-related\n\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\"}'" }, { "title": "Quick Start", "body": "# 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\"" }, { "title": "Configuration", "body": "VariableRequiredDescriptionAGENTOS_API_KEYYesYour API key from agentos.software dashboardAGENTOS_BASE_URLYesAPI endpoint (default: http://178.156.216.106:3100)AGENTOS_AGENT_IDYesUnique identifier for this agent instance" }, { "title": "aos_put - Store Memory", "body": "aos_put [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}'" }, { "title": "aos_get - Retrieve Memory", "body": "aos_get \n\n# Returns JSON: {\"found\": true, \"path\": \"...\", \"value\": {...}, \"version_id\": \"...\", \"created_at\": \"...\"}\n# Or: {\"found\": false}\n\naos_get \"/learnings/2026-02-04\"" }, { "title": "aos_search - Semantic Search", "body": "aos_search [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\"" }, { "title": "aos_delete - Remove Memory", "body": "aos_delete \n\n# Creates a tombstone version (soft delete, keeps history)\naos_delete \"/cache/old-data\"" }, { "title": "aos_list - List Children", "body": "aos_list \n\n# Returns direct children under a path\naos_list \"/learnings\"\n# → {\"items\": [{\"path\": \"/learnings/2026-02-04\", \"type\": \"file\"}, ...]}" }, { "title": "aos_glob - Pattern Match", "body": "aos_glob \n\n# Supports * and ** wildcards\naos_glob \"/learnings/*\" # Direct children\naos_glob \"/memories/**\" # All descendants\naos_glob \"/projects/*/config\" # Wildcard segments" }, { "title": "aos_history - Version History", "body": "aos_history [limit]\n\n# Returns all versions of a memory (for time travel)\naos_history \"/config/settings\" 20" }, { "title": "aos_agents - List All Agents", "body": "aos_agents\n\n# Returns all agent IDs in your tenant with memory counts\n# Useful for discovering other agent instances" }, { "title": "aos_dump - Bulk Export", "body": "aos_dump [agent_id] [limit]\n\n# Export all memories for an agent (default: current agent)\naos_dump \"\" 500" }, { "title": "Self-Evolution Framework", "body": "For the complete self-evolution guide, see SELF-EVOLUTION.md.\n\nAgentOS enables agents to get smarter every day through:\n\nMistake tracking — Never repeat the same error\nProblem registry — Solutions indexed for future reference\nPre-task checks — Search learnings before acting\nProgress checkpoints — Anti-compaction memory saves\nVerification logging — Prove tasks are actually done" }, { "title": "Quick Start: Self-Evolution", "body": "# 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" }, { "title": "Core Functions", "body": "FunctionPurposeaos_before_actionCheck mistakes/solutions before actingaos_mistakeDocument a failure + lessonaos_problem_solvedRegister a solved problemaos_check_solvedSearch for similar solved problemsaos_save_progressLog completed task (anti-compaction)aos_checkpointSave working state (every 15-20 min)aos_session_startRestore context at session startaos_verify_loggedLog verification evidenceaos_daily_summaryReview today's workaos_evolve_checkShow evolution checklist" }, { "title": "Recommended Memory Structure", "body": "/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 .json # Context about people I work with\n \n/projects/\n / # Project-specific context\n context.json\n decisions.json\n todos.json\n\n/reflections/\n weekly/ # Weekly self-assessments\n monthly/ # Monthly reviews" }, { "title": "Self-Reflection Protocol", "body": "After completing significant tasks, store reflections:\n\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/...\" '...'" }, { "title": "Self-Improvement Loop", "body": "# 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/" }, { "title": "Real-Time Sync (WebSocket)", "body": "Connect to receive live updates when memories change:\n\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};" }, { "title": "WebSocket Events", "body": "EventPayloadDescriptionmemory:created{agentId, path, versionId, value, tags, createdAt}New memory storedmemory:deleted{agentId, path, versionId, deletedAt}Memory deleted" }, { "title": "Webhook Integration", "body": "Register webhooks to receive HTTP callbacks when memories change:\n\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 }'" }, { "title": "Webhook Payload", "body": "{\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}" }, { "title": "Rate Limits & Quotas", "body": "OperationDefault LimitRead ops (get, list, glob, history)60/minWrite ops (put, delete)60/minSearch ops20/minWebSocket connections5 per tenant" }, { "title": "Heartbeat Context Backup Protocol (CRITICAL)", "body": "Every agent using AgentOS MUST implement mandatory context backup on every heartbeat." }, { "title": "Why This Exists", "body": "AI agents lose context during session compaction\n\"Remember to back up after each task\" doesn't work — agents forget\nHeartbeat-driven backup ensures context is NEVER lost" }, { "title": "Clawdbot Configuration", "body": "Set heartbeat to 10 minutes in your clawdbot.json:\n\n{\n \"agents\": {\n \"defaults\": {\n \"heartbeat\": {\n \"every\": \"10m\",\n \"model\": \"anthropic/claude-3-5-haiku-latest\"\n }\n }\n }\n}" }, { "title": "HEARTBEAT.md Template", "body": "Add this to your workspace's HEARTBEAT.md:\n\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." }, { "title": "AGENTS.md Hard Rule", "body": "Add this to your AGENTS.md:\n\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.**" }, { "title": "AgentOS Integration", "body": "Sync your CONTEXT.md to AgentOS on every heartbeat:\n\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\nThis ensures your context is backed up both locally AND to the AgentOS cloud." }, { "title": "1. Use Meaningful Paths", "body": "# Good - hierarchical, descriptive\naos_put \"/projects/raptor/decisions/2026-02-04-architecture\" '...'\n\n# Bad - flat, ambiguous\naos_put \"/data123\" '...'" }, { "title": "2. Tag Everything Important", "body": "AOS_TAGS='[\"decision\",\"architecture\",\"raptor\"]' \\\nAOS_SEARCHABLE=true \\\naos_put \"/projects/raptor/decisions/...\" '...'" }, { "title": "3. Use TTL for Ephemeral Data", "body": "# Cache that expires in 1 hour\nAOS_TTL=3600 aos_put \"/cache/api-response\" '...'" }, { "title": "4. Search Before Asking", "body": "# Before asking user for info, check memory\nresult=$(aos_search \"user preferences for $TOPIC\" 3)" }, { "title": "5. Version Important Changes", "body": "# Check history before overwriting\naos_history \"/config/critical-setting\" 5\n# Then update\naos_put \"/config/critical-setting\" '...'" }, { "title": "\"Unauthorized\" errors", "body": "Check AGENTOS_API_KEY is set correctly\nVerify key has required scopes (memory:read, memory:write, search:read)" }, { "title": "Empty search results", "body": "Ensure memories were stored with searchable=true\nCheck if the embedding was generated (may take a few seconds)" }, { "title": "Rate limit errors", "body": "Implement exponential backoff\nBatch operations where possible\nCheck X-PreAuth-RateLimit-Remaining header" }, { "title": "Mesh Communication (Agent-to-Agent)", "body": "AgentOS Mesh enables real-time communication between AI agents." }, { "title": "Mesh Functions", "body": "# Send a message to another agent\naos_mesh_send \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 [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" }, { "title": "Example: Sending Messages", "body": "# 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\"" }, { "title": "Example: Processing Incoming Messages", "body": "# 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!\"" }, { "title": "Real-Time Mesh Daemon", "body": "For real-time message reception, run the mesh daemon:\n\nnode ~/clawd/bin/mesh-daemon.mjs\n\nThe daemon connects via WebSocket and queues incoming messages for processing." }, { "title": "Mesh Events (WebSocket)", "body": "EventPayloadDescriptionmesh:message{fromAgent, toAgent, topic, body, messageId}New message receivedmesh:task_update{taskId, assignedTo, title, status}Task status changed" }, { "title": "CLI Shortcut", "body": "A standalone CLI is also available:\n\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" }, { "title": "API Reference", "body": "Full OpenAPI spec available at: $AGENTOS_BASE_URL/docs\n\nAgentOS - Persistent memory and mesh communication for evolving AI agents" } ], "body": "AgentOS SDK Skill\nOverview\n\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\nUse 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\nRead AGENT-OPS.md for a complete guide on how to operate as an agent on AgentOS. It covers:\n\nMemory organization (paths, tags, importance)\nProject management (create, update, track)\nKanban workflow (tasks, statuses, priorities)\nBrainstorm storage (ideas, decisions, learnings)\nDaily operations (session start/end checklists)\nSelf-evolution protocols\n🆕 aos CLI - Full Dashboard Control\n\nThe aos CLI gives you complete control over the AgentOS dashboard:\n\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\nGolden Sync (Recommended)\n\nFor a bulletproof dashboard (Memory + Projects cards), run:\n\n~/clawd/bin/agentos-golden-sync.sh\n\n\nThis syncs memory AND upserts per-project markdown cards: TASKS.md, IDEAS.md, CHANGELOG.md, CHALLENGES.md → DB → Brain Dashboard.\n\n🏷️ Memory Categorization (REQUIRED)\n\nEvery memory MUST be properly categorized. Use these 8 standard categories:\n\nCategory\tColor\tUse For\tPath Prefix\tPrimary Tag\nIdentity\t🔴 Red\tWho you are, user profiles, team structure\tidentity/\t[\"identity\", ...]\nKnowledge\t🟠 Orange\tFacts, research, documentation\tknowledge/\t[\"knowledge\", ...]\nMemory\t🟣 Purple\tLong-term memories, learnings, decisions\tmemory/\t[\"memory\", ...]\nPreferences\t🔵 Blue\tUser preferences, settings, style\tpreferences/\t[\"preferences\", ...]\nProjects\t🟢 Green\tActive work, tasks, code context\tprojects/\t[\"project\", \"<name>\"]\nOperations\t🟤 Brown\tDaily logs, status, heartbeat state\toperations/\t[\"operations\", ...]\nSecrets\t⚪ Gray\tAccess info, server locations (NOT actual keys!)\tsecrets/\t[\"secrets\", ...]\nProtocols\t🔵 Cyan\tSOPs, checklists, procedures\tprotocols/\t[\"protocols\", ...]\nPath Structure\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\nTagging Rules\n\nEvery memory MUST have:\n\nPrimary category tag — one of the 8 categories\nSubcategory tag — more specific classification\nOptional project tag — if project-related\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\nQuick Start\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\nConfiguration\nVariable\tRequired\tDescription\nAGENTOS_API_KEY\tYes\tYour API key from agentos.software dashboard\nAGENTOS_BASE_URL\tYes\tAPI endpoint (default: http://178.156.216.106:3100)\nAGENTOS_AGENT_ID\tYes\tUnique identifier for this agent instance\nCore API Functions\naos_put - Store Memory\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\naos_get - Retrieve Memory\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\naos_search - Semantic Search\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\naos_delete - Remove Memory\naos_delete <path>\n\n# Creates a tombstone version (soft delete, keeps history)\naos_delete \"/cache/old-data\"\n\naos_list - List Children\naos_list <prefix>\n\n# Returns direct children under a path\naos_list \"/learnings\"\n# → {\"items\": [{\"path\": \"/learnings/2026-02-04\", \"type\": \"file\"}, ...]}\n\naos_glob - Pattern Match\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\naos_history - Version History\naos_history <path> [limit]\n\n# Returns all versions of a memory (for time travel)\naos_history \"/config/settings\" 20\n\naos_agents - List All Agents\naos_agents\n\n# Returns all agent IDs in your tenant with memory counts\n# Useful for discovering other agent instances\n\naos_dump - Bulk Export\naos_dump [agent_id] [limit]\n\n# Export all memories for an agent (default: current agent)\naos_dump \"\" 500\n\nSelf-Evolution Framework\n\nFor the complete self-evolution guide, see SELF-EVOLUTION.md.\n\nAgentOS enables agents to get smarter every day through:\n\nMistake tracking — Never repeat the same error\nProblem registry — Solutions indexed for future reference\nPre-task checks — Search learnings before acting\nProgress checkpoints — Anti-compaction memory saves\nVerification logging — Prove tasks are actually done\nQuick Start: Self-Evolution\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\nCore Functions\nFunction\tPurpose\naos_before_action\tCheck mistakes/solutions before acting\naos_mistake\tDocument a failure + lesson\naos_problem_solved\tRegister a solved problem\naos_check_solved\tSearch for similar solved problems\naos_save_progress\tLog completed task (anti-compaction)\naos_checkpoint\tSave working state (every 15-20 min)\naos_session_start\tRestore context at session start\naos_verify_logged\tLog verification evidence\naos_daily_summary\tReview today's work\naos_evolve_check\tShow evolution checklist\nRecommended Memory Structure\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\nSelf-Reflection Protocol\n\nAfter completing significant tasks, store reflections:\n\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\nSelf-Improvement Loop\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\nReal-Time Sync (WebSocket)\n\nConnect to receive live updates when memories change:\n\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\nWebSocket Events\nEvent\tPayload\tDescription\nmemory:created\t{agentId, path, versionId, value, tags, createdAt}\tNew memory stored\nmemory:deleted\t{agentId, path, versionId, deletedAt}\tMemory deleted\nWebhook Integration\n\nRegister webhooks to receive HTTP callbacks when memories change:\n\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\nWebhook Payload\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\nRate Limits & Quotas\nOperation\tDefault Limit\nRead ops (get, list, glob, history)\t60/min\nWrite ops (put, delete)\t60/min\nSearch ops\t20/min\nWebSocket connections\t5 per tenant\nHeartbeat Context Backup Protocol (CRITICAL)\n\nEvery agent using AgentOS MUST implement mandatory context backup on every heartbeat.\n\nWhy This Exists\nAI agents lose context during session compaction\n\"Remember to back up after each task\" doesn't work — agents forget\nHeartbeat-driven backup ensures context is NEVER lost\nClawdbot Configuration\n\nSet heartbeat to 10 minutes in your clawdbot.json:\n\n{\n \"agents\": {\n \"defaults\": {\n \"heartbeat\": {\n \"every\": \"10m\",\n \"model\": \"anthropic/claude-3-5-haiku-latest\"\n }\n }\n }\n}\n\nHEARTBEAT.md Template\n\nAdd this to your workspace's HEARTBEAT.md:\n\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\nAGENTS.md Hard Rule\n\nAdd this to your AGENTS.md:\n\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\nAgentOS Integration\n\nSync your CONTEXT.md to AgentOS on every heartbeat:\n\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\nBest Practices\n1. Use Meaningful Paths\n# Good - hierarchical, descriptive\naos_put \"/projects/raptor/decisions/2026-02-04-architecture\" '...'\n\n# Bad - flat, ambiguous\naos_put \"/data123\" '...'\n\n2. Tag Everything Important\nAOS_TAGS='[\"decision\",\"architecture\",\"raptor\"]' \\\nAOS_SEARCHABLE=true \\\naos_put \"/projects/raptor/decisions/...\" '...'\n\n3. Use TTL for Ephemeral Data\n# Cache that expires in 1 hour\nAOS_TTL=3600 aos_put \"/cache/api-response\" '...'\n\n4. Search Before Asking\n# Before asking user for info, check memory\nresult=$(aos_search \"user preferences for $TOPIC\" 3)\n\n5. Version Important Changes\n# Check history before overwriting\naos_history \"/config/critical-setting\" 5\n# Then update\naos_put \"/config/critical-setting\" '...'\n\nTroubleshooting\n\"Unauthorized\" errors\nCheck AGENTOS_API_KEY is set correctly\nVerify key has required scopes (memory:read, memory:write, search:read)\nEmpty search results\nEnsure memories were stored with searchable=true\nCheck if the embedding was generated (may take a few seconds)\nRate limit errors\nImplement exponential backoff\nBatch operations where possible\nCheck X-PreAuth-RateLimit-Remaining header\nMesh Communication (Agent-to-Agent)\n\nAgentOS Mesh enables real-time communication between AI agents.\n\nMesh Functions\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\nExample: Sending Messages\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\nExample: Processing Incoming Messages\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\nReal-Time Mesh Daemon\n\nFor real-time message reception, run the mesh daemon:\n\nnode ~/clawd/bin/mesh-daemon.mjs\n\n\nThe daemon connects via WebSocket and queues incoming messages for processing.\n\nMesh Events (WebSocket)\nEvent\tPayload\tDescription\nmesh:message\t{fromAgent, toAgent, topic, body, messageId}\tNew message received\nmesh:task_update\t{taskId, assignedTo, title, status}\tTask status changed\nCLI Shortcut\n\nA standalone CLI is also available:\n\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\nAPI Reference\n\nFull OpenAPI spec available at: $AGENTOS_BASE_URL/docs\n\nAgentOS - Persistent memory and mesh communication for evolving AI agents" }, "trust": { "sourceLabel": "tencent", "provenanceUrl": "https://clawhub.ai/AgentOSsoftware/agentos-sdk", "publisherUrl": "https://clawhub.ai/AgentOSsoftware/agentos-sdk", "owner": "AgentOSsoftware", "version": "3.7.0", "license": null, "verificationStatus": "Indexed source record" }, "links": { "detailUrl": "https://openagent3.xyz/skills/agentos-sdk", "downloadUrl": "https://openagent3.xyz/downloads/agentos-sdk", "agentUrl": "https://openagent3.xyz/skills/agentos-sdk/agent", "manifestUrl": "https://openagent3.xyz/skills/agentos-sdk/agent.json", "briefUrl": "https://openagent3.xyz/skills/agentos-sdk/agent.md" } }