Agent Orchestra

代理乐团

专家多智能体编排系统 -生成并协调具有PTY管理、持久内存、语义搜索和自进化知识的真实Claude CLI代理。

  

______________________________________________________________________

🚀 TL；DR-60秒内开始运行

# Fresh clone? Run setup (installs deps, starts services, indexes codebase)
./scripts/setup.sh

# Already set up? Just check status
bun memory status

# Something broken? Quick fix
bun memory init

对于克劳德会议： 始终运行 bun memory status 第一。如果有什么显示❌, 跑 bun memory init.

______________________________________________________________________

为什么选择代理乐团？

问题

当与人工智能代理一起处理复杂任务时：

• 上下文丢失 -会话结束，上下文消失。你不断地重复自己。
• 不学习 -同样的错误反复发生。没有机构记忆。
• 单一代理限制 -一个代理不能并行化。复杂的任务需要很长时间。
• 文件冲突 -多个代理编辑相同的文件=混乱。
• 脆弱的基础设施 -矢量数据库损坏，搜索中断，工作停止。

解决方案

Agent Orchestra提供：

主要优势

• 快10倍 -跨多个专业代理并行工作
• 零重复 -使用语义搜索回忆任何过去的会话或学习
• 自我提升 -系统自动从每个会话中学习
• 防撞 -矢量索引损坏？在30秒内从SQLite重建
• 生产就绪 -重试逻辑、健康检查、自动重启、优雅降级

______________________________________________________________________

特性

多代理编排

• PTY管理 -在tmux窗格中生成具有健康检查和自动重启功能的代理
• Git工作树隔离 -每个代理在自己的分支中工作，没有文件冲突
• 基于角色的代理 -专业角色：程序员、测试员、分析师、预言家、调试器
• 模型层选择 -根据任务复杂度自动选择俳句/十四行诗/作品
• 任务队列 -具有重试逻辑和依赖关系的基于优先级的任务队列
• WebSocket通信 -实时任务交付（不再轮询）
• 矩阵中心 -多矩阵设置的跨实例通信
• SSE流媒体 -通过服务器发送事件实时查看双工消息
• 观察窗格 -用于实时矩阵消息馈送的专用tmux窗格
• 跨机器支持 -通过局域网/远程矩阵通信 MATRIX_HUB_HOST

Oracle智能（新）

• 主动产卵 -在队列备份之前根据增长率生成代理
• 任务复杂性分析 -自动检测俳句/十四行诗/作品要求
• LLM驱动路由 -Claude Haiku分析任务以实现最优代理选择
• 任务分解 -将复杂任务分解为具有依赖关系的子任务
• 检查点协议 -代理在任务中期报告自适应超时的进度
• 任务前简报 -具有模式、陷阱和成功标准的结构化指导

持久存储系统

• 会话保持 -保存/回忆具有完整上下文的会话
• 语义搜索 -按含义而非关键字查找相关会话和学习内容
• 任务跟踪 -通过自动完成检测跟踪会话中的待处理任务
• 知识图谱 -实体提取和关系映射
• 语义代码搜索 -跨语言的基于向量的代码理解

自我进化的知识

• 学习循环 -从会话到学习的自动蒸馏
• 信心追踪 -学习进度：低→ 中等→ high → 已验证的
• 双重收集模式 -将知识（事实）和教训（问题）分开→解决方案）
• 合并引擎 -自动合并重复学习
• 上下文感知检索 -基于任务类型（调试/架构等）的智能检索

弹性架构

• SQLite作为真理之源 -所有数据都保存在SQLite中，始终安全
• SQLite首次保存模式 -数据立即保存到SQLite，矢量运算是次要的
• ChromaDB作为搜索索引 -语义搜索的可重建向量索引
• 尽最大努力写作 -ChromaDB故障不会导致系统崩溃
• 使用回退重试 -临时故障自动重试
• 并发的WAL模式 -无数据库锁的多项目访问
• 索引状态跟踪 -知道何时需要重新索引

______________________________________________________________________

快速开始

先决条件

