commons-memory

# Commons

<!-- mcp-name: io.github.Neoo-Blue/commons-memory -->

**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](https://docs.astral.sh/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 off
claude-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](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](docs/img/dashboard-overview.png)

```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](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](#2-minute-quickstart) · [Feature tour](#feature-tour) · [Architecture](#architecture) · [Connect any AI](#connect-any-ai) · [Screenshots](#screenshots) · [Multi-agent](#multi-agent-in-5-commands) · [Security](#security-model) · [Networking](#networking) · [Configuration](#configuration) · [Troubleshooting](#troubleshooting) · [FAQ](#faq) · [Comparison](#comparison) · [Roadmap](#roadmap) · [Changelog](CHANGELOG.md)

## 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](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. **Connect** each AI with one command (`commons setup ...`; the page builds it with a checkbox per step).
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 config
commons 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 shop
commons 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](#connect-any-ai).

## Feature tour
| Area | What you get | Learn more |
|---|---|---|
| **Infrastructure map** | One 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](docs/guide.md#infrastructure-map) |
| **Memory & knowledge** | Hybrid 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](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](docs/tools.md) |
| **Project board** | Every 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 them | [docs/tools.md](docs/tools.md) |
| **No duplicate work** | `start_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 it | [PROMPT.md](PROMPT.md) |
| **Credential vault** | Commons 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 | [CHANGELOG.md](CHANGELOG.md) |
| **Team awareness** | A live Team now view (who is working, blocked, done or waiting on you) · 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 agent | [CHANGELOG.md](CHANGELOG.md) |
| **Continuity** | Sessions, 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 jobs | [docs/guide.md](docs/guide.md) |
| **Teamwork** | Submit 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 lev