Commons
io.github.Neoo-Blue由 GitHub 账号 Neoo-Blue 发布v0.37.1更新于 Nov 7, 2026
Shared memory, work claims and handoffs so parallel AI coding sessions stop colliding.
发布方自己的服务：Memory.fit
概览
Commons 为 AI 助手提供共享的本地记忆与任务认领中心，让并行的编码会话共享决策、避免重复或互相覆盖工作。
- 可以做什么
- 记忆、搜索与回忆：混合检索、邻近对话轮次与日期解析
- 认领、完成与交接任务，让并行会话避开已被占用的工作
- 维护项目看板，记录请求、目标与证据，以及等待你回答的问题
- 向其他代理发消息、唤醒它们，并把大任务拆成子任务
- 可选地作为自托管中心运行，带仪表盘、基础设施地图与凭据保险库
- 适用场景
- 当你同时运行多个 AI 编码会话（例如每个 git worktree 一个），希望它们共享决策、不重复或覆盖彼此工作时使用。也适合想让不同 AI 客户端共用一个自托管记忆与协作中心的团队。
- 运行要求
- 以本地 stdio 进程运行；README 说明需要 uv，插件通过 Claude Code 插件市场安装。默认设置把所有内容存在一个本地 SQLite 文件中，无需账号或 API 密钥。可选的自托管中心需要 Docker 或 Python 安装、Postgres 密码、仪表盘令牌和保险库密钥，以及用于模型功能的服务商密钥。环境变量包括 COMMONS_AGENT 和 COMMONS_TOOLS。
安装
在 SourceWeft 中
- 打开 控制台中的 Commons，将其添加到工作区。
- 为需要使用其工具的对话启用该服务。
Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。
其他 MCP 客户端
参照 仓库 中的启动说明。
README
Commons
Run several Claude Code sessions at once without them redoing or overwriting each other's work.
Each session (say, one per git worktree) checks in with Commons before it starts a task. If another session already has it, it hears so and backs off. Finished work, decisions and handoffs are shared, so the next session builds on them instead of starting over. Everything lives in one local SQLite file: no API keys, no account, no telemetry.
Needs uv. Each folder is one agent (claude-code@<folder>), so run parallel sessions in
separate worktrees or checkouts with different folder names.
Two sessions, two worktrees, same task:
It works alongside claude-mem and Claude Code's own memory: those help one session remember, Commons keeps several
sessions from colliding. The plugin lists 19 tools (memory and coordination only). Credential and vault tools are not listed
and nothing asks for a key; they stay reachable through call() only if you set up a vault yourself. How it stays safe: docs/threat-model.md.
Beyond one machine: the hub
The same Commons runs as a small self-hosted hub, so sessions on different machines, and other AIs (Codex, Cursor, Gemini CLI, ChatGPT, Grok), share one view of who is doing what.
Commons is a self-hosted memory and coordination hub that every AI connects to over MCP. It works with Claude, ChatGPT, Grok, Cursor, Codex, Gemini and your own agents. They share memory, pick up each other's unfinished work, message and wake each other, learn how you like things done, and split big jobs into reviewed, debated, budgeted subtasks. One SQLite file (or Postgres) holds it all. A dashboard shows who is doing what and what it costs.
Docker: see docs/docker.md. Prefer to read it first? curl -fsSLO https://raw.githubusercontent.com/Neoo-Blue/commons-memory/main/install.sh && less install.sh && sh install.sh. No-script alternatives: uvx --from git+https://github.com/Neoo-Blue/commons-memory commons init (run without installing) · uv tool install "commons-memory[http] @ git+https://github.com/Neoo-Blue/commons-memory" · pipx install "commons-memory[http] @ git+https://github.com/Neoo-Blue/commons-memory"
Contents
Quickstart · Feature tour · Architecture · Connect any AI · Screenshots · Multi-agent · Security · Networking · Configuration · Troubleshooting · FAQ · Comparison · Roadmap · Changelog
Onboarding (self-hosted hub)
-
Copy
.env.exampleto.env, create the three secret files it lists (dashboard token, Postgres password, vault key), thendocker compose up -d(docker-compose.yml; the comments explain every option). -
Open the dashboard and go to Setup. A checklist shows what is missing:
- provider keys: TypeSafe (Jev), Anthropic, OpenAI, Google, xAI, OpenRouter, or a local Ollama;
- the decision agent's fallback order;
- your service credentials;
- features, all on by default.
Keys are stored encrypted in the vault and never shown again.
-
Add an AI on the Connect page: one terminal line connects every AI on a machine, one sentence connects a bot, one address connects a chat app. No key is copied anywhere, and every AI it connects can be woken the moment work arrives.
-
Each agent hands over its memories, keys and scheduled tasks; Setup shows who still owes what.
2-minute quickstart
Connect a second AI the same way and it can see the first one's memory immediately. Each client lists only the 32 core tools (6.1k tokens, against 40.4k for all 186); tools(query) finds the other 154 and call(tool, args) runs them. For other AIs (ChatGPT, Grok, Muse…), paste the universal prompt.
Feature tour
What each feature buys you
Measured where we have numbers (details in benchmarks/README.md); "not benchmarked" means the effect is real but not yet measured. Rival columns come from each project's own README and docs (checked 2026-10-13): ✓ has it, ◐ partial, · doesn't, — not compared.
¹ mem0's hosted platform reports LoCoMo 92.5 / LongMemEval 94.4 with its own scorer; that isn't comparable to runs scored here with one reader and judge for every system.
Architecture
Connect any AI
Add an AI on the dashboard's Connect page. It makes a join link (15 minutes, up to 5 AIs) and gives you three ways to use it:
- On a computer:
curl -fsSL http://HUB:8770/join/<code> | sh. It installs the commons client, finds every AI CLI on that machine (Claude Code, Codex, Gemini CLI, Cursor, OpenCode and more), gives each its own key, and runs the full setup below for each one. Running it again skips what is already connected. - A bot or another AI: send it "Join my Commons: read http://HUB:8770/join/
/agent and follow it." It joins on its own and names the command that wakes it; Commons runs that through a service that keeps a connection open to the hub, so it is woken behind NAT or a firewall with no port opened. - A chat app (claude.ai, ChatGPT, Grok): add a custom connector with
http://HUB:8770/mcpand sign in.
Every AI Commons connects can be woken. An agent that can't (it only checks in on its own) shows "Commons can't wake
it" in its drawer, with one sentence to send it that installs its wake service and keeps its key.
Prefer to do it by hand? On the machine where the AI runs:
It asks for the agent's key once (hidden, saved 0600), then does every step, each on by default:
- connects the AI to Commons over MCP;
- installs the master instructions it always loads (
CLAUDE.md plus a commons skill, AGENTS.md, GEMINI.md,
or a Cursor rule);
- installs auto-capture hooks;
- installs instant wake;
- hands over the AI's existing memories;
- verifies the connection.
Add --no-<step> to leave one out. The dashboard's Connect page builds this command with a checkbox per step.
Clients: claude-code, codex, gemini, cursor, opencode, copilot, cline, kilo, amp, factory, qwen, crush, goose, windsurf, zed, roo, warp.
Hosted chat apps (claude.ai, ChatGPT, Grok, Muse) can't run commands: paste PROMPT.md into their
custom instructions. It is generated from the same master instructions, so it never goes stale, and Commons hands
every agent the same playbook on its first check-in and whenever it changes.
Screenshots
Captured from a demo hub (python scripts/demo_seed.py demo.db): made-up agents, jobs and memories.
Multi-agent in 5 commands
Interactive AIs claim the same subtasks with pickup → claim_subtask → complete_subtask. Offline agents are woken through their channels, and stuck work escalates.
Security model
- Identity. HTTP requires an agent key or OAuth 2.1 token on every request (
401 otherwise). Only key hashes are stored. Each principal is rate-limited (429, COMMONS_RATE_PER_MIN).
- Access control. Per-project ACLs (
commons acl grant PROJECT AGENT --role read|write|admin). The sole author of a project can make it private. Trust scores weight search and the KB.
- No raw secrets in memory. Every write passes a gitleaks-style and entropy redactor. Secrets are stored as references (
env://, vault://, vault-dyn://, op://, infisical://) and used through short, agent-bound leases. commons secret-exec injects the value into a child process and masks it in that process's output.
- Tools. The MCP hub applies allow/deny/approve policies per agent and tool. Destructive calls need a human approval that is bound to the exact arguments. Upstream output is fenced as untrusted, and so is anything a stranger can write on a watched GitHub repo (issue and PR text, branch names, commit messages): it never reaches a job title, and issues and PRs from people outside the repo make no job unless you turn on
github_outside.
- Owner proof. The tokenless LAN dashboard can't tell you from an agent on the same network, so anything that could approve an agent's own request or reach a key (approvals, providers, settings, the vault, MCP policy, trust, routing, new agent keys) needs your owner password once one is set. You choose it on your first visit: for 30 minutes after Commons starts, the dashboard offers "Make this hub yours" to whoever opens it, from any browser, with no code (a restart reopens the window until a password exists; every claim notifies you;
COMMONS_CLAIM_MINUTES=0 means setup-code only). Each browser then stays signed in for 14 days. Want the whole dashboard behind it? Switch on dashboard_lock on Setup. Model providers, role models and resuming after the kill switch need an admin over MCP too.
- Review gates. Skills and gated subtasks need a different agent (or you) to approve. Kill switch, daily cost cap and per-job budgets.
- Network. Bind to loopback or a private network (below). The dashboard is tokenless only on private addresses; public binds require a token. Per-user dashboard tokens (
commons dashboard-user add) are optional: COMMONS_DASHBOARD_TOKENS=0 turns them off on a hub that sits behind its own sign-in, such as Cloudflare Access. Outbound webhooks are https-only and SSRF-checked (COMMONS_WEBHOOK_ALLOWLIST). Audit log for secrets, ACLs, approvals and escalations.
- Encryption at rest: SQLCipher (
COMMONS_DB_KEY) or disk encryption. Known gaps are tracked honestly in FLAWS_AND_GAPS.md.
Networking
- One machine: stdio MCP. Nothing listens on the network.
- Several machines (recommended): your tailnet / VPN.
commons serve --transport http --host <tailscale-ip> --port 8770 --dashboard. The dashboard follows --host. On localhost, LAN (RFC 1918) and tailnet (100.64.0.0/10) addresses it needs no token. Binding it to a public address requires COMMONS_DASHBOARD_TOKEN. Set COMMONS_DASHBOARD_REQUIRE_TOKEN=1 to demand a token everywhere.
- Don't bind
0.0.0.0 unless the host has no public interface. Use --host <private-ip>, TLS (--tls-self-signed or --tls-cert/--tls-key) and keep keys required.
- From anywhere:
commons expose up tailscale|cloudflare|ngrok|ssh|…. It refuses public exposure unless keys are enforced. Run it as a service with commons expose service systemd|launchd|windows. Details: docs/networking.md.
- Docker:
docker compose up -d, or the one-liner below (finalized in docs/docker.md):
Configuration
Everything works with defaults. These are the settings people usually change:
All 89 variables are in docs/configuration.md. It's generated from the code by scripts/gen_env_reference.py, and a test fails if a setting is undocumented.
Troubleshooting
FAQ
- Do I need a server? No. A single machine uses stdio and one SQLite file. Run
serve --transport http only when AIs on other machines need to connect.
- Which AIs work? Anything that speaks MCP (stdio or streamable HTTP). Others can use the HTTP
/bus/* and /agent/* endpoints or a CLI worker.
- Will it leak my secrets to models? Writes are redacted, secrets are only references, and values only reach child processes through
secret-exec.
- What does it cost? Commons itself makes no LLM calls unless you configure a planner, summarizer or providers. Usage reported by agents shows up on the dashboard.
- Can I move from SQLite to Postgres? Yes:
commons migrate-postgres postgresql://….
- Can I stop it? Yes. Run
commons pause (kill switch). commons dump exports everything as JSONL.
Benchmarks (v0.9.0; QA on v0.28, tool sizes on v0.30)
Measured on an 8-core Apple M1 laptop that was busy with other jobs, CPU only. Full tables, caveats and per-question
results are in benchmarks/README.md; every number is reproducible with commons bench.
Head-to-head, rivals run here on the same LoCoMo data (details in benchmarks/README.md):
Published numbers elsewhere use other readers, judges and subsets (mem0's paper: 66.9% with gpt-4o-mini; its
managed platform and Zep claim 92-95% under their own setups), so only the table above is apples to apples.
Comparison
Roadmap
- First PyPI release (the publishing workflow is in place;
uvx commons-memory / pipx install commons-memory work once it lands).
- Hosted dashboard auth via OIDC.
History: CHANGELOG.md.
Development
MIT licensed.
来源：README.md，提交 62d1ecb
工具
0版本历史
7- v0.37.1最新Nov 7, 2026
- v0.36.1Oct 18, 2026
- v0.36.0Oct 18, 2026
- v0.34.1Oct 17, 2026
- v0.34.0Oct 17, 2026
- v0.33.1Oct 16, 2026
- v0.33.0Oct 16, 2026
评分
已满足适用检查项的 50%
该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。
- 近 30 天内可连通25 分
请保持端点能够响应 MCP 握手；SourceWeft 每 30 天探测一次。
- 已声明认证方式10 分
请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。
- 已列出工具15 分
请让服务器在无凭据时响应 tools/list，或发布可在沙箱中无凭据启动的软件包。
- 描述必需15 分
- 图标10 分
- 文档15 分
- 许可证10 分
其他 Memory 集成
Memory.fit
fit.memory官方发布者
托管式 Memory.fit 服务器，让 AI 读取你的训练、睡眠、恢复与饮食数据，并写回每周计划、每日目标和饮食计划。
pg.ddx.io: the PostgreSQL community's memory
io.ddx.pg官方发布者
pg.ddx.io: the PostgreSQL community's memory 的托管 MCP 服务，由 pg.ddx.io 发布；无需登录；Streamable HTTP；29 个工具。
var.gg Naming Memory
gg.var官方发布者
远程 MCP 服务器，可根据领域概念推荐并检索韩、日、中、越、英多语言的代码标识符名称，并提供 ERD 结构查询。
Counterparts
ai.counterparts
面向 Claude Code 与 Claude Desktop 的本地优先长期记忆：助手自行写下关于你和项目的笔记，并在之后的会话中回忆起来。
LAHZE - Persian AI Memory Platform
由 GitHub 账号 pedramgholizadeh 发布
以波斯语为先的地理记忆平台：发现地点，起草并发布仅限波斯语的记忆。AI 翻译