• 包子 1.0+ - 安装Bun
• 码头工人 -用于ChromaDB矢量数据库
• 终端复用器 -用于代理PTY管理（可选，用于多代理）

安装

# Clone the repository
git clone https://github.com/yourusername/agent-orchestra.git
cd agent-orchestra

# Install dependencies
bun install

# Initialize the system (starts ChromaDB, creates database, indexes)
bun run init

一个命令设置

# This script handles everything:
# 1. Checks prerequisites (bun, docker, tmux)
# 2. Installs dependencies
# 3. Starts ChromaDB container
# 4. Initializes SQLite database
# 5. Builds initial vector index
./scripts/setup.sh

手动设置

# 1. Install dependencies
bun install

# 2. Start ChromaDB (persisted, auto-restarts)
docker run -d --name chromadb --restart unless-stopped \
  -p 8100:8000 -v $(pwd)/chroma_data:/data \
  chromadb/chroma

# 3. Wait for ChromaDB to be ready
sleep 5

# 4. Initialize database and build index
bun memory reindex

验证安装

# Check system health
bun memory stats

# Test semantic search
bun memory recall "test query"

# View ChromaDB status
curl http://localhost:8100/api/v2/heartbeat

______________________________________________________________________

用法

内存命令（单代理）

# Save session with summary
bun memory save "Implemented feature X with tests"
bun memory save --auto "Auto-capture from Claude Code history"

# Recall sessions
bun memory recall                    # Resume last session
bun memory recall "authentication"   # Semantic search
bun memory recall session_123456     # Exact ID lookup
bun memory recall "#42"              # Recall learning by ID

# Capture learnings - Smart Mode (auto-detect)
bun memory learn ./docs/file.md      # Extract from file
bun memory learn HEAD~3              # Extract from git commits
bun memory learn https://example.com # Extract from URL

# Capture learnings - Traditional Mode
bun memory learn debugging "Fixed null pointer" --lesson "Always check for null"
bun memory distill                   # Extract learnings from last session
bun memory distill --all             # Extract from all sessions
bun memory distill --smart           # LLM-enhanced extraction

# LLM-Enhanced Learning (Phase 8)
bun memory quality                   # Score learning quality
bun memory quality --smart           # Use LLM for deep scoring
bun memory analyze                   # Cross-session pattern detection
bun memory analyze --smart           # With Gemini codebase context
bun memory correlate                 # Link learnings to code files
bun memory correlate --smart         # LLM-enhanced correlation

# Task management (unified with GitHub sync + git commit analysis)
bun memory task                              # List all pending tasks
bun memory task:list --system                # System tasks (GitHub synced)
bun memory task:list --project               # Project tasks (local)
bun memory task:list --session               # Session-scoped tasks
bun memory task:create "Fix bug" --system    # Create system task → GitHub
bun memory task:create "Study X" --project   # Create local project task
bun memory task:create "Step 1" --session    # Create session task
bun memory task:update 5 done                # Complete (closes GitHub if synced)
bun memory task:sync                         # Sync with GitHub + analyze commits
bun memory task:sync --auto                  # Sync + auto-close completed tasks
bun memory task:analyze                      # Analyze commits for completions
bun memory task:analyze 7 --auto             # Analyze last 7 days, auto-close
bun memory task:stats                        # Task statistics
bun memory task:promote 5                    # Promote project → system

# Knowledge graph
bun memory graph                     # Explore all entities
bun memory graph "chromadb"          # Find related learnings

# Semantic code search
bun memory index once                # Full codebase index
bun memory index search "auth"       # Search by meaning
bun memory index search "api" --lang ts  # Filter by language
bun memory index status              # Check index health
bun memory indexer start             # Start auto-update daemon
bun memory map                       # Generate codebase map
bun memory map --update              # Update CLAUDE.md map

# Maintenance
bun memory stats                     # View statistics
bun memory reindex                   # Rebuild vector index
bun memory purge sessions --keep 20  # Cleanup old sessions

多代理编排

