klypix-mcp 1.106.0 → 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 +236 -116
- package/package.json +10 -4
package/README.md
CHANGED
|
@@ -1,84 +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
|
-
[Supported hosts](#supported-hosts-and-their-integration-level).
|
|
12
|
-
|
|
13
|
-
Klypix is a **portable project workspace with a shared brain**. This repository provides its
|
|
14
|
-
local MCP server for shared project memory in coding tools. The **Apache-2.0 engine works without the KLYPIX
|
|
15
|
-
desktop app or a KLYPIX account**. The optional
|
|
16
|
-
[Windows workspace](https://klypix.com/developers) lets people inspect the same project brain
|
|
17
|
-
beside their files. App-based sharing has its own cloud path; see [Security and permissions](#security-and-permissions).
|
|
18
|
-
|
|
19
|
-
For the **Projects & Ideas** path — saved project materials in ChatGPT or Claude chat — follow
|
|
20
|
-
[Save project materials and use them with your assistant](https://klypix.com/guides/connect-klypix-to-chatgpt-and-claude).
|
|
21
|
-
That uses Klypix's separate hosted connection for the spaces you authorize. Installing this local
|
|
22
|
-
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)
|
|
23
15
|
|
|
24
|
-
|
|
25
|
-
[Supported hosts](#supported-hosts-and-their-integration-level) ·
|
|
26
|
-
[Privacy](#security-and-permissions) · [Limits](#current-limitations) · [Uninstall](#uninstall)
|
|
16
|
+
</div>
|
|
27
17
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
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.
|
|
31
22
|
|
|
32
|
-
|
|
33
24
|
|
|
34
|
-
<sub>
|
|
35
|
-
|
|
36
|
-
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>
|
|
37
27
|
|
|
38
|
-
|
|
28
|
+
**▶ Watch:** [For coding teams (40 s, with sound)](https://klypix.com/media/films/sessions-16x9-en.mp4) ·
|
|
29
|
+
[Correct it once (20 s)](https://klypix.com/media/films/correct-16x9-en.mp4) ·
|
|
30
|
+
[Full tour (4 min)](https://klypix.com/media/films/tour-16x9-en.mp4) ·
|
|
31
|
+
[KLYPIX network](https://klypix.com/network)
|
|
39
32
|
|
|
40
|
-
|
|
41
|
-
npx klypix-mcp install
|
|
42
|
-
```
|
|
33
|
+
## Install in three steps
|
|
43
34
|
|
|
44
|
-
|
|
45
|
-
registers the `.klypix` merge driver if this is a git repo, and exits only after a real MCP
|
|
46
|
-
handshake has counted the tools that answered.
|
|
35
|
+
You need **Node.js 20 or newer** (`node -v`).
|
|
47
36
|
|
|
48
|
-
|
|
49
|
-
A successful trial means a fresh session finds your recorded decision and its reason, then finds
|
|
50
|
-
the corrected decision as current. Check the returned source cards; a successful install alone
|
|
51
|
-
does not prove that your host has loaded the tools or that a particular decision was retrieved.
|
|
37
|
+
1. **Run this inside your project:**
|
|
52
38
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
[](#supported-hosts-and-their-integration-level)
|
|
39
|
+
```bash
|
|
40
|
+
npx klypix-mcp install
|
|
41
|
+
```
|
|
57
42
|
|
|
58
|
-
|
|
59
|
-
|
|
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) |
|
|
60
90
|
|
|
61
|
-
|
|
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.
|
|
62
93
|
|
|
63
|
-
|
|
64
|
-
router, a worktree manager, or a replacement for Git. It holds what the project currently believes.
|
|
94
|
+
> **One project. Many agents. One current understanding.**
|
|
65
95
|
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
[](LICENSE)
|
|
69
|
-
[](package.json)
|
|
70
|
-
[](https://modelcontextprotocol.io)
|
|
71
|
-
[](https://glama.ai/mcp/servers/dahshanlabs/klypix-mcp)
|
|
72
|
-
[](BENCHMARKS.md)
|
|
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.
|
|
73
98
|
|
|
74
|
-
|
|
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.
|
|
75
107
|
|
|
76
|
-
[
|
|
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)
|
|
77
111
|
|
|
78
|
-
|
|
79
|
-
carry forward into supported coding-agent sessions.
|
|
112
|
+
---
|
|
80
113
|
|
|
81
|
-
|
|
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)
|
|
82
135
|
|
|
83
136
|
---
|
|
84
137
|
|
|
@@ -100,6 +153,12 @@ Your agents may run independently. Their project understanding should not.
|
|
|
100
153
|
|
|
101
154
|
## 60 seconds: two agents, one project
|
|
102
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
|
+
|
|
103
162
|
Illustrative calls and responses: replace `/absolute/path/to/project` with the same project root
|
|
104
163
|
in both sessions (for example, `C:/work/api` on Windows).
|
|
105
164
|
|
|
@@ -189,8 +248,8 @@ broken entry dies in ~100ms with `Connection closed` and is reported, not shippe
|
|
|
189
248
|
|
|
190
249
|
What goes where:
|
|
191
250
|
|
|
192
|
-
- **Machine-global, once** — the engine + runtime in `~/.claude/project-brain`, Claude Code's
|
|
193
|
-
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
|
|
194
253
|
Code is therefore covered in every project on that machine that has a `./brain.klypix`.
|
|
195
254
|
- **Per project** — MCP config and rules for Cursor, Codex, Cline, Windsurf, Copilot, Gemini CLI /
|
|
196
255
|
Antigravity and Aider. Run `install` once inside each project.
|
|
@@ -297,11 +356,18 @@ trial does not plan source-code edits.
|
|
|
297
356
|
|
|
298
357
|
For a team on different machines, follow the [Git sharing steps](https://klypix.com/guides/shared-project-memory#team)
|
|
299
358
|
and install in each clone. Standalone live presence and file-overlap warnings stay local to one
|
|
300
|
-
machine and OS user
|
|
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.
|
|
301
362
|
|
|
302
363
|
---
|
|
303
364
|
|
|
304
|
-
##
|
|
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
|
|
305
371
|
|
|
306
372
|
The difference from a folder of notes is not the shape — it is that this memory is a mechanism,
|
|
307
373
|
not a filing convention.
|
|
@@ -339,7 +405,7 @@ not a filing convention.
|
|
|
339
405
|
("Getting this brain ready for search by meaning: 900 of 3,670 cards so far, about 5 min left").
|
|
340
406
|
After that, only new or edited cards are prepared.
|
|
341
407
|
|
|
342
|
-
|
|
408
|
+
#### Bounded semantic-memory runtime
|
|
343
409
|
|
|
344
410
|
Long-lived MCP and A2A workers use the bounded semantic-memory runtime by default. Models load only
|
|
345
411
|
when semantic work is requested, native inference is serialized per process, embedding work is
|
|
@@ -363,7 +429,7 @@ excludes the owning IDE/chat application's RAM, redacts command-line secrets, an
|
|
|
363
429
|
brain or terminates a process. Multiple processes under one host are reported as parallel sessions,
|
|
364
430
|
not called duplicates without an authoritative logical-session receipt.
|
|
365
431
|
|
|
366
|
-
|
|
432
|
+
#### Project Map: current structure beside project understanding
|
|
367
433
|
|
|
368
434
|
If the project contains a compatible NetworkX node-link `graph.json`, agents can ask for bounded
|
|
369
435
|
code-structure evidence and current brain context in one read-only call:
|
|
@@ -398,16 +464,14 @@ workflow has `contents: read`, pins every action by commit SHA, pins `graphifyy=
|
|
|
398
464
|
the graph contract, and uploads `graphify-out/` as a 14-day build artifact. This is opt-in CI code:
|
|
399
465
|
the local MCP tool still never installs or launches Graphify.
|
|
400
466
|
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
## Supported hosts and their integration level
|
|
467
|
+
### Supported hosts and their integration level
|
|
404
468
|
|
|
405
469
|
Levels are honest. Only the config-writing side is tested for the `link` hosts; their host-side
|
|
406
470
|
behaviour is unverified.
|
|
407
471
|
|
|
408
472
|
| Host | Level | Wired by | Brief into context | Decision capture | Live presence |
|
|
409
473
|
|---|---|---|---|---|---|
|
|
410
|
-
| **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 |
|
|
411
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 |
|
|
412
476
|
| **Cursor** | MCP config + always-on rules file | `link` | Model must call `brain_sync` | Model must call `brain_note` | For the MCP connection |
|
|
413
477
|
| **Cline** | MCP config + always-on rules file | `link` | Model must call `brain_sync` | Model must call `brain_note` | For the MCP connection |
|
|
@@ -438,11 +502,10 @@ it lists the tools:
|
|
|
438
502
|
}
|
|
439
503
|
```
|
|
440
504
|
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
## Running as a Claude plugin
|
|
505
|
+
### Running as a Claude plugin
|
|
444
506
|
|
|
445
|
-
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
|
|
446
509
|
a range or `latest`. It sets three variables: `KLYPIX_PLUGIN=1`,
|
|
447
510
|
`KLYPIX_PLUGIN_DATA=${CLAUDE_PLUGIN_DATA}` and `KLYPIX_VAULT=${CLAUDE_PROJECT_DIR}`.
|
|
448
511
|
`KLYPIX_PLUGIN=1` turns on **plugin mode**, which changes how the MCP server behaves and nothing
|
|
@@ -514,9 +577,7 @@ created in a project; and the presence lanes, write locks and restore points in
|
|
|
514
577
|
`~/.claude/project-brain`. Other KLYPIX tools on this computer share that folder. If you use none,
|
|
515
578
|
you can delete it.
|
|
516
579
|
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
## Task briefing
|
|
580
|
+
### Task briefing
|
|
520
581
|
|
|
521
582
|
Every Claude Code session starts already knowing the project: a bounded brief of at most 2KB in
|
|
522
583
|
context, with the full brief written to disk for when broad history or status work needs it.
|
|
@@ -530,7 +591,7 @@ so fresh relevant findings are not crowded out by older area vocabulary.
|
|
|
530
591
|
Briefs are **not** injected automatically on Cursor, Cline, Copilot, Gemini CLI or Antigravity —
|
|
531
592
|
there are no lifecycle hooks on those hosts.
|
|
532
593
|
|
|
533
|
-
|
|
594
|
+
#### The live projection — the file the agent obeys
|
|
534
595
|
|
|
535
596
|
The coordination bench showed that an agent trusts the instruction file it was launched with
|
|
536
597
|
over anything a tool or hook tells it, and that each host reads a different surface. So the
|
|
@@ -557,7 +618,7 @@ Sections for projects not touched in a day are pruned from the Codex file, at mo
|
|
|
557
618
|
kept, and `uninstall unlink` strips the block (deleting `CLAUDE.local.md` only when nothing else
|
|
558
619
|
is in it). `brain_sync` remains the live source; the block tells the agent to call it.
|
|
559
620
|
|
|
560
|
-
|
|
621
|
+
### Capture and corrections
|
|
561
622
|
|
|
562
623
|
`brain_note` accepts structured supporting references and inert verification text:
|
|
563
624
|
|
|
@@ -623,7 +684,7 @@ only (explicit correction cues, opposite-polarity pairs), never mere topical sim
|
|
|
623
684
|
means no contradiction signal was found — not verified consistency. A memory that cannot disagree
|
|
624
685
|
with you is flattery.
|
|
625
686
|
|
|
626
|
-
|
|
687
|
+
### Presence and task intent
|
|
627
688
|
|
|
628
689
|
An active session means an authorized MCP connection or host lifecycle adapter that heartbeated
|
|
629
690
|
within the TTL. A row in a recent-chat list is history, not presence.
|
|
@@ -639,7 +700,7 @@ Future hosts get baseline support merely by connecting the MCP server. A deeper
|
|
|
639
700
|
`peekMessages` and `receiveMessages`. The shared contract accepts `id`, `client`, `surface`,
|
|
640
701
|
`model`, `branch`, `intent`, touched `files`, and adapter `channel`.
|
|
641
702
|
|
|
642
|
-
|
|
703
|
+
### Overlap warnings
|
|
643
704
|
|
|
644
705
|
`brain_sync` reports three kinds of overlap with other live sessions on the same brain:
|
|
645
706
|
|
|
@@ -658,7 +719,32 @@ Future hosts get baseline support merely by connecting the MCP server. A deeper
|
|
|
658
719
|
This warns. It does not prevent. Nothing blocks an edit. A session that never declared its files
|
|
659
720
|
and was never observed editing is invisible to the file and folder checks.
|
|
660
721
|
|
|
661
|
-
|
|
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
|
|
662
748
|
|
|
663
749
|
`brain_message` leaves one-time coordination notes for other sessions — live, idle, or recently
|
|
664
750
|
closed. Address a session by id: a live session gets the note on its next action; a session
|
|
@@ -679,7 +765,7 @@ instead of silently looking delivered. The send-time audience is fixed, unresolv
|
|
|
679
765
|
fail closed, the core lane is machine-local, a note to every session expires after 24 hours and a
|
|
680
766
|
directed note after 7 days, and notes are never written into the brain.
|
|
681
767
|
|
|
682
|
-
|
|
768
|
+
#### Reopen on your OK
|
|
683
769
|
|
|
684
770
|
A note to a session that has closed would otherwise wait until someone happens to open that
|
|
685
771
|
session again. When the person wants it handled sooner, the sending agent calls `brain_reopen`, and
|
|
@@ -703,7 +789,7 @@ receives the waiting note at its first action and the sender sees the receipt as
|
|
|
703
789
|
waiting for them; `npx klypix-mcp sessions reopen <id>` reopens one (`--quiet` lets it wait for
|
|
704
790
|
you instead of starting on the note).
|
|
705
791
|
|
|
706
|
-
|
|
792
|
+
#### Session handoff — continue in the next session, with any agent
|
|
707
793
|
|
|
708
794
|
The case this exists for: a Claude Code session stops at its usage limit in the middle of a task,
|
|
709
795
|
and the person opens Codex (or a fresh Claude Code) and says *continue*. Until 1.99.0 the only
|
|
@@ -759,7 +845,7 @@ fail the sync that triggered it.
|
|
|
759
845
|
Durable decisions still go in the brain as cards — a handoff is the one card about *work in
|
|
760
846
|
flight*, and it closes when the work lands.
|
|
761
847
|
|
|
762
|
-
|
|
848
|
+
### Evidence-gated completion
|
|
763
849
|
|
|
764
850
|
When a task publishes a quantified or otherwise machine-checkable claim, it can attach one or more
|
|
765
851
|
versioned result manifests to `brain_sync { phase: "complete" }`. Each manifest binds the claim to a
|
|
@@ -776,7 +862,7 @@ Schema-v2 receipts can be converted into commit-bound publication evidence and i
|
|
|
776
862
|
with `klypix-mcp/release-evidence`; legacy schema-v1 results remain usable for coordination but cannot
|
|
777
863
|
authorize publication.
|
|
778
864
|
|
|
779
|
-
|
|
865
|
+
### Human control in Klypix
|
|
780
866
|
|
|
781
867
|
> **Not a second brain. A shared one.**
|
|
782
868
|
|
|
@@ -796,7 +882,7 @@ The app is a separate, proprietary Windows product. The format, this server and
|
|
|
796
882
|
Apache-2.0 and work with no app installed. The app's interface is available in English and Arabic
|
|
797
883
|
(some newer panels are still English-only).
|
|
798
884
|
|
|
799
|
-
|
|
885
|
+
#### KLYPIX canvases and your AI tool
|
|
800
886
|
|
|
801
887
|
Beyond project brains, the same connection reads and writes the KLYPIX canvases (spaces) saved on
|
|
802
888
|
your PC. **Your AI tool reads what KLYPIX has already read, and the files a saved canvas holds:**
|
|
@@ -821,7 +907,7 @@ your PC. **Your AI tool reads what KLYPIX has already read, and the files a save
|
|
|
821
907
|
again.
|
|
822
908
|
- Text that comes back from cards, pages, reels and files is fenced as data, never instructions.
|
|
823
909
|
|
|
824
|
-
|
|
910
|
+
#### App mode: your AI tool uses KLYPIX while it is open
|
|
825
911
|
|
|
826
912
|
On Windows, while the KLYPIX app is open and **Settings → Project → AI tools on this PC** is on (it is
|
|
827
913
|
on by default), the same connection reaches the running app. KLYPIX then runs its own code for the
|
|
@@ -876,7 +962,7 @@ prove they hold the token before a request is sent; klypix-mcp sends nothing to
|
|
|
876
962
|
prove itself. The token and the pipe name are never logged, returned to the AI tool or shown by
|
|
877
963
|
`brain_doctor`. Any program running under your Windows account can read the token.
|
|
878
964
|
|
|
879
|
-
|
|
965
|
+
#### Reading what is inside cards
|
|
880
966
|
|
|
881
967
|
A canvas saved by KLYPIX keeps a copy of every file dropped on it. `read_card_contents` hands those
|
|
882
968
|
files to your AI tool as they are, so it reads them with its own model and its own file tools —
|
|
@@ -914,10 +1000,11 @@ Limits, and why:
|
|
|
914
1000
|
it while it runs), so it cannot be handed over from the saved canvas; the answer says so.
|
|
915
1001
|
- Cards inside a box locked from AI tools are never read, copied or attached.
|
|
916
1002
|
|
|
917
|
-
|
|
1003
|
+
### Measure it yourself
|
|
918
1004
|
|
|
919
1005
|
Claims about a shared brain — "nothing is lost", "it stays fast" — are unfalsifiable until a
|
|
920
|
-
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)):
|
|
921
1008
|
|
|
922
1009
|
```bash
|
|
923
1010
|
npx klypix-mcp bench # ~25s, or --quick for a smaller run
|
|
@@ -942,7 +1029,7 @@ channel, a human copy-paste, `AGENTS.md` kept tidy or appended, and KLYPIX over
|
|
|
942
1029
|
is printed with its sample size and interval; tools it has not measured are listed as not measured.
|
|
943
1030
|
`--dry-run` costs nothing and proves the graders.
|
|
944
1031
|
|
|
945
|
-
|
|
1032
|
+
### Git and concurrency
|
|
946
1033
|
|
|
947
1034
|
One file in your repo, committed with your code — versioned, branchable, portable. So two
|
|
948
1035
|
developers already share one brain the way they share code: clone, branch, pull.
|
|
@@ -997,7 +1084,7 @@ rename, so a crash mid-write leaves the previous good file intact. The lock is a
|
|
|
997
1084
|
sustained contention can still lose an update. That is a deliberate trade — dropping the markers
|
|
998
1085
|
was judged worse — but it is a real limit, not a guarantee.
|
|
999
1086
|
|
|
1000
|
-
|
|
1087
|
+
#### Restore points
|
|
1001
1088
|
|
|
1002
1089
|
Merging, tidying and gardening are built to keep every card nobody deleted (one deliberate exception: a
|
|
1003
1090
|
card deleted permanently also leaves the other copies of the brain when they sync, an edited copy
|
|
@@ -1034,9 +1121,32 @@ that cannot be written is logged and skipped — it never blocks your save.
|
|
|
1034
1121
|
Normal canvases deliberately get none of this. One human made every mark and saw every change; the
|
|
1035
1122
|
brain is the file where that is not true.
|
|
1036
1123
|
|
|
1037
|
-
|
|
1124
|
+
### Whose is this? The git guard for a shared checkout
|
|
1125
|
+
|
|
1126
|
+
Since 1.105.0, when several AI sessions share one checkout, the Claude Code hooks check git
|
|
1127
|
+
commands before they run:
|
|
1038
1128
|
|
|
1039
|
-
|
|
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
|
|
1040
1150
|
|
|
1041
1151
|
The MCP verbs below are what agents call. These are what **you** call:
|
|
1042
1152
|
|
|
@@ -1054,10 +1164,10 @@ The MCP verbs below are what agents call. These are what **you** call:
|
|
|
1054
1164
|
| `npx klypix-mcp diff [ref]` | Card-level brain diff against a git ref, as markdown |
|
|
1055
1165
|
| `npx klypix-mcp pr-brief [ref]` | Brain cards referencing the files changed since a ref, as markdown |
|
|
1056
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 |
|
|
1057
1169
|
|
|
1058
|
-
|
|
1059
|
-
|
|
1060
|
-
## The verbs: 26, and 27 on Windows
|
|
1170
|
+
### The verbs: 26, and 27 on Windows
|
|
1061
1171
|
|
|
1062
1172
|
| Tool | What it does |
|
|
1063
1173
|
|---|---|
|
|
@@ -1106,7 +1216,7 @@ card itself. `brain_garden`, `brain_reconcile` and `brain_connect` always propos
|
|
|
1106
1216
|
apply.
|
|
1107
1217
|
`npx klypix-mcp doctor` gives one verdict and exits non-zero on drift, so it doubles as a CI gate.
|
|
1108
1218
|
|
|
1109
|
-
|
|
1219
|
+
### One file you can hold
|
|
1110
1220
|
|
|
1111
1221
|
The whole brain — layout, cards, arrows, and the actual bytes (images, PDFs, audio, video) — is a
|
|
1112
1222
|
single `.klypix` file: a plain ZIP with `manifest.json`, `canvas.json`, one JSON file per card, and
|
|
@@ -1140,7 +1250,7 @@ npx klypix-read node_modules/klypix-mcp/examples/showcase-brain.klypix
|
|
|
1140
1250
|
Both are text-and-arrows only — 14 cards, 4 arrows, no `assets/` entry — so they demonstrate the
|
|
1141
1251
|
card / container / connection model, not the embedded-binaries half of the format.
|
|
1142
1252
|
|
|
1143
|
-
|
|
1253
|
+
### Use it as a library
|
|
1144
1254
|
|
|
1145
1255
|
```js
|
|
1146
1256
|
import { parseKlypix, buildKlypix, appendToKlypix, structToMarkdown } from 'klypix-mcp';
|
|
@@ -1152,7 +1262,7 @@ echo '{ "title": "Plan", "cards": [{ "text": "kickoff" }] }' \
|
|
|
1152
1262
|
| npx -p klypix-mcp klypix-write --out plan.klypix
|
|
1153
1263
|
```
|
|
1154
1264
|
|
|
1155
|
-
|
|
1265
|
+
### Also speaks A2A protocol v0.3.0 — experimental
|
|
1156
1266
|
|
|
1157
1267
|
```bash
|
|
1158
1268
|
npx -p klypix-mcp klypix-a2a --vault ./canvases # 127.0.0.1:41241
|
|
@@ -1168,7 +1278,7 @@ agent that returns text, KLYPIX returns the `.klypix` board itself as a multimod
|
|
|
1168
1278
|
Treat this as a preview: the adversarial A2A smoke test runs in the default `npm test` chain, but
|
|
1169
1279
|
the server has not been exercised against a third-party A2A client.
|
|
1170
1280
|
|
|
1171
|
-
|
|
1281
|
+
### Updates — the propagation contract
|
|
1172
1282
|
|
|
1173
1283
|
The MCP entry point is a stable stdio supervisor that keeps the host-owned connection open while a
|
|
1174
1284
|
replaceable worker runs the brain core. A staged update is hash-verified, initialized in parallel,
|
|
@@ -1235,7 +1345,7 @@ re-index after a model/cache upgrade; cache writes are model-keyed and atomic ac
|
|
|
1235
1345
|
agent sessions. Lexical-only installs download nothing. Set `KLYPIX_SEMANTIC_WARM_ON_UPDATE=0` to
|
|
1236
1346
|
keep lazy first-use indexing instead.
|
|
1237
1347
|
|
|
1238
|
-
|
|
1348
|
+
### Security and permissions
|
|
1239
1349
|
|
|
1240
1350
|
- **Apache-2.0, source public** at [github.com/dahshanlabs/klypix-mcp](https://github.com/dahshanlabs/klypix-mcp).
|
|
1241
1351
|
- **The brain engine makes no network calls and sends no telemetry.** All engine intelligence is
|
|
@@ -1256,8 +1366,14 @@ keep lazy first-use indexing instead.
|
|
|
1256
1366
|
data, but a note relays whatever its sender typed (and automatic overlap alerts name the declared
|
|
1257
1367
|
file paths involved). The scope is versioned: an older metadata-only grant does not authorize note
|
|
1258
1368
|
text and must be granted again. No current consent, no frames.
|
|
1369
|
+
- **KLYPIX network is a separate, optional program.** When it is installed, `brain_sync` sends it
|
|
1370
|
+
this session's project key (a hash of the git remote, never the path), its one-line intent and
|
|
1371
|
+
repository-relative file paths, and `brain_message` sends the note text to a session on another
|
|
1372
|
+
computer. Nothing else is sent. Traffic between computers is encrypted; a relay, when one is
|
|
1373
|
+
needed, passes only encrypted traffic. Not installed, `KLYPIX_NETWORK=0`, or plugin mode: nothing
|
|
1374
|
+
runs.
|
|
1259
1375
|
- **`install` writes to your home directory:** `~/.claude/project-brain` (engine + runtime),
|
|
1260
|
-
`~/.claude/settings.json` (
|
|
1376
|
+
`~/.claude/settings.json` (six hooks since 1.105.0 — written even if Claude Code is not installed),
|
|
1261
1377
|
`~/.codex/AGENTS.md` (guidance block), and with `--codex-hooks`, `~/.codex/hooks.json`. It also
|
|
1262
1378
|
writes `<cwd>/.codex/config.toml` **inside the project** you run it in, and removes any KLYPIX
|
|
1263
1379
|
entry from the global `~/.codex/config.toml`. **`link` writes 14 files inside the project** you
|
|
@@ -1280,17 +1396,19 @@ keep lazy first-use indexing instead.
|
|
|
1280
1396
|
is closed or its AI-tools switch is off; the client proves the app holds the per-start token before
|
|
1281
1397
|
it sends a request, and never logs or returns the token or the pipe name.
|
|
1282
1398
|
|
|
1283
|
-
|
|
1399
|
+
### Current limitations
|
|
1284
1400
|
|
|
1285
1401
|
Read this section before you build on any of it.
|
|
1286
1402
|
|
|
1287
|
-
- **Coordination is machine-local and OS-user-local
|
|
1288
|
-
|
|
1289
|
-
|
|
1290
|
-
|
|
1291
|
-
|
|
1292
|
-
|
|
1293
|
-
|
|
1403
|
+
- **Coordination is machine-local and OS-user-local unless KLYPIX network is installed.** The
|
|
1404
|
+
presence lane is a file in your home directory. With `klypix-mcp` alone, two developers on two
|
|
1405
|
+
machines do not see each other's sessions, overlaps or messages. With
|
|
1406
|
+
[KLYPIX network](https://klypix.com/network) on both computers (1.106.0+), they see each other's
|
|
1407
|
+
sessions in the same project, with intent and declared files, get the exact-file overlap warning,
|
|
1408
|
+
and can send notes; read receipts, result reconciliation and the merge test stay local. The
|
|
1409
|
+
project match is by git remote (or folder name without one). This package also ships a
|
|
1410
|
+
cross-machine presence *core* for the desktop app's cloud channel (`./presence-relay`, default-off
|
|
1411
|
+
consent), which is a separate path.
|
|
1294
1412
|
- **File overlap is exact-path.** A session needs declared files or observed edits to be checked;
|
|
1295
1413
|
`src/auth/token.ts` does not match a rename. Folder overlap is advisory. The merge test sees
|
|
1296
1414
|
committed work only, needs git 2.38 or newer, and runs only for sessions on different local
|
|
@@ -1327,7 +1445,7 @@ Read this section before you build on any of it.
|
|
|
1327
1445
|
verified identity: any program running as you can read the bridge token.
|
|
1328
1446
|
- **`canvas_view`'s MCP Apps UI has never been verified on a real Apps host.**
|
|
1329
1447
|
|
|
1330
|
-
|
|
1448
|
+
### Numbers and methodology
|
|
1331
1449
|
|
|
1332
1450
|
Every number here is measured on our own project brain. Nothing below is published, benchmarked or
|
|
1333
1451
|
independently validated.
|
|
@@ -1353,7 +1471,7 @@ independently validated.
|
|
|
1353
1471
|
keywords at half weight:
|
|
1354
1472
|
recall@5 19% → 24% (5 found, none lost), recall@10 25% → 31%. Without the line, ranking is
|
|
1355
1473
|
unchanged byte for byte.
|
|
1356
|
-
- **
|
|
1474
|
+
- **A second project's brain.** The same ranker on a different project's brain (1,601 cards, 19 hand-written
|
|
1357
1475
|
paraphrases, first cross-brain run): recall@5 **42%** (CI 23–64), top-1 11%, MRR 0.25. Paraphrase
|
|
1358
1476
|
recall transfers between brains; the ranker is not tuned to the brain it was built on. It is
|
|
1359
1477
|
simply weak on paraphrase everywhere — the embedder's ceiling, documented in `rankForQuestion`.
|
|
@@ -1379,7 +1497,7 @@ independently validated.
|
|
|
1379
1497
|
- **The eval harness is not in this repo.** It lives in the private KLYPIX desktop repository. The
|
|
1380
1498
|
numbers above are ours to defend, not yours to reproduce from here — treat them accordingly.
|
|
1381
1499
|
|
|
1382
|
-
|
|
1500
|
+
### Uninstall
|
|
1383
1501
|
|
|
1384
1502
|
```bash
|
|
1385
1503
|
npx klypix-mcp uninstall --check # preview machine-global removal — writes nothing
|
|
@@ -1399,6 +1517,8 @@ every live section there.
|
|
|
1399
1517
|
|
|
1400
1518
|
Your `brain.klypix` is yours — it is a plain ZIP and stays readable with or without this package.
|
|
1401
1519
|
|
|
1520
|
+
---
|
|
1521
|
+
|
|
1402
1522
|
## Contributing
|
|
1403
1523
|
|
|
1404
1524
|
Issues and pull requests: [github.com/dahshanlabs/klypix-mcp](https://github.com/dahshanlabs/klypix-mcp).
|
package/package.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
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
|
-
"description": "Shared project memory for Claude Code, Codex and Cursor: decisions
|
|
5
|
+
"description": "Shared project memory for Claude Code, Codex and Cursor: decisions, corrections, overlap warnings.",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"license": "Apache-2.0",
|
|
8
8
|
"keywords": [
|
|
@@ -27,9 +27,15 @@
|
|
|
27
27
|
"agent-memory",
|
|
28
28
|
"local-first",
|
|
29
29
|
"klypix",
|
|
30
|
-
"ai"
|
|
30
|
+
"ai",
|
|
31
|
+
"gemini-cli",
|
|
32
|
+
"ai-coding",
|
|
33
|
+
"team-memory",
|
|
34
|
+
"decision-log",
|
|
35
|
+
"overlap-warnings",
|
|
36
|
+
"agent-collaboration"
|
|
31
37
|
],
|
|
32
|
-
"homepage": "https://klypix.com/
|
|
38
|
+
"homepage": "https://klypix.com/klypix-mcp",
|
|
33
39
|
"repository": {
|
|
34
40
|
"type": "git",
|
|
35
41
|
"url": "https://github.com/dahshanlabs/klypix-mcp"
|