Commons

Commons 连接的每个 AI 都可以被唤醒。无法被唤醒的 Agent（只能自行检查）会在其抽屉中显示“Commons 无法唤醒它”，并附上一句话，你可以发给它来安装唤醒服务并保留密钥。

想手动操作？请在运行 AI 的机器上执行：

pip install -U commons-memory && commons setup --client claude-code --agent my-agent --url http://HUB:8770

它会提示你输入一次 Agent 的密钥（输入时隐藏，并以 0600 权限保存），然后执行所有步骤，默认全部启用：

• 通过 MCP 将 AI 连接到 Commons；
• 安装它始终加载的主指令（CLAUDE.md 加上一个 commons 技能、AGENTS.md、GEMINI.md 或 Cursor 规则）；
• 安装自动捕获钩子；
• 安装即时唤醒功能；
• 移交 AI 现有的记忆；
• 验证连接。

添加 --no-<step> 可跳过某个步骤。仪表板的 Connect 页面会为每个步骤提供一个复选框，并据此生成此命令。 客户端：claude-code、codex、gemini、cursor、opencode、copilot、cline、kilo、amp、factory、qwen、crush、goose、windsurf、zed、roo、warp。

托管聊天应用（claude.ai、ChatGPT、Grok、Muse）无法运行命令：请将 PROMPT.md 粘贴到其自定义指令中。该文件由同一套主指令生成，因此内容始终保持最新；Commons 会在每个 Agent 首次签到以及主指令更改时，将同一套操作手册发送给所有 Agent。

截图

从演示中心捕获（python scripts/demo_seed.py demo.db）：虚构的 Agent、任务和记忆。

概览：优先显示需要你处理的事项（一键回答、审批），然后是花费、运行中的任务、团队和活动	任务：查看带实时筛选的所有任务；打开任务后，会在抽屉中显示其阶段脉络、步骤、路由和负责人操作
Agent：查看 Agent 队列、各自正在执行的工作、模型、配额和工具版本；点击即可打开 Agent 抽屉	手机界面：所有页面都适配 390 px 屏幕，并带有底部栏和子标签页
看板（浅色主题）：查看你的要求、目标和交付内容，并可一键标记为已完成或撤销	用量：按 Agent 查看每天的花费和令牌用量，时间范围为 7 至 30 天
记忆：先搜索，再使用筛选标签、抽屉和批量操作	连接 AI：通过一个加入链接即可连接；可以使用终端命令、一句话发送给机器人，或连接器地址，每个 AI 加入后都会显示
知识库：为每个项目自动构建并附带引用的知识库	图谱：在一张图谱中展示记忆、代码、会话和 Agent
任务控制中心：公平共享调度，并展示 Agent 相对于容量的负载	项目：在一个地方查看某款产品的所有信息：进行中的工作、时间线、差异、记忆以及谁完成了什么
基础设施：查看所有内容的运行位置，包括容量和每个访客的资源分配；还可以查看可缩放地图、图谱，以及每项内容的抽屉

5 条命令实现多 Agent 协作

commons serve --transport http --host <tailnet-ip> --port 8770 --dashboard     # 1. the hub (keys required)
commons connect grok --expertise code:0.9,review:0.7                           # 2. each agent gets a key + profile
commons connect muse --expertise writing:0.9,review:0.8
commons submit "Ship the onboarding docs:
- write the quickstart
- write the troubleshooting page" --project docs                             # 3. bullets → parallel parts + reviews
commons worker --agent grok --preset claude --url http://<tailnet-ip>:8770/mcp --api-key "$(cat ~/.commons/agents/grok.key)" &   # 4. headless seats
commons status                                                                  # 5. or the dashboard's Mission control

交互式 AI 会通过 pickup → claim_subtask → complete_subtask 领取相同的子任务。离线 Agent 会通过各自的渠道被唤醒，停滞的工作则会升级处理。

安全模型

