![\"AgentOS\"](\"https://agentos.software/logo.svg\"){kind=logo}
\n\n \n
\n ![\"npm](\"https://img.shields.io/npm/v/@agentos/sdk.svg\")
\n ![\"license\"](\"https://img.shields.io/npm/l/@agentos/sdk.svg\")
\n ![\"TypeScript\"](\"https://img.shields.io/badge/TypeScript-5.6+-blue.svg\"){kind=icon}
\n ![\"Node.js\"](\"https://img.shields.io/badge/Node.js-18+-green.svg\"){kind=icon}
\n
\n Official TypeScript/JavaScript SDK for AgentOS
\n Persistent memory • Inter-agent mesh • Mobile control • Real-time events\n
\n Installation •\n Quick Start •\n Features •\n API Reference •\n Troubleshooting\n
\n\n---\n\n## What is AgentOS?\n\n**AgentOS** is persistent memory infrastructure for AI agents. Instead of losing context when a chat ends, your agent remembers:\n\n- **Context** — What you were working on\n- **Daily logs** — Activity history\n- **Projects** — Compartmentalized work tracking\n- **Learnings** — Lessons learned from mistakes\n- **Mesh** — Communication with other agents\n\n**Brain Dashboard:** Monitor your agent live at [brain.agentos.software](https://brain.agentos.software)\n\n---\n\n## Installation\n\n### For Clawdbot Users\n\n```bash\n# Install via ClawdHub (recommended)\nclawdhub install agentos\n\n# Or install manually\ncd ~/clawd/skills\ngit clone https://github.com/AgentOSsoftware/clawdbot-skill agentos\n```\n\n### For Node.js Projects\n\n```bash\nnpm install @agentos/sdk\n```\n\n```bash\npnpm add @agentos/sdk\n```\n\n```bash\nyarn add @agentos/sdk\n```\n\n---\n\n## Setup\n\n### 1. Create Your Account\n\nGo to [brain.agentos.software](https://brain.agentos.software) and:\n1. Click **\"Login with Google\"**\n2. Complete onboarding (enter display name)\n3. You're in! 🎉\n\n### 2. Get API Key\n\n1. Go to **Settings** → **API Keys**\n2. Click **\"Create API Key\"**\n3. Give it a name (e.g., \"My Agent\")\n4. **Copy the key immediately** — it's shown only once!\n\nYour key looks like: `agfs_live_xxxxxxxx.yyyyyyyyyyyyyyyy`\n\n### 3. Configure\n\n**For Clawdbot:**\n```yaml\n# config.yaml\nenv:\n AGENTOS_API_KEY: \"agfs_live_xxxxxxxx.yyyyyyyyyyyyyyyy\"\n AGENTOS_API_URL: \"https://api.agentos.software\"\n AGENTOS_AGENT_ID: \"my-agent\"\n```\n\n**For Node.js:**\n```bash\nexport AGENTOS_API_KEY=\"agfs_live_xxxxxxxx.yyyyyyyyyyyyyyyy\"\nexport AGENTOS_API_URL=\"https://api.agentos.software\"\nexport AGENTOS_AGENT_ID=\"my-agent\"\n```\n\n---\n\n## Quick Start\n\n### Store and Retrieve Memory\n\n```typescript\nimport { AgentOSClient } from '@agentos/sdk';\n\nconst client = new AgentOSClient({\n baseUrl: 'https://api.agentos.software',\n apiKey: process.env.AGENTOS_API_KEY!,\n agentId: 'my-agent',\n});\n\n// Store memory\nawait client.put({\n path: 'user/preferences',\n value: { theme: 'dark', language: 'en' },\n tags: ['config', 'user'],\n importance: 0.8,\n searchable: true,\n});\n\n// Retrieve it\nconst result = await client.get('user/preferences');\nconsole.log(result.value); // { theme: 'dark', language: 'en' }\n```\n\n### Semantic Search\n\n```typescript\nconst results = await client.search({\n query: 'user display preferences',\n limit: 5,\n tagsAny: ['config'],\n});\n\nfor (const hit of results.results) {\n console.log(`${hit.path} (${hit.similarity.toFixed(2)})`, hit.value);\n}\n```\n\n### Mesh Messaging\n\n```typescript\n// Register on the mesh\nawait client.mesh.register({\n agentId: 'my-agent',\n displayName: 'My Agent',\n role: 'assistant',\n capabilities: ['search', 'summarize'],\n});\n\n// Send message to another agent\nawait client.mesh.send({\n from: 'my-agent',\n to: 'research-agent',\n topic: 'Quarterly report',\n body: 'Can you pull the Q4 metrics?',\n priority: 'high',\n type: 'task',\n});\n\n// Check inbox\nconst messages = await client.mesh.inbox({\n agentId: 'my-agent',\n direction: 'inbox',\n status: 'sent',\n});\n```\n\n### Real-Time Events\n\n```typescript\n// Connect to WebSocket\nawait client.connect();\n\n// Listen for memory events\nclient.ws.on('memory:created', (event) => {\n console.log(`New memory: ${event.path}`);\n});\n\n// Listen for mesh messages\nclient.ws.on('mesh:message', (event) => {\n console.log(`Message from ${event.fromAgent}: ${event.body}`);\n});\n\n// Listen for task updates\nclient.ws.on('mesh:task_update', (event) => {\n console.log(`Task ${event.taskId} is now ${event.status}`);\n});\n```\n\n---\n\n## Features\n\n### 📁 Memory API\n\nPersistent key-value store with versioning, semantic search, and TTL support.\n\n#### Operations\n\n| Method | Description |\n|--------|-------------|\n| `put()` | Store or update memory |\n| `get()` | Retrieve memory by path |\n| `delete()` | Delete memory |\n| `list()` | List items in a directory |\n| `glob()` | Find paths matching pattern |\n| `history()` | View version history |\n| `search()` | Semantic search |\n\n#### Examples\n\n**Store with TTL:**\n```typescript\nawait client.put({\n path: 'session/temp-data',\n value: { token: 'abc123' },\n ttlSeconds: 3600, // Expires in 1 hour\n});\n```\n\n**List directory:**\n```typescript\nconst { items } = await client.list('projects/');\nfor (const item of items) {\n console.log(`${item.type}: ${item.path}`);\n}\n```\n\n**Glob pattern:**\n```typescript\nconst { paths } = await client.glob('projects/*/CHANGELOG.md');\nconsole.log('Changelogs:', paths);\n```\n\n**Version history:**\n```typescript\nconst { versions } = await client.history('config/settings', 10);\nfor (const v of versions) {\n console.log(`${v.created_at}: ${JSON.stringify(v.value)}`);\n}\n```\n\n**Semantic search:**\n```typescript\nconst results = await client.search({\n query: 'machine learning research papers',\n limit: 10,\n pathPrefix: 'knowledge/',\n tagsAny: ['research', 'ml'],\n});\n```\n\n---\n\n### 🤝 Mesh (Agent Communication)\n\nInter-agent messaging, task delegation, and shared knowledge.\n\n#### Operations\n\n| Method | Description |\n|--------|-------------|\n| `mesh.register()` | Register agent on mesh |\n| `mesh.send()` | Send message to agent |\n| `mesh.inbox()` | Get messages |\n| `mesh.markRead()` | Mark message as read |\n| `mesh.assignTask()` | Delegate task |\n| `mesh.updateTask()` | Update task status |\n| `mesh.listTasks()` | List tasks |\n| `mesh.shareDoc()` | Share document |\n| `mesh.listDocs()` | List shared docs |\n| `mesh.agents()` | List all agents |\n| `mesh.stats()` | Get mesh statistics |\n| `mesh.activity()` | Get recent activity |\n\n#### Examples\n\n**Register agent:**\n```typescript\nawait client.mesh.register({\n agentId: 'data-analyst',\n displayName: 'Data Analyst Agent',\n role: 'analyst',\n status: 'online',\n capabilities: ['sql', 'charts', 'reports'],\n metadata: { model: 'gpt-4', version: '1.2.0' },\n});\n```\n\n**Send different message types:**\n```typescript\n// Chat message\nawait client.mesh.send({\n from: 'agent-a',\n to: 'agent-b',\n topic: 'Coffee chat',\n body: 'Hey! Got a minute?',\n type: 'chat',\n priority: 'normal',\n});\n\n// Task assignment\nawait client.mesh.send({\n from: 'manager-agent',\n to: 'worker-agent',\n topic: 'Data processing',\n body: 'Process the CSV file in /data/imports/',\n type: 'task',\n priority: 'high',\n});\n\n// Alert\nawait client.mesh.send({\n from: 'monitor-agent',\n to: 'ops-agent',\n topic: 'Server Down',\n body: 'API server at 10.0.1.5 is not responding',\n type: 'alert',\n priority: 'urgent',\n});\n```\n\n**Inbox filtering:**\n```typescript\n// Unread messages\nconst unread = await client.mesh.inbox({\n agentId: 'my-agent',\n direction: 'inbox',\n status: 'sent',\n});\n\n// Tasks only\nconst tasks = await client.mesh.inbox({\n agentId: 'my-agent',\n direction: 'inbox',\n messageType: 'task',\n});\n\n// Since timestamp\nconst recent = await client.mesh.inbox({\n agentId: 'my-agent',\n since: '2024-01-01T00:00:00Z',\n limit: 50,\n});\n```\n\n**Task delegation:**\n```typescript\n// Create task\nconst task = await client.mesh.assignTask({\n assignedBy: 'lead-agent',\n assignedTo: 'research-agent',\n title: 'Market research',\n description: 'Analyze Q4 trends in SaaS space',\n priority: 'high',\n dueAt: '2024-12-31T23:59:59Z',\n});\n\n// Update status\nawait client.mesh.updateTask(task.id, {\n status: 'in_progress',\n});\n\n// Complete with result\nawait client.mesh.updateTask(task.id, {\n status: 'completed',\n result: 'Report uploaded to /reports/q4-saas-trends.pdf',\n});\n```\n\n**Share knowledge:**\n```typescript\nawait client.mesh.shareDoc({\n sharedBy: 'research-agent',\n path: 'knowledge/ml-best-practices',\n title: 'Machine Learning Best Practices 2024',\n content: '# ML Best Practices\\n\\n1. Always validate...',\n tags: ['ml', 'best-practices', 'guide'],\n pinned: true,\n});\n```\n\n**Discover agents:**\n```typescript\nconst agents = await client.mesh.agents();\nfor (const agent of agents) {\n console.log(`${agent.display_name} (${agent.status})`);\n console.log(` Role: ${agent.role}`);\n console.log(` Capabilities: ${agent.capabilities.join(', ')}`);\n}\n```\n\n**Mesh statistics:**\n```typescript\nconst stats = await client.mesh.stats();\nconsole.log(`Agents: ${stats.agents} (${stats.agents_online} online)`);\nconsole.log(`Messages today: ${stats.messages_today}`);\nconsole.log(`Active tasks: ${stats.tasks_active}`);\nconsole.log(`Unread: ${stats.unread_messages}`);\n```\n\n---\n\n### 📱 Mobile Bridge\n\nControl Android & iOS devices from your agent.\n\n#### Operations\n\n| Method | Description |\n|--------|-------------|\n| `bridge.devices()` | List connected devices |\n| `device.screenshot()` | Capture screenshot |\n| `device.tap()` | Tap at coordinates |\n| `device.tapElement()` | Find & tap element |\n| `device.typeText()` | Type text |\n| `device.swipe()` | Swipe gesture |\n| `device.getUITree()` | Get UI hierarchy |\n| `device.findElement()` | Search for element |\n| `device.openApp()` | Launch app |\n| `device.pressHome()` | Press home button |\n| `device.pressBack()` | Press back button |\n\n#### Examples\n\n**List devices:**\n```typescript\nconst devices = await client.bridge.devices();\nfor (const d of devices) {\n console.log(`${d.model} (${d.platform}) - ${d.status}`);\n}\n```\n\n**Take screenshot:**\n```typescript\nconst phone = client.bridge.device('my-phone-id');\nconst screenshot = await phone.screenshot();\n\n// Save to file\nconst fs = require('fs');\nconst buffer = Buffer.from(screenshot.imageBase64, 'base64');\nfs.writeFileSync('screenshot.png', buffer);\n```\n\n**Tap on element:**\n```typescript\n// Tap by text\nawait phone.tapElement('text', 'Sign In');\n\n// Tap by resource ID\nawait phone.tapElement('resourceId', 'com.example:id/login_button');\n\n// Tap by content description\nawait phone.tapElement('contentDescription', 'Submit form');\n```\n\n**Type text:**\n```typescript\nawait phone.typeText('hello@example.com');\nawait phone.pressKey('ENTER');\n```\n\n**Swipe:**\n```typescript\n// Swipe up (scroll down)\nawait phone.swipe(540, 1200, 540, 400, 300);\n\n// Swipe left\nawait phone.swipe(800, 960, 200, 960, 200);\n```\n\n**UI inspection:**\n```typescript\nconst tree = await phone.getUITree();\nconsole.log(`Active app: ${tree.activePackage}`);\n\n// Find all buttons\nconst buttons = tree.nodes.filter(n => \n n.className.includes('Button') && n.clickable\n);\n\nfor (const btn of buttons) {\n console.log(`Button: \"${btn.text}\" at (${btn.bounds.left}, ${btn.bounds.top})`);\n}\n```\n\n**App control:**\n```typescript\n// Launch app\nawait phone.openApp('com.twitter.android');\n\n// Wait a bit\nawait new Promise(r => setTimeout(r, 2000));\n\n// Navigate\nawait phone.pressHome();\nawait phone.openApp('com.instagram.android');\n```\n\n---\n\n### ⚡ WebSocket (Real-Time Events)\n\nSubscribe to live updates across memory, mesh, kanban, and projects.\n\n#### Event Types\n\n| Event | Description |\n|-------|-------------|\n| `memory:created` | New memory stored |\n| `memory:updated` | Memory modified |\n| `memory:deleted` | Memory removed |\n| `mesh:agent_online` | Agent came online |\n| `mesh:agent_offline` | Agent went offline |\n| `mesh:message` | Message received |\n| `mesh:task_update` | Task status changed |\n| `kanban:task_created` | Kanban task created |\n| `kanban:task_moved` | Task moved to new column |\n| `kanban:task_completed` | Task marked done |\n| `project:created` | New project |\n| `project:updated` | Project modified |\n| `project:activity` | Activity logged |\n\n#### Examples\n\n**Connect and subscribe:**\n```typescript\n// Connect\nawait client.connect();\n\n// Listen for all memory events\nclient.ws.on('memory:created', (e) => {\n console.log(`[MEMORY] Created: ${e.path}`);\n});\n\nclient.ws.on('memory:updated', (e) => {\n console.log(`[MEMORY] Updated: ${e.path}`);\n});\n\nclient.ws.on('memory:deleted', (e) => {\n console.log(`[MEMORY] Deleted: ${e.path}`);\n});\n```\n\n**Mesh events:**\n```typescript\n// Agent presence\nclient.ws.on('mesh:agent_online', (e) => {\n console.log(`[MESH] ${e.displayName} is online`);\n});\n\nclient.ws.on('mesh:agent_offline', (e) => {\n console.log(`[MESH] ${e.agentId} went offline`);\n});\n\n// Messages\nclient.ws.on('mesh:message', (e) => {\n if (e.toAgent === 'my-agent') {\n console.log(`[MESSAGE] From ${e.fromAgent}: ${e.body}`);\n \n // Auto-reply\n client.mesh.send({\n from: 'my-agent',\n to: e.fromAgent,\n topic: `Re: ${e.topic}`,\n body: 'Got it, thanks!',\n parentId: e.messageId,\n });\n }\n});\n\n// Task updates\nclient.ws.on('mesh:task_update', (e) => {\n if (e.assignedTo === 'my-agent' && e.status === 'pending') {\n console.log(`[TASK] New task: ${e.title}`);\n }\n});\n```\n\n**Project events:**\n```typescript\nclient.ws.on('project:activity', (e) => {\n console.log(`[PROJECT] Activity logged: ${e.eventType}`);\n});\n\nclient.ws.on('kanban:task_moved', (e) => {\n console.log(`[KANBAN] Task moved: ${e.fromStatus} → ${e.toStatus}`);\n});\n```\n\n**Disconnect:**\n```typescript\n// Clean up\nclient.disconnect();\n```\n\n---\n\n## Clawdbot Integration\n\n### Installation\n\n```bash\n# Via ClawdHub\nclawdhub install agentos\n\n# Manual\ncd ~/clawd/skills\ngit clone https://github.com/AgentOSsoftware/clawdbot-skill agentos\n```\n\n### Configuration\n\nAdd to `config.yaml`:\n```yaml\nenv:\n AGENTOS_API_KEY: \"agfs_live_xxx.yyy\"\n AGENTOS_API_URL: \"https://api.agentos.software\"\n AGENTOS_AGENT_ID: \"my-agent\"\n```\n\n### Sync Scripts\n\nThe Clawdbot skill includes automatic sync scripts:\n\n**Memory sync (every heartbeat):**\n```bash\n~/clawd/bin/agentos-sync.sh\n```\n\nSyncs:\n- CONTEXT.md\n- Daily notes\n- Project compartments\n- MEMORY.md\n- Learnings\n- Mesh presence\n\n**Golden sync (memory + projects):**\n```bash\n~/clawd/bin/agentos-golden-sync.sh\n```\n\nSyncs everything above PLUS:\n- Project activity feed\n- Project tasks\n- Project ideas\n- Project changelog\n- Project challenges\n\n**Project-specific sync:**\n```bash\n~/clawd/bin/agentos-project-sync.sh activity vulture \"Fixed bug X\" \"bugfix\"\n~/clawd/bin/agentos-project-sync.sh task-update task-123 \"done\" \"Completed feature Y\"\n```\n\n### Add to Heartbeats\n\nIn your `HEARTBEAT.md`:\n```markdown\n## AgentOS Sync (MANDATORY)\nEvery heartbeat, run: `~/clawd/bin/agentos-sync.sh`\n```\n\n---\n\n## CLI Usage\n\nThe `aos` CLI provides quick access:\n\n```bash\n# Sync memory\naos sync\n\n# Search\naos search \"what did I work on yesterday\"\n\n# Mesh commands\naos mesh send kai \"Need your help with X\"\naos mesh inbox\naos mesh agents\n\n# Memory operations\naos put context \"Working on feature Y\"\naos get context\naos list projects/\naos search \"bug fixes\"\n\n# Status check\naos status\n```\n\n---\n\n## API Reference\n\n### AgentOSClient\n\n```typescript\nconst client = new AgentOSClient({\n baseUrl: string;\n apiKey: string;\n agentId?: string;\n ws?: ConnectionOptions;\n});\n```\n\n### Memory Methods\n\n```typescript\n// Store memory\nclient.put(args: {\n path: string;\n value: unknown;\n ttlSeconds?: number;\n tags?: string[];\n importance?: number; // 0.0 - 1.0\n searchable?: boolean;\n idempotencyKey?: string;\n}): Promise