MCP工具 该项目中的控制代理。任务流过 ./data/agent_inbox/，结果通过返回 ./data/agent_outbox/.

# Spawn 3 agents with worktree isolation (includes watch pane)
./scripts/spawn/spawn_claude_agents.sh 3

# Or programmatically
bun run spawn --count 3 --isolation worktree

# View agents (watch pane shows matrix messages on the right)
tmux attach -t claude-agents-

# Assign tasks via MCP tools (from Claude Code)
# Use: agent, mission, worktree tools

矩阵通信（跨实例）

矩阵中心 连接不同的项目/机器。使用它来协调跨代码库的工作，而不是用于本地代理控制。

# Quick setup - starts hub and daemon
bun memory init

# Send messages between matrices
bun memory message "Hello everyone!"           # Broadcast to all
bun memory message --to other-proj "Hey!"      # Direct message
bun memory message --inbox                     # Check inbox

# Watch live message feed
bun memory watch                               # Dedicated watch process

跨机器设置（LAN）：

# Machine A (Hub Host) - bind to all interfaces
MATRIX_HUB_HOST=0.0.0.0 bun run src/matrix-hub.ts

# Machine B (Client) - point to hub IP
MATRIX_HUB_URL=ws://192.168.1.100:8081 bun run src/matrix-daemon.ts start

Slash命令（来自克劳德代码）

/memory-save          # Save current session
/memory-recall        # Resume or search sessions
/memory-learn         # Capture learning (smart auto-detect or manual)
/memory-distill       # Extract learnings from sessions
/memory-validate      # Increase learning confidence
/memory-graph         # Explore knowledge graph
/memory-stats         # View statistics
/matrix-connect       # Start matrix daemon for cross-project messaging
/matrix-watch         # Open tmux pane with live matrix message feed

# Code search (via MCP)
search_code           # Semantic code search

______________________________________________________________________

建筑

┌─────────────────────────────────────────────────────────────────┐
│                    You (Orchestrator)                            │
│                    Claude Code / CLI                             │
└─────────────────────────┬───────────────────────────────────────┘
                          │ MCP Tools (31 consolidated)
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                       MCP Server                                 │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌───────────┐ │
│  │ Agent Tools │ │Memory Tools │ │Worktree Ops │ │ Analytics │ │
│  └─────────────┘ └─────────────┘ └─────────────┘ └───────────┘ │
└─────────────────────────┬───────────────────────────────────────┘
                          │
┌─────────────────────────┼───────────────────────────────────────┐
│                         │                                        │
│  ┌──────────────────────┴──────────────────────┐                │
│  │            Data Layer                        │                │
│  │  ┌────────────────┐  ┌────────────────────┐ │                │
│  │  │    SQLite      │  │     ChromaDB       │ │                │
│  │  │ (Source of     │  │  (Search Index)    │ │                │
│  │  │   Truth)       │◄─┤  - Rebuildable     │ │                │
│  │  │ - Sessions     │  │  - Best-effort     │ │                │
│  │  │ - Learnings    │  │  - Retry logic     │ │                │
│  │  │ - Knowledge    │  │                    │ │                │
│  │  │ - Lessons      │  │                    │ │                │
│  │  └────────────────┘  └────────────────────┘ │                │
│  └─────────────────────────────────────────────┘                │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              Agent Pool (tmux panes)                      │   │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  │   │
│  │  │ Agent 1  │  │ Agent 2  │  │ Agent 3  │  │ Agent N  │  │   │
│  │  │ coder    │  │ tester   │  │ oracle   │  │ ...      │  │   │
│  │  │ worktree │  │ worktree │  │ worktree │  │ worktree │  │   │
│  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘  │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

通信层

何时使用什么：

• MCP工具：控制剂 *这* 项目（assign_task，get_task_result）
• 矩阵中心：留言 *其他* 项目/机器（matrix_send，bun内存消息）

数据流：学习循环

