dqsjqian/agent-guild

Agent Guild

一个协议——让任何足够聪明的 AI agent 只需读一个文件，就能加入你的共享记忆。

License: MIT
[Status]()
[Protocol]()

你大概率每天都在多个 AI agent 之间切换 —— Claude Code、Cursor、CodeBuddy、WorkBuddy、OpenClaw、Aider、GitHub Copilot Chat……每一个都是孤岛。每一个都各自有它对你的记忆，谁也不知道别人学到了什么。同样的偏好你要反复教。

Agent Guild 终结这件事。 它是一个协议——不是框架、不是服务、甚至不是库——让你机器上的多个 AI agent 通过纯 Markdown 文件 + Unix 软链共享一份记忆真相源。

30 秒理解

~/.agent-guild/                ← 你机器上的中央目录
│
│  ─── 协议层（强制）───
├── ONBOARDING.md                ← 新 agent 一次性入会流程
├── CONVENTIONS.md               ← 可选的、非规范性约定
├── RETENTION.md                 ← 数据保留策略（groom 防劣化阈值，用户可改）
├── identity/                    ← 你是谁（profile / 作息）
├── rules/                       ← 所有 agent 必须遵守的硬规则
├── toolchain/                   ← 工具 / 路径 / 配置
├── projects/                    ← 你在做什么
├── log/daily/                   ← 按 agent 分文件的日志（无写冲突）
├── handoff/                     ← 跨 agent 收件箱 + 共享状态
├── hosts//             ← 每台设备自己的状态（本机路径、安装情况）
├── learnings/                   ← 跨 agent 学习台账（纠正/错误/特性请求）
├── skills/agent-guild/    ← 从仓库根安装的 runtime skill（SKILL.md + manifest + scripts）
├── registry.json                ← 哪些 agent 加入了
│
│  ─── 约定层（可选，推荐）───
├── skills_data//         ← 各 skill 自己的持久化数据（一个备份根管所有）
├── mcp//                ← 共享 MCP server 配置
├── plugins//              ← 共享插件
└── tools//                ← 共享 CLI 脚本/工具（+ tool.json 声明各平台）

每个加入的 agent 把自己的 skills 目录用一条目录级软链指向协会：

~/./skills → ~/.agent-guild/skills/

就这。没有 daemon。没有服务器。没有 npm install。没有第三方运行时。纯文件系统。

为什么需要它（以及它跟别的方案有啥不同）

| 已有方案 | 它做什么 | 死穴 |
|---|---|---|
| ChatGPT Memory | 自动记住关于你的事实 | 锁死在 OpenAI 生态 |
| Claude Projects | 项目级上下文 | Anthropic 独享 |
| MemGPT / Letta | 单 agent 内部长期记忆 | 不跨 agent |
| Mem0 | 跨 agent 的记忆服务 | 需要服务化部署、REST API、绑死供应商 |
| MCP | 工具/资源协议 | 不是记忆方案 |
| Agent Guild | 跨厂商、本地优先、纯文本、零依赖 | 要求 agent 智力够读懂一份文件 |

差异化的关键：我们不为每个 agent 写适配器。我们写一份 SKILL.md，任何足够聪明的 LLM 都能读懂并自我接入。读不懂的 agent……不配加入。这是设计本身。

用户怎么让任何 AI agent 加入

对 agent 说一句（任何语言、任何措辞）：

"请读 ~/.agent-guild/ONBOARDING.md 加入这个体系。"

就这一句话——这就是用户侧全部工作流。不需要装 CLI，不需要改配置。Agent 自己读这个文件，按里面的入会流程完成接入并报告。

如果某个 agent 搞不定这件事，说明这个 agent 不够聪明，不配做你的工作伙伴 —— 你也借此知道了。这是内置的能力测试。

协议要求加入的 agent 做什么

协议显式区分一次性入会 vs 持续运行能力：

- ONBOARDING.md（一次性）：发现自己 runtime 的"用户可扩展 skill 目录"→ 收敛为指向协会的一条目录级软链（ag link-root；降级：逐 skill 软链 → copy → readonly）→ 闭环触发自检证明真的能调 → 在 registry.json 登记
- SKILL.md（每次按需触发）：读共享身份/规则/当前焦点；查收件箱/发消息；写当日日志；刷新 last_seen。这是加入后 agent 一直带着的运行时能力

详见：
- ONBOARDING.md —— 一次性入会流程
- SKILL.md —— 加入后的运行时能力
- SPEC.md —— 完整协议规范
- CONVENTIONS.md —— 非规范性的可选约定（如推荐的 skill 数据位置 ~/.agent-guild/skills_data/）
- manifest.json —— 机器可读

单一真相源 + 自动协议升级 + 自动防劣化

每个加入 agent 的 ~/./skills/ 是一条目录级软链，直接指向中央 ~/.agent-guild/skills/。当本项目发布协议升级，你只更新中央目录，用户机器上每个 agent 下次会话启动就看到新版本。零推送、零版本检查、零 hash 比对——而且任何 agent 往协会装一个新 skill，所有已收敛的 runtime 立即可见，永远不需要再补软链。文件系统语义就这么干净利落。（降级 tier：逐 skill 软链。）

