io.github.magnusmage/cohort-mcp

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

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

What's inside

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/cohort
claude 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.

Client support, step-by-step setup, and the developer path

Which client is this for?

Step by step

1. Open a terminal. Windows: use the terminal inside your client, or Git Bash. Mac: the Terminal app. Linux: your terminal app.
2. Install: paste the curl line above and press Enter. You will see one installed cohort skill to ... line per client.
3. Check it landed (optional): ls ~/.claude/skills/cohort (or ~/.kimi-code/skills/cohort, ~/.zcode/skills/cohort).
4. Start your client in any project folder and load the skill as above.
5. Answer the connector's questions in chat. It creates your vault repo (or links an empty one you made in the browser), then asks when it loads context, when it proposes updates, and what content it reads.

No curl or sh? Download the skill zip from the latest release, unzip it, and upload the cohort folder in your client's skill settings (use the skill zip under Assets, not Source code).

Developer path

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

Register the MCP engine with one command: cohort init --vault <dir> --agent <id>.

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.

• [x] Phase 1: Walking skeleton. Policy engine, record schema, git transport, write gate, and the first four tools.
• [x] Phase 2: Trust and safety spine. Trust tiers, human-only verification, the adversarial suite.
• [x] Phase 3: Session capture and search. Turn session notes into gated drafts; search the vault.
• [x] Phase 4: Adoption bridge. Generate and reabsorb AGENTS.md / CLAUDE.md / Cursor rules; portable export and import.
• [x] 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.