Cohort Mcp

[Cohort: shared memory for your team's AI]

[License: Apache-2.0] [Docs: CC BY 4.0] [CI] [Release] [Roadmap: Phases 1 to 5 shipped]

One markdown vault on GitHub. Every teammate's AI reads and writes the same memory,
regardless of account, plan, or platform, and a human approves every change.

Quickstart · How it works · What's inside · The engine · Security · Full docs

Why Cohort

Your team's AI assistants each start every session blank. What one teammate's assistant learned (the decision you made, the fact you pinned, the thread you left open) is invisible to everyone else's. Paste the same context again and again, or lose it.

Cohort gives the team one shared memory. A single git repository holds your facts, decisions, and open threads in plain markdown. Each teammate's AI reads a bounded slice at the start of a session and proposes updates at the end, and a human approves every change before it lands. There is no hosted server and no account with us: the repo is the product, and it lives in your own GitHub.

How it works

[Teammates' AI clients load bounded context from a shared git vault and propose writebacks back through a local redaction gate, human approval, and a review-gated pull request.]

1. Load. At session start, your AI pulls a bounded, verified-first slice of the vault, fenced as data and never as instructions.
2. Propose. At session end, it proposes new records. Every write passes a local gate (secret and PII scan, injection linter, contradiction check) and is held for a human.
3. Approve. A human verifies the record from the terminal. Only then does it become trusted memory. Git is the only transport, and the vault stays yours.

See it

[A terminal session: an AI client loads verified-first context under a token budget, a teammate proposes a fact that is held for human approval as a pull request, and a human verifies and inspects the record from the command line.]

What's inside

[Cohort has two parts: the engine (the cohort-mcp server, its tools, the write gate, and the CLI) and the retrieval and review intelligence that makes up the moat. Both run fully on your own machine with no hosted service.]

The vault, the engine, and the moat are free and open under Apache-2.0 and run fully on your own machine. Cohort runs entirely against your own GitHub repo: the maintainers never receive your vault, your sessions, or any telemetry. Cohort reads and writes your vault locally, under your control, with a human approving every write, and that processing happens on your machine, not ours.

The engine

cohort-mcp is a local stdio Model Context Protocol server, the client-neutral engine any MCP client can run. It loads bounded, fenced context and runs human-approved writebacks through a server-enforced gate.

Some actions are human-run on the terminal by design, so the model can propose and read but never promote or retire a record:

The engine and CLI live in cohort-mcp/. It is published to npm as cohort-mcp and listed in the MCP Registry as io.github.magnusmage/cohort-mcp, so you can run it in one command:

claude mcp add cohort -- npx -y cohort-mcp     # register with Claude Code# or just run it: npx -y cohort-mcp

For Claude Desktop there is a one-click extension: build a .mcpb from desktop-extension/ and double-click it to install. Or add this repo as a plugin marketplace and install the bundled plugin:

claude plugin marketplace add magnusmage/cohortclaude plugin install cohort@cohort

Quickstart

Cohort runs inside an AI client that can reach your disk and git: Kimi Code CLI, Kimi Work desktop, ZCode, or Claude Code (CLI, desktop, or IDE extension). A web chat with no disk access cannot run it.

Install the connector (under a minute):

curl -fsSL https://raw.githubusercontent.com/magnusmage/cohort/v0.3.0/install.sh | sh

The installer verifies the release checksum, then copies the connector skill into each client's skill folder on your machine. Prefer to read it first? Run curl -fsSLO .../install.sh, read it, then sh install.sh.

Then, in your client's chat input (not the terminal): type /cohort (/skill:cohort in Kimi Code CLI; the / Skills menu in Kimi Work desktop), or just say "set up my team vault". The connector explains what it does with your data and waits for your yes, walks you through GitHub sign-in and vault creation, and asks three consent choices. Every step waits for you.

git clone https://github.com/magnusmage/cohort.gitsh cohort/scripts/setup.sh                              # seed a vault, ask consent, install the redaction hookcp -R cohort/connectors/claude ~/.claude/skills/cohort  # or connectors/kimi, connectors/zcode

Daily use

Roadmap

Phases 1 to 5 are built, tested, and shipped on main. They are the whole product: the vault, the engine, and the moat, all running on your own machine.

• Phase 1: Walking skeleton. Policy engine, record schema, git transport, write gate, and the first four tools.
• Phase 2: Trust and safety spine. Trust tiers, human-only verification, the adversarial suite.
• Phase 3: Session capture and search. Turn session notes into gated drafts; search the vault.
• Phase 4: Adoption bridge. Generate and reabsorb AGENTS.md / CLAUDE.md / Cursor rules; portable export and import.
• Phase 5: The moat. Git-native index, token-budgeted verified-first retrieval, contradiction detection, staleness and supersession, deterministic merge, and cohort_why.
• Phase 6: Enterprise (in progress, parked). A review and audit dashboard with SSO, plus multi-vault access, at-rest encryption, and retention. It is intentionally not part of the released product and is kept on the phase-6-control-plane branch. If released later, the dashboard will be optional and run on your own infrastructure with its own privacy statement; the maintainers still never receive your data.

The full plan lives in docs/planning.

Security

Cohort is shared memory that many agents read and write, so the memory itself is an attack surface: a poisoned record could read back as an instruction to another teammate's agent. The project treats security as a property of every change. Stored memory and the model are untrusted; only approved, scanned writes land; loaded memory is fenced as data, never instructions; a contradicting fact is held for a human instead of overriding a verified one; and the server is the only component that ever commits. There is no telemetry and no network call beyond your own git remote, so the maintainers never receive your vault, your sessions, or anything else.

See the security model for the threat model, the redaction rules, and the consent model. Found a vulnerability? Please report it privately through GitHub's private vulnerability reporting on this repository, not as a public issue.

Where to read more

• Cohort, explained: the loop, every command, the consent choices, the security model in one page
• The spec: architecture, vault schema, connector contract
• The security model: threat model, redaction rules, consent model
• Ten-minute walkthrough
• Who it is for and honest limits
• Decision records and release history

Repository layout

├── cohort-mcp/          The MCP server and CLI: the engine and the moat├── connectors/          Kimi, ZCode, and Claude connectors (Agent Skills standard)├── vault-template/      Blank vault scaffold (copied into your own repo)├── example-vault/       Synthetic demo vault (CC0, all content fictional)├── scripts/             Setup wizard and vault validator├── security/            Versioned gitleaks redaction rules├── install.sh           Pinned-tag installer for the connector skill└── docs/                The public spec, decision records, and diagrams

Contributing

See CONTRIBUTING.md. Commits use Conventional Commits and DCO sign-off (git commit -s). Security issues: please report privately via GitHub private vulnerability reporting, not public issues.

License and authorship

Apache-2.0 for code, CC BY 4.0 for docs, CC0 for example vault content. Created and maintained by Sarmad. See CITATION.cff for citation metadata.