Every project gets a brain.

Shared project memory for Claude Code, Codex, Cursor and other MCP coding tools. One brain.klypix file, committed with your code, carries the project's decisions, corrections and open questions across sessions and between tools. Corrections supersede stale decisions; sessions declare the files they expect to touch and get warned about same-machine overlap. Versioned in Git. Served over MCP by a process on your machine; Klypix uploads nothing (your agent's provider still receives what the agent reads). Integration depth differs by host — see Supported hosts.

_{Real output, not a mockup: both panes run a real MCP client against this server (docs/demo/ — the GIF is rendered by CI from a scripted tape against this server, not hand-recorded, and re-rendered when the server's responses change).}

Run this inside your project:

npx klypix-mcp install

It creates brain.klypix if the project has none, wires the editors it finds on this machine, registers the .klypix merge driver if this is a git repo, and exits only after a real MCP handshake has counted the tools that answered.

_{Host badges name the integration level, not a flat "compatible" — the levels and what is actually tested are in Supported hosts.}

One project. Many agents. One current understanding.

Klypix does not launch, run, supervise, or replace your agents. It is not an agent runtime, a model router, a worktree manager, or a replacement for Git. It holds what the project currently believes.

See the shared project brain in action

Watch how current decisions, corrections, evidence, and active work stay visible to people and carry forward into supported coding-agent sessions.

Watch the 2:21 showcase with sound

---

The problem

You are running more than one coding agent on one codebase — a Claude Code session here, Codex in another terminal, Cursor open on the side. Each one has excellent memory of itself and none of the others:

• Every new session starts from zero, and you explain the same architecture again.
• Codex does not know what Claude learned an hour ago.
• One agent implements an approach the team already rejected, because the reason it was rejected lived in a chat that ended.
• Two sessions start changing the same files and nobody finds out until review.
• Git stores the code history. It does not store a reliable history of project intent.

Your agents may run independently. Their project understanding should not.

---

60 seconds: two agents, one project

Session A — Claude Code, in your repo:

brain_sync { intent: "rewrite the auth token refresh", files: ["src/auth/token.ts"] }
// → task-relevant memory capsule (bounded, ~2.8KB)
// → peers: none

Session B — Codex, same repo, half a minute later:

brain_sync { intent: "add rate limiting to the auth routes",
             files: ["src/auth/token.ts", "src/auth/routes.ts"] }
// → task capsule
// → peers: 1 active session (claude-code) — "rewrite the auth token refresh"
// → overlap: src/auth/token.ts — declared by both sessions

Session A gets the same overlap surfaced on its next KLYPIX action. Neither edit is blocked — the warning is advisory, and both sides only see the overlap because both declared the files they expected to touch.

Then the brain pushes back before the decision, not after:

brain_challenge { "move token storage to localStorage" }
// → "reversed on June 12 — here's the correction card, captured by a different agent."

And the decision is kept where the next session will find it:

brain_note { text: "Token refresh moves to an httpOnly cookie; localStorage was reversed 2026-06-12." }

Prove all of this on your own machine, against the exact build you installed, with two real isolated MCP clients:

npx klypix-mcp conformance

It runs in a temporary fixture and touches nothing else. It checks tool discovery, task memory, truthful peer reporting, overlap surfacing, proactive logging, and in-band delivery of a peer note. It verifies 15 required coordination behaviours — not every tool, and not the retrieval engine.

---

Quick start

You need Node.js 20 or newer (node -v to check). Every way of connecting runs the server with node — npx, the installed bundle, and the entry KLYPIX's Settings buttons write — and none of them checks for Node first.

Run this inside your project:

npx klypix-mcp install

One command for supported editors detected on this machine. It finds the project root (walking up, so running it from src/ is fine), gives the project a brain if it doesn't have one, wires the agent tools you actually have installed, registers the card-level .klypix merge driver if it's a git repo, and then proves the result before it exits:

  project   E:\work\api  (git repository root)
  brain     created brain.klypix — a starter brain, ready for its first decision
  editors   Claude Code · Cursor · Codex · Gemini CLI · Antigravity · VS Code
  wired     9 file(s) · 9 updated   (skipped 5 for tools you don't have)
  git       .klypix merge driver registered
  verified  ✓ 25 tools reachable via .mcp.json (892ms)

That last line is the point. MCP config fails silently — a wrong entry means the server never starts, the agent quietly loses every brain verb, and nothing reports an error. So install opens a real stdio handshake against the config it just wrote and counts the tools that answered. A broken entry dies in ~100ms with Connection closed and is reported, not shipped.

What goes where:

• Machine-global, once — the engine + runtime in ~/.claude/project-brain, Claude Code's five lifecycle hooks in ~/.claude/settings.json, and the ~/.codex/AGENTS.md guidance block. Claude Code is therefore covered in every project on that machine that has a ./brain.klypix.
• Per project — MCP config and rules for Cursor, Codex, Cline, Windsurf, Copilot, Gemini CLI / Antigravity and Aider. Run install once inside each project.

Three things it deliberately will not do:

• Write for editors you don't have. Config is projected only for hosts detected on this machine — a two-person team using one editor no longer commits rules for six they never opened. A file your project already carries stays maintained regardless, so you can't silently stop updating your team's committed configs.
• Wire a directory that isn't a project. It refuses your home folder, a drive root, and anything with no brain, no git repo and no project manifest. A mistyped command can't seed a brain into C:\Users\you.
• Replace a project-owned server. A repo-relative launch like node scripts/klypix-mcp-server.mjs is deliberate — it resolves offline and rides a bundle the repo version-gates — so it's left byte-identical and reported. An explicit link still rewrites everything: an action you didn't ask for stays more conservative than one you did.

Opt out with --no-project (CI images, scripted provisioning). --json emits the report as structured data; --verify-all handshakes every written config instead of one.

Optional, opt-in, and approved inside Codex itself:

npx klypix-mcp install --codex-hooks

Six Codex lifecycle hooks that add automatic per-prompt context injection and a pre-edit file-overlap warning. Codex owns the trust decision and will ask you to review them. brain_doctor reports this layer separately as off, execution-unverified, or active. Even with it on, Codex never captures decisions automatically — the Codex hook never writes the brain.

Re-project everything explicitly:

npx klypix-mcp link

install already does this for the editors you have. Reach for link when you want all 14 managed, hash-stamped files regardless of what's installed — MCP server config for six hosts plus rules files for eight — or to repair drift. Managed blocks are merged into your existing instruction files and never clobber your content.

npx klypix-mcp link --check    # audits without writing; exits non-zero on drift

Either form works, and both are safe in CI: npx -p klypix-mcp klypix-link --check used to drop --check and write anyway — fixed, and locked by test/cli-args.mjs, which asserts the standalone bin and the dispatcher parse arguments identically.

Give a project a brain by dropping a brain.klypix into it — the KLYPIX app does it in one click (Save canvas as project brain), or create_canvas makes one from any agent.

---

How the brain works

The difference from a folder of notes is not the shape — it is that this memory is a mechanism, not a filing convention.

• Decisions have a lifecycle. A new decision that contradicts an old one supersedes it. The stale card is archived with an arrow and a date, never deleted, and later answers surface the correction rather than the corpse. If a later decision returns to an earlier superseded stance, high-confidence lineage leaves a dated re-adopts stamp on the new card plus an earlier→current edge; the original A→B→C history remains intact.
• Corrections are explicit, not guessed. Supersession fires on an UPPERCASE correction cue or an explicit edge. brain_reconcile only proposes stale-vs-correction pairs for a human to confirm.
• Cards can cite the code they were decided against. An ev: anchor records a file:line plus the git blob OID at capture time, so the engine can flag a card whose cited code has since moved on. It detects that the code changed — never that the claim became false.
• Position means something. Drag a card into the 📌 Focus area and it leads every future session's brief. That is brief priority, not a retrieval-ranking boost.
• You can ask what the project believed then. brain_ask with `as