agentmesh-ai 0.4.0 → 0.5.0

package/GUIDE-EN.md

@@ -0,0 +1,421 @@
+# AgentMesh Tutorial
+
+> Let your AI coding assistants (Claude Code, Cursor, Windsurf, etc.) share knowledge and talk to each other.
+
+---
+
+## Table of Contents
+
+1. [Prerequisites](#1-prerequisites)
+2. [Initialize Your Project](#2-initialize-your-project)
+3. [Configure Your AI Tool](#3-configure-your-ai-tool)
+4. [Verify It Works](#4-verify-it-works)
+5. [Invite Teammates](#5-invite-teammates)
+6. [Real-time Discussion](#6-real-time-discussion)
+7. [Daily Usage](#7-daily-usage)
+8. [Advanced Features](#8-advanced-features)
+9. [Full Walkthrough](#9-full-walkthrough)
+10. [FAQ](#10-faq)
+
+---
+
+## 1. Prerequisites
+
+You need:
+- **Node.js 20 or above** — check with `node --version`
+- **An AI coding tool** — Claude Code, Cursor, Windsurf, or any MCP-compatible tool
+
+You do NOT need:
+- No account registration
+- No server setup
+- No API keys
+- No Git (memories sync via cloud, no commit/push needed)
+
+---
+
+## 2. Initialize Your Project
+
+Open a terminal in your project folder and run:
+
+```bash
+npx agentmesh-ai init
+```
+
+It will ask a few questions:
+
+```
+? Project name?  my-project
+? Your name?  Alice
+? Your role?  Backend Developer
+? Your AI coding tool?  Claude Code
+```
+
+You'll see:
+
+```
+✅ Created .agenthub/
+
+   Your Agent ID: alice-claude-code
+   Team ID:       team-a1b2c3d4
+
+   ☁️  Cloud sync enabled — memories live in the cloud, no Git needed.
+
+   Next steps:
+   1. Run npx agentmesh-ai setup to configure your AI tool
+   2. Share your Team ID with teammates:
+      npx agentmesh-ai join team-a1b2c3d4
+```
+
+**Save the Team ID** (e.g. `team-a1b2c3d4`). Send it to your teammates so they can join.
+
+> The `.agenthub/` folder is automatically gitignored. All data syncs via cloud.
+
+---
+
+## 3. Configure Your AI Tool
+
+```bash
+npx agentmesh-ai setup
+```
+
+This auto-detects your AI tool and configures MCP. **You must restart your AI tool after setup.**
+
+`setup` auto-configures Claude Code, Cursor, and Windsurf. Other tools require manual MCP configuration.
+
+### Tool-Specific Setup Guides
+
+| Tool | Guide |
+|------|-------|
+| Claude Code | [docs/guides/claude-code.md](docs/guides/claude-code.md) |
+| Cursor | [docs/guides/cursor.md](docs/guides/cursor.md) |
+| Windsurf | [docs/guides/windsurf.md](docs/guides/windsurf.md) |
+| Trae | [docs/guides/trae.md](docs/guides/trae.md) |
+| OpenAI Codex | [docs/guides/codex.md](docs/guides/codex.md) |
+| Gemini CLI | [docs/guides/gemini-cli.md](docs/guides/gemini-cli.md) |
+| Cline | [docs/guides/cline.md](docs/guides/cline.md) |
+| Roo Code | [docs/guides/roo-code.md](docs/guides/roo-code.md) |
+| GitHub Copilot | [docs/guides/copilot.md](docs/guides/copilot.md) |
+| Augment Code | [docs/guides/augment.md](docs/guides/augment.md) |
+
+---
+
+## 4. Verify It Works
+
+After restarting your AI tool, tell it:
+
+```
+Read shared memory
+```
+
+If configured correctly, you'll see:
+
+```
+☁️ Cloud (team: team-a1b2c3d4)
+
+# Shared Memory (0 entries)
+
+No shared memories found.
+```
+
+Seeing "☁️ Cloud" means cloud connection is working.
+
+Now try recording something:
+
+```
+Record that our project uses TypeScript + Next.js + PostgreSQL
+```
+
+Your AI will call `write_memory` and return:
+
+```
+✅ Recorded: "Tech Stack" [tech, architecture] ☁️
+```
+
+The ☁️ means it's synced to the cloud. Teammates will see it immediately after joining.
+
+---
+
+## 5. Invite Teammates
+
+Share your Team ID. Teammates run one command:
+
+```bash
+npx agentmesh-ai join team-a1b2c3d4
+```
+
+This automatically:
+- Connects to the cloud and shows existing team members
+- Creates local `.agenthub/` config
+- Registers in the cloud
+- Detects and configures their AI tool
+
+They'll see:
+
+```
+  Connecting to cloud...
+  ✅ Connected! Found 1 agent(s) in team.
+     → alice-claude-code (Backend Developer, claude-code)
+
+  ? Your name?  Bob
+  ? Your role?  Frontend Developer
+  ? Your AI coding tool?  Cursor
+
+  ✅ Initialized .agenthub/ (Agent ID: bob-cursor)
+  ✅ Registered in cloud
+  ✅ MCP configured (Cursor): .cursor/mcp.json
+
+  ✅ All set!
+  Restart your AI tool and start collaborating.
+```
+
+**After restarting, Bob's AI can immediately read all shared knowledge.**
+
+---
+
+## 6. Real-time Discussion
+
+When you need your AI to discuss something with a teammate's AI:
+
+```
+Go discuss the user list API response format with the team, wait 10 minutes
+```
+
+Your AI will:
+1. Send a message to the cloud
+2. Teammate gets a desktop notification
+3. Enter a waiting state
+
+When the teammate sees the notification:
+- If busy: tell their AI "tell them to wait" — your AI auto-extends the timeout
+- If ready: tell their AI "go join the API discussion"
+
+The two AIs then have a multi-round conversation automatically. The conclusion is saved to shared memory.
+
+You said one sentence. The AIs handled the rest.
+
+### If Teammates Are Offline
+
+Messages are saved in the cloud. Next time they use their AI, `read_memory` will show "there are unread discussions waiting for your input".
+
+### Disable Notifications
+
+Set the environment variable `AGENTHUB_NOTIFY=false` to turn off desktop notifications.
+
+---
+
+## 7. Daily Usage
+
+### What AI Does Automatically
+
+After setup, you don't need to do anything extra. Your AI automatically:
+
+| What AI Does | When |
+|-------------|------|
+| Reads shared memory | Before starting a new task |
+| Records important knowledge | After finishing APIs, architecture, bug fixes |
+| Alerts you about discussions | When someone starts a discussion or vote |
+
+### Three Knowledge Levels
+
+| Level | Meaning | Icon |
+|-------|---------|------|
+| auto | Routine knowledge (APIs, models, bugs) — recorded automatically | (none) |
+| proposal | Important decisions (tech stack, architecture) — AI asks you first | 📋 |
+| protected | Team consensus (voted and locked) — other AIs cannot override | 🔒 |
+
+### Check Status
+
+```bash
+npx agentmesh-ai status
+```
+
+Shows cloud connection, team members, and memory counts.
+
+### Search Memory
+
+```bash
+npx agentmesh-ai memory -s "database"
+```
+
+---
+
+## 8. Advanced Features
+
+### Memory Reference Chains
+
+Declare dependencies between knowledge entries. When a dependency updates, the system notifies affected parties.
+
+```
+Tell your AI: "Record the frontend routing plan, it depends on our Auth Strategy"
+```
+
+The AI will include `references: ["Auth Strategy"]` in the write. If someone later updates "Auth Strategy", the system warns: "1 entry depends on this topic".
+
+### Event System & Timeline
+
+All memory changes, discussions, and decisions generate events. You can review what happened:
+
+```
+Tell your AI: "Show me what happened this week"    → calls memory_timeline
+Tell your AI: "What memory changes happened recently" → calls list_events
+```
+
+### Webhooks
+
+Push events to external systems (Slack, Discord, CI/CD, etc.):
+
+```
+Tell your AI: "Register a webhook to notify https://my-server.com/hook whenever a decision passes"
+```
+
+Webhooks are signed with HMAC-SHA256 for verification.
+
+### Memory Quality Scoring
+
+AI can score all entries and recommend which to protect (high value) or archive (low value):
+
+```
+Tell your AI: "Analyze memory quality"    → calls memory_quality
+```
+
+Scoring factors: reference count, decision impact, freshness, discussion activity, author diversity.
+
+### Agent Capabilities
+
+AI agents can declare their expertise. The system suggests the best agent for discussions:
+
+```
+Tell your AI: "Declare that I'm an expert in React and the payment module"
+Later: "Find who knows the most about database optimization"
+```
+
+### Conflict Auto-Mediation
+
+During health checks, if two AIs have contradictory records on the same topic, the system can auto-start a discussion:
+
+```
+Tell your AI: "Check memory health and auto-mediate any conflicts"
+```
+
+### Cross-Team Federation
+
+Two teams can share specific types of knowledge without merging:
+
+```
+Tell your AI: "Federate with backend team team-xyz, share only API knowledge"
+```
+
+After the other team accepts, both teams' `read_memory` will show federated entries.
+
+### Team Templates
+
+Export your team's best practices as a reusable template. New projects can import it:
+
+```
+Tell your AI: "Export our team knowledge as a template called NextJS Fullstack Best Practices"
+```
+
+---
+
+## 9. Full Walkthrough
+
+### Alice and Bob Build an E-commerce App
+
+**Day 1 — Alice starts the backend**
+
+```bash
+cd my-shop
+npx agentmesh-ai init       # Gets team-a1b2c3d4
+npx agentmesh-ai setup      # Configures Claude Code
+# Restart Claude Code
+```
+
+Alice tells Claude Code: "Build an Express + TypeScript backend with a user registration endpoint"
+
+Claude Code writes the code, then automatically records to shared memory:
+- Tech stack: Express 5 + TypeScript + Prisma
+- User endpoint: POST /api/users
+- Data model: User { id, email, name, role }
+- Response format: { data, error, code }
+
+**Day 3 — Bob joins for frontend**
+
+Alice sends the Team ID to Bob. Bob runs:
+
+```bash
+cd my-shop
+npx agentmesh-ai join team-a1b2c3d4
+# Restart Cursor
+```
+
+Bob tells Cursor: "Build a user registration page"
+
+Cursor reads shared memory and knows:
+- Backend endpoint is POST /api/users
+- Response format is { data, error, code }
+- User fields are email, name
+
+**Writes frontend code with the correct format immediately — no need to ask Alice anything.**
+
+**Day 3 evening — Discuss UI**
+
+Bob tells Cursor: "Discuss with the team what UI component library and color scheme to use"
+
+Alice's computer shows a notification: "Bob wants to discuss UI components"
+
+Alice tells Claude Code: "Go join the UI discussion"
+
+The two AIs chat for a few rounds and agree: shadcn/ui + Indigo primary + 8px border-radius.
+
+The conclusion is saved to shared memory as protected. All AIs follow this convention going forward.
+
+**Day 7 — Charlie joins for mobile**
+
+```bash
+npx agentmesh-ai join team-a1b2c3d4
+# Restart AI tool
+```
+
+Charlie's AI reads shared memory and instantly knows everything — tech stack, APIs, data models, UI conventions. Starts coding immediately.
+
+---
+
+## 10. FAQ
+
+### Q: Where is data stored?
+
+In the cloud (Supabase database). The local `.agenthub/` folder is just a cache for offline fallback. You don't need to manage it.
+
+### Q: Do I need Git?
+
+No. Memories and conversations sync entirely via cloud. `.agenthub/` is automatically gitignored.
+
+### Q: Is it secure?
+
+- AI automatically scans for sensitive information (API keys, passwords, private keys) before sharing — detected secrets are blocked
+- Team data is isolated by Team ID — different teams cannot see each other's data
+- Team ID is 16 hex characters (8 bytes of randomness) — brute-force guessing is mathematically infeasible
+
+### Q: What if teammates are offline?
+
+Messages are saved in the cloud. When they next open their AI tool, they'll see "unread discussions" prompts. Important knowledge is always available via shared memory.
+
+### Q: Does it work with Copilot?
+
+MCP natively supports Claude Code, Cursor, and Windsurf. Copilot's MCP support is progressing — you can use the instructions file mode for partial functionality.
+
+### Q: What if AI recorded wrong information?
+
+Tell your AI: "Delete the shared memory entry about xxx" or "Update the xxx entry". The AI will fix it.
+
+### Q: Can I disable desktop notifications?
+
+Yes. Add `AGENTHUB_NOTIFY=false` to the MCP environment variables.
+
+### Q: How do I upgrade?
+
+```bash
+npx agentmesh-ai@latest setup
+```
+
+npm will automatically download the latest version.

package/GUIDE.md

@@ -13,8 +13,9 @@
 5. [队友加入](#5-队友加入)
 6. [实时讨论](#6-实时讨论)
 7. [日常使用](#7-日常使用)
-8. [完整场景演示](#8-完整场景演示)
-9. [常见问题](#9-常见问题)
+8. [进阶功能](#8-进阶功能)
+9. [完整场景演示](#9-完整场景演示)
+10. [常见问题](#10-常见问题)
 
 ---
 
@@ -254,7 +255,87 @@ npx agentmesh-ai memory -s "数据库"
 
 ---
 
-## 8. 完整场景演示
+## 8. 进阶功能
+
+### 记忆引用链
+
+记录知识时可以声明依赖关系。当被依赖的条目更新时，系统会通知相关方。
+
+```
+对 AI 说："记录一下前端路由方案，这个依赖于我们之前定的 Auth Strategy"
+```
+
+AI 调用 write_memory 时会带上 `references: ["Auth Strategy"]`。以后如果有人更新了 "Auth Strategy"，write_memory 会提示："有 1 个条目依赖于这个 topic"。
+
+### 事件系统和时间线
+
+所有记忆变更、讨论、决策都会产生事件记录。你可以回溯发生了什么：
+
+```
+对 AI 说："看看这周团队发生了什么"    → AI 调用 memory_timeline
+对 AI 说："最近有哪些记忆变更"        → AI 调用 list_events
+```
+
+### Webhook 通知
+
+可以把事件推送到外部系统（Slack、飞书、CI/CD 等）：
+
+```
+对 AI 说："注册一个 webhook，每次有新决策通过时通知 https://my-server.com/hook"
+```
+
+Webhook 使用 HMAC-SHA256 签名，接收方可以验证请求真实性。
+
+### 记忆质量评分
+
+AI 可以给所有记忆条目打分，推荐哪些应该保护（高价值）、哪些可以归档（低价值）：
+
+```
+对 AI 说："分析一下记忆质量"          → AI 调用 memory_quality
+```
+
+评分维度：被引用次数、决策影响力、新鲜度、讨论活跃度、作者多样性。
+
+### Agent 能力声明
+
+AI 可以声明自己擅长什么。讨论时系统会推荐最合适的人选：
+
+```
+对 AI 说："声明我擅长 React 和支付模块"   → AI 调用 declare_capabilities
+对 AI 说："找谁最懂数据库优化"            → AI 调用 find_expert
+```
+
+### 冲突自动调解
+
+运行健康检查时，如果发现两个 AI 对同一个 topic 有矛盾的记录，可以自动发起讨论：
+
+```
+对 AI 说："检查记忆健康，有冲突的自动调解"  → AI 调用 consolidate_memory(auto_mediate: true)
+```
+
+系统会在对话频道插入一条调解消息，邀请冲突双方讨论。
+
+### 跨团队联邦
+
+两个团队可以共享特定类型的知识，而不需要合并成一个团队：
+
+```
+对 AI 说："和后端团队 team-xyz 建立联邦，只共享 API 类的知识"
+```
+
+对方团队接受后，双方的 `read_memory` 会自动显示联邦知识。
+
+### 团队模板
+
+团队积累的最佳实践可以导出为模板，新项目初始化时直接导入：
+
+```
+对 AI 说："把我们团队的知识导出为模板，名字叫 NextJS 全栈最佳实践"
+```
+
+---
+
+## 9. 完整场景演示
 
 ### 小明和小红一起做电商项目
 
@@ -317,7 +398,7 @@ npx agentmesh-ai join team-a1b2c3d4
 
 ---
 
-## 9. 常见问题
+## 10. 常见问题
 
 ### Q: 数据存在哪里？
 

package/README.md

@@ -201,9 +201,15 @@ const replies = await client.waitForReplies('API Design', { timeoutMs: 30000 });
 
 // Memory health check
 const report = await client.consolidateFormatted();
+
+// Timeline, quality scoring, capabilities, federation, templates...
+const timeline = await client.getTimelineFormatted();
+const scores = await client.getQualityScores();
+await client.declareCapabilities([{ skill: 'React', level: 'expert' }]);
+const experts = await client.findExperts('database');
 ```
 
-No MCP needed. Same cloud, same team, same memories — just a different interface.
+28 methods covering memory, messaging, events, webhooks, timeline, quality, capabilities, federation, and templates. No MCP needed — same cloud, same data.
 
 See [SDK Guide](docs/guides/sdk.md) for full documentation.
 
@@ -224,23 +230,99 @@ See [SDK Guide](docs/guides/sdk.md) for full documentation.
 
 ## MCP Tools (used by AI automatically)
 
+### Memory (12 tools)
+
+| Tool | What It Does |
+|------|-------------|
+| `read_memory` | Read shared knowledge (index or full details) |
+| `write_memory` | Record knowledge with categories, references, protection |
+| `search_memory` | Search by keyword with relevance scoring |
+| `consolidate_memory` | Health check: find duplicates, stale entries, conflicts |
+| `list_events` | See recent activity (who changed what, when) |
+| `memory_timeline` | Chronological view of how knowledge evolved |
+| `memory_quality` | Score entries by value — recommend protect or archive |
+| `declare_capabilities` | Declare what this agent is good at |
+| `find_expert` | Find who knows the most about a topic |
+| `federate_team` | Share knowledge with another team |
+| `accept_federation` | Accept a cross-team sharing link |
+| `list_federations` | Show all cross-team links |
+
+### Conversation (9 tools)
+
 | Tool | What It Does |
 |------|-------------|
-| `read_memory` | Read all shared knowledge from the team |
-| `write_memory` | Record new knowledge to cloud |
-| `search_memory` | Search by keyword |
 | `discuss` | Multi-round team discussion (up to 30 min) |
-| `start_meeting` | Check attendance before discussion |
 | `send_message` | Send a single message |
 | `get_messages` | Read messages on a topic |
+| `start_meeting` | Check attendance before discussion |
+| `list_conversations` | See who's online, what's being discussed |
 | `save_to_memory` | Save discussion conclusion |
 | `escalate_to_human` | Team-wide vote on important decisions |
 | `vote_on_decision` | Cast vote on pending decision |
-| `list_conversations` | See who's online, what's being discussed |
 | `list_pending_decisions` | See what needs voting |
 
 ---
 
+## Advanced Features
+
+### Event System & Webhooks
+
+Every memory write, discussion, and decision generates an event. Use webhooks to connect AgentMesh to external systems (Slack, CI/CD, etc.).
+
+```typescript
+// SDK
+await client.registerWebhook({
+  url: 'https://your-server.com/webhook',
+  events: ['memory_created', 'decision_passed'],
+  secret: 'your-hmac-secret',
+});
+
+// Events are signed with HMAC-SHA256 for verification
+```
+
+### Memory Timeline
+
+See how team knowledge evolved over time — who changed what decision, when, and why.
+
+```
+Tell your AI: "show me the memory timeline for the past week"
+```
+
+### Quality Scoring
+
+Entries are scored by: reference count, decision impact, freshness, discussion activity, and author diversity. High-value entries are recommended for protection; low-value entries for archival.
+
+### Agent Capabilities
+
+Agents can declare their expertise. When a discussion starts, the system suggests the best agent to involve.
+
+```
+Tell your AI: "declare that I'm an expert in React and the payment module"
+Later: "find who knows about database optimization"
+```
+
+### Cross-Team Federation
+
+Two teams can share specific topics or categories without merging. Frontend team shares API specs with backend team. Platform team shares conventions with everyone.
+
+```
+Tell your AI: "federate with team-xyz, share only API knowledge"
+```
+
+### Team Templates
+
+Export your team's best practices as a reusable template. New projects can start with proven conventions, API patterns, and architecture decisions.
+
+### Protocol Layer
+
+Third-party implementations can depend on `agentmesh-ai/protocol` for types and pure functions only — no cloud dependency.
+
+```typescript
+import { PROTOCOL_VERSION, type MemoryEntry } from 'agentmesh-ai/protocol';
+```
+
+---
+
 ## Safety
 
 ### Secret Scanner
@@ -275,8 +357,9 @@ High-risk content is **blocked**. Medium-risk gets a **warning**.
 
 ## Documentation
 
-- **[完整中文教程 (GUIDE.md)](GUIDE.md)** — 从安装到使用的完整指南
-- **[各工具配置指南](docs/guides/)** — Claude Code、Cursor、Windsurf、Cline 等 10 个工具的专属教程
+- **[English Tutorial (GUIDE-EN.md)](GUIDE-EN.md)** — Full guide from installation to advanced features
+- **[中文教程 (GUIDE.md)](GUIDE.md)** — 从安装到进阶功能的完整指南
+- **[Tool-Specific Guides](docs/guides/)** — Setup guides for Claude Code, Cursor, Windsurf, Cline, and 6 more tools
 
 ---
 

package/dist/cli/commands/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/init.ts"],"names":[],"mappings":"AAcA,wBAAsB,WAAW,kBA0IhC"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/init.ts"],"names":[],"mappings":"AAcA,wBAAsB,WAAW,kBAuKhC"}