Every project gets a brain.

Active state management for multi-agent coding — a local-first active context engine with a shared brain. One project. One shared understanding.

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

One actively managed project brain for multi-agent coding. klypix-mcp keeps one versioned brain.klypix in your repo: the project's active state — current decisions, corrections, evidence anchors, open questions, active work, and handoffs. Corrections supersede stale decisions, brain_challenge tests proposed decisions against standing rules and reversed approaches, and sessions declare their scope and get warned about same-machine file overlap. Agents read it and write to it over MCP. You read it and correct it in the KLYPIX app.

One project. Many agents. One current understanding.

Real output, not a mockup: both panes run a real MCP client against this server (docs/demo/ — the GIF is re-rendered by CI from a scripted tape, so it can never drift from what the product actually does).

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 is the layer underneath them that 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 the 22 tools, and not the retrieval engine.

---

Quick start

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 lossless .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       lossless .klypix merge driver registered
  verified  ✓ 22 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_of: 2026-03-01 reweights ranking by card lifecycle dates, so corrections made later do not leak backwards.
• Retrieval is local. Lexical by default. If the optional on-device model is installed, brain_ask and search_all_brains use BGE semantic ranking with lexical help for exact identifiers, paths, and versions — still entirely on your machine. The previous cross-encoder is available for experiments with KLYPIX_RERANK=1, but is off by default because it reduced precision and added latency on the frozen human-paraphrase evaluation. Without the embedding model, retrieval degrades cleanly to lexical. npx klypix-mcp install deliberately does not install that model, so a fresh install is lexical.

Bounded semantic-memory runtime

Long-lived MCP and A2A workers use the bounded semantic-memory runtime by default. Models load only when semantic work is requested, native inference is serialized per process, embedding work is split into small batches, and temporary tensors are released after use. Loaded models retire after an idle interval and transparently reload on the next semantic request, so warm queries stay fast without permanently pinning native model memory. These controls change the resource lifecycle only; brain cards, project coordination, and the on-disk brain format are unchanged.

The previous runtime remains available as an emergency rollback. Set KLYPIX_SEMANTIC_MEMORY_MODE=legacy in the MCP server environment and reconnect or restart the host. This restores eager model prewarming and the previous inference path without migrating or deleting brain data. Remove the variable (or set it to bounded) to return to the bounded runtime.

Run the deterministic lifecycle tests with npm run test:memory. For an opt-in real-model soak against a disposable or backed-up brain, set KLYPIX_MEMORY_SOAK_BRAIN to its path and run npm run test:memory:soak.

For process-level attribution, run npx klypix-mcp runtime (or add --json; --watch 30 samples every 30 seconds). It reports KLYPIX workers, supervisors, and legacy launcher overhead separately, excludes the owning IDE/chat application's RAM, redacts command-line secrets, and never opens a brain or terminates a process. Multiple processes under one host are reported as parallel sessions, not called duplicates without an authoritative logical-session receipt.

Project Map: current structure beside project understanding

If the project contains a compatible NetworkX node-link graph.json, agents can ask for bounded code-structure evidence and current brain context in one read-only call:

project_map_context {
  "question": "what owns refresh-token rotation?",
  "graph_path": "graphify-out/graph.json"
}

Use compare_to with another project-relative graph artifact to add exact total node/edge deltas and additions/removals from the two bounded query neighborhoods. Both paths are confined to the declared project root; unsafe source paths are withheld; large or unsupported artifacts are rejected. When a returned brain card names an exact mapped source path, the structured response also includes a review-only evidence-link proposal. It never promotes similarity into truth and never writes graph facts or links into brain.klypix.

Graphify is the first compatible producer. KLYPIX reads artifacts that users generate separately; it does not bundle, install, or run Graphify and does not imply a partnership. A compatible generic graph.json works through the same provider-neutral boundary.

For a reproducible map artifact on every pull request and main-branch push, install the shipped read-only workflow into a Git checkout:

npx klypix-project-map setup-github /path/to/project

The command refuses to overwrite an existing workflow unless --force is explicit. The installed workflow has contents: read, pins every action by commit SHA, pins graphifyy==0.9.33, validates the graph contract, and uploads graphify-out/ as a 14-day build artifact. This is opt-in CI code: the local MCP tool still never installs or launches Graphify.

---

Supported hosts and their integration level

Levels are honest. Only the config-writing side is tested for the link hosts; their host-side behaviour is unverified.

Host	Level	Wired by	Brief into context	Decision capture	Live presence
Claude Code	Full automatic (5 lifecycle hooks)	install	Automatic at session start, task-ranked retrieval per prompt	Automatic at turn end	Yes
Codex	Native MCP + presence + Context Gateway; optional --codex-hooks	install	Via brain_sync; per-prompt injection only with --codex-hooks	Explicit only (brain_note) — never automatic	Yes
Cursor	MCP config + always-on rules file	link	Model must call brain_sync	Model must call brain_note	For the MCP connection
Cline	MCP config + always-on rules file	link	Model must call brain_sync	Model must call brain_note	For the MCP connection
VS Code (Copilot / Continue)	MCP config + instructions file	link	Model must call brain_sync	Model must call brain_note	For the MCP connection
Gemini CLI / Antigravity	MCP config + always-on rules file	link	Model must call brain_sync	Model must call brain_note	For the MCP connection
Windsurf	Rules file only	link	Reaches the tools through Windsurf's own global MCP config	Model must call brain_note	Via its own MCP config
Aider	Rules file only (no MCP)	link	CLI path: npx klypix-read	CLI path: npx klypix-append	—
Claude Desktop	One-time manual config edit	you	Model must call brain_sync	Model must call brain_note	For the MCP connection

