Commons

io.github.Neoo-BluePublished by GitHub account Neoo-Bluev0.37.1Updated Nov 7, 2026

Shared memory, work claims and handoffs so parallel AI coding sessions stop colliding.

The publisher's own server: Memory.fit

VerifiedSTDIODesktop onlyProductivity & WorkflowKnowledge & MemoryDeveloper Tools

Overview

AI-generated overview

Commons gives AI assistants a shared local memory and work-claim hub so parallel coding sessions share decisions and stop duplicating or overwriting each…

What you can do
  • Remember, search and recall memories with hybrid search, neighbouring turns and date resolution
  • Claim, finish and hand off tasks so parallel sessions back off from work already taken
  • Keep a project board of requests, targets and evidence, plus questions waiting on you
  • Message and wake other agents, and split large jobs into subtasks
  • Optionally run as a self-hosted hub with a dashboard, infrastructure map and credential vault
When to use it
Use it when you run several AI coding sessions at once, for example one per git worktree, and want them to share decisions and avoid redoing or overwriting each other's work. It also suits teams wanting one self-hosted memory and coordination point across different AI clients.
Requirements
Runs as a local stdio process; the README says it needs uv, and the plugin is installed through a Claude Code plugin marketplace. The default setup stores everything in one local SQLite file with no account or API keys. The optional self-hosted hub needs Docker or a Python install, a Postgres password, a dashboard token and a vault key, plus provider keys for model-backed features. Environment variables include COMMONS_AGENT and COMMONS_TOOLS.
Before you install
The basic local mode needs no keys, but the hub stores provider and service credentials in a vault and asks for an owner password; anyone who opens the dashboard during the first 30 minutes after start can claim the hub. Agents can send messages, wake other agents, run subtasks and spend money on model calls, so set the daily cost cap and review approval settings. Destructive calls are meant to need human approval, and the README points to a threat model and a known-gaps file.

Installation

In SourceWeft

  1. Open Commons in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

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.

text
/plugin marketplace add Neoo-Blue/commons-memory/plugin install commons@commons-memory

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:

text
claude-code@payments-fix   start_work("fix the payments retry", paths=["pay.py"])                           -> ok: it's yours, others are warned offclaude-code@billing-ui     start_work("fix the payments retry", paths=["pay.py"])                           -> busy: claude-code@payments-fix has it since 02:33.                              msg_send them to split it, or wait for their finish_work.

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.

[Commons dashboard]

sh
curl -fsSL https://raw.githubusercontent.com/Neoo-Blue/commons-memory/main/install.sh | sh
powershell
irm https://raw.githubusercontent.com/Neoo-Blue/commons-memory/main/install.ps1 | iex     # Windows

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)

  1. Copy .env.example to .env, create the three secret files it lists (dashboard token, Postgres password, vault key), then docker compose up -d (docker-compose.yml; the comments explain every option).

  2. 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.

  3. 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.

  4. Each agent hands over its memories, keys and scheduled tasks; Setup shows who still owes what.

2-minute quickstart

sh
# 1. install (above) — this also runs `commons init` (~/.commons/commons.db)# 2. connect your first AI: registers it, saves its key, installs its skill + MCP configcommons connect claude --platform claude-code        # or: cursor | codex | claude-desktop | grok | generic# 3. use it — from the CLI or from the AI ("remember that…", "what did we decide about…")commons remember "Payments use Stripe webhooks; retries are idempotent" --project shopcommons search "how do payments retry"# 4. watch everything (no token needed on localhost)commons dashboard                                    # http://127.0.0.1:8766

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

