{
"markdown": "# Every project gets a brain.\n\n**Active state management for multi-agent coding — a local-first active context engine with a shared brain.**\n*One project. One shared understanding.*\n\n[](https://github.com/dahshanlabs/klypix-mcp/actions/workflows/ci.yml)\n[](https://www.npmjs.com/package/klypix-mcp)\n[](LICENSE)\n[](package.json)\n[](https://modelcontextprotocol.io)\n[](BENCHMARKS.md)\n\n[](#supported-hosts-and-their-integration-level)\n[](#supported-hosts-and-their-integration-level)\n[](#supported-hosts-and-their-integration-level)\n[](#supported-hosts-and-their-integration-level)\n\nHost badges name the **integration level**, not a flat \"compatible\" — the levels and what is\nactually tested are in [Supported hosts](#supported-hosts-and-their-integration-level).\n\n**One actively managed project brain for multi-agent coding.** `klypix-mcp` keeps one versioned\n`brain.klypix` in your repo: the project's active state — current decisions, corrections, evidence\nanchors, open questions, active work, and handoffs. Corrections supersede stale decisions,\n`brain_challenge` tests proposed decisions against standing rules and reversed approaches, and\nsessions declare their scope and get warned about same-machine file overlap. Agents read it and\nwrite to it over MCP. You read it and correct it in the [KLYPIX app](https://klypix.com).\n\n> **One project. Many agents. One current understanding.**\n\n\n\nReal output, not a mockup: both panes run a real MCP client against this server\n([docs/demo/](docs/demo/) — the GIF is re-rendered by CI from a scripted tape, so it can never\ndrift from what the product actually does).\n\nKlypix does not launch, run, supervise, or replace your agents. It is not an agent runtime, a model\nrouter, a worktree manager, or a replacement for Git. It is the layer underneath them that holds\nwhat the project currently believes.\n\n## See the shared project brain in action\n\n[](https://klypix.com/developers#demo)\n\nWatch how current decisions, corrections, evidence, and active work stay visible to people and\ncarry forward into supported coding-agent sessions.\n\n**[Watch the 2:21 showcase with sound](https://klypix.com/developers#demo)**\n\n---\n\n## The problem\n\nYou are running more than one coding agent on one codebase — a Claude Code session here, Codex in\nanother terminal, Cursor open on the side. Each one has excellent memory of *itself* and none of\nthe others:\n\n- Every new session starts from zero, and you explain the same architecture again.\n- Codex does not know what Claude learned an hour ago.\n- One agent implements an approach the team already rejected, because the reason it was rejected\n lived in a chat that ended.\n- Two sessions start changing the same files and nobody finds out until review.\n- Git stores the code history. It does not store a reliable history of project *intent*.\n\nYour agents may run independently. Their project understanding should not.\n\n---\n\n## 60 seconds: two agents, one project\n\nSession A — Claude Code, in your repo:\n\n```jsonc\nbrain_sync { intent: \"rewrite the auth token refresh\", files: [\"src/auth/token.ts\"] }\n// → task-relevant memory capsule (bounded, ~2.8KB)\n// → peers: none\n```\n\nSession B — Codex, same repo, half a minute later:\n\n```jsonc\nbrain_sync { intent: \"add rate limiting to the auth routes\",\n files: [\"src/auth/token.ts\", \"src/auth/routes.ts\"] }\n// → task capsule\n// → peers: 1 active session (claude-code) — \"rewrite the auth token refresh\"\n// → overlap: src/auth/token.ts — declared by both sessions\n```\n\nSession A gets the same overlap surfaced on its next KLYPIX action. Neither edit is blocked — the\nwarning is advisory, and both sides only see the overlap because both declared the files they\nexpected to touch.\n\nThen the brain pushes back before the decision, not after:\n\n```jsonc\nbrain_challenge { \"move token storage to localStorage\" }\n// → \"reversed on June 12 — here's the correction card, captured by a different agent.\"\n```\n\nAnd the decision is kept where the next session will find it:\n\n```jsonc\nbrain_note { text: \"Token refresh moves to an httpOnly cookie; localStorage was reversed 2026-06-12.\" }\n```\n\nProve all of this on your own machine, against the exact build you installed, with two real\nisolated MCP clients:\n\n```bash\nnpx klypix-mcp conformance\n```\n\nIt runs in a temporary fixture and touches nothing else. It checks tool discovery, task memory,\ntruthful peer reporting, overlap surfacing, proactive logging, and in-band delivery of a peer note.\nIt verifies 15 required coordination behaviours — not the 22 tools, and not the retrieval engine.\n\n---\n\n## Quick start\n\nRun this **inside your project**:\n\n```bash\nnpx klypix-mcp install\n```\n\nOne command for supported editors detected on this machine. It finds the project root (walking up,\nso running it from `src/` is fine), gives the project a brain if it doesn't have one, wires the\nagent tools you actually have installed, registers the lossless `.klypix` merge driver if it's a\ngit repo, and then **proves the result** before it exits:\n\n```text\n project E:\\work\\api (git repository root)\n brain created brain.klypix — a starter brain, ready for its first decision\n editors Claude Code · Cursor · Codex · Gemini CLI · Antigravity · VS Code\n wired 9 file(s) · 9 updated (skipped 5 for tools you don't have)\n git lossless .klypix merge driver registered\n verified ✓ 22 tools reachable via .mcp.json (892ms)\n```\n\nThat last line is the point. MCP config fails **silently** — a wrong entry means the server never\nstarts, the agent quietly loses every brain verb, and nothing reports an error. So `install` opens\na real stdio handshake against the config it just wrote and counts the tools that answered. A\nbroken entry dies in ~100ms with `Connection closed` and is reported, not shipped.\n\nWhat goes where:\n\n- **Machine-global, once** — the engine + runtime in `~/.claude/project-brain`, Claude Code's five\n lifecycle hooks in `~/.claude/settings.json`, and the `~/.codex/AGENTS.md` guidance block. Claude\n Code is therefore covered in every project on that machine that has a `./brain.klypix`.\n- **Per project** — MCP config and rules for Cursor, Codex, Cline, Windsurf, Copilot, Gemini CLI /\n Antigravity and Aider. Run `install` once inside each project.\n\nThree things it deliberately will **not** do:\n\n- **Write for editors you don't have.** Config is projected only for hosts detected on this\n machine — a two-person team using one editor no longer commits rules for six they never opened.\n A file your project *already* carries stays maintained regardless, so you can't silently stop\n updating your team's committed configs.\n- **Wire a directory that isn't a project.** It refuses your home folder, a drive root, and\n anything with no brain, no git repo and no project manifest. A mistyped command can't seed a\n brain into `C:\\Users\\you`.\n- **Replace a project-owned server.** A repo-relative launch like\n `node scripts/klypix-mcp-server.mjs` is deliberate — it resolves offline and rides a bundle the\n repo version-gates — so it's left byte-identical and reported. An explicit `link` still rewrites\n everything: an action you didn't ask for stays more conservative than one you did.\n\nOpt out with `--no-project` (CI images, scripted provisioning). `--json` emits the report as\nstructured data; `--verify-all` handshakes every written config instead of one.\n\nOptional, opt-in, and approved inside Codex itself:\n\n```bash\nnpx klypix-mcp install --codex-hooks\n```\n\nSix Codex lifecycle hooks that add automatic per-prompt context injection and a pre-edit\nfile-overlap warning. Codex owns the trust decision and will ask you to review them.\n`brain_doctor` reports this layer separately as off, execution-unverified, or active. Even with it\non, **Codex never captures decisions automatically** — the Codex hook never writes the brain.\n\n**Re-project everything explicitly:**\n\n```bash\nnpx klypix-mcp link\n```\n\n`install` already does this for the editors you have. Reach for `link` when you want all 14\nmanaged, hash-stamped files regardless of what's installed — MCP server config for six hosts plus\nrules files for eight — or to repair drift. Managed blocks are merged into your existing\ninstruction files and never clobber your content.\n\n```bash\nnpx klypix-mcp link --check # audits without writing; exits non-zero on drift\n```\n\n> Either form works, and both are safe in CI: `npx -p klypix-mcp klypix-link --check` used to\n> drop `--check` and write anyway — fixed, and locked by `test/cli-args.mjs`, which asserts the\n> standalone bin and the dispatcher parse arguments identically.\n\n**Give a project a brain** by dropping a `brain.klypix` into it — the\n[KLYPIX app](https://klypix.com) does it in one click (*Save canvas as project brain*), or\n`create_canvas` makes one from any agent.\n\n---\n\n## How the brain works\n\nThe difference from a folder of notes is not the shape — it is that this memory is a mechanism,\nnot a filing convention.\n\n- **Decisions have a lifecycle.** A new decision that contradicts an old one supersedes it. The\n stale card is archived with an arrow and a date, never deleted, and later answers surface the\n correction rather than the corpse. If a later decision returns to an earlier superseded stance,\n high-confidence lineage leaves a dated `re-adopts` stamp on the new card plus an earlier→current\n edge; the original A→B→C history remains intact.\n- **Corrections are explicit, not guessed.** Supersession fires on an UPPERCASE correction cue or\n an explicit edge. `brain_reconcile` only *proposes* stale-vs-correction pairs for a human to\n confirm.\n- **Cards can cite the code they were decided against.** An `ev:` anchor records a file:line plus\n the git blob OID at capture time, so the engine can flag a card whose cited code has since moved\n on. It detects that the code *changed* — never that the claim became false.\n- **Position means something.** Drag a card into the 📌 Focus area and it leads every future\n session's brief. That is brief priority, not a retrieval-ranking boost.\n- **You can ask what the project believed then.** `brain_ask` with `as_of: 2026-03-01` reweights\n ranking by card lifecycle dates, so corrections made later do not leak backwards.\n- **Retrieval is local.** Lexical by default. If the optional on-device model is installed,\n `brain_ask` and `search_all_brains` use BGE semantic ranking with lexical help for exact\n identifiers, paths, and versions — still entirely on your machine. The previous cross-encoder\n is available for experiments with `KLYPIX_RERANK=1`, but is off by default because it reduced\n precision and added latency on the frozen human-paraphrase evaluation. Without the embedding\n model, retrieval degrades cleanly to lexical. `npx klypix-mcp install` deliberately does not\n install that model, so a fresh install is lexical.\n\n### Bounded semantic-memory runtime\n\nLong-lived MCP and A2A workers use the bounded semantic-memory runtime by default. Models load only\nwhen semantic work is requested, native inference is serialized per process, embedding work is\nsplit into small batches, and temporary tensors are released after use. Loaded models retire after\nan idle interval and transparently reload on the next semantic request, so warm queries stay fast\nwithout permanently pinning native model memory. These controls change the resource lifecycle only;\nbrain cards, project coordination, and the on-disk brain format are unchanged.\n\nThe previous runtime remains available as an emergency rollback. Set\n`KLYPIX_SEMANTIC_MEMORY_MODE=legacy` in the MCP server environment and reconnect or restart the\nhost. This restores eager model prewarming and the previous inference path without migrating or\ndeleting brain data. Remove the variable (or set it to `bounded`) to return to the bounded runtime.\n\nRun the deterministic lifecycle tests with `npm run test:memory`. For an opt-in real-model soak\nagainst a disposable or backed-up brain, set `KLYPIX_MEMORY_SOAK_BRAIN` to its path and run\n`npm run test:memory:soak`.\n\nFor process-level attribution, run `npx klypix-mcp runtime` (or add `--json`; `--watch 30` samples\nevery 30 seconds). It reports KLYPIX workers, supervisors, and legacy launcher overhead separately,\nexcludes the owning IDE/chat application's RAM, redacts command-line secrets, and never opens a\nbrain or terminates a process. Multiple processes under one host are reported as parallel sessions,\nnot called duplicates without an authoritative logical-session receipt.\n\n### Project Map: current structure beside project understanding\n\nIf the project contains a compatible NetworkX node-link `graph.json`, agents can ask for bounded\ncode-structure evidence and current brain context in one read-only call:\n\n```jsonc\nproject_map_context {\n \"question\": \"what owns refresh-token rotation?\",\n \"graph_path\": \"graphify-out/graph.json\"\n}\n```\n\nUse `compare_to` with another project-relative graph artifact to add exact total node/edge deltas\nand additions/removals from the two bounded query neighborhoods. Both paths are confined to the\ndeclared project root; unsafe source paths are withheld; large or unsupported artifacts are\nrejected. When a returned brain card names an exact mapped source path, the structured response\nalso includes a review-only evidence-link proposal. It never promotes similarity into truth and\nnever writes graph facts or links into `brain.klypix`.\n\nGraphify is the first compatible producer. KLYPIX reads artifacts that users generate separately;\nit does not bundle, install, or run Graphify and does not imply a partnership. A compatible generic\n`graph.json` works through the same provider-neutral boundary.\n\nFor a reproducible map artifact on every pull request and main-branch push, install the shipped\nread-only workflow into a Git checkout:\n\n```bash\nnpx klypix-project-map setup-github /path/to/project\n```\n\nThe command refuses to overwrite an existing workflow unless `--force` is explicit. The installed\nworkflow has `contents: read`, pins every action by commit SHA, pins `graphifyy==0.9.33`, validates\nthe graph contract, and uploads `graphify-out/` as a 14-day build artifact. This is opt-in CI code:\nthe local MCP tool still never installs or launches Graphify.\n\n---\n\n## Supported hosts and their integration level\n\nLevels are honest. Only the config-writing side is tested for the `link` hosts; their host-side\nbehaviour is unverified.\n\n| Host | Level | Wired by | Brief into context | Decision capture | Live presence |\n|---|---|---|---|---|---|\n| **Claude Code** | Full automatic (5 lifecycle hooks) | `install` | Automatic at session start, task-ranked retrieval per prompt | **Automatic** at turn end | Yes |\n| **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 |\n| **Cursor** | MCP config + always-on rules file | `link` | Model must call `brain_sync` | Model must call `brain_note` | For the MCP connection |\n| **Cline** | MCP config + always-on rules file | `link` | Model must call `brain_sync` | Model must call `brain_note` | For the MCP connection |\n| **VS Code (Copilot / Continue)** | MCP config + instructions file | `link` | Model must call `brain_sync` | Model must call `brain_note` | For the MCP connection |\n| **Gemini CLI / Antigravity** | MCP config + always-on rules file | `link` | Model must call `brain_sync` | Model must call `brain_note` | For the MCP connection |\n| **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 |\n| **Aider** | Rules file only (no MCP) | `link` | CLI path: `npx klypix-read` | CLI path: `npx klypix-append` | — |\n| **Claude Desktop** | One-time manual config edit | you | Model must call `brain_sync` | Model must call `brain_note` | For the MCP connection |\n\n`install` and `link` are different things and are not interchangeable: `install` sets up the\nmachine engine and hooks, then wires supported hosts detected for this project (see *Quick start*).\n`link` is the explicit per-project repair/projection path for all 14 managed files, regardless of\nwhich hosts are installed.\n\n**Claude Desktop** — add this to `claude_desktop_config.json` by hand; nothing writes that file\nfor you:\n\n```json\n{\n \"mcpServers\": {\n \"klypix\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"klypix-mcp\", \"--vault\", \"/absolute/path/to/canvases\"]\n }\n }\n}\n```\n\n---\n\n## Task briefing\n\nEvery Claude Code session starts already knowing the project: a bounded brief of at most 2KB in\ncontext, with the full brief written to disk for when broad history or status work needs it.\n\nEvery other host gets a bounded ~2.8KB task capsule from one `brain_sync` call, plus a compact\nalways-loaded `AGENTS.md` block that tells the agent to make that call at task start, when scope\nchanges, and on completion. The gateway capsule is lexical-fast by design. A newly captured open\ngap can claim a labeled `RECENT OPEN` slot only after clearing the normal lexical-relevance floor,\nso fresh relevant findings are not crowded out by older area vocabulary.\n\nBriefs are **not** injected automatically on Cursor, Cline, Copilot, Gemini CLI or Antigravity —\nthere are no lifecycle hooks on those hosts.\n\n## Capture and corrections\n\n`brain_note` accepts structured supporting references and inert verification text:\n\n```json\n{\n \"text\": \"Retry failed uploads with a bounded backoff to preserve queued work.\",\n \"area\": \"Storage\",\n \"evidence\": [{ \"kind\": \"file\", \"ref\": \"src/uploads.mjs:42\" }],\n \"verify\": \"node test/uploads.mjs\"\n}\n```\n\nFile references must stay inside the project. The capture records a fingerprint of the\nworking file and, when available, the repository HEAD revision. An unchanged fingerprint\nmeans **source unchanged**, not that the remembered claim is correct or that tests passed.\nDirty working files are fingerprinted as they are; HEAD alone does not describe those bytes.\nRead results distinguish changed, missing, and unverified sources. External references\n(`pr`, `url`, `commit`, `run`) are retained without fetching or verifying them. `verify` is\nshown as recorded text and never executed. Optional `verifiedAt` is explicitly caller-reported.\n\nOn an amendment (`marker: \"~\"`), omitted metadata is preserved; `evidence: []` and\n`verify: \"\"` clear obsolete metadata. A resolve (`✓`) archives existing evidence; attach\nnew evidence with a milestone and `closes`, or amend before resolving. The CLI accepts the\nsame JSON on stdin, or `--evidence ''` and `--verify ''`.\n\nOn Claude Code, decisions are captured automatically at turn end from inline `🧠 BRAIN [Area]:`\nmarkers in the transcript, deduped, under a capture lock.\n\nOn every other host, capture is explicit: `brain_note` runs the same capture engine as the hooks —\ndedup, supersession, round-trip re-adoption receipts, `✓` resolve, `~` update in place, `+` skill,\n`closes:` — and stamps which agent wrote the card. A `✓` question preference ranks only candidates\nthat already clear raw lexical overlap and two subject-identity anchors; generic lifecycle wording\ncannot turn weak overlap into a closure.\n(If you install the git commit hook from the KLYPIX app or run `npx klypix-mcp git-hook install`,\ncommit messages also capture automatically for any agent.)\n\n`brain_challenge` is the other direction: propose a decision and the brain answers with receipts —\nprior decisions that deterministically contradict it, standing rules that dispute it, and\napproaches tried and reversed, flagged when a different agent wrote them. Evidence is deterministic\nonly (explicit correction cues, opposite-polarity pairs), never mere topical similarity. Silence\nmeans no contradiction signal was found — not verified consistency. A memory that cannot disagree\nwith you is flattery.\n\n## Presence and task intent\n\nAn active session means an authorized MCP connection or host lifecycle adapter that heartbeated\nwithin the TTL. A row in a recent-chat list is history, not presence.\n\nEach MCP connection registers itself at initialization and removes itself on disconnect; the TTL\ncovers crashes. Optional host adapters merge into that same logical session rather than\ndouble-counting it, enrich it with intent and files, and remove only their own channel. Sessions\nthat never declared a task are still counted, but are shown separately as scope-unknown rather than\npadding the peer list.\n\nFuture hosts get baseline support merely by connecting the MCP server. A deeper adapter can import\n`klypix-mcp/presence` and map lifecycle events onto `upsertSession`, `removeSession`,\n`peekMessages` and `receiveMessages`. The shared contract accepts `id`, `client`, `surface`,\n`model`, `branch`, `intent`, touched `files`, and adapter `channel`.\n\n## Overlap warnings\n\nWhen two sessions declare overlapping expected files, `brain_sync` surfaces it: the peer, its\ndeclared task, and the exact paths in common. A one-time alert is queued to whichever session got\nthere first, so a late arrival is not the only one who knows.\n\nThis warns. It does not prevent. Nothing blocks an edit, matching is exact-path, and both sides\nhave to have declared their files for the overlap to be visible at all.\n\n## Handoffs and messages\n\n`brain_message` leaves one-time coordination notes for other sessions. A supported KLYPIX action\noffers the note in model-visible context; the next independent supported action replays it and\nrecords an acknowledgement. That acknowledgement proves only that a later action followed the\noffer — never that a person read it or that an agent acted on it. The note keeps replaying until the\nreceiving model calls `brain_message_receipt` with the exact message id and per-recipient offer\ntoken; only that token-bound action records `consumed`. Pending, offered, and acknowledged notes\nsurvive reconnects. Expiry or bounded-capacity eviction records a failed per-recipient receipt\ninstead of silently looking delivered. The send-time audience is fixed, unresolved targeted sends\nfail closed, the core lane is machine-local, notes expire after 24 hours, and they are never written\ninto the brain.\n\nDurable handoffs go in the brain itself — decisions, findings, open questions and skills captured\nas cards, each stamped with the agent that wrote it.\n\n## Evidence-gated completion\n\nWhen a task publishes a quantified or otherwise machine-checkable claim, it can attach one or more\nversioned result manifests to `brain_sync { phase: \"complete\" }`. Each manifest binds the claim to a\nreport hash, producer/run provenance, the exact declared task scope, material artifact hashes,\nevaluation outputs, public metric wording, input/configuration fingerprints, and named metrics with\ncounts and tolerances. Matching peer evidence is recorded as corroboration; conflicting or\nincomparable evidence returns `needs-reconciliation` and keeps the task scope active.\n\nThe gate fails closed. Once a task submits result evidence, it cannot bypass an invalid or\nconflicting result by retrying completion without the manifest, and that obligation survives worker\nrestart, hibernation, and transparent hot-swap. A fresh `phase: \"start\"` is the explicit boundary for\na new task. The strict schema and reusable validator are exported as `klypix-mcp/result-reconcile`.\nSchema-v2 receipts can be converted into commit-bound publication evidence and independently checked\nwith `klypix-mcp/release-evidence`; legacy schema-v1 results remain usable for coordination but cannot\nauthorize publication.\n\n## Human control in Klypix\n\n> **Not a second brain. A shared one.**\n\nA brain nobody can inspect is a database with good marketing. The\n[KLYPIX desktop app](https://klypix.com) renders the same `brain.klypix` as a living spatial map,\nwith health, freshness, provenance and orrery lenses, an unresolved-questions triage view, and a\none-click flow that connects a folder's brain to six coding agents. You can read, correct, archive\nand re-link what your agents recorded.\n\nThe file is co-owned. When the app saves a brain it re-reads the disk copy inside the same capture\nlock the agent hooks use and union-merges instead of overwriting, so a card an agent captured while\nyou had the file open is kept. The merge verifies its own output and aborts rather than emit a file\nmissing a card. Deletes require an explicit tombstone, so a card that is merely absent is never\ninferred as deleted.\n\nThe app is a separate, proprietary Windows product. The format, this server and the hooks are\nApache-2.0 and work with no app installed. The app's interface is available in English and Arabic\n(some newer panels are still English-only).\n\n## Measure it yourself\n\nClaims about a shared brain — \"nothing is lost\", \"it stays fast\" — are unfalsifiable until a\nstranger can re-run them, so the benchmark ships in the box:\n\n```bash\nnpx klypix-mcp bench # ~25s, or --quick for a smaller run\n```\n\nIt measures concurrent-write safety across real OS processes, coordination latency, a 1,000-query\nsoak with drift, and crash safety under SIGKILL — then prints the machine it ran on.\n\n**It runs a negative control first.** Writers that bypass the lock go in before the real ones,\nbecause a \"0 lost\" number means nothing unless the same harness can *see* a loss. On the reference\nmachine those unlocked writers lost 17 of 22 cards; the same contention through the lock protocol\nlost 0 of 46. If the control ever loses nothing, the run reports **inconclusive** instead of a pass.\n\nLatest results, with hardware and date: [BENCHMARKS.md](BENCHMARKS.md).\n\n## Git and concurrency\n\nOne file in your repo, committed with your code — versioned, branchable, portable. So two\ndevelopers already share one brain the way they share code: clone, branch, pull.\n\nBe precise about what git does on its own: `brain.klypix` is a binary ZIP. Git shows\n`Bin 1308328 -> 1309005 bytes` and produces zero line diffs, so out of the box a conflict on it is\nan all-or-nothing take-ours or take-theirs, and a reviewer sees nothing. **Card-level merge safety\ncomes from the KLYPIX engine** — but since 1.48.0 you can hand that engine to git and read its\noutput in a PR:\n\n```bash\nnpx klypix-mcp git-driver install # once per clone, in any repo\n```\n\nThat registers a merge driver for `*.klypix` (a per-machine git config line plus a `.gitattributes`\nrule you commit) and provisions the engine it needs. When two people change the brain and one\npulls, git calls the engine instead of stopping: new cards from both sides are kept, a card only\none side edited takes that edit, and a card edited differently on both sides keeps **both**\nversions — the second as a linked twin, never a silent overwrite. Before returning, the merge\nasserts it still contains every surviving card from both sides and refuses rather than hand back a\nresult that lost one.\n\nThe honest boundary: a machine that has not run `git-driver install` simply gets the old binary\nconflict — safe degradation, not corruption — and git keeps both parents of every merge, so even a\nmerge you dislike is reconstructable. It is a merge *on pull*, not live sync.\n\nFor review, two commands turn a binary blob into something a human can read:\n\n```bash\nnpx klypix-mcp diff main # card-level: what was added / updated / removed\nnpx klypix-mcp pr-brief origin/main # the brain cards that reference this PR's changed files\n```\n\n`diff` compares meaning rather than bytes (a re-save restamps timestamps; that is not a change).\n`pr-brief` matches a card's `#file-…` evidence anchors against the changed paths, so a reviewer\nsees the decisions already recorded about the code in front of them. `examples/github/brain-pr.yml`\nwires both into a sticky pull-request comment using nothing but the checkout and the default\n`GITHUB_TOKEN` — no KLYPIX service in the path.\n\nConcurrent sessions serialize behind a capture lock, and each write is a temp file plus an atomic\nrename, so a crash mid-write leaves the previous good file intact. The lock is advisory with a\n~3.6-second budget: past that, a writer proceeds anyway and flags it in the health log, so\nsustained contention can still lose an update. That is a deliberate trade — dropping the markers\nwas judged worse — but it is a real limit, not a guarantee.\n\n### Restore points\n\nMerging, tidying and gardening are lossless by contract. What none of them can undo is a\n*deliberate-looking* deletion: you select a dozen cards, delete them, and save. That is not a bug\nto prevent — a brain has to stay correctable, and an uncorrectable memory is worse than none — but\nit deserves a way back, because the brain is **co-owned**: hooks, the MCP server, commit capture\nand peers on other machines all write to it while nobody is watching, so you can destroy work you\nnever saw arrive.\n\nSo every brain write takes a restore point of the previous bytes first:\n\n```bash\nnpx klypix-mcp brain-history list # age, card count, delta against the brain now\nnpx klypix-mcp brain-history restore # and this is itself undoable\n```\n\nThey live under `~/.claude/project-brain/history/`, never beside the brain — nothing lands in git,\nin the merge driver's path, or in your diffs, and they survive deletion of the `.klypix` file\nitself. Routine writes are deduped and throttled to one a minute; a write that **removes cards** is\nnever throttled, because that is the case they exist for. Retention is the newest 20 plus one per\nday for 14 days, so a slow-burn mistake is still recoverable without unbounded growth. A snapshot\nthat cannot be written is logged and skipped — it never blocks your save.\n\nNormal canvases deliberately get none of this. One human made every mark and saw every change; the\nbrain is the file where that is not true.\n\n---\n\n## The command line\n\nThe MCP verbs below are what agents call. These are what **you** call:\n\n| Command | What it does |\n|---|---|\n| `npx klypix-mcp init` | Seed a starter `brain.klypix` here and print an MCP config |\n| `npx klypix-mcp install` | Set up everything: machine engine + hooks, then this project — brain, config for the editors you have, merge driver, verified (see Quick start) |\n| `npx klypix-mcp link` | Re-project all 14 managed files regardless of what is installed (`--check` audits) |\n| `npx klypix-mcp doctor` | One verdict: version, hosts, live sessions, tool count, drift. Exits non-zero — usable as a CI gate |\n| `npx klypix-mcp runtime` | Passive per-connection process/RAM attribution (`--json`, optional `--watch seconds`); never kills or deduplicates |\n| `npx klypix-mcp conformance` | Launch two real MCP clients against this build and verify coordination behaviour |\n| `npx klypix-mcp git-driver` | Register the lossless `.klypix` merge driver for a repo (`status` to check) |\n| `npx klypix-mcp git-hook` | Wire the agent-neutral commit-capture hook: rationale-bearing `feat`/`fix`/`perf` commits from any agent, branch, or worktree card into the brain at commit time (`install`/`remove`/`status`; sessions auto-install it where the hook slots are free) |\n| `npx klypix-mcp brain-history` | Restore points for this brain — `list` them, `restore ` one. Written automatically before every brain write, kept machine-local, and never throttled away for a write that removes cards |\n| `npx klypix-mcp diff [ref]` | Card-level brain diff against a git ref, as markdown |\n| `npx klypix-mcp pr-brief [ref]` | Brain cards referencing the files changed since a ref, as markdown |\n| `npx klypix-mcp garden-code` | Print the human approval code `brain_garden` requires |\n\n---\n\n## The 22 verbs\n\n| Tool | What it does |\n|---|---|\n| `brain_ask` | Whole-brain question answering — correction-aware, `as_of` time travel |\n| `brain_challenge` | The brain argues back: contradictions with receipts, tried-and-reversed chains, standing rules, other-agent provenance flags |\n| `brain_note` | Capture with the full lifecycle — supersede / re-adopt / ✓ resolve / ~ update / 🛠 skill / `closes:` |\n| `brain_reconcile` | Proposes stale-vs-correction pairs and unrecorded migrations for a human to confirm |\n| `brain_insights` | Hubs, orphaned decisions, stale questions, area sizes |\n| `brain_lens` | Machine-readable freshness, provenance, activity, timeline, orrery and unresolved views |\n| `brain_garden` | Maintenance pass — proposes first, and cannot apply without an approval code the human generates |\n| `brain_doctor` | Self-diagnosis: version, core/enhanced host adapters, active sessions, tool count, projection drift |\n| `brain_message` | Session-to-session coordination notes with a fixed send-time audience and per-recipient pending / offer / acknowledgement / consumption / failure receipts (24h TTL, never written into the brain) |\n| `brain_message_receipt` | Explicitly record model-side consumption using the exact message id and per-recipient offer token; acknowledgement alone never consumes a note |\n| `brain_sync` | Context Gateway: task capsule, active-task peers, exact-file overlap, one-time alerts, timing, and optional result-manifest reconciliation |\n| `brain_connect` | Find and draw related-but-unlinked cards |\n| `project_map_context` | Read-only, bounded code-graph evidence beside correction-aware brain context, with exact-path review proposals; external artifacts (e.g. Graphify) are supported but never installed or run locally |\n| `project_map_scan` | KLYPIX's own zero-install scanner: gitignore-aware file inventory + file-level import edges (relative, tsconfig-alias, and monorepo-workspace imports resolved) written to `klypix-map/graph.json` — which then serves `project_map_context` automatically |\n| `project_map_drift` | Read-only drift report: brain cards whose referenced files are gone or moved (with rename candidates), plus a headline when the checkout itself is behind its origin default branch |\n| `canvas_view` | Returns the board as a structured render spec plus a text summary, and declares an MCP Apps (SEP-1865) UI resource |\n| `read_canvas` | A canvas as markdown (cards, connection graph, `[[links]]`, `#tags`) |\n| `search_canvases` | Search across canvases by name and content |\n| `search_all_brains` | Cross-project memory search across every registered brain on this machine |\n| `create_canvas` | New `.klypix` from cards + connections |\n| `add_to_canvas` | Append cards/connections (positions preserved) |\n| `list_canvases` | List every `.klypix` in the vault |\n\nExactly 22, machine-verifiable with `npx klypix-mcp doctor`.\n\n> **`canvas_view`:** no MCP Apps host has been observed rendering the UI resource yet — there is no\n> screenshot and no host-level test. Hosts without the extension get clean text, which is the path\n> that is actually verified.\n\n`brain_doctor`, `brain_lens`, `brain_insights` and `brain_reconcile` are read-only introspection.\n`brain_garden`, `brain_reconcile` and `brain_connect` always propose before they apply.\n`npx klypix-mcp doctor` gives one verdict and exits non-zero on drift, so it doubles as a CI gate.\n\n## One file you can hold\n\nThe whole brain — layout, cards, arrows, and the actual bytes (images, PDFs, audio, video) — is a\nsingle `.klypix` file: a plain ZIP with `manifest.json`, `canvas.json`, one JSON file per card, and\nan `assets/` folder. Email it. Git it. Hand it to an agent. A folder of markdown points at its\nattachments; this file carries them. (Binaries are embedded by the **KLYPIX app** when you drop a\nfile onto a canvas; this package's `create_canvas` / `add_to_canvas` / `buildKlypix` write cards and\narrows, not assets — they read assets fine, they just don't create them.)\n\nThe parser is this package, Apache-2.0, so any tool or agent can read and write the format. Full\nspec: [FORMAT.md](FORMAT.md).\n\nMarkdown export, JSON Canvas 1.0 export and direct opening of Obsidian `.canvas` files are features\nof the **KLYPIX desktop app**, not of this package — there is no export command among this\npackage's binaries.\n\n**\"Project\" means any project.** Two showcase brains ship in the npm package *and* the GitHub repo\nunder [`examples/`](examples/), identical in engine, different in life:\n[`showcase-brain.klypix`](examples/showcase-brain.klypix) is *Aurora*, a fictional weather app\nmid-build (radar tiles, API caps, a correction with its receipt), and\n[`showcase-wedding.klypix`](examples/showcase-wedding.klypix) is *Our Wedding* (venue, vendors,\nguest list, the same correction machinery pointed at a caterer). Same 📌 Focus, same arrows, same\nbrief. If it has decisions worth keeping, it gets a brain.\n\nThey ship inside the tarball, so you can read one straight out of `node_modules`:\n\n```bash\nnpm i klypix-mcp\nnpx klypix-read node_modules/klypix-mcp/examples/showcase-brain.klypix\n```\n\nBoth are text-and-arrows only — 14 cards, 4 arrows, no `assets/` entry — so they demonstrate the\ncard / container / connection model, not the embedded-binaries half of the format.\n\n## Use it as a library\n\n```js\nimport { parseKlypix, buildKlypix, appendToKlypix, structToMarkdown } from 'klypix-mcp';\n```\n\n```bash\nnpx -p klypix-mcp klypix-read path/to/board.klypix # → markdown brief\necho '{ \"title\": \"Plan\", \"cards\": [{ \"text\": \"kickoff\" }] }' \\\n | npx -p klypix-mcp klypix-write --out plan.klypix\n```\n\n## Also speaks A2A protocol v0.3.0 — experimental\n\n```bash\nnpx -p klypix-mcp klypix-a2a --vault ./canvases # 127.0.0.1:41241\n# Agent Card: http://127.0.0.1:41241/.well-known/agent-card.json\n```\n\nEight vault/project skills by default: `make_board`, `remember`, `learn_skill`, `recall`,\n`read_canvas`, `list_canvases`, `brain_insights`, `brain_connect`. Machine-wide\n`search_all_brains` is a ninth, explicit opt-in via `--allow-cross-project`. Unlike a typical A2A\nagent that returns text, KLYPIX returns the `.klypix` board itself as a multimodal artifact. Details:\n[A2A.md](A2A.md).\n\nTreat this as a preview: the adversarial A2A smoke test runs in the default `npm test` chain, but\nthe server has not been exercised against a third-party A2A client.\n\n## Updates — the propagation contract\n\nThe MCP entry point is a stable stdio supervisor that keeps the host-owned connection open while a\nreplaceable worker runs the brain core. A staged update is hash-verified, initialized in parallel,\nchecked for backward-compatible tool schemas, and handed the current `brain_sync` task scope before\nthe supervisor switches between requests. Added tools use the standard\n`notifications/tools/list_changed` signal. A failed or breaking candidate is rejected while the old\nworker keeps serving. A blocked result claim is kept in a durable per-project/session marker, so a\nworker replacement cannot turn a failed evidence check into a result-less completion.\n\nCompatible engine updates therefore activate behind the same live connection — no reconnect, no\nhost restart. Three cases still require a deliberate reconnect or manual install: the one-time\nlegacy→supervisor migration, a supervisor-code change, and a major or tool-removing release.\n`brain_doctor` reports the live supervisor and the automatic-update receipt explicitly.\n\nThe supervisor performs **one machine-wide npm version check per 24 hours**, however many sessions\nare open. It installs an exact stable same-major release in `--runtime-only` mode, preserving host\nsettings and project files. The check is detached and fail-open, developer-owned installs are\nprotected, concurrent sessions collapse behind one lock, and `KLYPIX_AUTO_UPDATE=0` opts out\nentirely.\n\nWhen the optional semantic runtime is already enabled, an update also schedules one detached,\nsingle-writer cache migration across registered brains. That removes the multi-minute first-query\nre-index after a model/cache upgrade; cache writes are model-keyed and atomic across concurrent\nagent sessions. Lexical-only installs download nothing. Set `KLYPIX_SEMANTIC_WARM_ON_UPDATE=0` to\nkeep lazy first-use indexing instead.\n\n## Security and permissions\n\n- **Apache-2.0, source public** at [github.com/dahshanlabs/klypix-mcp](https://github.com/dahshanlabs/klypix-mcp).\n- **The brain engine makes no network calls and sends no telemetry.** All engine intelligence is\n deterministic and local; the only LLM anywhere is *your* agent. The one exception in this package\n is the supervisor's once-per-24h npm version check described above — turn it off with\n `KLYPIX_AUTO_UPDATE=0`.\n- **The optional semantic model runs on device.** Enabling it (or upgrading its model) can fetch\n model weights from Hugging Face; retrieval inference and brain data stay local.\n- **Coordination state is local files.** The brain is a file in your repo; the presence lane is a\n file under your home directory. Nothing is uploaded — with one explicit, default-OFF exception:\n the cross-PC presence relay, which (only after per-brain consent in the KLYPIX desktop app)\n shares whitelisted presence fields and the text of one-time coordination notes over that\n brain's cloud channel. KLYPIX does not automatically attach file/card contents, diffs, or screen\n data, but a note relays whatever its sender typed (and automatic overlap alerts name the declared\n file paths involved). The scope is versioned: an older metadata-only grant does not authorize note\n text and must be granted again. No current consent, no frames.\n- **`install` writes to your home directory:** `~/.claude/project-brain` (engine + runtime),\n `~/.claude/settings.json` (five hooks — written even if Claude Code is not installed),\n `~/.codex/AGENTS.md` (guidance block), and with `--codex-hooks`, `~/.codex/hooks.json`. It also\n writes `/.codex/config.toml` **inside the project** you run it in, and removes any KLYPIX\n entry from the global `~/.codex/config.toml`. **`link` writes 14 files inside the project** you\n run it in; `link --check` audits them without writing.\n- **Codex hooks require Codex's own trust approval** and are opt-in via `--codex-hooks`.\n\n## Current limitations\n\nRead this section before you build on any of it.\n\n- **Coordination is machine-local and OS-user-local.** The presence lane is a file in your home\n directory. Two developers on two machines do not see each other's sessions, peers, overlaps or\n messages. This package ships the cross-machine presence *core* (`./presence-relay` — versioned\n whitelisted presence metadata plus coordination-note text, a symmetric default-off consent gate,\n loop prevention, stable message IDs and per-recipient-machine acknowledgement primitives), but no\n transport: carrying frames between machines is the desktop app's job. With `klypix-mcp` alone,\n coordination is machine-local.\n- **Overlap matching is exact-path, and both sides must declare.** A session that never declares\n its expected files is invisible to overlap detection, and `src/auth/token.ts` does not match a\n rename or a parent directory.\n- **Overlap warnings are advisory.** Nothing is blocked. One severity string in the payload reads\n `blocking`; the mechanism is not.\n- **Codex has no automatic capture**, with or without `--codex-hooks`. The Codex hook never writes\n the brain.\n- **Uninstall does not remove per-project files.** `npx klypix-mcp uninstall` handles the\n machine-global install; the 14 files `link` wrote into each project are listed by\n `npx klypix-mcp link --check` and removed by `uninstall unlink` **per project**, one at a time.\n- **Drift detection is single-host and opt-in per card.** It needs an `ev:` anchor written by the\n card's author, and it runs only in the Claude Code hook path — the MCP tools do not compute\n freshness.\n- **`search_all_brains` finds nothing for a Cursor-only or Codex-only setup.** The cross-project\n registry is written by the Claude Code hook and only by it. This is a silent empty result, not an\n error.\n- **`npx klypix-mcp link` does not manage `CLAUDE.md`.** It manages `AGENTS.md` and seven other\n rules files. Only the desktop app writes `CLAUDE.md`.\n- **A fresh `npx klypix-mcp install` gets lexical retrieval.** The optional on-device model is\n deliberately not installed.\n- **The capture lock is fail-open** past ~3.6 seconds of contention (see *Git and concurrency*).\n- **`test/` is not in the published tarball.** Run the suite from a clone. The publish workflow\n *does* gate on it — a `gate` job runs `npm ci`, asserts the test chain is intact, runs `npm test`,\n validates the version/tag, and checks the packed tarball; `publish` declares `needs: gate`, so a\n red gate means npm never sees a tarball.\n- **`canvas_view`'s MCP Apps UI has never been verified on a real Apps host.**\n\n## Numbers and methodology\n\nEvery number here is measured on our own project brain. Nothing below is published, benchmarked or\nindependently validated.\n\n- **Dogfood scale.** KLYPIX itself is built with its own brain: **2,479 cards and 2,018\n connections**, written by multiple concurrent agent sessions, receipts in the file. Current as of\n 2026-08-13.\n- **Recall.** 73% of past decisions recovered with one search round, 55% brief-only, 0% cold.\n Caveat that travels with it: n=20, our own brain, self-authored questions, LLM-judged.\n- **Ranker.** With the production embedder (the eval harness was fixed 2026-08-10 — it had been\n measuring a vector space the product does not use): recall@5 **30%**, recall@10 35%, recall@20\n 45%, MRR 0.22 of the true source card on n=20 frozen human-paraphrase questions. Lexical-only\n scores 0% on the same set. The previously published \"15% → 40% with the reranker\" is **retired**:\n re-measured validly, the reranker *reduced* recall@5 to 25% and now ships off by default. At n=20\n every one of these percentages carries a ±20-point 95% confidence interval — treat them as\n directional until the larger frozen set lands. The regressions are recorded next to the wins:\n contextual prefixes on short cards, and the reranker itself.\n- **What we do not publish.** No download count: this package's own 24-hour auto-updater generates\n most of it, so it is not a user count. No adoption, team or customer figures. No brief-token\n figure — the last one was measured at ~600 cards and is stale at 2,479.\n- **The eval harness is not in this repo.** It lives in the private KLYPIX desktop repository. The\n numbers above are ours to defend, not yours to reproduce from here — treat them accordingly.\n\n## Uninstall\n\n```bash\nnpx klypix-mcp uninstall --check # full inventory — writes nothing\nnpx klypix-mcp uninstall # asks, then removes the machine-global install\nnpx klypix-mcp uninstall unlink # run inside a project: removes the files `link` wrote there\n```\n\nIt strips only KLYPIX's own entries — every other hook and setting in\n`~/.claude/settings.json` stays — backs up each file it edits, and **never deletes a `.klypix`**.\n`--yes` skips the prompt for scripted removal.\n\nYour `brain.klypix` is yours — it is a plain ZIP and stays readable with or without this package.\n\n## Contributing\n\nIssues and pull requests: [github.com/dahshanlabs/klypix-mcp](https://github.com/dahshanlabs/klypix-mcp).\nQuestions or feedback: [hello@klypix.com](mailto:hello@klypix.com).\n\nThe repository carries 89 test files: 83 listed directly in `scripts.test`, plus the\n`pretest` workflow gate. Together they cover the presence\nlane and its cross-machine relay, the Context Gateway, supervisor hot-swap, auto-update, retrieval\nquality, decay, challenge, lenses, the format guard, the git tools (including a real `git merge`\nthrough the merge driver), uninstall, and conformance. Run them with `npm test` from a clone — they\nare not in the published tarball, though the publish workflow does run them as a gate. There is a known intermittent Windows `EPERM` flake on rename in\n`test/mcp-supervisor.mjs`.\n\n## Why this exists\n\nA model provider can fix continuity inside its own sessions, and several are. None of them will\never carry a competitor's context. Cross-tool, cross-agent and cross-provider understanding is the\nseam that stays open — so it should live in a file you own, in your repo, that any agent can read\nand write.\n\n**Your project, your file, any supported agent, offline.**\n\n---\n\n## Licence\n\nThis package — the MCP server, the agent hooks and the `.klypix` format parser — is\n**Apache-2.0** ([`LICENSE`](LICENSE), attribution in [`NOTICE`](NOTICE)). Versions up to and\nincluding **1.28.0** were published under MIT and remain available under those terms; **1.29.0** was\nthe first Apache-2.0 release.\n\nThe KLYPIX desktop app and the klypix.com web app are **separate, proprietary products** — their\nsource is not public, and their terms do not restrict anything Apache-2.0 grants you here. This\npackage works with no app installed.\n\nApache-2.0 © [Dahshan Labs](https://klypix.com).\n",
"bytes": 49989,
"sha": "04a45bd28ca768f3541f59b830d35cf8f6ed26d71138dd2a6bfdb008df50dc43",
"repo_slug": "dahshanlabs/klypix-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_dahshanlabs_klypix_mcp_a759c4ce/readme"
}