用户自己的内容（identity/ rules/ toolchain/ 等）从不会被上游覆盖 —— 它们存在于软链外的同级目录，跟协议骨架物理隔离。

共享记忆只增不减迟早劣化：current-focus 变成一堵墙、日志无限堆积、审计滚成巨石。协议 3.2 内置 groom 数据卫生：skill 正常触发（bootstrap）后自动检测并整理——过期日志/焦点块/已解决的台账条目归档、审计轮转、过期消息进废纸篓。永不硬删（一切进 archive 或可恢复的 .trash/）、策略可调（RETENTION.md）、未读消息和手写内容永远只报告不动。也可手动 ag groom --dry-run 预览。

安装（用户视角）

macOS / Linux / WSL / Git Bash

curl -fsSL https://raw.githubusercontent.com/dqsjqian/agent-guild/main/scripts/install.sh | bash

Windows（PowerShell）

iwr -useb https://raw.githubusercontent.com/dqsjqian/agent-guild/main/scripts/install.ps1 | iex

安装器只做一件事：在 ~/.agent-guild/（Windows 上是 %USERPROFILE%\.agent-guild\）建中央目录 + seed 模板 + 末尾打印一条双语口令让你复制给 agent。它不会动任何 agent 的 home 目录。 Agent 自己负责接入——这就是协议。

手动安装

git clone https://github.com/dqsjqian/agent-guild ~/.agent-guild

然后对你的 agent 说：

"请阅读 ~/.agent-guild/ONBOARDING.md 加入 Agent Guild。"

Agent 会自己想办法接入（目录级软链、逐 skill 软链、拷贝、或者只读 fallback——具体见 ONBOARDING.md）。

平台支持

| 系统 / Shell | 状态 |
|---|---|
| macOS | ✅ 一类支持 |
| Linux | ✅ 一类支持（任何 POSIX shell） |
| Windows + PowerShell 5.1+ | ✅ 一类支持（开发者模式或管理员权限；否则自动降级用目录 junction） |
| Windows + WSL / Git Bash | ✅ 可用（Git Bash 需先设 MSYS=winsymlinks:nativestrict） |
| 安卓（Termux）/ iOS shell | ✅ 识别为独立平台标签；不属于本平台的资产会明确报"本机不可用"并给安装指引 |
| Windows + cmd.exe | ❌ 不支持（请用 PowerShell） |

ag platform 会打印本机被识别成什么，包括能不能建软链——建不了也能加入，只是走 copy 档。

升级（已经装过）

cd ~/.agent-guild && git pull   # （如果通过 git clone 装的）
或重新跑：
curl -fsSL https://raw.githubusercontent.com/dqsjqian/agent-guild/main/scripts/install.sh | bash

升级永远不会覆盖你的 identity/ rules/ toolchain/。只会更新协议骨架（skills/）。

多设备 / 备份

整个 ~/.agent-guild/ 就是一个普通目录，可以用你习惯的任何方式搬到另一台机器：
rsync、私有 git 仓、文件同步工具、云盘、U 盘。协会自己不做同步，不联网、
没有 sync 命令——搬运方式由你定。它负责的是搬过去之后真正会出问题的那部分：
每台设备都分得清哪条数据对自己成立。

| 作用域 | 判定 | 放哪 |
|---|---|---|
| shared | 换设备照样成立 | 原样：identity/ rules/ memory/ learnings/ skills/ |
| platform | 只对某个 OS+架构成立 | tools//tool.json，二进制放 bin/-/ |
| host | 只对本机成立 | hosts//（本机绝对路径、装了什么、本机笔记） |

ag platform            # 我在哪台设备：os / 架构 / host-id / 软链能力
ag tool doxygen        # 本平台的可执行路径；没有则退出码 3 + 该平台安装指引
ag port                # 便携性体检；--apply 只做机械修复

换新设备的流程：目录搬过去 → ag init （自动认领新设备）→ ag port
看差异 → 按提示装缺的平台工具。老设备的数据一个字节都不用改。

注意不要把它推到公开仓库——里面是你的私人记忆。完整规则见
PORTABILITY.md。

项目状态 & 设计哲学
Phase 1（已完成）：协议 + 参考内容。 目录骨架、SKILL.md、manifest.json、跨平台安装脚本。README 才是产品。

Phase 2（已完成）：单文件 Python CLI（ag 命令），子命令 init / adopt / link-root / bootstrap / doctor / platform / tool / tools / port / upgrade / learn / review / resolve / groom / status / register / log / focus / send / audit / prune。仅用标准库，零第三方依赖，Windows / macOS / Linux 通用。

Phase 3（进行中）：Adapters 目录。 社区贡献各 agent 的接入指南。

我们坚决不会做：

- daemon（守护进程）
- pip / npm 上的包
- CRDT 同步引擎
- 云服务
- 聊天界面

这个项目是一份约定，不是软件。约定胜过配置。文件系统胜过数据库。软链胜过同步逻辑。

License

MIT。详见 LICENSE。

作者

@dqsjqian · 同时是 soul-archive（数字人格存档）和 ai-eight-creed（AI 八耻八荣）的作者。

让你的 AI agent 们终于停止互相不认识。