Content
<div align="center">
# Aether OS
### Agent Native Operating System
**Transform AI Agents from Disposable Chat Programs to 24/7 Digital Employees**
[](https://opensource.org/licenses/MIT)
[](https://github.com/worldop123/aether-os/actions/workflows/ci.yml)
[](https://www.typescriptlang.org/)
[](https://nodejs.org/)
[](#tests)
[](#package-structure)
[](https://github.com/worldop123/aether-os/discussions)
</div>
---
## Table of Contents
- [Introduction](#introduction)
- [Features](#features)
- [Quick Start](#quick-start)
- [Package Structure](#package-structure)
- [Core Concepts](#core-concepts)
- [Usage Examples](#usage-examples)
- [CLI Commands](#cli-commands)
- [Web UI](#web-ui)
- [Configuration](#configuration)
- [Tests](#tests)
- [Architecture Documentation](#architecture-documentation)
- [Contributing](#contributing)
- [License](#license)
## Introduction
Aether OS is a stateful runtime operating system for AI Agents. It manages the lifecycle, resource scheduling, memory storage, and process isolation of Agents, transforming them from disposable chat programs to 24/7 digital employees.
### Design Philosophy
1. **Local-first**: Run locally by default, with user-owned data
2. **Progressive Complexity**: Simple things should be simple, complex things should be possible
3. **Standard Compatibility**: Embrace standards like MCP and A2A, avoid reinventing the wheel
4. **Observability**: System internal state must be observable and debuggable
5. **Security by Default**: Security is the default option, not an optional feature
## Features
### Core Capabilities
- **Agent Lifecycle Management** - Create, start, pause, resume, and stop Agents
- **Process Isolation** - ProcessManager manages multiple independent Agents
- **Memory System** - Short-term and long-term memory (with vector retrieval)
- **Model Routing** - Supports OpenAI, Anthropic, Ollama, and Mock providers
- **Budget Control** - Token usage tracking and budget limits
- **MCP Tool System** - Built-in tools and external MCP server connections (stdio)
- **Task Scheduling** - Complete cron syntax and SQLite persistence
- **Event-driven** - All modules communicate through EventBus
### Advanced Features
- **Agent-to-Agent Communication (A2A)** - Agent discovery, message passing, and request-response patterns
- Local inter-process communication (LocalA2AChannel)
- Cross-process HTTP communication (HttpA2AChannel)
- **Security Sandbox** - Code isolation with node:vm, 14 permission controls, and audit logs
- **Workflow Orchestration** - DAG-based workflows with conditional branching, parallel execution, loops, and retries
- **Skill System** - 5 built-in skills (code assistant, document writing, data analysis, etc.) with custom skill support
- **Observability** - Log aggregation, metric collection (Counter/Gauge/Histogram), and tracing
- **Memory Consolidation and Forgetting** - Automatic consolidation of important short-term memory to long-term memory and forgetting of unimportant memory
- **Web UI** - Visual management interface with REST API and SSE event stream
- **CLI Tool** - Colorful output, progress bars, interactive mode, and configuration files
## Quick Start
### Environment Requirements
- **Node.js** >= 18.0.0 (recommended 20+)
- **pnpm** >= 9.0.0
### Installation
```bash
# Clone repository
git clone https://github.com/worldop123/aether-os.git
cd aether-os
# Install dependencies
pnpm install
# Build all packages
pnpm build
# Run all tests (optional, verify environment)
pnpm test
```
### First Agent
```bash
# Create Agent
node packages/cli/dist/cli.js agent create --name my-agent
# Start Agent
node packages/cli/dist/cli.js agent start --id <agent-id>
# View status
node packages/cli/dist/cli.js agent list
# Chat with Agent
node packages/cli/dist/cli.js chat --message "Hello"
# Interactive mode
node packages/cli/dist/cli.js chat -i
```
### Programmatic Usage
```typescript
import { ProcessManager, AgentStatus } from '@aether/core';
import { MemoryManager } from '@aether/memory';
import { ModelRouter, MockModelProvider, BudgetController } from '@aether/model-router';
// Initialize components
const processManager = new ProcessManager();
const memoryManager = new MemoryManager();
const budgetController = new BudgetController({ dailyBudget: 100000 });
const modelRouter = new ModelRouter();
modelRouter.registerProvider(new MockModelProvider());
// Create and start Agent
const agent = processManager.createAgent({
name: 'my-agent',
description: 'My first Agent',
});
processManager.startAgent(agent.id);
// Add memory
memoryManager.addMessage(agent.id, {
role: 'user',
content: 'Remember: User likes Python',
});
// Consolidate to long-term memory
await memoryManager.consolidateToLongTerm(agent.id);
// Search memory
const results = await memoryManager.searchLongTerm(agent.id, 'Programming language preference');
console.log(results);
```
## Package Structure
Aether OS uses a monorepo architecture with 13 packages:
| Package | Description | Status |
| --- | --- | --- |
| [@aether/shared](./packages/shared) | Shared modules (constants, error classes, event bus, utility functions) | ✅ Stable |
| [@aether/core](./packages/core) | Core modules (Agent class, ProcessManager, AgentRuntime) | ✅ Stable |
| [@aether/memory](./packages/memory) | Memory system (short-term/long-term memory, vector retrieval, consolidation, and forgetting) | ✅ Stable |
| [@aether/model-router](./packages/model-router) | Model routing (OpenAI/Anthropic/Ollama + budget control) | ✅ Stable |
| [@aether/mcp](./packages/mcp) | MCP tool system (built-in tools + stdio client) | ✅ Stable |
| [@aether/scheduler](./packages/scheduler) | Task scheduling (complete cron + SQLite persistence) | ✅ Stable |
| [@aether/cli](./packages/cli) | Command-line tool (colorful output + interactive mode) | ✅ Stable |
| [@aether/skills](./packages/skills) | Skill system (5 built-in skills + custom skills) | 🚧 Experimental |
| [@aether/observability](./packages/observability) | Observability (logs + metrics + tracing) | 🚧 Experimental |
| [@aether/a2a](./packages/a2a) | Agent-to-Agent communication (local + HTTP cross-process) | 🚧 Experimental |
| [@aether/sandbox](./packages/sandbox) | Security sandbox (permission control + audit logs) | 🚧 Experimental |
| [@aether/workflow](./packages/workflow) | Workflow orchestration (DAG + conditional branching + parallel) | 🚧 Experimental |
| [@aether/web](./packages/web) | Web UI (REST API + management interface) | 🚧 Experimental |
## Core Concepts
### Agent
Agent is the core entity of Aether OS. Each Agent has its own state, memory, and lifecycle.
```typescript
import { ProcessManager, AgentStatus } from '@aether/core';
const processManager = new ProcessManager();
// Create Agent
const agent = processManager.createAgent({
name: 'assistant',
description: 'Personal assistant',
model: 'gpt-4',
});
// Lifecycle management
processManager.startAgent(agent.id); // IDLE -> RUNNING
processManager.pauseAgent(agent.id); // RUNNING -> PAUSED
processManager.resumeAgent(agent.id); // PAUSED -> RUNNING
processManager.stopAgent(agent.id); // -> STOPPED
```
### Memory System
The memory system consists of short-term and long-term memory:
```typescript
import { MemoryManager } from '@aether/memory';
import { VectorMemoryManager } from '@aether/memory';
import { MockModelProvider } from '@aether/model-router';
// Basic usage
const memory = new MemoryManager();
// Advanced usage with vector retrieval
const vectorMemory = new VectorMemoryManager({
provider: new MockModelProvider(),
});
// Add short-term memory
memory.addMessage(agentId, {
role: 'user',
content: 'I like using TypeScript',
});
// Consolidate to long-term memory
await memory.consolidateToLongTerm(agentId);
// Search long-term memory
const results = await memory.searchLongTerm(agentId, 'Programming language preference');
```
### Model Routing
Supports multiple model providers with automatic selection:
```typescript
import { ModelRouter, OpenAIProvider, AnthropicProvider, OllamaProvider } from '@aether/model-router';
const router = new ModelRouter();
// Register providers
router.registerProvider(new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY }));
router.registerProvider(new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY }));
router.registerProvider(new OllamaProvider({ baseURL: 'http://localhost:11434' }));
// Route by strategy
const response = await router.route({
messages: [{ role: 'user', content: 'Hello' }],
strategy: 'cheapest', // cheapest | fastest | best-quality | balanced
});
```
### MCP Tool System
Supports built-in tools and external MCP servers:
```typescript
import { McpManager } from '@aether/mcp';
const manager = new McpManager();
// Use built-in tools
const result = await manager.executeTool('calculate', { expression: '1 + 2 * 3' });
// Connect to external MCP server (stdio mode)
await manager.loadServer('filesystem', {
type: 'stdio',
command: 'npx',
args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
});
// Call remote tools
const tools = manager.listAllTools();
```
### Task Scheduling
Supports complete cron syntax for scheduled tasks:
```typescript
import { TaskScheduler } from '@aether/scheduler';
import { SqlitePersistence } from '@aether/scheduler';
const scheduler = new TaskScheduler();
// Optional: connect to SQLite persistence
const persistence = new SqlitePersistence({ dbPath: './aether.db' });
await persistence.initialize();
scheduler.setPersistence(persistence);
// Register task handler
scheduler.registerTaskHandler('monitor', async (task) => {
console.log('Execute monitoring task:', task.id);
});
// Add scheduled task (complete cron syntax)
const task = await scheduler.schedule({
name: 'Hourly monitoring',
agentId: 'agent-1',
cron: '0 * * * *', // Every hour on the hour
type: 'monitor',
handler: 'monitor',
payload: { url: 'https://example.com' },
});
// Start scheduler
scheduler.start();
```
### Agent-to-Agent Communication (A2A)
```typescript
import { A2AProtocol, createAgentCard } from '@aether/a2a';
const protocol = new A2AProtocol();
// Register Agent
const card = createAgentCard({
name: 'researcher',
capabilities: [{ name: 'search', description: 'Search capability' }],
});
await protocol.registerAgent(card);
// Send request and wait for response
const response = await protocol.request(
'agent-1',
'agent-2',
{ query: 'How is the weather today?' },
5000 // timeout
);
```
### Security Sandbox
Execute untrusted code in an isolated environment:
```typescript
import { SkillSandbox, PermissionPolicy } from '@aether/sandbox';
const policy: PermissionPolicy = {
default: 'deny',
rules: [
{ permission: 'time', allowed: true },
{ permission: 'random', allowed: true },
{ permission: 'fs.read', allowed: true, resources: ['/tmp/safe/**'] },
],
limits: { maxTimeoutMs: 5000 },
};
const sandbox = new SkillSandbox({ policy });
const result = await sandbox.execute(
{ skillId: 'untrusted-skill', policy },
'return 1 + 2;',
{}
);
```
### Workflow Orchestration
```typescript
import { WorkflowBuilder, WorkflowExecutor } from '@aether/workflow';
const workflow = new WorkflowBuilder('data-pipeline')
.task('fetch', 'Fetch Data', async (input) => {
return { data: [1, 2, 3] };
})
.task('process', 'Process Data', async (input: any) => {
return input.data.map((x: number) => x * 2);
})
.condition('check', 'Check Result', async (input: any) => input.length > 0)
.task('save', 'Save Result', async (input) => `saved ${input.length} items`)
.edge('fetch', 'process')
.edge('process', 'check')
.edge('check', 'save', 'true')
.retry('fetch', { maxAttempts: 3, delayMs: 100 })
.build();
const executor = new WorkflowExecutor();
const result = await executor.execute(workflow, {});
```
## Usage Examples
The project includes 3 complete examples:
| Example | Description |
|---|---|
| [monitor-agent-demo.ts](./examples/monitor-agent-demo.ts) | Background Monitoring Agent (Scheduled Task + Memory + Budget Control) |
| [memory-system-demo.ts](./examples/memory-system-demo.ts) | Complete Memory System Example (Vector Retrieval + Semantic Similarity) |
| [custom-skill-demo.ts](./examples/custom-skill-demo.ts) | Custom Skill (MCP Tool + Chain Call) |
Run examples:
```bash
# Use tsx to run (recommended)
pnpm dlx tsx examples/memory-system-demo.ts
# Or compile and run
npx tsc --outDir dist examples/memory-system-demo.ts
node dist/memory-system-demo.js
```
## CLI Commands
```bash
# View help
aether --help
# Agent management
aether agent list
aether agent create --name <name>
aether agent start --id <id>
aether agent stop --id <id>
aether agent status --id <id>
# Memory management
aether memory list --agent <id>
aether memory add --agent <id> --content "content"
aether memory search --agent <id> --query "keyword"
# Budget control
aether budget status
aether budget set --amount 100000
# MCP tools
aether mcp servers
aether mcp tools
aether mcp run --tool calculate --args '{"expression":"1+2"}'
# Task scheduling
aether schedule list
aether schedule add --name <name> --cron "0 * * * *" --type <type>
# Chat
aether chat --message "Hello"
aether chat -i # Interactive mode
# Configuration management
aether config list
aether config get defaultModel
aether config set defaultModel gpt-4
# Web UI
aether web --port 3000
```
## Web UI
Start the web management interface:
```bash
aether web --port 3000
# Then access http://localhost:3000
```
The Web UI provides:
- **Dashboard** - System overview
- **Agents** - Agent management interface
- **Memories** - Memory viewing and search
- **Budget** - Budget status
- **MCP** - Tool management
- **Schedules** - Task scheduling
- **SSE Event Stream** - Real-time event push
See the REST API documentation at [packages/web/README.md](./packages/web/).
## Configuration
The configuration file is located at `~/.aether/config.json`:
```json
{
"defaultModel": "gpt-4",
"defaultAgentId": "agent-1",
"color": true,
"format": "text",
"providers": {
"openai": {
"apiKey": "your-api-key"
},
"anthropic": {
"apiKey": "your-api-key"
},
"ollama": {
"baseURL": "http://localhost:11434"
}
},
"mcpServers": {
"filesystem": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
"enabled": true
}
},
"dataDir": "~/.aether/data"
}
```
Environment variables:
| Variable | Description |
|---|---|
| `OPENAI_API_KEY` | OpenAI API key |
| `ANTHROPIC_API_KEY` | Anthropic API key |
| `OLLAMA_BASE_URL` | Ollama service address (default http://localhost:11434) |
## Testing
```bash
# Run all tests
pnpm test
# Run tests for a single package
pnpm --filter @aether/core test
# Watch mode
pnpm test:watch
# Generate coverage report
pnpm test:coverage
```
Current test status:
- **735 tests pass**
- **25 test files**
- Covers all 11 packages
## Architecture Documentation
See the detailed architecture design in [ARCHITECTURE.md](./ARCHITECTURE.md).
### Tech Stack
- **Language**: TypeScript (strict mode)
- **Package management**: pnpm (monorepo workspace)
- **Testing**: Vitest
- **Event-driven**: Node.js EventEmitter
- **Database**: SQLite (better-sqlite3)
- **Module system**: ESM (NodeNext)
### Event System
All modules communicate through `globalEventBus`, with event names defined in `@aether/shared`'s `EVENTS`. There are 30+ events defined, covering Agent lifecycle, memory, model routing, MCP, scheduling, A2A, sandbox, workflow, etc.
## Contribution
Contributions are welcome! Read [CONTRIBUTING.md](./CONTRIBUTING.md) to learn how to participate.
- Report bugs: [GitHub Issues](https://github.com/worldop123/aether-os/issues)
- Discuss ideas: [GitHub Discussions](https://github.com/worldop123/aether-os/discussions)
- Contribute code: [Pull Request](https://github.com/worldop123/aether-os/pulls)
### Contributors
<a href="https://github.com/worldop123/aether-os/graphs/contributors">
<img src="https://contrib.rocks/image?repo=worldop123/aether-os" />
</a>
## Roadmap
### Completed ✅
- [x] 7 core packages (shared/core/memory/model-router/mcp/scheduler/cli)
- [x] Real model providers (OpenAI/Anthropic/Ollama)
- [x] SQLite persistence
- [x] Real MCP server connection (stdio)
- [x] Vector memory retrieval
- [x] CLI improvement (color output/progress bar/interactive mode/configuration file)
- [x] Agent-to-Agent communication (A2A)
- [x] Secure sandbox
- [x] Workflow orchestration
- [x] Web UI
### Planned 🚀
- [ ] HTTP/SSE mode MCP server connection
- [ ] Real vector database integration (e.g., sqlite-vss)
- [ ] Distributed Agent deployment
- [ ] Plugin market
- [ ] More language SDKs (Python/Go)
## License
[MIT License](./LICENSE) © 2026 Aether OS Contributors
---
<div align="center">
**If this project helps you, give it a Star ⭐**
</div>
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available