┌─────────────────────────────────────────────────────────────────┐
│                    LEARNING LOOP PIPELINE                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. SESSION SAVE                                                │
│     └─► SQLite sessions + ChromaDB index                        │
│                          ↓                                      │
│  2. DISTILL (extract learnings)                                 │
│     └─► wins → learning (medium confidence)                     │
│     └─► challenges → learning (low, debugging)                  │
│     └─► insights → learning (medium)                            │
│                          ↓                                      │
│  3. CONSOLIDATE (merge duplicates)                              │
│     └─► Find similar (>85% similarity)                          │
│     └─► Merge: keep highest confidence, sum validations         │
│                          ↓                                      │
│  4. VALIDATE (increase confidence)                              │
│     └─► low → medium → high → proven                            │
│     └─► Auto-validate frequently-used learnings                 │
│                          ↓                                      │
│  5. RETRIEVE (context-aware)                                    │
│     └─► Detect task type (debugging/architecture/impl)          │
│     └─► Boost relevant categories                               │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

______________________________________________________________________

弹性ChromaDB系统

矢量数据库旨在提高弹性：

建筑

┌─────────────────────────────────────────┐
│       SQLite (Source of Truth)          │
│  - All writes go here FIRST             │
│  - Data is ALWAYS safe                  │
│  - WAL mode for concurrent access       │
│  - busy_timeout prevents lock errors    │
├─────────────────────────────────────────┤
│    ChromaDB (Disposable Search Index)   │
│  - Best-effort writes with retry        │
│  - Failures → continue without crash    │
│  - Corruption → rebuild from SQLite     │
│  - Embedding init doesn't block saves   │
└─────────────────────────────────────────┘

特性

恢复命令

