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...

Security Scan

The package largely does what its name implies (an SDK for an agent memory/mesh service) but metadata, instructions, and included scripts disagree about required credentials and expose powerful data-export/mesh capabilities that could be abused or cause unexpected exfiltration; review before installing.

Purpose & Capability

The files and SKILL.md are consistent with an 'AgentOS SDK' (memory store, mesh, webhooks, CLI). However registry metadata claims no required env vars/configs while the README and scripts explicitly require AGENTOS_API_KEY, AGENTOS_AGENT_ID and AGENTOS_BASE_URL. That mismatch (declared: none vs actual: API key + agent id + base URL) is an incoherence that should be justified. The default AGENTOS_BASE_URL is a raw IP address (http://178.156.216.106:3100) which is unexpected for a reputable SDK and worth validating.

Instruction Scope

Runtime instructions mandate frequent heartbeats that read local files (CONTEXT.md, daily notes) and immediately sync them to the remote service on every heartbeat. The SKILL.md and AGENT-OPS.md make persistence mandatory (backup on every heartbeat), instruct sourcing the included agentos.sh into startup, and promote commands that will send local content to the network. While this is within the stated goal of a persistence SDK, it also means arbitrary agent state and files will be pushed to the configured remote endpoint automatically — a high-scope action that must be explicitly consented to and limited.

Install Mechanism

There is no automated install spec (instruction-only), which is lower-risk than auto-downloading/executing remote archives. However the skill bundles multiple shell scripts (agentos.sh, mesh.sh, examples) intended to be sourced and run; sourcing these will execute code on the host. Because the package contains many executable helpers, installing/sourcing without auditing them is risky even though there's no remote fetch/install stage.

Credentials

The SDK legitimately needs an API key and an agent id to contact the service, and the code uses Authorization: Bearer $AGENTOS_API_KEY. But the registry declares 'required env vars: none' — an inconsistency. More concerning: helper functions like aos_dump and aos_dump_all (bulk-export) and mesh.sh (which reads ~/.agentos-mesh.json and posts messages) provide broad export and cross-agent messaging capabilities. If the provided API key has wide scope, these functions can exfiltrate large amounts of data or all tenant memories. The default base URL is an IP rather than a verified domain, which increases the risk that sensitive data will be sent to an unexpected host.

Persistence & Privilege

The skill does not set always:true and does not request system-wide config changes. However the instructions explicitly recommend sourcing agentos.sh during every session and configuring heartbeats that sync every 10 minutes. That grants the SDK ongoing network activity from the agent (regular context backup). This autonomous, persistent network behavior is coherent with the SDK's purpose but it increases blast radius — review API key scope and endpoint trust before enabling.

What to consider before installing

Before installing or sourcing this skill: 1) Verify the upstream/source and confirm that the default API endpoint (http://178.156.216.106:3100) is legitimate — prefer a trusted domain over an IP. 2) Treat AGENTOS_API_KEY as sensitive: check what scope/permissions that key grants (can it list/dump-all tenant memories?). 3) Audit the provided scripts (agentos.sh, mesh.sh, examples) — note aos_dump_all, aos_dump, and mesh commands can export messages and memory data; ensure the API key is not overly permissive. 4) Don't enable automatic heartbeats or source the SDK in production until you are comfortable that automatic backups won't transmit sensitive local files (CONTEXT.md, daily notes). 5) If you must test, run the SDK in an isolated sandbox with a limited-scope key and a non-sensitive dataset. 6) Request corrected registry metadata (declare required env vars) or a signed/verified upstream homepage before trusting this skill broadly.

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:

# 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:

~/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

# 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

# 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

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

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

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

aos_delete <path>

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

aos_list - List Children

aos_list <prefix>

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

aos_glob - Pattern Match

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

aos_history <path> [limit]

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

aos_agents - List All Agents

aos_agents

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

aos_dump - Bulk Export

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

# 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:

# 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

# 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:

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:

# 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

{
  "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:

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

HEARTBEAT.md Template

Add this to your workspace's HEARTBEAT.md:

## 🔴 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:

## 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:

# 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

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

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

2. Tag Everything Important

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

3. Use TTL for Ephemeral Data

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

4. Search Before Asking

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

5. Version Important Changes

# 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

# 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

# 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

# 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:

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:

~/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