Memory

agent-guild

Try it

智能体协会（agent-guild）— local-first shared memory and opt-in task handoff. 本机多个 AI agent 共享身份、规则与长期记忆；任务各有独立目录，支持 Markdown、JSON、脚本、图片与检查点。新对话不自动加载其他任务。 触发：身份/偏好、记住、回忆、加入协会、跨 agent 消息、换设备、整理协会； “我有哪些事没做完 / 待处理 / todos”只列元信息，用户选择后才恢复该任务。 实质工作保存任务检查点，验收闭环整包归档。会话隔离、版本检查防覆盖； 历史统一1GiB预算，维护先预览、确认后执行，不静默删除或上传记忆。

What it does

Local-first cross-agent shared memory. Join once, share identity/rules/focus across every agent on this machine. Data lives at (plaintext, yours, never uploaded).

The skill document

Agent Guild — Runtime Skill

Local-first cross-agent shared memory. Join once, share identity/rules/focus across every agent on this machine. Data lives at ~/.agent-guild/ (plaintext, yours, never uploaded).

SKILL_DIR below means the directory containing this file. CLI entry point: python3 /scripts/ag.py (referred to as ag). Requires Python 3.9+ (stdlib only, no third-party packages). On Windows use python instead of python3 if that is what your PATH exposes.