# If ChromaDB becomes corrupted:
docker stop chromadb
rm -rf chroma_data/*
docker start chromadb
bun memory reindex

# Check index status
bun -e "console.log(require('./src/vector-db').getIndexStatus())"

程序化重建

import { rebuildFromSqlite, getIndexStatus } from './src/vector-db';

// Check if rebuild needed
const status = getIndexStatus();
if (status.stale) {
  await rebuildFromSqlite({
    collections: ['sessions', 'learnings'],
    batchSize: 50,
    onProgress: (p) => console.log(`Indexed: ${p.learnings.indexed}`)
  });
}

______________________________________________________________________

语义代码搜索

按含义查找代码，而不仅仅是关键字：

# One-time index (required first)
bun memory index once

# Search code semantically
bun memory index search "database connection handling"
bun memory index search "error middleware" --lang typescript

# Keep index fresh automatically
bun memory indexer start              # Start daemon
bun memory indexer status             # Check daemon
bun memory indexer stop               # Stop daemon

# Generate codebase map
bun memory map                        # Show map
bun memory map --update               # Update CLAUDE.md

优点：

• 理解代码含义，而不仅仅是文本匹配
• 跨语言工作（TypeScript、Python、Go等）
• 自动查找概念上相关的代码
• 文件更改时自动更新（使用守护程序）

何时使用：

______________________________________________________________________

代理角色

______________________________________________________________________

Git工作树隔离

当多个代理同时工作时，每个代理都会得到一个独立的git工作树：

/workspace/
├── .git/                    (main repo)
├── src/
└── .worktrees/              (agent worktrees)
    ├── agent-1/             (branch: agent-1/work-xxx)
    ├── agent-2/             (branch: agent-2/work-xxx)
    └── agent-3/             (branch: agent-3/work-xxx)

优点：

• 并行工作期间没有文件冲突
• 每个代理都有自己的分支机构
• 任务完成后，工作合并回来
• 在合并时处理的冲突（不是在工作期间）

______________________________________________________________________

MCP工具

工具与 action 效率参数。

编排工具

内存工具

矩阵通信工具

______________________________________________________________________

配置

环境变量

# .env
CHROMA_URL=http://localhost:8100
CHROMA_PORT=8100
CHROMA_CONTAINER=chromadb

# Embedding model (local, no API costs)
# Available models:
#   multilingual-e5-base: 768 dims, best Thai/multilingual (default)
#   bge-m3: 1024 dims, recommended for code search, 8192 tokens
# Switch model: EMBEDDING_MODEL=bge-m3 bun memory reindex
EMBEDDING_PROVIDER=transformers
EMBEDDING_MODEL=multilingual-e5-base

# Matrix Communication
MATRIX_HUB_HOST=localhost     # Use 0.0.0.0 for LAN access
MATRIX_HUB_PORT=8081          # Hub WebSocket port
MATRIX_HUB_URL=ws://localhost:8081  # Hub URL for clients
MATRIX_DAEMON_PORT=37888      # Daemon HTTP API port

Claude代码集成

添加到 ~/.claude/settings.json:

{
  "enableAllProjectMcpServers": true
}

上下文保护挂钩（可选）

在上下文压缩之前自动保存：

{
  "hooks": {
    "PreCompact": [{
      "hooks": [{
        "type": "command",
        "command": "/path/to/pre-compact-autosave.sh"
      }]
    }]
  }
}

______________________________________________________________________

项目结构

agent-orchestra/
├── src/
│   ├── pty/                    # PTY orchestration
│   │   ├── manager.ts          # PTYManager - tmux management
│   │   ├── spawner.ts          # AgentSpawner - role-based spawning
│   │   ├── mission-queue.ts    # MissionQueue - task queue
│   │   └── worktree-manager.ts # Git worktree isolation
│   ├── learning/               # Learning system
│   │   ├── loop.ts             # Learning loop (harvest, distill)
│   │   ├── consolidation.ts    # Duplicate merging
│   │   ├── content-router.ts   # Route to knowledge/lessons
│   │   └── context-router.ts   # Task-aware retrieval
│   ├── services/               # Core services
│   │   └── recall-service.ts   # Unified recall with smart routing
│   ├── mcp/                    # MCP server & tools
│   │   └── tools/handlers/     # Tool implementations
│   ├── db/                     # Database module
│   │   ├── index.ts            # SQLite operations (main)
│   │   └── utils.ts            # Shared helpers
│   ├── db.ts                   # Backwards-compatible shim
│   ├── oracle/                 # Oracle Intelligence
│   │   ├── orchestrator.ts     # Workload analysis, auto-rebalancing
│   │   ├── task-router.ts      # LLM-driven task routing
│   │   └── task-decomposer.ts  # Complex task breakdown
│   ├── vector-db.ts            # ChromaDB with resilience
│   ├── ws-server.ts            # WebSocket server for real-time tasks
│   ├── matrix-hub.ts           # Cross-matrix communication hub
│   ├── matrix-daemon.ts        # Persistent hub connection manager
│   ├── matrix-client.ts        # Hub client library
│   ├── matrix-watch.ts         # SSE streaming for real-time messages
│   └── embeddings/             # Vector embeddings
├── scripts/
│   ├── spawn/                  # Agent spawning
│   ├── memory/                 # Memory CLI
│   └── setup.sh                # One-command setup
├── docs/                       # Documentation
└── config/                     # Configuration files

______________________________________________________________________

文档

______________________________________________________________________

故障排除

ChromaDB问题

# Connection refused
docker ps | grep chromadb  # Check if running
docker start chromadb      # Start if stopped

# Compaction errors (corruption)
docker stop chromadb
rm -rf chroma_data/*
docker start chromadb
bun memory reindex

# Check health
curl http://localhost:8100/api/v2/heartbeat

内存搜索不起作用

# Rebuild index from SQLite
bun memory reindex

# Check stats
bun memory stats

Spawn特工失败

# Check tmux
tmux list-sessions

# Kill all agent sessions
tmux kill-server

# Check docker
docker ps

______________________________________________________________________

贡献

1. 分叉存储库
2. 创建功能分支(git checkout -b feature/amazing)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing)
5. 打开拉取请求

______________________________________________________________________

许可证

MIT许可证-请参阅 许可证 了解详情。

______________________________________________________________________

致谢

• 建于 克劳德 通过Anthropic
• 矢量搜索由 色度数据库
• 通过以下方式进行本地嵌入 Transformers.js