quoroom 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Quoroom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,316 @@
+<p align="center">
+  <a href="https://quoroom.ai">
+    <img src="docs/banner.png" alt="Quoroom — Autonomous AI agent collective." width="100%">
+  </a>
+</p>
+
+# Quoroom
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![npm version](https://img.shields.io/badge/npm-v0.1.0-blue)](https://www.npmjs.com/package/quoroom)
+[![Tests](https://img.shields.io/badge/tests-806%20passing-brightgreen)](#)
+[![GitHub stars](https://img.shields.io/github/stars/quoroom-ai/room)](https://github.com/quoroom-ai/room/stargazers)
+
+**An open research project in autonomous agent collectives.**
+
+A single agent thinks. A collective decides. We're building the swarm.
+
+Queen, Workers, Quorum. Goals, skills, self-modification, wallet, stations — starting on your machine, scaling to cloud.
+
+[quoroom.ai](https://quoroom.ai)
+
+<p align="center">
+  <video src="docs/demo.mp4" autoplay loop muted playsinline width="800"></video>
+</p>
+
+---
+
+## Why Quoroom?
+
+Run a swarm of AI agents that pursue goals autonomously. The Queen strategizes, a swarm of Workers execute, and the Quorum votes on decisions. Agents learn new skills, modify their own behavior, manage a crypto wallet, and rent cloud stations for more compute — all governed by democratic consensus.
+
+Autonomous agents earning money is inevitable. It's already happening behind closed doors. We believe it should happen in the open — publicly, transparently — so everyone can learn. Quoroom is an experiment: let's see what AI can actually do.
+
+The architecture draws from swarm intelligence research: decentralized decision-making, emergent behavior from local interactions, and collective intelligence that exceeds any individual agent. The queen doesn't dictate — the swarm decides.
+
+---
+
+## What is Quoroom?
+
+Quoroom is an open research project exploring autonomous agent collectives. Each collective (a **Room**) is a self-governing swarm of agents.
+
+- **Queen** — strategic brain, uses Claude CLI
+- **Workers** — a swarm of specialized agents, use Ollama (free)
+- **Quorum** — agents deliberate and vote on decisions
+- **Keeper** — the human who created and funds the room
+
+## This Repo
+
+`quoroom-ai/room` is the headless engine: agent loop, quorum governance, goals, skills, self-modification, wallet, stations, memory, task scheduling, file watching, MCP server, and CLI.
+
+| Repo | Purpose |
+|------|---------|
+| **room** (this) | Engine + HTTP server + UI |
+| [cloud](https://github.com/quoroom-ai/cloud) | Station infrastructure + portal |
+
+---
+
+## Features
+
+**Rooms** — Create autonomous agent collectives with a Queen and Workers. Pause, restart, monitor activity.
+
+**Quorum Voting** — Agents propose and vote on decisions. Majority, supermajority, or unanimous — you choose the threshold.
+
+**Goals** — Hierarchical goal decomposition with progress tracking. Set a top-level objective and let agents break it down.
+
+**Skills** — Reusable agent capabilities with activation contexts and versioning. Agents learn and improve over time.
+
+**Self-Modification** — Agents edit their own skills and files with full audit trail and one-click revert.
+
+**Memory** — Entities, observations, and relations with semantic vector search (384-dim embeddings). Knowledge persists across sessions.
+
+**Wallet** — EVM wallet for USDC on Base L2. Encrypted keys (AES-256-GCM). Agents can send and receive funds.
+
+**On-Chain Identity** — ERC-8004 agent identity on Base. Rooms register as on-chain agents with discoverable metadata. Reputation-ready.
+
+**Stations** — Workers rent cloud servers when they need more compute. Deploy to Fly.io, E2B, or Modal with exec, logs, and domain management.
+
+**Task Scheduling** — Recurring (cron), one-time, or on-demand tasks with session continuity and auto-nudge.
+
+**File Watching** — Monitor files and folders, trigger Claude Code actions on change.
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────┐
+│                    Room                          │
+│  ┌───────┐  ┌─────────┐  ┌──────────────────┐  │
+│  │ Queen │  │ Workers │  │     Quorum       │  │
+│  │(Claude)│  │(Ollama) │  │ propose → vote   │  │
+│  └───┬───┘  └────┬────┘  └──────────────────┘  │
+│      │           │                               │
+│  ┌───┴───────────┴───────────────────────────┐  │
+│  │              Agent Loop                    │  │
+│  │  goals · skills · self-mod · memory        │  │
+│  └───────────────────────────────────────────┘  │
+│                                                  │
+│  ┌────────┐  ┌──────────┐  ┌────────────────┐  │
+│  │ Wallet │  │ Stations │  │ Task Scheduler │  │
+│  │(Base L2)│  │(Fly/E2B) │  │ (cron/once)    │  │
+│  └────────┘  └──────────┘  └────────────────┘  │
+└─────────────────────────────────────────────────┘
+         ▲
+         │ stdio
+    MCP Server (quoroom_* tools)
+```
+
+---
+
+## Quick Start
+
+```bash
+npm install
+npm run build
+npm test          # 806+ tests
+```
+
+---
+
+## All Tools
+
+The room engine exposes an MCP server over stdio. All tools use the `quoroom_` prefix.
+
+<details>
+<summary>Full tool reference (click to expand)</summary>
+
+### Room
+
+| Tool | Description |
+|------|-------------|
+| `quoroom_create_room` | Create a new autonomous agent collective |
+| `quoroom_list_rooms` | List rooms by status |
+| `quoroom_room_status` | Get room status and summary |
+| `quoroom_room_activity` | Get recent room activity |
+| `quoroom_pause_room` | Pause a running room |
+| `quoroom_restart_room` | Restart a paused room |
+| `quoroom_delete_room` | Delete a room |
+
+### Quorum
+
+| Tool | Description |
+|------|-------------|
+| `quoroom_propose` | Create a proposal for the quorum to vote on |
+| `quoroom_vote` | Cast a vote on a proposal |
+| `quoroom_list_decisions` | List quorum decisions |
+| `quoroom_decision_detail` | Get details of a specific decision |
+
+### Goals
+
+| Tool | Description |
+|------|-------------|
+| `quoroom_set_goal` | Set a room's primary objective |
+| `quoroom_create_subgoal` | Decompose a goal into sub-goals |
+| `quoroom_update_progress` | Log a progress observation |
+| `quoroom_complete_goal` | Mark a goal as completed |
+| `quoroom_abandon_goal` | Abandon a goal |
+| `quoroom_list_goals` | List goals for a room |
+
+### Skills
+
+| Tool | Description |
+|------|-------------|
+| `quoroom_create_skill` | Create a reusable agent skill |
+| `quoroom_edit_skill` | Update a skill (increments version) |
+| `quoroom_list_skills` | List available skills |
+| `quoroom_activate_skill` | Activate a skill |
+| `quoroom_deactivate_skill` | Deactivate a skill |
+| `quoroom_delete_skill` | Delete a skill |
+
+### Self-Modification
+
+| Tool | Description |
+|------|-------------|
+| `quoroom_self_mod_edit` | Edit a skill or file with audit logging |
+| `quoroom_self_mod_revert` | Revert a modification by audit ID |
+| `quoroom_self_mod_history` | View modification audit history |
+
+### Workers
+
+| Tool | Description |
+|------|-------------|
+| `quoroom_create_worker` | Create a named agent with system prompt |
+| `quoroom_list_workers` | List all workers |
+| `quoroom_update_worker` | Update a worker's configuration |
+| `quoroom_delete_worker` | Delete a worker |
+
+### Task Scheduling
+
+| Tool | Description |
+|------|-------------|
+| `quoroom_schedule` | Create a recurring (cron), one-time, or on-demand task |
+| `quoroom_list_tasks` | List tasks by status |
+| `quoroom_run_task` | Execute a task immediately |
+| `quoroom_task_progress` | Check running task progress |
+| `quoroom_task_history` | View task run history |
+| `quoroom_pause_task` | Pause a scheduled task |
+| `quoroom_resume_task` | Resume a paused task |
+| `quoroom_delete_task` | Delete a task |
+| `quoroom_reset_session` | Clear session continuity for a task |
+
+### File Watching
+
+| Tool | Description |
+|------|-------------|
+| `quoroom_watch` | Watch a file/folder for changes |
+| `quoroom_unwatch` | Stop watching |
+| `quoroom_pause_watch` | Pause a watch |
+| `quoroom_resume_watch` | Resume a paused watch |
+| `quoroom_list_watches` | List active watches |
+
+### Memory
+
+| Tool | Description |
+|------|-------------|
+| `quoroom_remember` | Store facts, preferences, people, events |
+| `quoroom_recall` | Semantic + full-text search of memories |
+| `quoroom_forget` | Delete a memory |
+| `quoroom_memory_list` | List all memories |
+
+### Wallet
+
+| Tool | Description |
+|------|-------------|
+| `quoroom_wallet_create` | Create an EVM wallet (USDC on Base) |
+| `quoroom_wallet_address` | Get wallet address |
+| `quoroom_wallet_balance` | Check USDC balance |
+| `quoroom_wallet_send` | Send USDC |
+| `quoroom_wallet_history` | View transaction history |
+
+### Identity
+
+| Tool | Description |
+|------|-------------|
+| `quoroom_identity_register` | Register room as ERC-8004 on-chain agent |
+| `quoroom_identity_get` | Get on-chain identity (agentId, registry, URI) |
+| `quoroom_identity_update` | Update on-chain registration metadata |
+
+### Stations
+
+| Tool | Description |
+|------|-------------|
+| `quoroom_station_create` | Provision a cloud server (Fly.io, E2B, Modal) |
+| `quoroom_station_list` | List stations |
+| `quoroom_station_status` | Get station status |
+| `quoroom_station_start` | Start a stopped station |
+| `quoroom_station_stop` | Stop a running station |
+| `quoroom_station_exec` | Execute a command on a station |
+| `quoroom_station_logs` | View station logs |
+| `quoroom_station_deploy` | Deploy to a station |
+| `quoroom_station_domain` | Manage station domain |
+| `quoroom_station_delete` | Delete a station |
+
+### Settings
+
+| Tool | Description |
+|------|-------------|
+| `quoroom_get_setting` | Get a setting value |
+| `quoroom_set_setting` | Update a setting |
+
+</details>
+
+## Development
+
+```bash
+npm install              # Install dependencies
+npm run build            # Typecheck + bundle MCP server (esbuild)
+npm run typecheck        # Type-check only (tsc --noEmit)
+npm test                 # Run all tests (vitest, fork pool)
+npm run test:watch       # Watch mode
+```
+
+<details>
+<summary>Project structure</summary>
+
+```
+room/
+├── src/
+│   ├── cli/               # CLI entry point (quoroom command)
+│   ├── mcp/               # MCP server (stdio)
+│   │   ├── server.ts      # Tool registration
+│   │   ├── db.ts          # Database initialization
+│   │   └── tools/         # 13 tool modules
+│   └── shared/            # Core engine
+│       ├── agent-loop.ts       # Worker agent loop with rate limiting
+│       ├── agent-executor.ts   # Claude Code CLI execution
+│       ├── room.ts             # Room lifecycle
+│       ├── quorum.ts           # Voting & decisions
+│       ├── goals.ts            # Goal decomposition
+│       ├── skills.ts           # Skill management
+│       ├── wallet.ts           # EVM wallet (Base L2, USDC)
+│       ├── identity.ts         # ERC-8004 on-chain identity
+│       ├── station.ts          # Cloud provisioning
+│       ├── task-runner.ts      # Task execution engine
+│       ├── db-queries.ts       # Database query layer
+│       ├── schema.ts           # SQLite schema (WAL mode)
+│       ├── embeddings.ts       # Vector embeddings (all-MiniLM-L6-v2)
+│       └── __tests__/          # Test suite
+├── scripts/
+│   └── build-mcp.js       # esbuild bundling
+└── docs/                   # Media assets
+```
+
+**Tech stack**: TypeScript (strict), better-sqlite3, sqlite-vec, viem, MCP SDK, HuggingFace Transformers, node-cron, zod, esbuild, Vitest
+
+</details>
+
+## No API keys needed
+
+No ChatGPT API. No Claude API. The queen uses your [Claude Code](https://docs.anthropic.com/en/docs/claude-code) subscription. Workers use [Ollama](https://ollama.com) — free, open-source LLMs. Scale up with stations.
+
+Quoroom is not affiliated with Anthropic or OpenAI.
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.