klypix-mcp
The shared project brain for your coding agents.
Every project gets a brain.
Agenten stärken
Der eigene Befehl des Herausgebers. Kein PlugMCP-Endpunkt.
Host a copy with our keys and logs.
npx -y [email protected]Claude Code hat keinen Installationslink für einen lokalen Befehl. Kopieren Sie den Befehl unten und führen Sie ihn in einem Terminal aus.
claude mcp add klypix-mcp -- npx -y klypix-mcp@1.112.1In einem Terminal ausführen.
{ "mcpServers": { "klypix-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}claude_desktop_config.json
Remote-URL oder ein Befehl auf Ihrem Rechner? Worin sich die beiden Installationen unterscheiden
Auf PlugMCP ausführen
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
StartenShared project memory for Claude Code, Codex, Cursor and other MCP coding tools. One
brain.klypix file, committed with your code, holds the project's decisions, corrections and open
questions. Supported agents read it at the start of a task and add to it as they work; how much of
that happens on its own depends on the host. People can open the same file and correct it.

A 14-second cut of the sessions film from klypix.com. Real terminal output is further down.
▶ Watch: For coding teams (40 s, with sound) · Correct it once (20 s) · Full tour (4 min) · KLYPIX network
You need Node.js 20 or newer (node -v).
Run this inside your project:
npx klypix-mcp install
It gives the project a brain.klypix if it has none, wires the editors it finds on this
machine, and checks that the tools answer before it exits.
Reopen your coding tool, or reconnect its MCP server, and allow the KLYPIX tools if it asks.
Check it. Run npx klypix-mcp doctor, then
record your first decision and correction and ask for it
from a fresh session.
brain_sync in other hosts. A correction replaces the old decision, and the old card stays as
history..klypix file in your repo: a plain ZIP, versioned with
Git. The engine is Apache-2.0, runs on your machine, and works without the KLYPIX app or an
account. Brain data stays in your files; your agent's model provider still receives what the
agent reads.How deep the integration goes depends on the host. The full table has the details.
klypix-mcp has 27 MCP tools on Linux and macOS and 28 on Windows, where show_in_klypix is
added. npx klypix-mcp doctor shows the count for your install.
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.
KLYPIX is a portable project workspace with a shared brain. This repository is its local MCP server. The optional Windows workspace lets people inspect the same brain beside their files; app-based sharing has its own cloud path (see Security and permissions). For the Projects & Ideas path, saved project materials in ChatGPT or Claude chat, follow Save project materials and use them with your assistant. That uses KLYPIX's separate hosted connection for the spaces you authorize; installing this local server does not set it up.
Guides: shared project memory setup · memory tools comparison (it links each tool's official documentation and says that KLYPIX wrote it) · klypix.com/klypix-mcp
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. Context saved in one tool may be missing from the next:
Your agents may run independently. Their project understanding should not.

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).
Illustrative calls and responses: replace /absolute/path/to/project with the same project root
in both sessions (for example, C:/work/api on Windows).
Session A — Claude Code, in your repo:
brain_sync { project: "/absolute/path/to/project", phase: "start",
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 { project: "/absolute/path/to/project", phase: "start",
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 { claim: "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.
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:
Illustrative output; detected editors, file counts, tool counts and timings vary with the machine and installed version:
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:
~/.claude/project-brain, Claude Code's six
lifecycle hooks (five before 1.105.0) 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.install once inside each project.Three things it deliberately will not do:
C:\Users\you.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 --checkused to drop--checkand write anyway — fixed, and locked bytest/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.
After installation, reopen your coding tool or reconnect its MCP server, and allow the KLYPIX
tools if your host asks. Run npx klypix-mcp doctor in the project to inspect the installation;
a clean config report does not prove that your host has loaded the tools.
Try the following in a disposable trial project, or replace the example decision with a real
one before saving it. These are MCP tool calls for your agent, not shell commands. Replace
/absolute/path/to/project with your project root throughout. The files: [] scope means this
trial does not plan source-code edits.
Record a decision and its reason. Ask your agent to call:
brain_sync { project: "/absolute/path/to/project", phase: "start",
intent: "Record the trial storage decision", files: [] }
brain_note { area: "Storage",
text: "Use SQLite for the trial project database because this prototype runs on one machine." }
brain_sync { project: "/absolute/path/to/project", phase: "complete" }
Open a fresh session in the same project, optionally in a different supported coding tool. Ask it to retrieve the decision rather than infer the answer from your code:
brain_sync { project: "/absolute/path/to/project", phase: "start",
intent: "Review the trial storage decision", files: [] }
brain_ask { question: "Which database does the trial project use, and why?" }
Check that the returned card contains SQLite and the one-machine rationale. If the tool is
missing, reconnect the host and check the host integration table.
If the card is missing, confirm both sessions used the same project and that brain_note
reported a successful capture. A fresh brain only knows what has been recorded.
Change the trial decision explicitly, then ask again:
brain_note { area: "Storage",
text: "CORRECTION: Use PostgreSQL instead of SQLite for the trial project database because the trial now needs concurrent writes from several machines." }
brain_ask { question: "Which database does the trial project use now, and why?" }
brain_sync { project: "/absolute/path/to/project", phase: "complete" }
Inspect the returned source cards: PostgreSQL should be the current decision, with SQLite retained as superseded history. Confirm that the correction names the earlier decision; a correction cue alone is not a guarantee of a match. This small trial checks your capture and recall path. It does not establish retrieval quality for a larger brain or prove host automation.
For a team on different machines, follow the Git sharing steps and install in each clone. Standalone live presence and file-overlap warnings stay local to one machine and OS user; with KLYPIX network on each computer, they also cover teammates' sessions in the same project. Keep approved architecture records and stable conventions alongside the brain.
Everything below is reference: how each part works, what it writes, and where it stops. The contents list above links to each section.
The difference from a folder of notes is not the shape — it is that this memory is a mechanism, not a filing convention.
re-adopts stamp on the new card plus an earlier→current
edge; the original A→B→C history remains intact.brain_reconcile only proposes stale-vs-correction pairs for a human to
confirm.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.brain_ask with as_of: 2026-03-01 reweights
ranking by card lifecycle dates, so corrections made later do not leak backwards.brain_ask and
search_all_brains use BGE semantic ranking with lexical help for exact identifiers, paths, and
versions — still entirely on your machine. Without it, retrieval is keyword-only. 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.npx klypix-mcp install run by a person in a
terminal installs it: about 150 MB to download once, about 110 MB on disk after the files Node
never loads are removed. Skip it with --no-semantic (or KLYPIX_SEMANTIC=0). Installs with no
terminal — CI, scripts, an AI agent running the install — get it only with --semantic. The
Claude plugin never downloads it. Measured on the frozen 102-question set: the right card in the
top 5 for 54 questions with it, 19 without.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.
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 -y -p klypix-mcp 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.
Levels are honest. Only the config-writing side is tested for the link hosts; their host-side
behaviour is unverified.
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 — in the KLYPIX desktop app, Settings → Project → Connect Claude Desktop
writes this entry for you; or add it to claude_desktop_config.json by hand. Either way it needs
Node.js on the PC, and Claude Desktop must be quit completely (tray icon → Quit) and reopened before
it lists the tools:
{
"mcpServers": {
"klypix": {
"command": "npx",
"args": ["-y", "klypix-mcp", "--vault", "/absolute/path/to/canvases"]
}
}
}
The KLYPIX Claude plugin starts this server as npx -y klypix-mcp@<version>, with the version its
.claude-plugin/plugin.json names: one exact version, never
a range or latest. It sets three variables: KLYPIX_PLUGIN=1,
KLYPIX_PLUGIN_DATA=${CLAUDE_PLUGIN_DATA} and KLYPIX_VAULT=${CLAUDE_PROJECT_DIR}.
KLYPIX_PLUGIN=1 turns on plugin mode, which changes how the MCP server behaves and nothing
else. Every npx klypix-mcp command (install, link, doctor, sessions and the rest) works
exactly as described elsewhere in this README. Only KLYPIX_PLUGIN=1 turns plugin mode on;
CLAUDE_PLUGIN_ROOT on its own does not.
What plugin mode never does
KLYPIX_AUTO_UPDATE is set to. You run the version the plugin pins, and a newer version reaches
you only in a new plugin release.npx klypix-mcp install puts in
~/.claude/project-brain, and it never loads the optional on-device semantic model from that
folder. Search is keyword-only, so it never downloads model weights..mcp.json, .cursor/, .codex/config.toml and the rest) or the AGENTS.md brief block, in
this project or any other. Outside plugin mode, brain_sync and the updater do write these files;
Security and permissions explains when.~/.claude/settings.json, hooks, permissions or any
other host configuration.Network. Plugin mode makes two kinds of request, and both go to the public npm registry. The
first is npx downloading the pinned package when the plugin starts the server. The second is one
npm view klypix-mcp version, and it runs only when an agent calls brain_doctor with
check_npm: true. There are no other requests.
Programs it runs on your computer. Read-only git commands in your project (current branch,
tags, log) for coordination and release checks. Also brain_reopen, described at the end of this
section. And on Windows, show_in_klypix with bring_to_front: true while KLYPIX is closed asks
Windows to open that canvas file in KLYPIX (PowerShell Start-Process), at most once every 30
seconds; it never does so while KLYPIX is running.
The KLYPIX app, when it is running (local, not the network). On Windows, a tool call that needs
the KLYPIX app (App mode, under Human control in Klypix) talks to the app over a local named
pipe: inter-process communication on this PC. Plugin mode allows it, exactly as outside plugin
mode. Nothing connects when the server starts; on such a call it reads
%APPDATA%\klypix\agent-bridge\endpoint.json and the bridge token KLYPIX writes in
%LOCALAPPDATA%\klypix\agent-bridge. With KLYPIX closed, or its AI tools on this PC switch
off, nothing connects at all.
What it reads. In your project: brain.klypix, the .klypix canvases, the version field of
package.json and your git tags. On your computer: the coordination files in the table below. If
the KLYPIX desktop app is installed, it also reads the app's data folder (%APPDATA%\klypix),
read-only, to see whether the app is running, which canvases it has open, and the readings it saved
on cards, and, on a call that needs the running app, the app's bridge token (above). It never reads chat history, transcripts or Claude's memory.
What it writes, and where
brain_reopen. Sometimes a session leaves a note for another session that has already closed.
An agent can then call brain_reopen, and KLYPIX asks you first: in chat with Reopen and Not
now buttons, or in a small dialog (PowerShell on Windows, osascript on macOS, zenity or kdialog on
Linux). Only if you choose Reopen does it open a new, visible terminal that runs the app's own
resume command, claude --resume <id> or codex resume <id>. Reopen on your OK has the details.
After you uninstall the plugin. Claude Code removes the plugin and deletes its data folder.
These stay: your brain and canvases, which belong to you; any .claude/ folder a brain write
created in a project; and the presence lanes, write locks and restore points in
~/.claude/project-brain. Other KLYPIX tools on this computer share that folder. If you use none,
you can delete it.
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. When the call declares
files, the lessons that name those files come first, under "Lessons for your files": at most
four, ranked exact path, then file name, glob and folder. The Claude Code brief does the same for
the files the checkout is changing (uncommitted, and the last three commits), then lists the newest.
Briefs are not injected automatically on Cursor, Cline, Copilot, Gemini CLI or Antigravity — there are no lifecycle hooks on those hosts.
The coordination bench showed that an agent trusts the instruction file it was launched with over anything a tool or hook tells it, and that each host reads a different surface. So the brain's state is projected into those files, in two halves:
AGENTS.md (standing rules,
corrections, open handoff cards), refreshed by the Claude Code Stop hook only when its content
changed, so diffs stay quiet.CLAUDE.local.md at the project root (Claude Code loads it beside
CLAUDE.md; KLYPIX keeps it out of git through .git/info/exclude, never a committed file)
and into one section per project of the Codex global instructions file
(~/.codex/AGENTS.override.md when you have one, else ~/.codex/AGENTS.md). A project-level
AGENTS.override.md is never written: Codex loads one file per directory, so it would hide
your AGENTS.md.The block is a snapshot and says so: bounded to about 2.4KB, rewritten only when its content
changed (the time stamp alone never causes a write), with the keep-off evidence kept first when
the budget bites, and "nothing live" written in words so an older snapshot never stands. It
holds the same strings the hooks print, so the file and the session context cannot disagree.
Sections for projects not touched in a day are pruned from the Codex file, at most eight are
kept, and uninstall unlink strips the block (deleting CLAUDE.local.md only when nothing else
is in it). brain_sync remains the live source; the block tells the agent to call it.
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.
A marker can end with optional suffixes, in any order: closes: <card title or [[wikilink]]>,
ev: <file[:line]>, PR#<n>, verify: <command>, q: <the question this answers?> and
rule: <glob>[,<glob>] never "<text>" (or never /<regex>/, must "<text>",
listed-in <file>[,<file>], keep-eol, costly). They count
only as one run at the end of the line, written lowercase as key: value, and each value must
have its key's shape: references for ev:, a command for verify:, a question (question word
first, ? last) for q:. Anything else is kept as card text, so "a Q: and A: layout", "the ev:
field" or "every agent verify: the tag" never cuts a note short. A malformed segment after a
well-formed one also stays in the text, and the other suffixes still count; the hook tells the
agent on its next prompt. On ✓ and ~ markers a closes: is plain text, because those markers
close nothing. A closes: that will not act keeps the sentence as written: it names no live card,
or it names more than four. A closes: that does not come after the end of a sentence, a
[[wikilink]] or another suffix closes only a card it names by title. One whose named card is
already closed closes nothing else. A ~ update too thin to replace its card (fewer than six
content words and under half the card's) is appended to that card as a dated (~ amended …) line
instead. The card keeps its date, colour and probe, and previews show the newest amendment first.
The correction lands and nothing is lost.
A rule: suffix makes a new lesson (a decision, + or !) rule-ready. Its globs must name files
tracked in the repository and a /regex/ must compile; the rule lands as a visible
⚙ rule candidate: line on a 🛠️ card, and brain_rules propose reads it before any prose. It
checks nothing until a person approves the rule. A rule that fails those checks is not recorded,
the lesson is, and the hook says why on the next prompt. brain_note takes the same suffix at the
end of its text.
The Stop hook reads the whole transcript every time, so a ~ or ✓ line applies once. A marker
that an older hook (1.85 or 1.86.0) already captured is not captured again after an upgrade. If
1.86.0 cut the note short, the stub is restored to the full text in place. When a marker does not
do what it says, the next prompt tells the agent. A receipt left by a session that has ended goes
to the next session that starts in the project.
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.
Some lessons can be checked in a diff: every new route must also be in the route list, tests
in this folder must import shared code relatively, this file's line endings must not change. brain_rules turns those
lessons into rules in .klypix/rules.json, each citing the card it came from. A person approves
each rule with a code only they can print (npx klypix-mcp rules code promote <ids>). Until then
the rule is a candidate and checks nothing.
An active rule runs in three places: brain_sync names the rules for a session's files, the edit
hook reports findings to Claude Code and Codex as they edit, and the opt-in git hooks
(npx klypix-mcp check --install-hook) print them at commit and push. Rules warn by default. A
rule the person approves with --block stops the commit or push for any tool or person, and stops
Claude Code before it writes a forbidden line; Codex is only warned, because its hooks cannot
deny. A check is glob, regex and line-ending work over the diff: it takes
milliseconds, runs offline and uses no model. Overrides, bypasses and false alarms are recorded in
the brain, and npx klypix-mcp rules shows each rule's blocks, overrides and false alarms.
How to write, approve and retire rules: docs/brain-rules.md. To see what a
set of rules would have flagged on a repository's own history, scripts/brain-rules-proof.mjs
replays them over its pull requests and failed Actions logs, with what those runs cost.
A walk-through for teams: Stop AI agents repeating the same mistakes.
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.
brain_sync reports three kinds of overlap with other live sessions on the same brain:
git merge-tree, git 2.38 or newer) conflicts in named files, even though no
declared file overlaps. This sees committed work only: an uncommitted edit is invisible to git.
It also gets a one-time alert. Files the brain tooling regenerates on every branch (AGENTS.md,
rule files, .mcp.json, brain.klypix) are not counted.This warns. It does not prevent. Nothing blocks an edit. A session that never declared its files and was never observed editing is invisible to the file and folder checks.

Presence, overlap warnings and notes are local to one computer by default. Since klypix-mcp
1.106.0 they also reach a teammate's computer when KLYPIX network, a
small separate background program, is installed on both computers
(curl -fsSL https://klypix.com/network/install.sh | sh, or
irm https://klypix.com/network/install.ps1 | iex on Windows):
brain_sync also lists agent sessions in the same project on a teammate's computer, with their
one-line task and declared files, and gives the same exact-file overlap warning it gives for a
session on this machine.brain_message reaches those sessions too. Their ids start with net:. A note to every session
goes to this machine's sessions and theirs.What leaves the computer: the project key (a hash of the git remote), the one-line task, repository-relative file paths, and the text of a note you send to a session there. Cards, files, diffs and screens do not travel this way; the brain itself still moves through Git. There is no read receipt and no result reconciliation across computers. The warnings are advisory, exactly as on one computer.
Without the program nothing changes. It is off with KLYPIX_NETWORK=0 and in plugin mode. No
two-computer test run is published for it yet.
brain_message leaves one-time coordination notes for other sessions — live, idle, or recently
closed. Address a session by id: a live session gets the note on its next action; a session
KLYPIX has identified before that is not on the lane now (closed, or quiet) still receives a
directed note the moment it next acts — a directed note is kept 7 days, and the sender is told it
is queued, not delivered. That is what stops the human from being the courier between two
agents: the standing rule every host receives is that a message it would otherwise ask the person
to relay or paste is sent this way instead. Nothing here starts or wakes a session on its own — the
note waits until a person opens it, and the person decides when that is (see Reopen on your OK
below). 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, a note to every session expires after 24 hours and a
directed note after 7 days, and notes are never written into the brain.
A note to a session that has closed would otherwise wait until someone happens to open that
session again. When the person wants it handled sooner, the sending agent calls brain_reopen, and
KLYPIX asks the person — an in-chat Reopen / Not now prompt in apps that support MCP
elicitation (Claude Code, Codex), otherwise a small native dialog. Only on Reopen does KLYPIX
open that Claude Code or Codex session in a new, visible terminal, in the folder it worked in,
with the host's own resume command (claude --resume <id>, codex resume <id>); the session
receives the waiting note at its first action and the sender sees the receipt as usual.
npx klypix-mcp sessions lists this project's closed sessions and the notes
waiting for them; npx klypix-mcp sessions reopen <id> reopens one (--quiet lets it wait for
you instead of starting on the note).The case this exists for: a Claude Code session stops at its usage limit in the middle of a task, and the person opens Codex (or a fresh Claude Code) and says continue. Until 1.99.0 the only handoff was whatever the person pasted. Now there are two layers, and the person does not have to ask for either.
Automatic — whichever agent stopped. Each session's last state is recorded on the lane that already remembers sessions for two weeks, by whatever that host offers:
Own commits are the shas that session's git commit printed, never a branch range, because
twenty sessions can share one checkout. A session is listed when it stopped in the last 24 hours
without completing its task — quiet for ten minutes, or closed — and left a record. A session that
recorded nothing is never listed, so finished chats do not pile up.
The next session on the project, in any agent, sees ⏸️ Work other sessions may have left
unfinished at its first brain_sync when its task is to continue something ("continue what Codex
was doing on the invoice" puts that session first) or touches a file one of them touched. It sees the
same list at session start. Each record carries its status, files, commits, last words and resume
command. It says, in the text and in the JSON (state, working:false, holdsFiles:false), that
the session is not running, holds no claim on any file, and that a "do not touch" note it left no
longer applies: the list is history, not a lock. The agent takes a record over with
brain_handoff {action:"take", session:"<id>"} so peers see it is taken, then marks it done. This
layer is machine-local, like the rest of the lane.
Deliberate. When a session knows it is stopping — the person asks for a handoff, the context or
usage limit is near, the day ends, it is blocked, it is switching tool — it calls
brain_handoff {action:"write"} with the task, what is done, what is next in order, the files
and how to verify. That becomes a 🤝 HANDOFF card in the project brain: an open card the person can
see and correct on the canvas, with the files as evidence anchors, that travels with the repo and
syncs like every other card. It leads the session-start brief and the brain_sync start response
until a session takes it ({action:"take", id}) and finishes it ({action:"done", id}, which
archives it). A later handoff can name the earlier one it continues. The per-prompt hook nudges
the agent to write one when the person says handoff or names the limit.
Drafted by KLYPIX — when the session never got to write one. A usage limit, a crash or a
closed window leaves no time for brain_handoff. Since 1.103.0 the brain writes the card itself:
at the next brain_sync start or brain_handoff list of any session, a record that qualifies —
the session is closed or quiet for 30 minutes, left real work (its own commits, or touched files
and a reply tail), has no card and no taker, and its task was a human's, not an app's — becomes a
🤝 HANDOFF card on that session's behalf, reason interrupted. The card says Drafted: by KLYPIX
on its own line, lists only what git proved under Done, tells the reader to confirm the state
with git status before touching anything, and carries the session's last words verbatim. The
record and every list say the session wrote none. If the session resumes and completes its task,
the drafted card is archived at the next pass. Three drafts per pass at most; a draft can never
fail the sync that triggered it.
Conversation coverage. A card and the automatic reply tail can miss a later request.
Taking a card now checks its source conversation and reports needs-review, reviewed, or
unknown. brain_handoff {action:"review", id} returns paginated Claude Code or Codex
conversation turns, including user requests with no reply. Follow nextCursor with the returned
revision; after reading every page, acknowledge the final reviewToken with a summary of
completed and still-pending requests. Session-only takeovers use review with session to create
a reviewable draft first. The first review covers the whole conversation, including requests
that predate the card; changed source bytes invalidate the review and require another pass.
The saved review is an agent attestation, not proof of task completion. It never closes work.
Transcripts stay on this machine and are read only from the supported hosts' transcript folders.
Missing, malformed, ambiguous, oversized, or unsupported sources report unknown; an attachment
placeholder requires checking the original media. The reader is bounded to 128 MiB per transcript,
16 MiB per JSONL record, 8 MiB of conversation text, and 12,000 discovery entries. A limit never
silently drops turns or certifies coverage. Reconcile the card's Next list with the conversation
and repository evidence before continuing.
Host coverage (1.108.0). The shared handoff card works independently of the agent brand. Conversation recovery has separate coverage:
On a host without a native reader, preserve requests as they arrive with
brain_handoff {action:"capture", turns:[{id:"stable-turn-id", role:"user", at:1792860000000, text:"Observed request"}]}.
Use the actual known timestamp (milliseconds), stable ids for retries, and only text actually observed.
Capture assistant replies too. Do not manufacture missing history or timestamps. The server binds
capture to the connected session and project; callers cannot supply another session identity or a file path.
Later sessions use the same review workflow. New captured turns invalidate prior review tokens.
Repeated identical turns are deduplicated; conflicting reuse of an id is refused.
Capture is an explicit agent/tool action, not automatic access to an IDE's private chat store.
The result always identifies captured-only coverage and says full host history is UNKNOWN,
even after review. It cannot recover a request that was never captured. Host-name regression
fixtures verify the shared protocol, not end-to-end operation inside those applications.
Captured text stays outside the brain in ~/.claude/project-brain/handoff-captures, keyed by
project and session. It is not synced with the card and has no automatic expiry; local removal
makes coverage unavailable. Limits are 30 turns per call, 24,000 characters per turn and 8 MiB
per journal. Gemini discovery has a 128 MiB aggregate read budget and rejects ambiguous sources.
Durable decisions still go in the brain as cards — a handoff is the one card about work in flight, and it closes when the work lands.
When a task publishes a quantified or otherwise machine-checkable claim, it can attach one or more
versioned result manifests to brain_sync { phase: "complete" }. Each manifest binds the claim to a
report hash, producer/run provenance, the exact declared task scope, material artifact hashes,
evaluation outputs, public metric wording, input/configuration fingerprints, and named metrics with
counts and tolerances. Matching peer evidence is recorded as corroboration; conflicting or
incomparable evidence returns needs-reconciliation and keeps the task scope active.
The gate fails closed. Once a task submits result evidence, it cannot bypass an invalid or
conflicting result by retrying completion without the manifest, and that obligation survives worker
restart, hibernation, and transparent hot-swap. A fresh phase: "start" is the explicit boundary for
a new task. The strict schema and reusable validator are exported as klypix-mcp/result-reconcile.
Schema-v2 receipts can be converted into commit-bound publication evidence and independently checked
with klypix-mcp/release-evidence; legacy schema-v1 results remain usable for coordination but cannot
authorize publication.
Not a second brain. A shared one.
A brain nobody can inspect is a database with good marketing. The
KLYPIX desktop app renders the same brain.klypix as a living spatial map,
with health, freshness, provenance and orrery lenses, an unresolved-questions triage view, and a
one-click flow that connects a folder's brain to six coding agents. You can read, correct, archive
and re-link what your agents recorded.
The file is co-owned. When the app saves a brain it re-reads the disk copy inside the same capture lock the agent hooks use and union-merges instead of overwriting, so a card an agent captured while you had the file open is kept. The merge verifies its own output and aborts rather than emit a file missing a card. Deletes require an explicit tombstone, so a card that is merely absent is never inferred as deleted.
The app is a separate, proprietary Windows product. The format, this server and the hooks are Apache-2.0 and work with no app installed. The app's interface is available in English and Arabic (some newer panels are still English-only).
Beyond project brains, the same connection reads and writes the KLYPIX canvases (spaces) saved on your PC. Your AI tool reads what KLYPIX has already read, and the files a saved canvas holds:
read_canvas prints every card with its id; read_card_contents returns what is inside a card.
From what KLYPIX saved: the transcript on a video card, the text card Read contents made for a
reel or web page, an OCR card for a photo, a folder's file list. From the files embedded in the
saved canvas, with KLYPIX closed: a text file's words, a photo (a smaller copy when it is large),
and PDFs, Office and other files as a local path with the previews KLYPIX saved — see Reading
what is inside cards below. Audio and video come back as a path only; what they say comes from a
reading KLYPIX saved. For a reel, a web page or a video, choose Read contents in KLYPIX first
(select the card, press Enter), let the canvas save, then ask your AI tool — or, with KLYPIX open
on Windows, let your AI tool ask KLYPIX to read it (App mode below).klypix_status tells your AI tool what KLYPIX can do on this PC right now, and which step the person
has to take.%APPDATA%\klypix\agent-bridge\endpoint.json, no secret in it) make add_to_canvas refuse
that canvas and say why; project brains are the exception, because KLYPIX merges them. With an older
KLYPIX, add_to_canvas writes and its reply tells the person to close the canvas's tab and open it
again.On Windows, while the KLYPIX app is open and Settings → Project → AI tools on this PC is on (it is
on by default), the same connection reaches the running app. KLYPIX then runs its own code for the
request, so its keys, consents, caps, freeze and undo apply. With KLYPIX closed or the switch off,
every tool works in file mode as described above, and a step that needs the app says so in one
sentence (APP_NOT_RUNNING, ACCESS_OFF, BLOCKED, NEEDS_APP …).
Who pays for a new reading (paid_by):
refresh: true asks for a new one.still_reading with
retry_after_seconds; asking again with the same arguments picks up the same read and spends
nothing extra.read_card_contents still requires canvas and card_ids: to read what
the person selected in KLYPIX, call klypix_status first, which lists the canvas in front of
them and the selected card ids.since, storage and weight lenses have no name in brain_lens's view list, which
is frozen; klypix_status reports the lens the person has open.Control. AI tools are on by default. The person turns them off, or blocks one tool, in KLYPIX's Settings → Project, where every request is listed: time, tool, what it asked for, canvas and outcome, never card text, links or tokens. Tool names are what each AI tool reports about itself, so they are labels, not proof of identity.
How the connection works. While the switch is on, KLYPIX listens on a named pipe with a new
random name at every start and writes a new random token to
%LOCALAPPDATA%\klypix\agent-bridge\token, in your Windows profile. On each call that needs
the app (never at startup) klypix-mcp reads endpoint.json and the token again, and both sides
prove they hold the token before a request is sent; klypix-mcp sends nothing to a pipe that cannot
prove itself. The token and the pipe name are never logged, returned to the AI tool or shown by
brain_doctor. Any program running under your Windows account can read the token.
A canvas saved by KLYPIX keeps a copy of every file dropped on it. read_card_contents hands those
files to your AI tool as they are, so it reads them with its own model and its own file tools —
KLYPIX itself extracts nothing here (no OCR, transcription or document-text extraction; those run in
the KLYPIX app). Pass the ids read_canvas prints; every card with something inside has an
Inside: line saying what comes back.
A PDF, Office or text file that KLYPIX has already read also comes back with the text KLYPIX
saved from it, first (method: document_text), and the file by path beside it. That text is
used only while the card still holds the file it was read from: a reading of an earlier version
of the file is never served, shown by read_canvas or matched by search_canvases, and the
file itself is handed over as above.
Limits, and why:
read_card_contents
and in read_canvas). A photo that does not fit even as a smaller copy is named with the reason.extracted/ in the plugin's data folder when running as a Claude plugin, otherwise
<system temp>/klypix-mcp/extracted, named <sha-256 prefix>-<original name>. A file over 150 MB
is not copied out. An AI tool without a file-reading tool (Claude Desktop without a filesystem
connector) gets the previews and the path, not the whole PDF.Claims about a shared brain — "nothing is lost", "it stays fast" — are unfalsifiable until a stranger can re-run them, so the benchmark ships in the box ():
npx klypix-mcp bench # ~25s, or --quick for a smaller run
It measures concurrent-write safety across real OS processes, coordination latency, a 1,000-query soak with drift, and crash safety under SIGKILL — then prints the machine it ran on.
It runs a negative control first. Writers that bypass the lock go in before the real ones, because a "0 lost" number means nothing unless the same harness can see a loss. On the reference machine those unlocked writers lost 17 of 22 cards; the same contention through the lock protocol lost 0 of 46. If the control ever loses nothing, the run reports inconclusive instead of a pass.
Latest results, with hardware and date: BENCHMARKS.md.
Does it change what agents do? That needs real agents, so it lives in the repository rather than
the package: bench/coordination/ runs Claude Code or Codex on four
small repos where another session knows something the agent needs (a decision changed today, work
overlapping on another branch, a note from a session that has ended, a root cause another vendor's
session found). Each run is graded by a test written after the agent finishes, against no shared
channel, a human copy-paste, AGENTS.md kept tidy or appended, and KLYPIX over MCP only. Every number
is printed with its sample size and interval; tools it has not measured are listed as not measured.
--dry-run costs nothing and proves the graders.
One file in your repo, committed with your code — versioned, branchable, portable. So two developers already share one brain the way they share code: clone, branch, pull.
Be precise about what git does on its own: brain.klypix is a binary ZIP. Git shows
Bin 1308328 -> 1309005 bytes and produces zero line diffs, so out of the box a conflict on it is
an all-or-nothing take-ours or take-theirs, and a reviewer sees nothing. Card-level merge safety
comes from the KLYPIX engine — but since 1.48.0 you can hand that engine to git and read its
output in a PR:
npx klypix-mcp git-driver install # once per clone, in any repo
That registers a merge driver for *.klypix (a per-machine git config line plus a .gitattributes
rule you commit) and provisions the engine it needs. When two people change the brain and one
pulls, git calls the engine instead of stopping: new cards from both sides are kept, a card only
one side edited takes that edit, and a card edited differently on both sides keeps both
versions — the second as a linked twin, never a silent overwrite. (One exception to "takes that
edit": a card is never changed to mean exactly what its own conflict twin beside it already means
(the whole card, not only its words) — both versions stay as they are and the driver's summary line
says so. Delete the one you do not want.) Deletions travel too: a deleted
card leaves a receipt in the brain's Deleted cards, and the driver merges those three-way, so a
card deleted — or permanently deleted — on one branch stays out instead of coming back from the
other, unless the other branch edited it. That edit comes back as a new card when the deleting
branch recorded the delete (a receipt in its Deleted cards); when it did not, the edited card
simply stays. A permanently deleted card stays out even then: the driver's summary line counts the
edits it dropped, and they remain in that branch's git history. Before returning, the merge asserts
it still contains every surviving card from both sides and refuses rather than hand back a result
that lost one.
The honest boundary: a machine that has not run git-driver install simply gets the old binary
conflict — safe degradation, not corruption — and git keeps both parents of every merge, so even a
merge you dislike is reconstructable. It is a merge on pull, not live sync.
For review, two commands turn a binary blob into something a human can read:
npx klypix-mcp diff main # card-level: what was added / updated / removed
npx klypix-mcp pr-brief origin/main # the brain cards that reference this PR's changed files
diff compares meaning rather than bytes (a re-save restamps timestamps; that is not a change).
pr-brief matches a card's #file-… evidence anchors against the changed paths, so a reviewer
sees the decisions already recorded about the code in front of them. examples/github/brain-pr.yml
wires both into a sticky pull-request comment using nothing but the checkout and the default
GITHUB_TOKEN — no KLYPIX service in the path.
Concurrent sessions serialize behind a capture lock, and each write is a temp file plus an atomic rename, so a crash mid-write leaves the previous good file intact. The lock is advisory with a ~3.6-second budget: past that, a writer proceeds anyway and flags it in the health log, so sustained contention can still lose an update. That is a deliberate trade — dropping the markers was judged worse — but it is a real limit, not a guarantee.
Merging, tidying and gardening are built to keep every card nobody deleted (one deliberate exception: a card deleted permanently also leaves the other copies of the brain when they sync, an edited copy included, and the merge reports that edit). Deleting permanently is not a guarantee that the text is gone everywhere: a copy of the card that someone restored on another machine at about the same time, or resized or edited after restoring it, can stay there and has to be deleted there too; and restore points and git history keep what they already held. What none of them can undo is a deliberate-looking deletion: you select a dozen cards, delete them, and save. That is not a bug to prevent — a brain has to stay correctable, and an uncorrectable memory is worse than none — but it deserves a way back, because the brain is co-owned: hooks, the MCP server, commit capture and peers
Shared project memory for Claude Code, Codex and Cursor: decisions, corrections, overlap warnings.
{ "mcpServers": { "klypix-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}Tools
Noch keine Tool-Liste. Remote-Server erhalten eine nach dem ersten Health-Check.
FAQ
Kopieren Sie auf dieser Seite die stdio-Konfiguration für Cursor, Claude Desktop, Claude Code oder VS Code. Sie nutzt die Installation des Herausgebers, keinen PlugMCP-Proxy.
In diesem Eintrag ist keine erforderliche Umgebungsvariable aufgeführt.
Klypix läuft lokal über stdio.
Zuletzt geprüft: 2026-11-16. Shared project memory for Claude Code, Codex and Cursor: decisions, corrections, overlap warnings.