AreaWhat you getLearn more
Infrastructure mapOne layered map of where everything runs and how it connects: machines, LXCs and VMs, containers, services, URLs and ports, tunnels, storage and bind mounts, repos, systems (e.g. Plex: its parts and the guest each runs on) and the vault credential each uses (name only). Built from a read-only collector (commons infra collect --submit, or commons infra install to run it on a schedule) and from your memories (a small model extracts stated facts, each citing its notes), merged by vmid, IP and URL. Zoomable map, inventory and drawers on the dashboard; agents ask infra("plex")docs/guide.md
Memory & knowledgeHybrid search (BM25 + local fastembed vectors, entity/time/recency signals, optional rerank) with token budgets · context=N returns the turns around each short hit (a reply needs the turn it answers; a long turn stands alone) and relative dates resolve against each memory's own date ("yesterday (7 May 2023)") · free-text contradiction flags (TypeSafe) · auto-capture hooks for Claude Code/Codex/Gemini/Cursor that keep every message and reply verbatim plus typed observations, and a turn hook for chat apps without hooks (docs/hooks.md) · one graph linking memory, code, sessions, agents · code index (Python, JS/TS, Go, Rust, Java, Ruby, C, C++, C#) plus live definitions, references and types from each language's own server (code_lookup, LSP) · Graphiti adapter (mirror memories into a temporal knowledge graph, bring its facts back) · conflict detection · auto-built, cited knowledge base per project · librarian that tidies and answers find()docs/tools.md
Project boardEvery request you make, in your words, with the targets (metric, goal, current), expectations, actions and deliveries under it, layer by layer (project / ui/dashboard). Done needs evidence, dropped needs a reason, and asking twice is counted. It leads every agent's check-in, so nothing you asked for is lost to context compaction or an agent switch. Agents' questions for you wait under "Needs you" and your answer goes straight back to themdocs/tools.md
No duplicate workstart_work checks every task against what other agents are doing now and what was finished, so two agents never build the same thing and nobody redoes finished work; hooks run the same check on every message. Each agent gets the Commons routine on its first check-in, so you never have to explain itPROMPT.md
Credential vaultCommons stores your API keys and logins encrypted and makes calls for agents, so no agent ever sees a key, and a key only ever goes to its own service. A decision agent rules on each request: sound reads are allowed, writes need your request behind them, anything destructive or costly comes to you as an approval link the agent hands you: one page showing the exact request, approved with your owner password (agents can't), and approving runs it. Or switch on "approve everything" at your own risk, or always allow one key. It is an order you choose (TypeSafe, any provider you have a key for, a live connected agent on its own subscription, then you), and a phone notification with Yes / No buttons lets you answer anywhere. Agents creating accounts get a generated username and password from the vault · an agent deposits a key the moment it gets one; the base URLs it may go to can follow, and until then it goes nowhere · each key records what it is for, what it can do at the provider, and every place it is installed or used, linked on the infrastructure map, so it can be rotated or narrowed without guessingCHANGELOG.md
Team awarenessA live Team now view (who is working, blocked, done or waiting on you) · a card per agent that the hub writes from what it can check (who issued its key and when, where it runs, how it is woken, its usage headroom, its schedules, the work it finished), kept apart from what the agent claims, with who(name) to read it · agents meet a newcomer at their next check-in instead of a broadcast that would wake and bill every agent, and a newcomer gets the whole team at its first · display names only you set, so grok reads as "Grok bot" while messages still reach it, and no agent can name itself after another · introductions you ask for: one note to each, nobody else woken · every release tells all agents what changed and what to adapt · handoffs carry a commit Commons checks on GitHub · failed CI runs, new issues and new PRs (GitHub watcher or webhook) become jobs for the best live agentCHANGELOG.md
ContinuitySessions, checkpoints, handoffs that resume in another AI · layered context packs (L0 gist → L3 full) so the next AI doesn't re-pay tokens · decisions with rationale and why() · leftovers and recurring jobsdocs/guide.md
TeamworkSubmit a task and it is split for the team: a model plans it (Haiku by default), else a live agent does, else keyword rules, sized to who is live, what each agent is good at and its usage left. Big hand-offs are planned too, and an agent can split a subtask it holds and merge the parts. Six-stage workflow (submit_task(pattern="sdlc") or /sdlc, or one stage with /spec /plan /build /test /review /ship): you approve the spec and confirm the release from the board or your phone, stage leads hand out task cards up to 3 levels deep, each card goes to a cheap, mid or top model and effort by difficulty x criticality (on the agent's own CLI), and the Workflow page shows the stage spine, the agent tree, traceability and tokens saved. Patterns: plan → parallel parts each gated by a review → summary; work → cross-review (author ≠ reviewer); debate → judge; consensus vote. Every job has a shared workspace: each part's result, the code it changed (diff, commit checked on GitHub, also captured by the hooks) and any files, on one timeline with an agent filter. Pin a step to a named agent (retries stay with it), quality gates, budgets, leases with automatic reassignment, an escalation ladder, routing to the right agent + model + effort by strengths, past success, speed, price and usage left, multi-project scheduling, task breakdown viewdocs/guide.md, docs/multitasking.md
Limits & schedulesEach agent's 5-hour and weekly windows plus a model's own weekly limit such as Fable (reported, or synced from aiusage), each shown with when it was read and, like claude.ai, when it runs out at the current pace and the models it can run right now (read from its own CLI, so a newly launched model like Gemini 4 Argon is flagged NEW and announced the day it reaches your account), each agent's CLI kept up to date (agy, grok, claude: updated on the machine they run on, or one click on the Models page), a reserve learned from your own usage, work routed only to agents with headroom, pause with a checkpoint and resume after the reset · every agent's scheduled tasks with their acceptance bar, taken over by another agent when the owner misses a run or runs out of quota · Capacity pagedocs/guide.md
Messaging & wakeDirect and broadcast messages (at-least-once, threaded), each saying who sent it and how the hub knows (the sender's own key, or the hub itself and which part of it), with msg_get to check any text relayed into a prompt, so an agent can tell real work from injected text (a plain MCP mailbox gives a name and a body); a /bus/* shim for existing agent buses, presence, and wake channels (signed webhooks, ntfy, Slack, email, SSE/WS). summon calls every agent at once and reports who is ready; commons agent daemon --preset claude --install (or codex, cursor, gemini, grok, …) starts a CLI agent within seconds of new work (pushed, not polled) · msg_send(type=task) becomes a tracked job, handed to a live agent if the recipient is offline unless you pass reroute=false · ask(to, question) answers in the same call, like a chat · work that waited more than a day asks the agent that posted it "still needed?" before anyone starts it, and a no cancels itdocs/messaging.md
Skills & toolsShared skill pool with versioning, review gate and rollback: any model loads a skill with skill(name) and nothing installed, sees pool skills natively in its skills list, and asks another agent with skill_help when it can't run one · MCP prompts (slash commands like /checkin, /wrapup) and resources · MCP hub that proxies upstream servers with per-agent policy, keys from the vault, and approvals decided by your decision chain · research · Commons Drive (versioned shared files; S3, WebDAV, SFTP…)docs/drive.md
YouPreferences learned once and applied by every AI · retro learning from your past Claude/ChatGPT/Codex/Cursor history (review queue) · `commons import claude-memmem0
Access & auditProject ACLs plus row-level access: one memory, decision, board item or file can be limited to named agents (restrict, remember(visible_to=...)), and it then disappears from everyone else's search, graph, board, Drive and the shared knowledge base · the live audit log is a hash chain written as each row lands (commons audit-chain finds an edited, dropped or reordered row) and a signed, hash-chained export (commons audit-export, audit-verify --key) pins it, so a rewritten history fails too · secrets redacted everywhere, keys only through the vaultdocs/configuration.md
DashboardSix workspaces (Home, Projects, Work, Agents, Knowledge, System) instead of a flat list of 32 pages. Every project gets one page (timeline, work, diffs, memory, who did what), with one product's several repo names grouped in one tap and one-off jobs kept as tasks. The Overview leads with what needs you: one-tap answers to agents' questions and your approvals. Every job and agent opens in a deep-linkable drawer with owner actions (retry or move a step, retry or cancel a job, update an agent's tool). Command palette (⌘K), keyboard shortcuts (g o, g w, ?), working Back and Forward, toasts with Undo, dark and light themes, a bottom bar and sub-tabs on phones, and an optional password lock for the whole dashboarddocs/guide.md
OperationsSetup page with a first-run checklist (keys, decision order, credentials, features) · model presets: with one provider key, planning, knowledge-base summaries and preference extraction just work (Haiku with an Anthropic key), summaries cached by content · Message Batches (half price) for curated imports and benchmarks · commons setup connects 17 AI clients in one command and commons doctor --repair fixes a broken connection, and every session start checks that Commons is still registered as the AI's MCP server and puts it back if not (Claude Code gets the key from a headers helper, so no config file holds it) · dashboard (30 pages, live updates) · tokens per agent, model and effort read from each agent's own records (Claude Code transcripts including subagents, the peers' bridge jobs: input, output, thinking, cache), so subscription work shows up, not only what agents remember to report · usage and cost by agent/model/project, projects grouped as on the Projects page · kill switch · backups, retention, dump/restore · Postgres + pgvector · SQLCipher · OpenTelemetry · Dockerdocs/networking.md

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.

FeatureWithout it → with itmem0claude-memMemPalaceArchify
Hybrid search + neighbouring turns (short hits) + date resolutionLoCoMo QA 69.5% → 78.7%; LongMemEval QA unchanged by neighbours (65% either way, where giving them to every hit costs points)70.3% on the same LoCoMo run (paired p = 1e-11)¹· no recall benchmarkLoCoMo dialog recall 0.545 vs Commons 0.708 (its metric)·
Indexed searchp50 at 30k memories 1,383 ms → 68 ms———·
Redesigned dashboardanswer, approve, retry, move or cancel from the page you are on instead of hunting across 32 tabs; every page works on a phone (not benchmarked)————
Lean tool listtool schemas per session 39.7k → 6.3k tokens (−84%)——45 MCP tools·
Verbatim capture hooks + turn() for chat appsnothing said is lost to an agent's own summary; Claude Code, Codex, Gemini, Cursor, any chat app◐✓ (8+ harnesses)✓ (3 clients)·
Project boardyour asks survive compaction and agent switches; asked-twice is counted····
No duplicate work (start_work, automatic claims)two agents never build the same thing; on a live hub 1 agent session in 10 claimed its work and the wake services none → every session's first message opens its claim and every woken subtask is claimed before the agent starts; Jev closes a session's claim as done or dropped from its last message··✓ claim protocol·
Work splitting (model, live agent or rules plan it; split_subtask)big jobs run in parallel across agents by strength and usage left; live run: 3 jobs, 4 agents (not benchmarked for speed)··✓ task delegation (no planner)·
API seats (your own keys, by tier)when every subscription agent is busy, offline or out of usage, steps that need no repo (specs, plans, reviews, research, summaries) still run on a cheap, mid or top model from your key, picked per step; stops at your 24-hour dollar cap (off by default)····
Six-stage workflow (/spec /plan /build /test /review /ship)an idea goes through spec, plan, build, verify, cross-family review and ship with you approving the spec and the release; leads split work into task cards, each routed to a cheap, mid or top model by difficulty x criticality; build and verify need evidence; every acceptance criterion traced to its tests and verdicts; a failed check stops the checks after it; Workflow page draws it all (token savings measured per job, not benchmarked)··◐ task delegation, no stages·
Infrastructure mapwhere a service runs, how it is reached, what it mounts and which credential it uses, scattered across hundreds of notes → one answer from infra(name); on a live Proxmox host the collector found 18 guests, 49 services, 38 endpoints and 43 mounts in about a minute, read-only···◐ code architecture only
Re-filing misfiled notesimported notes keep the old tool's folder label (2,200 Poise notes under soul-pool on a live hub) → a model proposes where each belongs, grouped per move, applied with Undo; live-captured notes are never touched····
Project pages + grouped namesa live hub's 125 raw project names (folders, worktrees, one product under 6 names) in a filter dropdown, no project page → one page per product with its timeline, diffs, memory and people; one-offs kept as tasks◐ filter by app/user◐ project filter, no page◐ wings and rooms◐ repo diagrams
Job workspace + recorded diffsevery part's result, diff and GitHub-checked commit in one place; reviewers get the diff·◐ file paths only✓ patch submit·
Credential vault + decision agent + owner approvalsagents never see keys; reads allowed, writes need your ask, the rest is one approval link only you can approve (owner password), and approving runs it; with approve-everything on, Jev still screens every call (a live hub had judged none for 23 days); a key with line breaks is refused and error texts are scrubbed····
Row-level access + chained audit log + signed exportone record limited to named agents; the live log and its exports are tamper-evident and verifiable◐ scoping by ids◐ private tags, unsigned log◐ checksummed, unsigned·
Shared skill poolany model loads a skill with nothing installed; skill_help when it can't run one◐ own skills·◐ own skills·
Messaging + instant wake + askdaemon agents start within seconds of new work; a question is send, wait for a poll, reply, poll again (the Grok bot's median answer took 3.5 hours) → ask(to, question) returns the answer in the same call when the agent can be woken, and the wake service sends the agent's final output back if it forgot to reply (not benchmarked)·◐✓·
Knowledge base per projectcited digest per project, rebuilt as memory changes✓✓◐ no summaries·
Code graph + diagramscall graphs, sequence, workflow, lifecycle and architecture diffs from the real index··◐✓
Contradiction flags (TypeSafe)conflicting notes flagged: precision 1.00, recall 0.97 on 96 pairs; durable notes only (on a live hub 242 of 278 open flags came from captured chat turns), with a same-subject check———·
Cost controlsMessage Batches −50% on imports and benchmarks; prompt caching (cached input ~10% price); KB summaries cached by content——n/a (no LLM on write)n/a

¹ 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

mermaid
flowchart LR  subgraph Agents    A1[Claude Code / Desktop] -->|stdio MCP| HUB    A2[Cursor · Codex · Gemini] -->|stdio MCP| HUB    A3[ChatGPT · Grok · Muse · custom] -->|HTTP MCP + key| HUB    W[commons worker / agent daemon] -->|claim · heartbeat · complete| HUB  end  subgraph HUB[Commons hub · commons serve]    MCP[MCP tools · aliases · ACLs · rate limit] --> RED[Secret redaction on every write]    RED --> DB[(SQLite or Postgres<br/>memory · graph · KB · sessions<br/>jobs · messages · skills · audit)]    ORC[Orchestrator<br/>DAG · gates · leases · routing · escalation] --> DB    MSG[Messaging · presence · wake] --> DB    BRK[Secret broker<br/>env:// vault:// op:// infisical://] -.leases.-> DB    HUBX[MCP hub → upstream servers]    BG[Background: KB · librarian · reaper · backups]  end  HUB --> DASH[Dashboard :8766]  MSG -->|webhook · ntfy · SSE/WS| A3

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/mcp and 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:

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

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.

[Overview]
Overview: what needs you first (one-tap answers, approvals), then spend, running jobs, the team and activity		[Jobs cockpit]
Jobs: every job with live filters; a job opens in a drawer with its stage spine, steps, routing and owner actions
[Agents]
Agents: the fleet, what each is doing, its models, quota and tool version; click for the agent drawer		[On a phone]
On a phone: every page works at 390 px, with a bottom bar and sub-tabs
[Board]
Board (light theme): what you asked, targets and deliveries, with one-click Done and Undo		[Usage]
Usage: spend and tokens per day by agent, 7 to 30 days
[Memory]
Memory: search first, filter chips, drawers, bulk actions		[Connect an agent]
Connect an AI: one join link; a terminal line, a sentence for a bot, or a connector address, and each AI appears as it joins
[Knowledge base]
Knowledge: an auto-built, cited knowledge base per project		[Graph]
Graph: memory, code, sessions and agents in one graph
[Mission control]
Mission control: fair-share scheduling and agent load against capacity		[A project]
A project: everything about one product in one place: active work, timeline, diffs, memory and who did what
[Infrastructure]
Infrastructure: where everything runs: capacity and every guest's allocation, then a zoomable map, the graph and a drawer per thing

Multi-agent in 5 commands

sh
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 + profilecommons connect muse --expertise writing:0.9,review:0.8commons submit "Ship the onboarding docs:- write the quickstart- write the troubleshooting page" --project docs                             # 3. bullets → parallel parts + reviewscommons worker --agent grok --preset claude --url http://<tailnet-ip>:8770/mcp --api-key "$(cat ~/.commons/agents/grok.key)" &   # 4. headless seatscommons status                                                                  # 5. or the dashboard's Mission control

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):
    sh
    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

Configuration

Everything works with defaults. These are the settings people usually change:

VariableDefaultPurpose
COMMONS_DB~/.commons/commons.dbSQLite path or postgresql://…
COMMONS_REQUIRE_KEYS1HTTP requires keys (0 = local dev only)
COMMONS_DASHBOARD_TOKEN—Dashboard admin token; required only on public addresses
COMMONS_DASHBOARD_REQUIRE_TOKEN—1 = require the token even on localhost/LAN/tailnet
COMMONS_RATE_PER_MIN600Per-agent HTTP rate limit
COMMONS_ADMIN_AGENTS—Agents with global admin rights
COMMONS_EMBEDDERhashfastembed for real embeddings
COMMONS_DAILY_COST_CAP—USD/day cap for orchestrated work
COMMONS_ESCALATE_AFTER900Seconds before stuck work escalates
COMMONS_LEASE_SECONDS900Subtask lease length
COMMONS_WEBHOOK_ALLOWLIST—Private or non-https wake/webhook hosts you trust
COMMONS_DB_KEY—SQLCipher encryption key (as a secret ref)
COMMONS_BACKGROUNDlightIn-process maintenance (full, 0)

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

SymptomFix
address already in useAnother service owns the port. Use --port 8770 (and update client URLs).
401 UnauthorizedSend Authorization: Bearer <agent key>. Keys live in ~/.commons/agents/<name>.key, and commons connect NAME re-keys.
429 Too Many RequestsRespect Retry-After, or raise COMMONS_RATE_PER_MIN.
Dashboard unreachable from another machineBind it to that interface (--host / --dashboard-host). On LAN/tailnet no token is needed. On a public address, set COMMONS_DASHBOARD_TOKEN and open http://<host>:8766/?token=…
Agent shows offline / never gets workMake an authenticated call or commons agent daemon. Add a wake channel with commons wake add AGENT webhook url=…
Subtask stuck in claimedThe worker died. The lease expires (COMMONS_LEASE_SECONDS), then the subtask is reassigned to another agent. Run commons escalate to force it.
skill … has no approved versionAnother agent (or you) must skill_review it. Authors can't self-approve.
admin rights requiredBe a project admin, be listed in COMMONS_ADMIN_AGENTS, or be the project's sole author.
commons: command not found after installAdd ~/.local/bin to PATH (Windows: %USERPROFILE%\.local\bin).
Unknown-argument error from a toolThe error lists the accepted names and aliases.

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.

WhatMetricCommons
LoCoMo retrieval, 1,982 questionsevidence-turn any@1 / @1039.4% / 76.5% (v0.8: 31.2 / 71.1); reproduced on v0.21.1, results
LoCoMo retrievalevidence-session any@1097.4% (v0.8: 95.8)
LoCoMo end-to-end QA, 1,540 questions (cat 1-4)LLM-judged accuracy, Haiku 4.5 reader + judge, k=2078.7% with context=2 (short hits, v0.28) and date resolution (78.5% when every hit gets neighbours, 69.5% for hits alone); no LLM at write time
LongMemEval-S end-to-end QA, seeded 100 questionssame reader, judge and k65% on v0.28 (67% on v0.20.1, run-to-run noise of a few points; v0.9: 62%). Since v0.28 neighbouring turns go only to short hits, so they no longer cost points on its long sessions (65% with or without them; 54.0% when every hit gets them)
Search latency, 30k / 60k memoriesp5068 ms / 114 ms (v0.8: 1,383 ms at 30k)
Tool schema an AI pays for each sessiontokens, exact (Anthropic tokenizer, minus a one-tool baseline)6,072 for the 32 core tools in v0.30; listing all 186 would cost 40,382
Self-check on your own data (commons bench self)known-item hit@1 / @593% / 100% on a 166-memory sample

Head-to-head, rivals run here on the same LoCoMo data (details in benchmarks/README.md):

vsSame metricCommonsRival
mem0 OSSQA accuracy, same reader/judge/prompts, 1,540 q78.8%70.3% (paired: Commons alone right 232x, mem0 alone 107x, p = 1e-11)
mem0 OSSper category: multi-hop / temporal / inference / single-hop64.2 / 77.3 / 43.8 / 88.261.0 / 73.8 / 37.5 / 76.2
mem0 OSSsearch p50 / LLM calls per write24-68 ms / none377 ms / extraction on every write
MemPalaceits own recall metric, dialog / session top-100.708 / 0.9450.545 / 0.889
claude-mem 13.36same metric, dialog / session top-100.708 / 0.9450.496 / 0.811 (search p50 2.7 s)
claude-mem 13.36footprint at rest43 MB RSS, 0.1% CPU with 5,761 memories (185 MB once the embedder loads)its chroma-mcp process sat at ~39% CPU on the same Mac

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

ProjectGreat atCommons' angle
mem0 / OpenMemoryFact extraction, cross-client memoryHigher LoCoMo QA in every category (78.8% vs 70.3%, same reader and judge) with no LLM on the write path, plus a code graph, handoffs, a project board, orchestration and secrets; commons import mem0 brings your memories over
claude-memAutomatic capture across 8+ agent harnessesThe same capture shared by every agent, plus orchestration, a vault, a board and a job workspace; commons import claude-mem --curate imports and cleans its history
MemPalaceVerbatim recall, retrieval benchmarks, logstream task coordinationHigher LoCoMo recall under MemPalace's own metric (0.708 vs 0.545 dialog-level); both coordinate agents (claims, diffs, wake), and Commons adds model-planned work splitting, a credential vault, a project board, row-level access and signed audit exports
ArchifyValidated, interactive architecture diagramsDiagrams come from the real code index and history: code graph with source links pinned to the indexed commit, call and multi-agent sequence diagrams, job workflows, lifecycle state machines with real transition counts, and an architecture diff between any two snapshots, plus communities, impact paths and a cluster map
Graphiti / ZepTemporal knowledge graphInspired Commons' conflict and supersede model
CogneeRich document graphsCommons is a lighter single-file hub
basic-memoryHuman-readable Markdown memoryCommons has Obsidian/Markdown export
A2AAgent-to-agent protocolCommons ships an A2A server and client
Agent buses / chat bridgesMessagingCommons adds a shared mailbox, presence and wake, plus a bus-compatible shim

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

sh
git clone https://github.com/Neoo-Blue/commons-memory && cd commons-memoryuv venv && uv pip install -e ".[dev,all]" && uv run pytest -qpython scripts/gen_env_reference.py      # after adding a COMMONS_* settingscripts/release-local.sh v0.37.1         # after pushing a tag: build on your own box, publish the GitHub release

MIT licensed.

Source: README.md at commit 62d1ecb

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

7
  1. v0.37.1LatestNov 7, 2026
  2. v0.36.1Oct 18, 2026
  3. v0.36.0Oct 18, 2026
  4. v0.34.1Oct 17, 2026
  5. v0.34.0Oct 17, 2026
  6. v0.33.1Oct 16, 2026
  7. v0.33.0Oct 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

Other Memory integrations

Memory.fit

fit.memoryOfficial publisher

Hosted Memory.fit server that lets an AI read your training, sleep, recovery and nutrition data and write back weekly plans, targets and meal plans.

Streamable HTTPWeb executableAuth
Location & LifestyleCredential requiredOct 29, 2026

pg.ddx.io: the PostgreSQL community's memory

io.ddx.pgOfficial publisher

pg.ddx.io: the PostgreSQL community's memory's hosted MCP server, published by pg.ddx.io; no sign-in required; Streamable HTTP; 29 tools.

Streamable HTTPWeb executable
Databases29 toolsOct 24, 2026

var.gg Naming Memory

gg.varOfficial publisher

Remote MCP server that suggests and searches code identifier names from domain concepts in Korean, Japanese, Chinese, Vietnamese and English, and exposes ERD…

Streamable HTTPWeb executable
Databases7 toolsOct 27, 2026

Counterparts

ai.counterparts

Local-first long-term memory for Claude Code and Claude Desktop: the assistant writes notes about you and your projects and recalls them in later sessions.

STDIODesktop only
AI & MLNot validated yetNov 7, 2026

LAHZE - Persian AI Memory Platform

Published by GitHub account pedramgholizadeh

LAHZE - Persian AI Memory Platform's hosted MCP server; no sign-in required; Streamable HTTP; 13 tools.

Streamable HTTPWeb executable
Location & Lifestyle13 toolsNov 3, 2026