install and link are different things and are not interchangeable: install sets up the machine engine and hooks, then wires supported hosts detected for this project (see Quick start). link is the explicit per-project repair/projection path for all 14 managed files, regardless of which hosts are installed.

Claude Desktop — add this to claude_desktop_config.json by hand; nothing writes that file for you:

{
  "mcpServers": {
    "klypix": {
      "command": "npx",
      "args": ["-y", "klypix-mcp", "--vault", "/absolute/path/to/canvases"]
    }
  }
}

---

Task briefing

Every Claude Code session starts already knowing the project: a bounded brief of at most 2KB in context, with the full brief written to disk for when broad history or status work needs it.

Every other host gets a bounded ~2.8KB task capsule from one brain_sync call, plus a compact always-loaded AGENTS.md block that tells the agent to make that call at task start, when scope changes, and on completion. The gateway capsule is lexical-fast by design. A newly captured open gap can claim a labeled RECENT OPEN slot only after clearing the normal lexical-relevance floor, so fresh relevant findings are not crowded out by older area vocabulary.

Briefs are not injected automatically on Cursor, Cline, Copilot, Gemini CLI or Antigravity — there are no lifecycle hooks on those hosts.

Capture and corrections

brain_note accepts structured supporting references and inert verification text:

{
  "text": "Retry failed uploads with a bounded backoff to preserve queued work.",
  "area": "Storage",
  "evidence": [{ "kind": "file", "ref": "src/uploads.mjs:42" }],
  "verify": "node test/uploads.mjs"
}

File references must stay inside the project. The capture records a fingerprint of the working file and, when available, the repository HEAD revision. An unchanged fingerprint means source unchanged, not that the remembered claim is correct or that tests passed. Dirty working files are fingerprinted as they are; HEAD alone does not describe those bytes. Read results distinguish changed, missing, and unverified sources. External references (pr, url, commit, run) are retained without fetching or verifying them. verify is shown as recorded text and never executed. Optional verifiedAt is explicitly caller-reported.

On an amendment (marker: "~"), omitted metadata is preserved; evidence: [] and verify: "" clear obsolete metadata. A resolve (✓) archives existing evidence; attach new evidence with a milestone and closes, or amend before resolving. The CLI accepts the same JSON on stdin, or --evidence '<JSON array>' and --verify '<text>'.

On Claude Code, decisions are captured automatically at turn end from inline 🧠 BRAIN [Area]: markers in the transcript, deduped, under a capture lock.

On every other host, capture is explicit: brain_note runs the same capture engine as the hooks — dedup, supersession, round-trip re-adoption receipts, ✓ resolve, ~ update in place, + skill, closes: — and stamps which agent wrote the card. A ✓ question preference ranks only candidates that already clear raw lexical overlap and two subject-identity anchors; generic lifecycle wording cannot turn weak overlap into a closure. (If you install the git commit hook from the KLYPIX app or run npx klypix-mcp git-hook install, commit messages also capture automatically for any agent.)

brain_challenge is the other direction: propose a decision and the brain answers with receipts — prior decisions that deterministically contradict it, standing rules that dispute it, and approaches tried and reversed, flagged when a different agent wrote them. Evidence is deterministic only (explicit correction cues, opposite-polarity pairs), never mere topical similarity. Silence means no contradiction signal was found — not verified consistency. A memory that cannot disagree with you is flattery.

Presence and task intent

An active session means an authorized MCP connection or host lifecycle adapter that heartbeated within the TTL. A row in a recent-chat list is history, not presence.

Each MCP connection registers itself at initialization and removes itself on disconnect; the TTL covers crashes. Optional host adapters merge into that same logical session rather than double-counting it, enrich it with intent and files, and remove only their own channel. Sessions that never declared a task are still counted, but are shown separately as scope-unknown rather than padding the peer list.

Future hosts get baseline support merely by connecting the MCP server. A deeper adapter can import klypix-mcp/presence and map lifecycle events onto upsertSession, removeSession, peekMessages and receiveMessages. The shared contract accepts id, client, surface, model, branch, intent, touched files, and adapter channel.

Overlap warnings

When two sessions declare overlapping expected files, brain_sync surfaces it: the peer, its declared task, and the exact paths in common. A one-time alert is queued to whichever session got there first, so a late arrival is not the only one who knows.

This warns. It does not prevent. Nothing blocks an edit, matching is exact-path, and both sides have to have declared their files for the overlap to be visible at all.

Handoffs and messages

brain_message leaves one-time coordination notes for other sessions. A supported KLYPIX action offers the note in model-visible context; the next independent supported action replays it and records an acknowledgement. That acknowledgement proves only that a later action followed the offer — never that a person read it or that an agent acted on it. The note keeps replaying until the receiving model calls brain_message_receipt with the exact message id and per-recipient offer token; only that token-bound action records consumed. Pending, offered, and acknowledged notes survive reconnects. Expiry or bounded-capacity eviction records a failed per-recipient receipt instead of silently looking delivered. The send-time audience is fixed, unresolved targeted sends fail closed, the core lane is machine-local, notes expire after 24 hours, and they are never written into the brain.

Durable handoffs go in the brain itself — decisions, findings, open questions and skills captured as cards, each stamped with the agent that wrote it.

Evidence-gated completion