使用说明

代理乐团

专家多智能体编排系统 -生成并协调具有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提供：

问题	解决方案
上下文丢失	持久内存 -会话、学习和任务在对话中得以保留
没有学习	自我进化的知识 -自动蒸馏、验证和置信度跟踪
单一代理	多代理编排 -培养专业代理人才库
文件冲突	Git工作树隔离 -每个代理都在自己的分支上工作
脆弱的基础设施	弹性架构 -SQLite真相来源，ChromaDB作为可重建索引

主要优势

快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-<pid>

# 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工具	stdio	编排器→ 当地代理商	`./data/agent_inbox/`
双向通信	8080	实时任务交付	（内存中）
文件回退	-	可靠的任务队列	`./data/agent_outbox/`
矩阵中心	8081	跨项目消息传递	仅限WebSocket

何时使用什么：

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   │
└─────────────────────────────────────────┘

特性

特性	描述
SQLite首次保存	数据立即保存到SQLite，向量操作是异步/可选的
WAL模式	无数据库锁的多项目并发访问
使用回退重试	100ms内重试3次→ 200ms → 400ms延迟
尽最大努力写作	失败不会崩溃——只需将索引标记为过时
稳定性跟踪	知道何时需要重新索引
批量重建	在约30秒内重建500+个项目

恢复命令

# 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等）
自动查找概念上相关的代码
文件更改时自动更新（使用守护程序）

何时使用：

需要	工具
查找实现	`search_code`
定位图案	`search_code`
类似代码	`search_code`
精确字符串	`grep`
文件名	`glob`

代理角色

角色	模型	目的
`oracle`	作品	编排、综合、关键决策
`architect`	opus	系统设计、架构
`coder`	sonnet	实现、编码
`analyst`	十四行诗	需求分析，问题分解
`reviewer`	十四行诗	代码审查、质量保证
`tester`	十四行诗	测试创建、边缘案例、覆盖率
`debugger`	十四行诗	漏洞调查，修复
`researcher`	俳句	快速信息收集
`scribe`	十四行诗	文档、会议笔记
`generalist`	十四行诗	通用任务

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 效率参数。

编排工具

工具	操作	描述
`agent`	spawn、spawn_pool、kill、restart、health、health_all、status	代理生命周期
`mission`	分发、完成、失败、状态、重新平衡	任务队列
`worktree`	配置、合并、同步、清理、状态、列表	Git工作树

内存工具

工具	说明
`save_session`	保存具有完整上下文的会话
`recall_session`	搜索过去的会话
`add_learning`	用结构化字段捕捉学习
`recall_learnings`	按查询搜索学习内容
`consolidate_learnings`	合并重复学习
`search`	跨所有集合的语义搜索
`search_code`	跨索引代码库的语义代码搜索
`get_context_bundle`	获取新会话的相关上下文
`export_learnings`	导出到LEARNINGS.md
`stats`	系统统计

矩阵通信工具

工具	说明
`get_inbox`	检查具有集线器状态的交叉矩阵消息
`matrix_send`	向其他矩阵发送消息（广播或直接）

配置

环境变量

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

文档

文档	描述
Oracle智能	任务路由、分解、主动生成
存储器系统	会话持久性、学习、自动完成
学习循环	闭环学习，双采集模式
PTY编排	代理产卵和管理
工作树隔离	Git工作树集成
会话快照	会话捕获和恢复
语义搜索	代码搜索和索引

故障排除

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

贡献

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

许可证

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

致谢

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

使用说明

代理乐团

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

为什么选择代理乐团？

问题

解决方案

主要优势

特性

多代理编排

Oracle智能（新）

持久存储系统

自我进化的知识

弹性架构

快速开始

先决条件

安装

一个命令设置

手动设置

验证安装

用法

内存命令（单代理）

多代理编排

矩阵通信（跨实例）

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

建筑

通信层

数据流：学习循环

弹性ChromaDB系统

建筑

特性

恢复命令

程序化重建

语义代码搜索

代理角色

Git工作树隔离

MCP工具

编排工具

内存工具

矩阵通信工具

配置

环境变量

Claude代码集成

上下文保护挂钩（可选）

项目结构

文档

故障排除

ChromaDB问题

内存搜索不起作用

Spawn特工失败

贡献

许可证

致谢

相关 MCP

知识图谱记忆服务器

AI智能体记忆服务

多智能体工作流自动化工具

多智能体协作协议

AI代理记忆存储服务

多智能体AI系统监控平台