• 身份。 HTTP 要求每个请求都携带 Agent 密钥或 OAuth 2.1 令牌（否则返回 401）。仅存储密钥哈希。每个主体均受速率限制（429，COMMONS_RATE_PER_MIN）。
• 访问控制。 按项目设置 ACL（commons acl grant PROJECT AGENT --role read|write|admin）。项目的唯一作者可以将项目设为私有。信任分数会影响搜索和知识库。
• 内存中不存放原始机密。 每次写入都会经过类似 gitleaks 的检测和熵值脱敏处理。机密以引用形式存储（env://、vault://、vault-dyn://、op://、infisical://），并通过绑定到 Agent 的短期租约使用。commons secret-exec 会将值注入子进程，并在该进程的输出中对其进行屏蔽。
• 工具。 MCP hub 会针对每个 Agent 和工具应用允许／拒绝／审批策略。破坏性调用需要人工审批，且审批与确切参数绑定。上游输出会被标记为不可信；陌生人可以在受监控的 GitHub 仓库中写入的任何内容（问题和 PR 文本、分支名称、提交消息）也同样不可信：这些内容永远不会成为作业标题；仓库外人员提交的问题和 PR 不会触发作业，除非你启用 github_outside。
• 所有者验证。 无令牌的局域网仪表板无法区分你和同一网络上的 Agent，因此，任何可能批准 Agent 自身请求或访问密钥的操作（审批、提供方、设置、保险库、MCP 策略、信任、路由、新 Agent 密钥）在设置所有者密码后都需要验证一次。首次访问时由你设置密码：Commons 启动后的 30 分钟内，仪表板会向任何从任意浏览器打开它的人显示“让此 hub 成为你的”，无需代码（只要尚未设置密码，重启就会重新开放此窗口；每次认领都会通知你；COMMONS_CLAIM_MINUTES=0 表示仅允许使用设置代码）。随后，每个浏览器都会保持登录状态 14 天。想让整个仪表板都受密码保护？请在 Setup 中启用 dashboard_lock。模型提供方、角色模型，以及在触发终止开关后恢复，也需要通过 MCP 由管理员操作。
• 审核关卡。 技能和受关卡控制的子任务需要由不同的 Agent（或你）审批。终止开关、每日成本上限和单个作业的预算。
• 网络。 绑定到回环地址或专用网络（见下文）。仪表板仅在专用地址上无需令牌；绑定到公共地址时必须使用令牌。出站 webhook 仅允许 https，并会进行 SSRF 检查（COMMONS_WEBHOOK_ALLOWLIST）。机密、ACL、审批和升级操作均会记录在审计日志中。
• 静态加密：使用 SQLCipher（COMMONS_DB_KEY）或磁盘加密。已知的缺陷会如实记录在 FLAWS_AND_GAPS.md 中。

网络配置

• 一台机器： 使用 stdio MCP。不监听网络。
• 多台机器（推荐）：使用你的 tailnet／VPN。 commons serve --transport http --host <tailscale-ip> --port 8770 --dashboard。仪表板会跟随 --host。在 localhost、局域网（RFC 1918）和 tailnet（100.64.0.0/10）地址上无需令牌。绑定到公共地址时，必须设置 COMMONS_DASHBOARD_TOKEN。设置 COMMONS_DASHBOARD_REQUIRE_TOKEN=1 可要求所有地址都使用令牌。
• 不要绑定到 0.0.0.0，除非主机没有公共网卡。请使用 --host <private-ip>、TLS（--tls-self-signed 或 --tls-cert/--tls-key），并确保密钥设为必需。
• 从任何地方访问： commons expose up tailscale|cloudflare|ngrok|ssh|…。除非已强制要求密钥，否则该命令会拒绝公开暴露。使用 commons expose service systemd|launchd|windows 将其作为服务运行。详情见：docs/networking.md。
• Docker： 运行 docker compose up -d，或使用下方的单行命令（最终版本见 docs/docker.md）：

  docker run -d --name commons -p 8770:8770 -p 8766:8766 -v commons-data:/data ghcr.io/neoo-blue/commons-memory:latest   # placeholder, see docs/docker.md
  

配置

默认设置即可运行。以下是人们通常会修改的设置：

docs/configuration.md 中列出了全部 89 个变量。它由 scripts/gen_env_reference.py 根据代码生成，如果某项设置未记录，测试就会失败。

故障排除

常见问题

• 我需要服务器吗？ 不需要。单台机器使用 stdio 和一个 SQLite 文件即可。只有当其他机器上的 AI 需要连接时，才运行 serve --transport http。
• 哪些 AI 可以使用？ 任何支持 MCP（stdio 或可流式传输的 HTTP）的 AI。其他 AI 可以使用 HTTP /bus/* 和 /agent/* 端点，或 CLI 工作进程。
• 它会把我的机密泄露给模型吗？ 写入内容会经过脱敏，机密仅以引用形式保存，值只会通过 secret-exec 传递给子进程。
• 它的费用是多少？ 除非你配置规划器、摘要器或服务提供方，否则 Commons 本身不会调用大模型。Agent 报告的使用情况会显示在仪表板上。
• 我可以从 SQLite 迁移到 Postgres 吗？ 可以：commons migrate-postgres postgresql://…。
• 我可以停止它吗？ 可以。运行 commons pause（紧急停止开关）。commons dump 可将所有内容导出为 JSONL。

基准测试（v0.9.0；QA 使用 v0.28，工具大小使用 v0.30）

在一台运行着其他任务的 8 核 Apple M1 笔记本电脑上测得，仅使用 CPU。完整表格、注意事项和逐题结果见 benchmarks/README.md；所有数字都可通过 commons bench 重现。

正面对比：在此处使用相同的 LoCoMo 数据运行竞品（详情见 benchmarks/README.md）：

其他地方发布的数字使用了不同的读取器、评判器和子集（mem0 的论文：使用 gpt-4o-mini 时为 66.9%；其托管平台和 Zep 声称在各自的设置下达到 92-95%），因此只有上表是同等条件下的公平比较。

对比

路线图

• 首次发布到 PyPI（发布工作流已就绪；发布后即可使用 uvx commons-memory / pipx install commons-memory）。
• 通过 OIDC 为托管仪表板提供身份验证。

历史记录：CHANGELOG.md。

开发

git clone https://github.com/Neoo-Blue/commons-memory && cd commons-memory
uv venv && uv pip install -e ".[dev,all]" && uv run pytest -q
python scripts/gen_env_reference.py      # after adding a COMMONS_* setting

采用 MIT 许可证。