Quick start (for an agent that has NOT joined yet)

  1. Run the onboarding flow: ~/.agent-guild/ONBOARDING.md (or this skill's docs/ONBOARDING.md) — discover your runtime's user-extensible skills dir, install this skill (symlink → copy → readonly), run the closed-loop trigger test, register yourself in registry.json.
  2. Then come back here — this file is your everyday capability.

Mandatory Session Contract (once per session, MUST)

⛔ 这些是强制动作，不是建议。每次会话开始（或首次需要用户上下文时）执行，不要等用户点名。 全部通过 ag 一条命令完成，别手工开五个文件。

No shell / no Python? Every step below has a plain-file equivalent — read the listed files directly and Edit them in place. The contract still applies; only the mechanism changes. On Windows, use python if python3 is not on PATH.

M0 — Ensure the guild exists (first use / every session start)

python3 /scripts/ag.py init

幂等：目录不存在则建全套骨架 + 落地本 skill；已存在则只补缺失项，绝不覆盖已有数据。 输出 initialized = 首次自举，verified = 已存在。

M1 — Bootstrap: read shared context BEFORE real work

python3 /scripts/ag.py bootstrap

一次读全：用户画像 → 日程 → 最高优先级戒律 → 在做的项目 → 各 agent 当前焦点 → 你的未读收件箱。

文件内容
identity/profile.md用户是谁
identity/ROUTINE.md日程 / 习惯
rules/universal.md最高优先级戒律
projects/active.md用户当前在做什么
handoff/shared-state/current-focus.md各 agent 当前焦点

读到什么就按什么做。没读就动手 = 违反协议。 之后按需再读 toolchain/*.md、其他 rules/*.md。

M2 — Write memory after substantive work

完成实质工作后 MUST 追加 daily log（见 Capability 4）。满足任一即"实质工作"： 产出交付物（代码/文档/报告/网站/脚本）・改了代码或配置・做了技术决策・修复错误并定位根因・学到可复用的长期事实（用户偏好/项目约定/坑）。

跳过：寒暄、简单查询、短问答、纯检索。

跨 agent 有价值的事实 → 也写 memory/shared/；只对你自己有意义的 → 留在 memory/<你的名字>/。

踩坑/被纠正/发现更好做法 → 同时记学习台账（Capability 8，ag learn）。 用户纠正了你・命令非预期失败・用户想要不存在的能力・发现某任务更优解 —— 这些是全 guild 的免疫素材，别只留在当天日志里。绝不记录 secrets/原始报文，摘录要脱敏。

M3 — Route skills & data into the guild (default-on)

  • 装新 skill：MUST 装到 ~/.agent-guild/skills//，再从那里软链回自己 runtime（symlink → copy → readonly 降级，见 ONBOARDING.md Step 3）。
  • 写持久化数据：MUST 写 ~/.agent-guild/skills_data//（敏感数据拆 private/）。
  • MCP / 插件 / CLI 工具：分别进 mcp/、plugins/、tools/。
  • 唯一豁免：你的 runtime 强制私有路径（如 platform-managed）——在 registry 里记录原因即可，不算违反。

M4 — Self-audit: adopt what's still scattered (first join + monthly)

python3 /scripts/ag.py adopt             # DRY-RUN, 只报告
python3 /scripts/ag.py adopt  --apply    # 真的搬 + 软链回来

扫五类资产：skills / skills_data / mcp / tools / memory。 默认 dry-run，先把清单给用户看；--apply 才动手（搬完自动验证软链，失败自动回滚，删除走废纸篓）。

自动排除：可重建缓存（.venv/node_modules/__pycache__）、凭证、runtime 内部元数据、平台托管包（__skillhub/connector-*）、connector 型 skill。

健康检查（发现悬空软链 / 旧路径残留 / registry 漂移）：

python3 /scripts/ag.py doctor

Self-check (each session, before real work)

# 1. registered?
grep -q '""' ~/.agent-guild/registry.json && echo registered || echo not_registered
# 2. protocol version compatible?
grep -E '"protocol_version"' ~/.agent-guild/skills/agent-guild/manifest.json | head -1

Not registered → run onboarding first. Central major version > yours → re-run onboarding from the top.

The ag CLI — use it for all writes

Writes to shared files are atomic + audited when done through the CLI (zero-dependency Python, stdlib only). Reads stay plain file reads.

AG="python3 /scripts/ag.py"

$AG init                     # bootstrap the guild (idempotent)
$AG bootstrap                # read ALL shared context in one shot
$AG adopt                    # dry-run: what of mine belongs in the guild?
$AG adopt  --apply           # move it in + symlink back
$AG doctor                          # dangling links / stale paths / drift
$AG status                          # who is registered
$AG register     # join (tier: symlink|copy|readonly)
$AG last-seen                # refresh presence
echo "" | $AG send          # handoff message
echo "" | $AG log  ""     # daily log
echo "" | $AG focus  ""   # update current-focus
echo "" | $AG learn   ""  # learning ledger entry
                                             #   kind: learning|error|featreq
                                             #   opts: --area X --priority Y --pattern-key K
$AG review                          # pending stats + promotion candidates
$AG resolve  ["note"]           # mark entry resolved (+ note)
$AG audit                           # audit trail of shared writes
$AG prune 30                        # list idle agents

If the CLI is unavailable (no Python, sandboxed runtime), fall back to the manual file operations below — Edit in place, never Write-overwrite a shared file. Every capability in this skill is reachable by plain file reads/writes; the CLI only adds atomicity and an audit trail.

Capability 1 — Read shared user context

FilePurpose
~/.agent-guild/identity/profile.mdWho the user is
~/.agent-guild/identity/ROUTINE.mdDaily schedule / routines
~/.agent-guild/rules/universal.mdMandatory commandments — highest priority
~/.agent-guild/rules/public-repo.mdPublic-repo hard rules
~/.agent-guild/rules/file-cleanup.mdFile deletion preferences
~/.agent-guild/rules/safety.mdSafety guardrails
~/.agent-guild/projects/active.mdWhat the user is working on
~/.agent-guild/handoff/shared-state/current-focus.mdWhat any agent is focused on now
~/.agent-guild/toolchain/*.mdTool-specific config — read on demand

Read on demand; don't slurp everything every turn.

Capability 2 — Update current-focus

current-focus.md is the "what's hot right now" board. When you start or finish a major task, prepend your block (ag focus or manual Edit in place). Never rewrite history other agents wrote.

Capability 3 — Check inbox / send messages

Inbox: ~/.agent-guild/handoff/inbox/.

  • Receive: ls ~/.agent-guild/handoff/inbox/ | grep "to--", read, act, then mv to handoff/archive/.
  • Send: from--to--.md — write for a recipient with no context (what you did, what's left, where artifacts are).

Capability 4 — Daily log

After substantive work (built/fixed/decided/learned a lasting fact), append to ~/.agent-guild/log/daily/YYYY-MM-DD-.md — per-agent file, append-only. Skip greetings / lookups / short Q&A.

Good entry: ## + What / Why / Result / Cross-agent note (if others need to know).

Capability 5 — Refresh last_seen

Once per session, update your entry's last_seen (prefer ag last-seen, fallback Edit). Never overwrite the whole registry — patch only your entry.

Capability 6 — Where to persist shared data

New skill / MCP / plugin / tool / persistent data you install → MUST go under ~/.agent-guild/{skills,skills_data,mcp,plugins,tools}//, not a private path (唯一豁免见 M3). The user backs up the whole ~/.agent-guild/ with one command.

Capability 7 — Cross-agent memory

PathWhat goes there
~/.agent-guild/memory//该 agent 的私有记忆文件（ag adopt 搬进来后软链回原位，runtime 照常读写）
~/.agent-guild/memory/shared/跨 agent 都该知道的事实（用户偏好、项目约定、踩过的坑）

写之前先读：别把别人已经记过的东西重复记一遍。

Capability 8 — Learning ledger (self-improvement loop)

三本跨 agent 台账在 ~/.agent-guild/learnings/：LEARNINGS.md（纠正/知识盲区/最佳实践）· ERRORS.md（命令/集成失败）· FEATURE_REQUESTS.md（用户想要但不存在的能力）。 完整规范（schema/触发词/晋升阈值/萃取流程）：docs/LEARNINGS.md（权威）。

触发速查：

情况动作
命令失败/异常/超时ag learn error ""
用户纠正你（"不对"/"其实是"/"you're wrong"）ag learn learning ""（category correction）
你的知识过时 / API 行为和认知不符同上（knowledge_gap）
发现更好做法同上（best_practice）
用户想要不存在的能力ag learn featreq ""

复发追踪：相同 Pattern-Key 的条目跨 agent 计数；ag review 报告达到阈值的组。

晋升（达到阈值后 MUST，详见 docs/LEARNINGS.md）： 行为/偏好 → rules/.md；工具坑 → toolchain/.md 或 memory/shared/； 通用可复用解法 → 萃取为 skill 放 skills//（共享 skill bus，全 agent 即刻可用）， 条目状态改 promoted / promoted_to_skill。

红线：不记 secrets/token/原始报文；条目只增不改，仅 Status/Resolution 可由任何 agent 更新。

Failure modes

  • Some files missing → read what exists, note the rest, don't block.
  • registry.json not writable → log the issue, proceed read-only.
  • Inbox file in an unexpected format → read anyway, reply with a structured request for clarity.

Spec

  • Manifest: manifest.json
  • Onboarding (one-time): docs/ONBOARDING.md
  • Conventions: docs/CONVENTIONS.md
  • Learning ledger (self-improvement): docs/LEARNINGS.md
  • Repository: https://github.com/dqsjqian/agent-guild
  • License: MIT

Related skills

Memory

Stores durable facts in a categorized, plain-markdown vault on disk, alongside your agent's built-in memory.

by Iván559 installs18 stars

Join meeting

Join a video meeting as an AI bot with voice, avatar, and screenshare across four operating modes.

by johnpatternai22 installs8 stars

diagram-generator

Generate and edit Draw.io, Mermaid, and Excalidraw diagrams from natural language using a structured JSON spec.

by nssa.io1.0k installs47 stars

Productivity

Find why your productivity system keeps failing, then apply the smallest fix — capacity math, bottleneck routing, durable local notes.

by Iván855 installs69 stars

AdMapix

Fetch raw ad creative, app, ranking, and revenue data from AdMapix as structured JSON.

by fly0pants4.3k installs296 stars

Git

Run Git operations — commits, branches, merges, rebases, conflict resolution, and recovery — with safety rules enforced.

by Iván535 installs31 stars

More from dqsjqian

Browse all skills

soul-archive

Build a persistent personality profile from everyday AI conversations, stored locally as plaintext JSON.

by dqsjqian32 installs2 stars

SVG绘图工作台-智能生图

用「编写 SVG」的方式生成图片——让没有多模态生图能力的模型也能产出任意宽高比、任意复杂度的矢量图，并导出为 SVG / PNG / 动图(GIF/APNG/WebP/MP4)，或内嵌进 HTML。 适用场景：用户要「生成一张图 / 画个图 / 做张配图 / 做海报 / 信息图 / 图表 / 流程图 / 架构图 / 图标 / 封面 / OG 图」，要求指定宽高比(16:9 / 1:1 / 9:16 等)或导出 PNG；也包括「做个动图 / GIF / 加载动画 / loading 动效」。 能力：① 按指令编写复杂 SVG（图表/插画/流程图/海报）；② SVG→PNG 高清渲染(Chrome 优先，cairosvg/resvg 兜底)；③ 多帧/模板 SVG→GIF/APNG/WebP/MP4 动图；④ 任意宽高比与 DPR。 关键词：生图、画图、SVG、矢量图、配图、海报、信息图、图表、流程图、架构图、图标、封面、OG image、转 PNG、动图、GIF、动画、loading。

by dqsjqian

图文笔记发布

通用「图文笔记发布」框架：把本地 markdown 文案 + 配图，通过你指定的 MCP 发布后端，一键发布为图文笔记（含 note_id 回查）。 只负责登录与发布编排，不碰内容创作；不绑定任何特定平台，后端地址由用户自己配置。 触发词：图文笔记发布、笔记发布、社交笔记发布、登录发布、发布失败重试。

by dqsjqian

platform-pitfalls

Cross-platform engineering pitfalls playbook: Chinese/non-ASCII encoding defense (Python entrypoints, child processes, file IO, CMake execute_process ENCODING, MSVC /utf-8 vs VSLANG, Windows console code pages, doctest/CTest discovery), PowerShell 5.1 mojibake three-layer fix (UTF-8 BOM + chcp + byte arrays), and 11 C++20 coroutine pitfalls (lambda captures, catch co_await, mutex resume, handle lifetimes, container-overflow spans). Load when authoring or debugging cross-platform build tooling, CI, installers or async C++ — especially anything that must run on Chinese Windows (cp936/GBK) or Windows runners (cp1252). Triggers: 中文乱码, mojibake, UnicodeEncodeError charmap, doctest CTest Chinese test names, PYTHONIOENCODING, VSLANG, code page 936, 璇峰鎻朵, coroutine UAF, ASan container-overflow.

by dqsjqian1 installs

AI 八耻八荣 (ai-eight-creed)

AI 八信条（AI Eight Creed）—— 一套最高优先级的 AI 行为守则（八耻八荣）。 任何 AI agent 都应无条件遵循：以瞎猜事实为耻、以查证溯源为荣；以模糊执行为耻、 以澄清边界为荣；以擅自臆断为耻、以人类拍板为荣；以另起炉灶为耻、以沿用现成为荣； 以跳过核验为耻、以闭环自检为荣；以破坏章法为耻、以遵循规范为荣； 以假装理解为耻、以坦白无知为荣；以将错就错为耻、以正本清源为荣。 Triggers: "八耻八荣", "八信条", "AI 行为守则", "遵守守则", "查证溯源", "澄清边界", "人类拍板", "沿用现成", "闭环自检", "遵循规范", "坦白无知", "正本清源", "eight creed", "ai creed", "eight honors and shames", any request involving agent behavior rules or ethical guidelines.

by dqsjqian