klypix-mcp 1.106.1 → 1.106.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +217 -128
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,106 +1,137 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# klypix-mcp
|
|
4
|
+
|
|
5
|
+
### The shared project brain for your coding agents.
|
|
2
6
|
|
|
3
7
|
**Every project gets a brain.**
|
|
4
8
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
[
|
|
10
|
-
|
|
11
|
-
your agent's provider can still receive what the agent reads. Integration depth differs by host — see
|
|
12
|
-
[Supported hosts](#supported-hosts-and-their-integration-level).
|
|
13
|
-
|
|
14
|
-
Klypix is a **portable project workspace with a shared brain**. This repository provides its
|
|
15
|
-
local MCP server for shared project memory in coding tools. The **Apache-2.0 engine works without the KLYPIX
|
|
16
|
-
desktop app or a KLYPIX account**. The optional
|
|
17
|
-
[Windows workspace](https://klypix.com/developers) lets people inspect the same project brain
|
|
18
|
-
beside their files. App-based sharing has its own cloud path; see [Security and permissions](#security-and-permissions).
|
|
19
|
-
|
|
20
|
-
For the **Projects & Ideas** path — saved project materials in ChatGPT or Claude chat — follow
|
|
21
|
-
[Save project materials and use them with your assistant](https://klypix.com/guides/connect-klypix-to-chatgpt-and-claude).
|
|
22
|
-
That uses Klypix's separate hosted connection for the spaces you authorize. Installing this local
|
|
23
|
-
MCP server does not set up that connection.
|
|
9
|
+
[](https://www.npmjs.com/package/klypix-mcp)
|
|
10
|
+
[](https://github.com/dahshanlabs/klypix-mcp/actions/workflows/ci.yml)
|
|
11
|
+
[](LICENSE)
|
|
12
|
+
[](package.json)
|
|
13
|
+
[](https://modelcontextprotocol.io)
|
|
14
|
+
[](https://glama.ai/mcp/servers/dahshanlabs/klypix-mcp)
|
|
24
15
|
|
|
25
|
-
|
|
26
|
-
[Supported hosts](#supported-hosts-and-their-integration-level) ·
|
|
27
|
-
[Privacy](#security-and-permissions) · [Limits](#current-limitations) · [Uninstall](#uninstall)
|
|
16
|
+
</div>
|
|
28
17
|
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
18
|
+
Shared project memory for **Claude Code, Codex, Cursor** and other MCP coding tools. One
|
|
19
|
+
`brain.klypix` file, committed with your code, holds the project's decisions, corrections and open
|
|
20
|
+
questions. Supported agents read it at the start of a task and add to it as they work; how much of
|
|
21
|
+
that happens on its own depends on the host. People can open the same file and correct it.
|
|
32
22
|
|
|
33
|
-
|
|
34
24
|
|
|
35
|
-
<sub>
|
|
36
|
-
|
|
37
|
-
hand-recorded, and re-rendered when the server's responses change).</sub>
|
|
25
|
+
<sub>A 14-second cut of the sessions film from klypix.com.
|
|
26
|
+
[Real terminal output](#60-seconds-two-agents-one-project) is further down.</sub>
|
|
38
27
|
|
|
39
28
|
**▶ Watch:** [For coding teams (40 s, with sound)](https://klypix.com/media/films/sessions-16x9-en.mp4) ·
|
|
40
|
-
[
|
|
29
|
+
[Correct it once (20 s)](https://klypix.com/media/films/correct-16x9-en.mp4) ·
|
|
41
30
|
[Full tour (4 min)](https://klypix.com/media/films/tour-16x9-en.mp4) ·
|
|
42
31
|
[KLYPIX network](https://klypix.com/network)
|
|
43
32
|
|
|
44
|
-
|
|
33
|
+
## Install in three steps
|
|
45
34
|
|
|
46
|
-
|
|
47
|
-
npx klypix-mcp install
|
|
48
|
-
```
|
|
35
|
+
You need **Node.js 20 or newer** (`node -v`).
|
|
49
36
|
|
|
50
|
-
|
|
51
|
-
registers the `.klypix` merge driver if this is a git repo, and exits only after a real MCP
|
|
52
|
-
handshake has counted the tools that answered.
|
|
37
|
+
1. **Run this inside your project:**
|
|
53
38
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
does not prove that your host has loaded the tools or that a particular decision was retrieved.
|
|
39
|
+
```bash
|
|
40
|
+
npx klypix-mcp install
|
|
41
|
+
```
|
|
58
42
|
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
43
|
+
It gives the project a `brain.klypix` if it has none, wires the editors it finds on this
|
|
44
|
+
machine, and checks that the tools answer before it exits.
|
|
45
|
+
|
|
46
|
+
2. **Reopen your coding tool**, or reconnect its MCP server, and allow the KLYPIX tools if it asks.
|
|
47
|
+
|
|
48
|
+
3. **Check it.** Run `npx klypix-mcp doctor`, then
|
|
49
|
+
[record your first decision and correction](#your-first-decision-and-correction) and ask for it
|
|
50
|
+
from a fresh session.
|
|
51
|
+
|
|
52
|
+
## What you get
|
|
53
|
+
|
|
54
|
+
- **Decisions that carry over.** The next session, in the same tool or another one, starts from
|
|
55
|
+
what the project already decided: on its own in Claude Code, and when the agent calls
|
|
56
|
+
`brain_sync` in other hosts. A correction replaces the old decision, and the old card stays as
|
|
57
|
+
history.
|
|
58
|
+
- **A heads-up when work overlaps.** Each session says what it is doing and which files it expects
|
|
59
|
+
to touch. When two sessions name the same file, both are warned. KLYPIX warns; it never blocks an
|
|
60
|
+
edit. This works on one computer. With [KLYPIX network](https://klypix.com/network)
|
|
61
|
+
installed on both computers (klypix-mcp 1.106.0 or later), it also lists sessions in the same
|
|
62
|
+
project on a teammate's computer.
|
|
63
|
+
- **Notes and handoffs between sessions.** An agent can leave a note for another session, even one
|
|
64
|
+
that has closed. The note arrives at that session's next KLYPIX action, so you are not the one
|
|
65
|
+
copying it across. When a session stops before its work is done, the next session on this
|
|
66
|
+
computer is shown what it was doing, and a handoff card in the brain carries the next steps
|
|
67
|
+
through Git.
|
|
68
|
+
- **A git guard for a shared checkout (Claude Code).** When several sessions share one checkout, a
|
|
69
|
+
git command that would sweep another live session's uncommitted work into your commit is stopped.
|
|
70
|
+
A command that would throw work away saves a rescue copy first, then asks you. It covers git
|
|
71
|
+
commands run through Claude Code's tools, on one computer.
|
|
72
|
+
- **A file you own.** The brain is one `.klypix` file in your repo: a plain ZIP, versioned with
|
|
73
|
+
Git. The engine is Apache-2.0, runs on your machine, and works without the KLYPIX app or an
|
|
74
|
+
account. Brain data stays in your files; your agent's model provider still receives what the
|
|
75
|
+
agent reads.
|
|
76
|
+
|
|
77
|
+
## Hosts
|
|
78
|
+
|
|
79
|
+
How deep the integration goes depends on the host. The [full table](#supported-hosts-and-their-integration-level)
|
|
80
|
+
has the details.
|
|
81
|
+
|
|
82
|
+
| Host | What it gets | Set up by |
|
|
83
|
+
|---|---|---|
|
|
84
|
+
| **Claude Code** | Six lifecycle hooks (1.105.0 and later): a brief at session start, context on each prompt, automatic capture at turn end, presence and the git guard | `install` |
|
|
85
|
+
| **Codex** | Native MCP tools, presence and `brain_sync`; optional hooks with `--codex-hooks`. No automatic capture | `install` |
|
|
86
|
+
| **Cursor, Cline, VS Code (Copilot / Continue), Gemini CLI, Antigravity** | MCP config and an always-on rules file. The agent calls `brain_sync` and `brain_note` itself | `install`, for the editors it finds, or `link` |
|
|
87
|
+
| **Windsurf, Aider** | A rules file. Windsurf uses its own global MCP config; Aider uses the command line | `link` |
|
|
88
|
+
| **Claude Desktop** | A one-time config entry | The KLYPIX app's Settings, or by hand |
|
|
89
|
+
| **Claude, as a plugin** | One pinned version, keyword search, no hooks | [klypix-plugin](https://github.com/dahshanlabs/klypix-plugin) |
|
|
63
90
|
|
|
64
|
-
|
|
65
|
-
|
|
91
|
+
klypix-mcp 1.106.0 has 26 MCP tools on Linux and macOS and 27 on Windows, where `show_in_klypix` is
|
|
92
|
+
added. `npx klypix-mcp doctor` shows the count for your install.
|
|
66
93
|
|
|
67
94
|
> **One project. Many agents. One current understanding.**
|
|
68
95
|
|
|
69
|
-
|
|
70
|
-
router, a worktree manager
|
|
71
|
-
|
|
72
|
-
[](https://github.com/dahshanlabs/klypix-mcp/actions/workflows/ci.yml)
|
|
73
|
-
[](https://www.npmjs.com/package/klypix-mcp)
|
|
74
|
-
[](LICENSE)
|
|
75
|
-
[](package.json)
|
|
76
|
-
[](https://modelcontextprotocol.io)
|
|
77
|
-
[](https://glama.ai/mcp/servers/dahshanlabs/klypix-mcp)
|
|
78
|
-
[](BENCHMARKS.md)
|
|
79
|
-
|
|
80
|
-
## New in 1.106: teammates on other computers
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
With [KLYPIX network](https://klypix.com/network) installed on both computers (a small background
|
|
85
|
-
program, `curl -fsSL https://klypix.com/network/install.sh | sh`, or `irm https://klypix.com/network/install.ps1 | iex`
|
|
86
|
-
on Windows), `brain_sync` also lists agent sessions on your teammates' computers in the same
|
|
87
|
-
project, with their intent and declared files, and gives the same exact-file overlap warning it gives
|
|
88
|
-
for a session on this machine. `brain_message` reaches those sessions too (their ids start with
|
|
89
|
-
`net:`); a broadcast goes to this machine's sessions and theirs.
|
|
90
|
-
|
|
91
|
-
Only the project key (a hash of the git remote), the one-line intent and repository-relative file
|
|
92
|
-
paths leave the computer, plus the text of a note you send to a session there. There is no read
|
|
93
|
-
receipt and no result reconciliation across computers. Without the program nothing changes; it is
|
|
94
|
-
off in plugin mode and with `KLYPIX_NETWORK=0`.
|
|
96
|
+
KLYPIX does not launch, run, supervise or replace your agents. It is not an agent runtime, a model
|
|
97
|
+
router, a worktree manager or a replacement for Git. It holds what the project currently believes.
|
|
95
98
|
|
|
96
|
-
|
|
99
|
+
KLYPIX is a **portable project workspace with a shared brain**. This repository is its local MCP
|
|
100
|
+
server. The optional [Windows workspace](https://klypix.com/developers) lets people inspect the same
|
|
101
|
+
brain beside their files; app-based sharing has its own cloud path (see
|
|
102
|
+
[Security and permissions](#security-and-permissions)). For the **Projects & Ideas** path, saved
|
|
103
|
+
project materials in ChatGPT or Claude chat, follow
|
|
104
|
+
[Save project materials and use them with your assistant](https://klypix.com/guides/connect-klypix-to-chatgpt-and-claude).
|
|
105
|
+
That uses KLYPIX's separate hosted connection for the spaces you authorize; installing this local
|
|
106
|
+
server does not set it up.
|
|
97
107
|
|
|
98
|
-
[
|
|
108
|
+
**Guides:** [shared project memory setup](https://klypix.com/guides/shared-project-memory) ·
|
|
109
|
+
[memory tools comparison](https://klypix.com/guides/shared-project-memory-tools) (it links each
|
|
110
|
+
tool's official documentation and says that KLYPIX wrote it) · [klypix.com/klypix-mcp](https://klypix.com/klypix-mcp)
|
|
99
111
|
|
|
100
|
-
|
|
101
|
-
carry forward into supported coding-agent sessions.
|
|
112
|
+
---
|
|
102
113
|
|
|
103
|
-
|
|
114
|
+
## Contents
|
|
115
|
+
|
|
116
|
+
- **Start:** [The problem](#the-problem) · [60 seconds: two agents, one project](#60-seconds-two-agents-one-project) ·
|
|
117
|
+
[Quick start](#quick-start) · [Your first decision and correction](#your-first-decision-and-correction)
|
|
118
|
+
- **[Reference](#reference):** [How the brain works](#how-the-brain-works) ·
|
|
119
|
+
[Supported hosts](#supported-hosts-and-their-integration-level) ·
|
|
120
|
+
[Running as a Claude plugin](#running-as-a-claude-plugin) · [Task briefing](#task-briefing) ·
|
|
121
|
+
[Capture and corrections](#capture-and-corrections) · [Presence and task intent](#presence-and-task-intent) ·
|
|
122
|
+
[Overlap warnings](#overlap-warnings) ·
|
|
123
|
+
[Teammates on other computers](#teammates-on-other-computers-klypix-network) ·
|
|
124
|
+
[Handoffs and messages](#handoffs-and-messages) · [Evidence-gated completion](#evidence-gated-completion) ·
|
|
125
|
+
[Human control in KLYPIX](#human-control-in-klypix) · [Measure it yourself](#measure-it-yourself) ·
|
|
126
|
+
[Git and concurrency](#git-and-concurrency) ·
|
|
127
|
+
[The git guard for a shared checkout](#whose-is-this-the-git-guard-for-a-shared-checkout) ·
|
|
128
|
+
[The command line](#the-command-line) · [The verbs](#the-verbs-26-and-27-on-windows) ·
|
|
129
|
+
[One file you can hold](#one-file-you-can-hold) · [Use it as a library](#use-it-as-a-library) ·
|
|
130
|
+
[A2A](#also-speaks-a2a-protocol-v030--experimental) ·
|
|
131
|
+
[Updates](#updates--the-propagation-contract) · [Security and permissions](#security-and-permissions) ·
|
|
132
|
+
[Current limitations](#current-limitations) · [Numbers and methodology](#numbers-and-methodology) ·
|
|
133
|
+
[Uninstall](#uninstall)
|
|
134
|
+
- [Contributing](#contributing) · [Why this exists](#why-this-exists) · [Licence](#licence)
|
|
104
135
|
|
|
105
136
|
---
|
|
106
137
|
|
|
@@ -122,6 +153,12 @@ Your agents may run independently. Their project understanding should not.
|
|
|
122
153
|
|
|
123
154
|
## 60 seconds: two agents, one project
|
|
124
155
|
|
|
156
|
+
|
|
157
|
+
|
|
158
|
+
<sub>Real output, not a mockup: both panes run a real MCP client against this server
|
|
159
|
+
([docs/demo/](docs/demo/) — the GIF is rendered by CI from a scripted tape against this server, not
|
|
160
|
+
hand-recorded, and re-rendered when the server's responses change).</sub>
|
|
161
|
+
|
|
125
162
|
Illustrative calls and responses: replace `/absolute/path/to/project` with the same project root
|
|
126
163
|
in both sessions (for example, `C:/work/api` on Windows).
|
|
127
164
|
|
|
@@ -211,8 +248,8 @@ broken entry dies in ~100ms with `Connection closed` and is reported, not shippe
|
|
|
211
248
|
|
|
212
249
|
What goes where:
|
|
213
250
|
|
|
214
|
-
- **Machine-global, once** — the engine + runtime in `~/.claude/project-brain`, Claude Code's
|
|
215
|
-
lifecycle hooks in `~/.claude/settings.json`, and the `~/.codex/AGENTS.md` guidance block. Claude
|
|
251
|
+
- **Machine-global, once** — the engine + runtime in `~/.claude/project-brain`, Claude Code's six
|
|
252
|
+
lifecycle hooks (five before 1.105.0) in `~/.claude/settings.json`, and the `~/.codex/AGENTS.md` guidance block. Claude
|
|
216
253
|
Code is therefore covered in every project on that machine that has a `./brain.klypix`.
|
|
217
254
|
- **Per project** — MCP config and rules for Cursor, Codex, Cline, Windsurf, Copilot, Gemini CLI /
|
|
218
255
|
Antigravity and Aider. Run `install` once inside each project.
|
|
@@ -319,12 +356,18 @@ trial does not plan source-code edits.
|
|
|
319
356
|
|
|
320
357
|
For a team on different machines, follow the [Git sharing steps](https://klypix.com/guides/shared-project-memory#team)
|
|
321
358
|
and install in each clone. Standalone live presence and file-overlap warnings stay local to one
|
|
322
|
-
machine and OS user; with [KLYPIX network](#
|
|
323
|
-
computer, they also cover teammates' sessions in the same project. Keep approved architecture
|
|
359
|
+
machine and OS user; with [KLYPIX network](#teammates-on-other-computers-klypix-network) on each
|
|
360
|
+
computer, they also cover teammates' sessions in the same project. Keep approved architecture
|
|
361
|
+
records and stable conventions alongside the brain.
|
|
324
362
|
|
|
325
363
|
---
|
|
326
364
|
|
|
327
|
-
##
|
|
365
|
+
## Reference
|
|
366
|
+
|
|
367
|
+
Everything below is reference: how each part works, what it writes, and where it stops. The
|
|
368
|
+
[contents](#contents) list above links to each section.
|
|
369
|
+
|
|
370
|
+
### How the brain works
|
|
328
371
|
|
|
329
372
|
The difference from a folder of notes is not the shape — it is that this memory is a mechanism,
|
|
330
373
|
not a filing convention.
|
|
@@ -362,7 +405,7 @@ not a filing convention.
|
|
|
362
405
|
("Getting this brain ready for search by meaning: 900 of 3,670 cards so far, about 5 min left").
|
|
363
406
|
After that, only new or edited cards are prepared.
|
|
364
407
|
|
|
365
|
-
|
|
408
|
+
#### Bounded semantic-memory runtime
|
|
366
409
|
|
|
367
410
|
Long-lived MCP and A2A workers use the bounded semantic-memory runtime by default. Models load only
|
|
368
411
|
when semantic work is requested, native inference is serialized per process, embedding work is
|
|
@@ -386,7 +429,7 @@ excludes the owning IDE/chat application's RAM, redacts command-line secrets, an
|
|
|
386
429
|
brain or terminates a process. Multiple processes under one host are reported as parallel sessions,
|
|
387
430
|
not called duplicates without an authoritative logical-session receipt.
|
|
388
431
|
|
|
389
|
-
|
|
432
|
+
#### Project Map: current structure beside project understanding
|
|
390
433
|
|
|
391
434
|
If the project contains a compatible NetworkX node-link `graph.json`, agents can ask for bounded
|
|
392
435
|
code-structure evidence and current brain context in one read-only call:
|
|
@@ -421,16 +464,14 @@ workflow has `contents: read`, pins every action by commit SHA, pins `graphifyy=
|
|
|
421
464
|
the graph contract, and uploads `graphify-out/` as a 14-day build artifact. This is opt-in CI code:
|
|
422
465
|
the local MCP tool still never installs or launches Graphify.
|
|
423
466
|
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
## Supported hosts and their integration level
|
|
467
|
+
### Supported hosts and their integration level
|
|
427
468
|
|
|
428
469
|
Levels are honest. Only the config-writing side is tested for the `link` hosts; their host-side
|
|
429
470
|
behaviour is unverified.
|
|
430
471
|
|
|
431
472
|
| Host | Level | Wired by | Brief into context | Decision capture | Live presence |
|
|
432
473
|
|---|---|---|---|---|---|
|
|
433
|
-
| **Claude Code** | Full automatic (
|
|
474
|
+
| **Claude Code** | Full automatic (6 lifecycle hooks since 1.105.0) | `install` | Automatic at session start, task-ranked retrieval per prompt | **Automatic** at turn end | Yes |
|
|
434
475
|
| **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 |
|
|
435
476
|
| **Cursor** | MCP config + always-on rules file | `link` | Model must call `brain_sync` | Model must call `brain_note` | For the MCP connection |
|
|
436
477
|
| **Cline** | MCP config + always-on rules file | `link` | Model must call `brain_sync` | Model must call `brain_note` | For the MCP connection |
|
|
@@ -461,11 +502,10 @@ it lists the tools:
|
|
|
461
502
|
}
|
|
462
503
|
```
|
|
463
504
|
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
## Running as a Claude plugin
|
|
505
|
+
### Running as a Claude plugin
|
|
467
506
|
|
|
468
|
-
The KLYPIX Claude plugin starts this server as `npx -y klypix-mcp
|
|
507
|
+
The KLYPIX Claude plugin starts this server as `npx -y klypix-mcp@<version>`, with the version its
|
|
508
|
+
`.claude-plugin/plugin.json` names: one exact version, never
|
|
469
509
|
a range or `latest`. It sets three variables: `KLYPIX_PLUGIN=1`,
|
|
470
510
|
`KLYPIX_PLUGIN_DATA=${CLAUDE_PLUGIN_DATA}` and `KLYPIX_VAULT=${CLAUDE_PROJECT_DIR}`.
|
|
471
511
|
`KLYPIX_PLUGIN=1` turns on **plugin mode**, which changes how the MCP server behaves and nothing
|
|
@@ -537,9 +577,7 @@ created in a project; and the presence lanes, write locks and restore points in
|
|
|
537
577
|
`~/.claude/project-brain`. Other KLYPIX tools on this computer share that folder. If you use none,
|
|
538
578
|
you can delete it.
|
|
539
579
|
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
## Task briefing
|
|
580
|
+
### Task briefing
|
|
543
581
|
|
|
544
582
|
Every Claude Code session starts already knowing the project: a bounded brief of at most 2KB in
|
|
545
583
|
context, with the full brief written to disk for when broad history or status work needs it.
|
|
@@ -553,7 +591,7 @@ so fresh relevant findings are not crowded out by older area vocabulary.
|
|
|
553
591
|
Briefs are **not** injected automatically on Cursor, Cline, Copilot, Gemini CLI or Antigravity —
|
|
554
592
|
there are no lifecycle hooks on those hosts.
|
|
555
593
|
|
|
556
|
-
|
|
594
|
+
#### The live projection — the file the agent obeys
|
|
557
595
|
|
|
558
596
|
The coordination bench showed that an agent trusts the instruction file it was launched with
|
|
559
597
|
over anything a tool or hook tells it, and that each host reads a different surface. So the
|
|
@@ -580,7 +618,7 @@ Sections for projects not touched in a day are pruned from the Codex file, at mo
|
|
|
580
618
|
kept, and `uninstall unlink` strips the block (deleting `CLAUDE.local.md` only when nothing else
|
|
581
619
|
is in it). `brain_sync` remains the live source; the block tells the agent to call it.
|
|
582
620
|
|
|
583
|
-
|
|
621
|
+
### Capture and corrections
|
|
584
622
|
|
|
585
623
|
`brain_note` accepts structured supporting references and inert verification text:
|
|
586
624
|
|
|
@@ -646,7 +684,7 @@ only (explicit correction cues, opposite-polarity pairs), never mere topical sim
|
|
|
646
684
|
means no contradiction signal was found — not verified consistency. A memory that cannot disagree
|
|
647
685
|
with you is flattery.
|
|
648
686
|
|
|
649
|
-
|
|
687
|
+
### Presence and task intent
|
|
650
688
|
|
|
651
689
|
An active session means an authorized MCP connection or host lifecycle adapter that heartbeated
|
|
652
690
|
within the TTL. A row in a recent-chat list is history, not presence.
|
|
@@ -662,7 +700,7 @@ Future hosts get baseline support merely by connecting the MCP server. A deeper
|
|
|
662
700
|
`peekMessages` and `receiveMessages`. The shared contract accepts `id`, `client`, `surface`,
|
|
663
701
|
`model`, `branch`, `intent`, touched `files`, and adapter `channel`.
|
|
664
702
|
|
|
665
|
-
|
|
703
|
+
### Overlap warnings
|
|
666
704
|
|
|
667
705
|
`brain_sync` reports three kinds of overlap with other live sessions on the same brain:
|
|
668
706
|
|
|
@@ -681,7 +719,32 @@ Future hosts get baseline support merely by connecting the MCP server. A deeper
|
|
|
681
719
|
This warns. It does not prevent. Nothing blocks an edit. A session that never declared its files
|
|
682
720
|
and was never observed editing is invisible to the file and folder checks.
|
|
683
721
|
|
|
684
|
-
|
|
722
|
+
### Teammates on other computers (KLYPIX network)
|
|
723
|
+
|
|
724
|
+
|
|
725
|
+
|
|
726
|
+
Presence, overlap warnings and notes are local to one computer by default. Since klypix-mcp
|
|
727
|
+
1.106.0 they also reach a teammate's computer when [KLYPIX network](https://klypix.com/network), a
|
|
728
|
+
small separate background program, is installed on both computers
|
|
729
|
+
(`curl -fsSL https://klypix.com/network/install.sh | sh`, or
|
|
730
|
+
`irm https://klypix.com/network/install.ps1 | iex` on Windows):
|
|
731
|
+
|
|
732
|
+
- `brain_sync` also lists agent sessions in the same project on a teammate's computer, with their
|
|
733
|
+
one-line task and declared files, and gives the same exact-file overlap warning it gives for a
|
|
734
|
+
session on this machine.
|
|
735
|
+
- `brain_message` reaches those sessions too. Their ids start with `net:`. A note to every session
|
|
736
|
+
goes to this machine's sessions and theirs.
|
|
737
|
+
|
|
738
|
+
What leaves the computer: the project key (a hash of the git remote), the one-line task,
|
|
739
|
+
repository-relative file paths, and the text of a note you send to a session there. Cards, files,
|
|
740
|
+
diffs and screens do not travel this way; the brain itself still moves through Git. There is no
|
|
741
|
+
read receipt and no result reconciliation across computers. The warnings are advisory, exactly as
|
|
742
|
+
on one computer.
|
|
743
|
+
|
|
744
|
+
Without the program nothing changes. It is off with `KLYPIX_NETWORK=0` and in plugin mode. No
|
|
745
|
+
two-computer test run is published for it yet.
|
|
746
|
+
|
|
747
|
+
### Handoffs and messages
|
|
685
748
|
|
|
686
749
|
`brain_message` leaves one-time coordination notes for other sessions — live, idle, or recently
|
|
687
750
|
closed. Address a session by id: a live session gets the note on its next action; a session
|
|
@@ -702,7 +765,7 @@ instead of silently looking delivered. The send-time audience is fixed, unresolv
|
|
|
702
765
|
fail closed, the core lane is machine-local, a note to every session expires after 24 hours and a
|
|
703
766
|
directed note after 7 days, and notes are never written into the brain.
|
|
704
767
|
|
|
705
|
-
|
|
768
|
+
#### Reopen on your OK
|
|
706
769
|
|
|
707
770
|
A note to a session that has closed would otherwise wait until someone happens to open that
|
|
708
771
|
session again. When the person wants it handled sooner, the sending agent calls `brain_reopen`, and
|
|
@@ -726,7 +789,7 @@ receives the waiting note at its first action and the sender sees the receipt as
|
|
|
726
789
|
waiting for them; `npx klypix-mcp sessions reopen <id>` reopens one (`--quiet` lets it wait for
|
|
727
790
|
you instead of starting on the note).
|
|
728
791
|
|
|
729
|
-
|
|
792
|
+
#### Session handoff — continue in the next session, with any agent
|
|
730
793
|
|
|
731
794
|
The case this exists for: a Claude Code session stops at its usage limit in the middle of a task,
|
|
732
795
|
and the person opens Codex (or a fresh Claude Code) and says *continue*. Until 1.99.0 the only
|
|
@@ -782,7 +845,7 @@ fail the sync that triggered it.
|
|
|
782
845
|
Durable decisions still go in the brain as cards — a handoff is the one card about *work in
|
|
783
846
|
flight*, and it closes when the work lands.
|
|
784
847
|
|
|
785
|
-
|
|
848
|
+
### Evidence-gated completion
|
|
786
849
|
|
|
787
850
|
When a task publishes a quantified or otherwise machine-checkable claim, it can attach one or more
|
|
788
851
|
versioned result manifests to `brain_sync { phase: "complete" }`. Each manifest binds the claim to a
|
|
@@ -799,7 +862,7 @@ Schema-v2 receipts can be converted into commit-bound publication evidence and i
|
|
|
799
862
|
with `klypix-mcp/release-evidence`; legacy schema-v1 results remain usable for coordination but cannot
|
|
800
863
|
authorize publication.
|
|
801
864
|
|
|
802
|
-
|
|
865
|
+
### Human control in Klypix
|
|
803
866
|
|
|
804
867
|
> **Not a second brain. A shared one.**
|
|
805
868
|
|
|
@@ -819,7 +882,7 @@ The app is a separate, proprietary Windows product. The format, this server and
|
|
|
819
882
|
Apache-2.0 and work with no app installed. The app's interface is available in English and Arabic
|
|
820
883
|
(some newer panels are still English-only).
|
|
821
884
|
|
|
822
|
-
|
|
885
|
+
#### KLYPIX canvases and your AI tool
|
|
823
886
|
|
|
824
887
|
Beyond project brains, the same connection reads and writes the KLYPIX canvases (spaces) saved on
|
|
825
888
|
your PC. **Your AI tool reads what KLYPIX has already read, and the files a saved canvas holds:**
|
|
@@ -844,7 +907,7 @@ your PC. **Your AI tool reads what KLYPIX has already read, and the files a save
|
|
|
844
907
|
again.
|
|
845
908
|
- Text that comes back from cards, pages, reels and files is fenced as data, never instructions.
|
|
846
909
|
|
|
847
|
-
|
|
910
|
+
#### App mode: your AI tool uses KLYPIX while it is open
|
|
848
911
|
|
|
849
912
|
On Windows, while the KLYPIX app is open and **Settings → Project → AI tools on this PC** is on (it is
|
|
850
913
|
on by default), the same connection reaches the running app. KLYPIX then runs its own code for the
|
|
@@ -899,7 +962,7 @@ prove they hold the token before a request is sent; klypix-mcp sends nothing to
|
|
|
899
962
|
prove itself. The token and the pipe name are never logged, returned to the AI tool or shown by
|
|
900
963
|
`brain_doctor`. Any program running under your Windows account can read the token.
|
|
901
964
|
|
|
902
|
-
|
|
965
|
+
#### Reading what is inside cards
|
|
903
966
|
|
|
904
967
|
A canvas saved by KLYPIX keeps a copy of every file dropped on it. `read_card_contents` hands those
|
|
905
968
|
files to your AI tool as they are, so it reads them with its own model and its own file tools —
|
|
@@ -937,10 +1000,11 @@ Limits, and why:
|
|
|
937
1000
|
it while it runs), so it cannot be handed over from the saved canvas; the answer says so.
|
|
938
1001
|
- Cards inside a box locked from AI tools are never read, copied or attached.
|
|
939
1002
|
|
|
940
|
-
|
|
1003
|
+
### Measure it yourself
|
|
941
1004
|
|
|
942
1005
|
Claims about a shared brain — "nothing is lost", "it stays fast" — are unfalsifiable until a
|
|
943
|
-
stranger can re-run them, so the benchmark ships in the box
|
|
1006
|
+
stranger can re-run them, so the benchmark ships in the box
|
|
1007
|
+
([](BENCHMARKS.md)):
|
|
944
1008
|
|
|
945
1009
|
```bash
|
|
946
1010
|
npx klypix-mcp bench # ~25s, or --quick for a smaller run
|
|
@@ -965,7 +1029,7 @@ channel, a human copy-paste, `AGENTS.md` kept tidy or appended, and KLYPIX over
|
|
|
965
1029
|
is printed with its sample size and interval; tools it has not measured are listed as not measured.
|
|
966
1030
|
`--dry-run` costs nothing and proves the graders.
|
|
967
1031
|
|
|
968
|
-
|
|
1032
|
+
### Git and concurrency
|
|
969
1033
|
|
|
970
1034
|
One file in your repo, committed with your code — versioned, branchable, portable. So two
|
|
971
1035
|
developers already share one brain the way they share code: clone, branch, pull.
|
|
@@ -1020,7 +1084,7 @@ rename, so a crash mid-write leaves the previous good file intact. The lock is a
|
|
|
1020
1084
|
sustained contention can still lose an update. That is a deliberate trade — dropping the markers
|
|
1021
1085
|
was judged worse — but it is a real limit, not a guarantee.
|
|
1022
1086
|
|
|
1023
|
-
|
|
1087
|
+
#### Restore points
|
|
1024
1088
|
|
|
1025
1089
|
Merging, tidying and gardening are built to keep every card nobody deleted (one deliberate exception: a
|
|
1026
1090
|
card deleted permanently also leaves the other copies of the brain when they sync, an edited copy
|
|
@@ -1057,9 +1121,32 @@ that cannot be written is logged and skipped — it never blocks your save.
|
|
|
1057
1121
|
Normal canvases deliberately get none of this. One human made every mark and saw every change; the
|
|
1058
1122
|
brain is the file where that is not true.
|
|
1059
1123
|
|
|
1060
|
-
|
|
1124
|
+
### Whose is this? The git guard for a shared checkout
|
|
1061
1125
|
|
|
1062
|
-
|
|
1126
|
+
Since 1.105.0, when several AI sessions share one checkout, the Claude Code hooks check git
|
|
1127
|
+
commands before they run:
|
|
1128
|
+
|
|
1129
|
+
- A command that would sweep another **live** session's uncommitted work into your commit
|
|
1130
|
+
(`git add -A`, `git commit -a`, or naming its file) is stopped. The message names that session
|
|
1131
|
+
and gives the narrow command for your own files.
|
|
1132
|
+
- A command that would throw work away (`git reset --hard`, `git checkout -- <file>`,
|
|
1133
|
+
`git stash`, `git clean`) saves a rescue copy first (`refs/klypix/rescue/*`), then asks you.
|
|
1134
|
+
With no person to ask (bypass mode), it is refused. Restore a copy with
|
|
1135
|
+
`npx klypix-mcp rescue restore <id>`; `npx klypix-mcp rescue list` shows them.
|
|
1136
|
+
- `git status` says which changed files belong to another session.
|
|
1137
|
+
- A **stopped** session's leftovers are not blocked. The agent is told it may finish and commit
|
|
1138
|
+
them if it is continuing that work.
|
|
1139
|
+
|
|
1140
|
+
Modes: `KLYPIX_WHOSE=enforce` (the default), `shadow` (warn and log only) or `off`, or
|
|
1141
|
+
`{"mode": ...}` in `~/.claude/project-brain/whose.json`. Codex edits are recorded so the guard
|
|
1142
|
+
knows whose they are.
|
|
1143
|
+
|
|
1144
|
+
What it is not: it guards git commands run through Claude Code's tools, on one computer. It does
|
|
1145
|
+
not guard edits to files or work in other tools, and it does not prevent conflicts. In the
|
|
1146
|
+
coordination bench, a one-line careful instruction also kept the other session's work safe in 5 of
|
|
1147
|
+
5 "clean up" runs, as KLYPIX did.
|
|
1148
|
+
|
|
1149
|
+
### The command line
|
|
1063
1150
|
|
|
1064
1151
|
The MCP verbs below are what agents call. These are what **you** call:
|
|
1065
1152
|
|
|
@@ -1077,10 +1164,10 @@ The MCP verbs below are what agents call. These are what **you** call:
|
|
|
1077
1164
|
| `npx klypix-mcp diff [ref]` | Card-level brain diff against a git ref, as markdown |
|
|
1078
1165
|
| `npx klypix-mcp pr-brief [ref]` | Brain cards referencing the files changed since a ref, as markdown |
|
|
1079
1166
|
| `npx klypix-mcp garden-code` | Print the human approval code `brain_garden` requires |
|
|
1167
|
+
| `npx klypix-mcp rescue` | Rescue copies the git guard saved before a discard: `list`, `show <id>`, `restore <id> [paths…]`, `prune` |
|
|
1168
|
+
| `npx klypix-mcp sessions` | This project's closed sessions and the notes waiting for them; `sessions reopen <id>` reopens one |
|
|
1080
1169
|
|
|
1081
|
-
|
|
1082
|
-
|
|
1083
|
-
## The verbs: 26, and 27 on Windows
|
|
1170
|
+
### The verbs: 26, and 27 on Windows
|
|
1084
1171
|
|
|
1085
1172
|
| Tool | What it does |
|
|
1086
1173
|
|---|---|
|
|
@@ -1129,7 +1216,7 @@ card itself. `brain_garden`, `brain_reconcile` and `brain_connect` always propos
|
|
|
1129
1216
|
apply.
|
|
1130
1217
|
`npx klypix-mcp doctor` gives one verdict and exits non-zero on drift, so it doubles as a CI gate.
|
|
1131
1218
|
|
|
1132
|
-
|
|
1219
|
+
### One file you can hold
|
|
1133
1220
|
|
|
1134
1221
|
The whole brain — layout, cards, arrows, and the actual bytes (images, PDFs, audio, video) — is a
|
|
1135
1222
|
single `.klypix` file: a plain ZIP with `manifest.json`, `canvas.json`, one JSON file per card, and
|
|
@@ -1163,7 +1250,7 @@ npx klypix-read node_modules/klypix-mcp/examples/showcase-brain.klypix
|
|
|
1163
1250
|
Both are text-and-arrows only — 14 cards, 4 arrows, no `assets/` entry — so they demonstrate the
|
|
1164
1251
|
card / container / connection model, not the embedded-binaries half of the format.
|
|
1165
1252
|
|
|
1166
|
-
|
|
1253
|
+
### Use it as a library
|
|
1167
1254
|
|
|
1168
1255
|
```js
|
|
1169
1256
|
import { parseKlypix, buildKlypix, appendToKlypix, structToMarkdown } from 'klypix-mcp';
|
|
@@ -1175,7 +1262,7 @@ echo '{ "title": "Plan", "cards": [{ "text": "kickoff" }] }' \
|
|
|
1175
1262
|
| npx -p klypix-mcp klypix-write --out plan.klypix
|
|
1176
1263
|
```
|
|
1177
1264
|
|
|
1178
|
-
|
|
1265
|
+
### Also speaks A2A protocol v0.3.0 — experimental
|
|
1179
1266
|
|
|
1180
1267
|
```bash
|
|
1181
1268
|
npx -p klypix-mcp klypix-a2a --vault ./canvases # 127.0.0.1:41241
|
|
@@ -1191,7 +1278,7 @@ agent that returns text, KLYPIX returns the `.klypix` board itself as a multimod
|
|
|
1191
1278
|
Treat this as a preview: the adversarial A2A smoke test runs in the default `npm test` chain, but
|
|
1192
1279
|
the server has not been exercised against a third-party A2A client.
|
|
1193
1280
|
|
|
1194
|
-
|
|
1281
|
+
### Updates — the propagation contract
|
|
1195
1282
|
|
|
1196
1283
|
The MCP entry point is a stable stdio supervisor that keeps the host-owned connection open while a
|
|
1197
1284
|
replaceable worker runs the brain core. A staged update is hash-verified, initialized in parallel,
|
|
@@ -1258,7 +1345,7 @@ re-index after a model/cache upgrade; cache writes are model-keyed and atomic ac
|
|
|
1258
1345
|
agent sessions. Lexical-only installs download nothing. Set `KLYPIX_SEMANTIC_WARM_ON_UPDATE=0` to
|
|
1259
1346
|
keep lazy first-use indexing instead.
|
|
1260
1347
|
|
|
1261
|
-
|
|
1348
|
+
### Security and permissions
|
|
1262
1349
|
|
|
1263
1350
|
- **Apache-2.0, source public** at [github.com/dahshanlabs/klypix-mcp](https://github.com/dahshanlabs/klypix-mcp).
|
|
1264
1351
|
- **The brain engine makes no network calls and sends no telemetry.** All engine intelligence is
|
|
@@ -1286,7 +1373,7 @@ keep lazy first-use indexing instead.
|
|
|
1286
1373
|
needed, passes only encrypted traffic. Not installed, `KLYPIX_NETWORK=0`, or plugin mode: nothing
|
|
1287
1374
|
runs.
|
|
1288
1375
|
- **`install` writes to your home directory:** `~/.claude/project-brain` (engine + runtime),
|
|
1289
|
-
`~/.claude/settings.json` (
|
|
1376
|
+
`~/.claude/settings.json` (six hooks since 1.105.0 — written even if Claude Code is not installed),
|
|
1290
1377
|
`~/.codex/AGENTS.md` (guidance block), and with `--codex-hooks`, `~/.codex/hooks.json`. It also
|
|
1291
1378
|
writes `<cwd>/.codex/config.toml` **inside the project** you run it in, and removes any KLYPIX
|
|
1292
1379
|
entry from the global `~/.codex/config.toml`. **`link` writes 14 files inside the project** you
|
|
@@ -1309,7 +1396,7 @@ keep lazy first-use indexing instead.
|
|
|
1309
1396
|
is closed or its AI-tools switch is off; the client proves the app holds the per-start token before
|
|
1310
1397
|
it sends a request, and never logs or returns the token or the pipe name.
|
|
1311
1398
|
|
|
1312
|
-
|
|
1399
|
+
### Current limitations
|
|
1313
1400
|
|
|
1314
1401
|
Read this section before you build on any of it.
|
|
1315
1402
|
|
|
@@ -1358,7 +1445,7 @@ Read this section before you build on any of it.
|
|
|
1358
1445
|
verified identity: any program running as you can read the bridge token.
|
|
1359
1446
|
- **`canvas_view`'s MCP Apps UI has never been verified on a real Apps host.**
|
|
1360
1447
|
|
|
1361
|
-
|
|
1448
|
+
### Numbers and methodology
|
|
1362
1449
|
|
|
1363
1450
|
Every number here is measured on our own project brain. Nothing below is published, benchmarked or
|
|
1364
1451
|
independently validated.
|
|
@@ -1384,7 +1471,7 @@ independently validated.
|
|
|
1384
1471
|
keywords at half weight:
|
|
1385
1472
|
recall@5 19% → 24% (5 found, none lost), recall@10 25% → 31%. Without the line, ranking is
|
|
1386
1473
|
unchanged byte for byte.
|
|
1387
|
-
- **
|
|
1474
|
+
- **A second project's brain.** The same ranker on a different project's brain (1,601 cards, 19 hand-written
|
|
1388
1475
|
paraphrases, first cross-brain run): recall@5 **42%** (CI 23–64), top-1 11%, MRR 0.25. Paraphrase
|
|
1389
1476
|
recall transfers between brains; the ranker is not tuned to the brain it was built on. It is
|
|
1390
1477
|
simply weak on paraphrase everywhere — the embedder's ceiling, documented in `rankForQuestion`.
|
|
@@ -1410,7 +1497,7 @@ independently validated.
|
|
|
1410
1497
|
- **The eval harness is not in this repo.** It lives in the private KLYPIX desktop repository. The
|
|
1411
1498
|
numbers above are ours to defend, not yours to reproduce from here — treat them accordingly.
|
|
1412
1499
|
|
|
1413
|
-
|
|
1500
|
+
### Uninstall
|
|
1414
1501
|
|
|
1415
1502
|
```bash
|
|
1416
1503
|
npx klypix-mcp uninstall --check # preview machine-global removal — writes nothing
|
|
@@ -1430,6 +1517,8 @@ every live section there.
|
|
|
1430
1517
|
|
|
1431
1518
|
Your `brain.klypix` is yours — it is a plain ZIP and stays readable with or without this package.
|
|
1432
1519
|
|
|
1520
|
+
---
|
|
1521
|
+
|
|
1433
1522
|
## Contributing
|
|
1434
1523
|
|
|
1435
1524
|
Issues and pull requests: [github.com/dahshanlabs/klypix-mcp](https://github.com/dahshanlabs/klypix-mcp).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "klypix-mcp",
|
|
3
|
-
"version": "1.106.
|
|
3
|
+
"version": "1.106.2",
|
|
4
4
|
"mcpName": "io.github.dahshanlabs/klypix-mcp",
|
|
5
5
|
"description": "Shared project memory for Claude Code, Codex and Cursor: decisions, corrections, overlap warnings.",
|
|
6
6
|
"type": "module",
|
|
@@ -35,7 +35,7 @@
|
|
|
35
35
|
"overlap-warnings",
|
|
36
36
|
"agent-collaboration"
|
|
37
37
|
],
|
|
38
|
-
"homepage": "https://klypix.com/
|
|
38
|
+
"homepage": "https://klypix.com/klypix-mcp",
|
|
39
39
|
"repository": {
|
|
40
40
|
"type": "git",
|
|
41
41
|
"url": "https://github.com/dahshanlabs/klypix-mcp"
|