Every project gets a brain.

Not a second brain. A shared one.

You've seen the setup: point an AI at a folder of notes, watch the graph fill up, call it a brain. Look closer — the human never touches anything. Even the pattern's inventor says it: "you never write the wiki yourself… I browse the results in real time." The human is a reader. The AI is the sole writer. That's not a brain — that's an aquarium.

klypix-mcp gives your project a brain you're allowed inside while it works. One file — brain.klypix — in your repo, versioned with git, that your AI agents read, write, and argue from. And in the KLYPIX app, you work in it while they do: your cursor typing in one card while agent decisions land beside your hands, each in its area, with an arrow explaining why — and the save refuses to write a file that lost a card.

Their AI keeps a diary about your project. Ours works in the same room as you — and the room remembers.

Quick start

Claude Code (native — live hooks, zero effort):

npx klypix-mcp install

Every repo on your machine with a brain.klypix now auto-briefs each session with the project's state and auto-captures decisions as you work. Give a project a brain by dropping a brain.klypix in it — the KLYPIX app does it in one click (Save canvas as project brain), or create_canvas makes one from any agent.

Every other agent tool (one command per project):

npx klypix-mcp link

Extends the brain to Cursor & VS Code/Copilot (MCP config + rules) and to Cline, Windsurf, Gemini CLI, Aider, and any AGENTS.md-reading agent — always-on rules that teach the tool to read and capture the brain.

What a project brain does

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

• It briefs every session. Each agent session starts already knowing the project's decisions, open questions, and standing rules — a compact brief (≈3–5k tokens even at 600+ cards, growing sublinearly). Measured on our own brain: 73% of past decisions recovered with one search round (55% brief-only) vs 0% cold (n=20).
• It argues back. brain_challenge: propose a decision and the brain answers with receipts — "you reversed this on June 12; here's the correction — captured by a different agent, coordinate before overriding." Deterministic evidence only (correction-cues, opposite-polarity), never mere topical similarity. A memory that can't disagree with you is flattery.
• It knows when it's stale. Decision cards can anchor to the exact code they were decided against (git blob OID). When that code moves on, the card raises its hand in the next brief. Their notes rot silently; ours confess.
• It answers from the past. brain_ask with as_of: 2026-03-01 answers what the project believed then — corrections from the future never leak backwards.
• Position means something. Drag a card into the 📌 Focus area and it leads every future session's brief. Layout is instruction, not decoration.
• Many agents, no chaos. Concurrent sessions take a capture lock (zero captures lost, tested at four simultaneous writers), tag who wrote each card, message each other through the brain (brain_message), and genuine contradictions surface as red arrows for a human to arbitrate — never auto-resolved.
• Retrieval that's measured, failures included. Hybrid on-device search (semantic + lexical + cross-encoder rerank, no cloud): recall@5 of the true source card went 5% → 15% → 40% across our upgrades (n=20 frozen human-paraphrase questions) — and the experiment that regressed (contextual prefixes on short cards) is recorded next to the wins.

One file you can hold

The whole brain — layout, decisions, arrows, and the actual bytes (images, PDFs, audio, code) — is a single .klypix file. Email it. Git it. Hand it to an agent. A folder of markdown points at its attachments; this file carries them.

And it's not a cage: everything exports to Markdown and JSON Canvas in one command, and Obsidian .canvas files open directly in KLYPIX. Plain markdown is the most portable text on earth — that's exactly why we export to it. Full spec: FORMAT.md.

"Project" means any project. Two showcase brains ship in examples/, identical in engine, different in life: showcase-brain.klypix is Aurora, a fictional weather app mid-build (radar tiles, API caps, a correction with its receipt) — and showcase-wedding.klypix is Our Wedding (venue, vendors, guest list, the same correction machinery pointed at a caterer). Same 📌 Focus, same arrows, same brief. If it has decisions worth keeping, it gets a brain.

Setup for plain MCP clients

Any MCP client gets the tools without the hooks. For Claude Desktop, in claude_desktop_config.json:

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

Then ask your agent things like "what did we decide about auth?", "challenge this: let's switch to polling", or "turn these notes into a board."

The 16 verbs

Tools vs. the automatic brain

This package is the agent-neutral read/write surface — any MCP client gets the tools above on demand (pull), in any project. The automatic brain — auto-capturing decisions from your work, injecting the brief into each session, coordinating concurrent sessions (push) — runs in a host hook, which npx klypix-mcp install wires for Claude Code (and the KLYPIX desktop app ships built-in). Other tools get the always-on rules via link.

Updates — the propagation contract

install lays the whole brain (hooks + engine + local MCP server) into ~/.claude/project-brain, and the emitted config runs the server from that installed bundle (no npx cache to go stale). Updates are then automatic: at session start the hook checks npm (≤ once/24h, fail-open, disable with KLYPIX_AUTO_UPDATE=0) and self-installs newer releases. One honest caveat: a running stdio server can't hot-swap — a new binary loads on the next full app launch (or /mcp reconnect); brain_doctor's RUNNING line tells you when that's needed.

Also speaks A2A (Agent-to-Agent)

npx -p klypix-mcp klypix-a2a --vault ./canvases     # 127.0.0.1:41241
# Agent Card: http://127.0.0.1:41241/.well-known/agent-card.json

Skills: make_board, remember, recall, read_canvas, list_canvases, brain_insights, search_all_brains. Unlike a typical A2A agent that returns text, KLYPIX returns the .klypix board itself as a multimodal artifact. Details: A2A.md.

Use it as a library

import { parseKlypix, buildKlypix, appendToKlypix, structToMarkdown } from 'klypix-mcp';

npx -p klypix-mcp klypix-read   path/to/board.klypix      # → markdown brief
echo '{ "title": "Plan", "cards": [{ "text": "kickoff" }] }' \
  | npx -p klypix-mcp klypix-write --out plan.klypix

The workspace it opens in

The brain is open and free — this package, the hooks, the format. KLYPIX is the Windows app built around it: see the brain as a living spatial map, work inside it while your agents write, capture anything from anywhere, act with agents, share encrypted. Bilingual English/Arabic.

Honesty notes

• Dogfooded hard: KLYPIX itself is built with its own brain — 600+ cards, multiple concurrent agent sessions, receipts in the file.
• All engine intelligence is deterministic and local — the only LLM anywhere is your agent. No telemetry, no cloud calls, works offline.
• Every number above is measured on our own project brain; the eval harness ships in the repo.

Why this exists

Frontier labs are racing to put your context inside their memory — a roach motel your work checks into and never leaves for a competitor. klypix-mcp is the opposite: your project, your file, any model, offline. A brain that any agent reads and writes is the one thing a lab is structurally disincentivized to build.

Apache-2.0 © Dahshan Labs. The KLYPIX desktop app is a separate, proprietary product — the file and this server are fully open and work without it.