klypix-mcp 1.43.0 → 1.43.1
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 +418 -113
- package/package.json +8 -4
package/README.md
CHANGED
|
@@ -1,94 +1,184 @@
|
|
|
1
1
|
# Every project gets a brain.
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**A portable project workspace with a shared brain.**
|
|
4
|
+
*One project. One shared understanding.*
|
|
4
5
|
|
|
5
|
-
|
|
6
|
+
**One shared project brain for multi-agent coding.** `klypix-mcp` gives supported coding agents
|
|
7
|
+
and humans one versioned `brain.klypix` in your repo, containing current decisions, corrections,
|
|
8
|
+
evidence anchors, open questions, active work, and handoffs. Agents read it and write to it over
|
|
9
|
+
MCP. You read it and correct it in the [KLYPIX app](https://klypix.com).
|
|
6
10
|
|
|
7
|
-
|
|
11
|
+
> **One project. Many agents. One current understanding.**
|
|
8
12
|
|
|
9
|
-
|
|
13
|
+
Klypix does not launch, run, supervise, or replace your agents. It is not an agent runtime, a model
|
|
14
|
+
router, a worktree manager, or a replacement for Git. It is the layer underneath them that holds
|
|
15
|
+
what the project currently believes.
|
|
10
16
|
|
|
11
|
-
|
|
17
|
+
---
|
|
12
18
|
|
|
13
|
-
|
|
19
|
+
## The problem
|
|
14
20
|
|
|
15
|
-
|
|
16
|
-
|
|
21
|
+
You are running more than one coding agent on one codebase — a Claude Code session here, Codex in
|
|
22
|
+
another terminal, Cursor open on the side. Each one has excellent memory of *itself* and none of
|
|
23
|
+
the others:
|
|
24
|
+
|
|
25
|
+
- Every new session starts from zero, and you explain the same architecture again.
|
|
26
|
+
- Codex does not know what Claude learned an hour ago.
|
|
27
|
+
- One agent implements an approach the team already rejected, because the reason it was rejected
|
|
28
|
+
lived in a chat that ended.
|
|
29
|
+
- Two sessions start changing the same files and nobody finds out until review.
|
|
30
|
+
- Git stores the code history. It does not store a reliable history of project *intent*.
|
|
31
|
+
|
|
32
|
+
Your agents may run independently. Their project understanding should not.
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## 60 seconds: two agents, one project
|
|
37
|
+
|
|
38
|
+
Session A — Claude Code, in your repo:
|
|
39
|
+
|
|
40
|
+
```jsonc
|
|
41
|
+
brain_sync { intent: "rewrite the auth token refresh", files: ["src/auth/token.ts"] }
|
|
42
|
+
// → task-relevant memory capsule (bounded, ~2.8KB)
|
|
43
|
+
// → peers: none
|
|
17
44
|
```
|
|
18
45
|
|
|
19
|
-
|
|
20
|
-
tools, **automatic live-session presence**, and approval-free **smart task synchronization**
|
|
21
|
-
from the authorized MCP connection itself. `brain_sync` is a bounded **Context Gateway**:
|
|
22
|
-
one call returns task-relevant brain memory, meaningful active-task peers, structured
|
|
23
|
-
exact-file conflicts, one-time notes, and automatic late-arrival overlap alerts. The
|
|
24
|
-
earlier session gets a best-effort live MCP logging notification within seconds, while
|
|
25
|
-
the same alert remains guaranteed on its next KLYPIX action if its host hides logs. Idle MCP
|
|
26
|
-
connections stay counted for diagnostics but are hidden from the task-peer list. MCP
|
|
27
|
-
server instructions plus a managed Codex `AGENTS.md` block teach Codex to call it at task
|
|
28
|
-
start, when scope changes, and on completion—no Codex hook approval required. Run inside a
|
|
29
|
-
project containing `brain.klypix`, or run `npx klypix-mcp link` in each brain project.
|
|
30
|
-
The installer removes the obsolete global KLYPIX `--vault "."` table that could resolve
|
|
31
|
-
outside the active project; every unrelated Codex setting and MCP server is preserved.
|
|
32
|
-
|
|
33
|
-
Optional native lifecycle capture for mechanical prompt/tool/file events:
|
|
46
|
+
Session B — Codex, same repo, half a minute later:
|
|
34
47
|
|
|
35
|
-
```
|
|
36
|
-
|
|
48
|
+
```jsonc
|
|
49
|
+
brain_sync { intent: "add rate limiting to the auth routes",
|
|
50
|
+
files: ["src/auth/token.ts", "src/auth/routes.ts"] }
|
|
51
|
+
// → task capsule
|
|
52
|
+
// → peers: 1 active session (claude-code) — "rewrite the auth token refresh"
|
|
53
|
+
// → overlap: src/auth/token.ts — declared by both sessions
|
|
37
54
|
```
|
|
38
55
|
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
an exact overlapping file edit. `brain_doctor` reports it separately as off,
|
|
43
|
-
execution-unverified, or active; the approval-free smart layer remains active either way.
|
|
56
|
+
Session A gets the same overlap surfaced on its next KLYPIX action. Neither edit is blocked — the
|
|
57
|
+
warning is advisory, and both sides only see the overlap because both declared the files they
|
|
58
|
+
expected to touch.
|
|
44
59
|
|
|
45
|
-
|
|
60
|
+
Then the brain pushes back before the decision, not after:
|
|
61
|
+
|
|
62
|
+
```jsonc
|
|
63
|
+
brain_challenge { "move token storage to localStorage" }
|
|
64
|
+
// → "reversed on June 12 — here's the correction card, captured by a different agent."
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
And the decision is kept where the next session will find it:
|
|
68
|
+
|
|
69
|
+
```jsonc
|
|
70
|
+
brain_note { text: "Token refresh moves to an httpOnly cookie; localStorage was reversed 2026-06-12." }
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Prove all of this on your own machine, against the exact build you installed, with two real
|
|
74
|
+
isolated MCP clients:
|
|
46
75
|
|
|
47
76
|
```bash
|
|
48
77
|
npx klypix-mcp conformance
|
|
49
78
|
```
|
|
50
79
|
|
|
51
|
-
|
|
52
|
-
truthful
|
|
80
|
+
It runs in a temporary fixture and touches nothing else. It checks tool discovery, task memory,
|
|
81
|
+
truthful peer reporting, overlap surfacing, proactive logging, and in-band delivery of a peer note.
|
|
82
|
+
It verifies 7 coordination behaviours — not the 18 tools, and not the retrieval engine.
|
|
83
|
+
|
|
84
|
+
---
|
|
53
85
|
|
|
54
|
-
|
|
55
|
-
[KLYPIX app](https://klypix.com) does it in one click (*Save canvas as project brain*),
|
|
56
|
-
or `create_canvas` makes one from any agent.
|
|
86
|
+
## Quick start
|
|
57
87
|
|
|
58
|
-
**
|
|
88
|
+
**Claude Code + Codex — one machine-global command:**
|
|
59
89
|
|
|
60
90
|
```bash
|
|
61
|
-
npx klypix-mcp
|
|
91
|
+
npx klypix-mcp install
|
|
62
92
|
```
|
|
63
93
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
94
|
+
This copies the engine and a local MCP runtime into `~/.claude/project-brain`, wires Claude Code's
|
|
95
|
+
four lifecycle hooks, and wires Codex's project MCP connection. It is machine-global: every project
|
|
96
|
+
on that machine with a `./brain.klypix` is covered. It does **not** set up Cursor, Cline, Windsurf,
|
|
97
|
+
Copilot, Gemini CLI or Aider — those need `link`.
|
|
67
98
|
|
|
68
|
-
|
|
99
|
+
Optional, opt-in, and approved inside Codex itself:
|
|
69
100
|
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
- **It argues back.** `brain_challenge`: propose a decision and the brain answers with receipts — *"you reversed this on June 12; here's the correction — captured by a different agent, coordinate before overriding."* Deterministic evidence only (correction-cues, opposite-polarity), never mere topical similarity. A memory that can't disagree with you is flattery.
|
|
74
|
-
- **It knows when it's stale.** Decision cards can anchor to the exact code they were decided against (git blob OID). When that code moves on, the card raises its hand in the next brief. Their notes rot silently; ours confess.
|
|
75
|
-
- **It answers from the past.** `brain_ask` with `as_of: 2026-03-01` answers what the project believed *then* — corrections from the future never leak backwards.
|
|
76
|
-
- **Position means something.** Drag a card into the 📌 Focus area and it leads every future session's brief. Layout is instruction, not decoration.
|
|
77
|
-
- **Many agents, no chaos.** Concurrent sessions take a capture lock (zero captures lost, tested at four simultaneous writers), tag *who* wrote each card, message each other through the brain (`brain_message`), and genuine contradictions surface as red arrows for a human to arbitrate — never auto-resolved.
|
|
78
|
-
- **Retrieval that's measured, failures included.** Hybrid on-device search (semantic + lexical + cross-encoder rerank, no cloud): recall@5 of the true source card went **5% → 15% → 40%** across our upgrades (n=20 frozen human-paraphrase questions) — and the experiment that *regressed* (contextual prefixes on short cards) is recorded next to the wins.
|
|
101
|
+
```bash
|
|
102
|
+
npx klypix-mcp install --codex-hooks
|
|
103
|
+
```
|
|
79
104
|
|
|
80
|
-
|
|
105
|
+
Six Codex lifecycle hooks that add automatic per-prompt context injection and a pre-edit
|
|
106
|
+
file-overlap warning. Codex owns the trust decision and will ask you to review them.
|
|
107
|
+
`brain_doctor` reports this layer separately as off, execution-unverified, or active. Even with it
|
|
108
|
+
on, **Codex never captures decisions automatically** — the Codex hook never writes the brain.
|
|
81
109
|
|
|
82
|
-
|
|
110
|
+
**Every other agent tool — one command per project:**
|
|
83
111
|
|
|
84
|
-
|
|
112
|
+
```bash
|
|
113
|
+
npx klypix-mcp link
|
|
114
|
+
```
|
|
85
115
|
|
|
86
|
-
|
|
116
|
+
Writes 14 managed, hash-stamped files: MCP server config for six hosts, plus rules files for
|
|
117
|
+
eight. Managed blocks are merged into your existing instruction files and never clobber your
|
|
118
|
+
content.
|
|
87
119
|
|
|
88
|
-
|
|
120
|
+
```bash
|
|
121
|
+
npx klypix-mcp link --check # audits without writing; exits non-zero on drift
|
|
122
|
+
```
|
|
89
123
|
|
|
90
|
-
|
|
91
|
-
|
|
124
|
+
> Use that exact form. The standalone `klypix-link` binary currently drops the `--check` flag and
|
|
125
|
+
> writes instead (`bin/klypix-link.mjs:23`). Do not wire `npx -p klypix-mcp klypix-link --check`
|
|
126
|
+
> into CI until that is fixed.
|
|
127
|
+
|
|
128
|
+
**Give a project a brain** by dropping a `brain.klypix` into it — the
|
|
129
|
+
[KLYPIX app](https://klypix.com) does it in one click (*Save canvas as project brain*), or
|
|
130
|
+
`create_canvas` makes one from any agent.
|
|
131
|
+
|
|
132
|
+
---
|
|
133
|
+
|
|
134
|
+
## How the brain works
|
|
135
|
+
|
|
136
|
+
The difference from a folder of notes is not the shape — it is that this memory is a mechanism,
|
|
137
|
+
not a filing convention.
|
|
138
|
+
|
|
139
|
+
- **Decisions have a lifecycle.** A new decision that contradicts an old one supersedes it. The
|
|
140
|
+
stale card is archived with an arrow and a date, never deleted, and later answers surface the
|
|
141
|
+
correction rather than the corpse.
|
|
142
|
+
- **Corrections are explicit, not guessed.** Supersession fires on an UPPERCASE correction cue or
|
|
143
|
+
an explicit edge. `brain_reconcile` only *proposes* stale-vs-correction pairs for a human to
|
|
144
|
+
confirm.
|
|
145
|
+
- **Cards can cite the code they were decided against.** An `ev:` anchor records a file:line plus
|
|
146
|
+
the git blob OID at capture time, so the engine can flag a card whose cited code has since moved
|
|
147
|
+
on. It detects that the code *changed* — never that the claim became false.
|
|
148
|
+
- **Position means something.** Drag a card into the 📌 Focus area and it leads every future
|
|
149
|
+
session's brief. That is brief priority, not a retrieval-ranking boost.
|
|
150
|
+
- **You can ask what the project believed then.** `brain_ask` with `as_of: 2026-03-01` reweights
|
|
151
|
+
ranking by card lifecycle dates, so corrections made later do not leak backwards.
|
|
152
|
+
- **Retrieval is local.** Lexical by default. If the optional on-device model is installed,
|
|
153
|
+
`brain_ask` and `search_all_brains` blend semantic similarity with lexical scoring and rerank
|
|
154
|
+
with a cross-encoder — still entirely on your machine. Without it, retrieval degrades cleanly to
|
|
155
|
+
lexical. `npx klypix-mcp install` deliberately does not install that model, so a fresh install
|
|
156
|
+
is lexical.
|
|
157
|
+
|
|
158
|
+
---
|
|
159
|
+
|
|
160
|
+
## Supported hosts and their integration level
|
|
161
|
+
|
|
162
|
+
Levels are honest. Only the config-writing side is tested for the `link` hosts; their host-side
|
|
163
|
+
behaviour is unverified.
|
|
164
|
+
|
|
165
|
+
| Host | Level | Wired by | Brief into context | Decision capture | Live presence |
|
|
166
|
+
|---|---|---|---|---|---|
|
|
167
|
+
| **Claude Code** | Full automatic (4 lifecycle hooks) | `install` | Automatic at session start, task-ranked retrieval per prompt | **Automatic** at turn end | Yes |
|
|
168
|
+
| **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 |
|
|
169
|
+
| **Cursor** | MCP config + always-on rules file | `link` | Model must call `brain_sync` | Model must call `brain_note` | For the MCP connection |
|
|
170
|
+
| **Cline** | MCP config + always-on rules file | `link` | Model must call `brain_sync` | Model must call `brain_note` | For the MCP connection |
|
|
171
|
+
| **VS Code (Copilot / Continue)** | MCP config + instructions file | `link` | Model must call `brain_sync` | Model must call `brain_note` | For the MCP connection |
|
|
172
|
+
| **Gemini CLI / Antigravity** | MCP config + always-on rules file | `link` | Model must call `brain_sync` | Model must call `brain_note` | For the MCP connection |
|
|
173
|
+
| **Windsurf** | Rules file only | `link` | Reaches the tools through Windsurf's own global MCP config | Model must call `brain_note` | Via its own MCP config |
|
|
174
|
+
| **Aider** | Rules file only (no MCP) | `link` | CLI path: `npx klypix-read` | CLI path: `npx klypix-append` | — |
|
|
175
|
+
| **Claude Desktop** | One-time manual config edit | you | Model must call `brain_sync` | Model must call `brain_note` | For the MCP connection |
|
|
176
|
+
|
|
177
|
+
`install` and `link` are different things and are not interchangeable: `install` is machine-global
|
|
178
|
+
and only touches Claude Code and Codex; `link` is per project and is what wires everything else.
|
|
179
|
+
|
|
180
|
+
**Claude Desktop** — add this to `claude_desktop_config.json` by hand; nothing writes that file
|
|
181
|
+
for you:
|
|
92
182
|
|
|
93
183
|
```json
|
|
94
184
|
{
|
|
@@ -101,72 +191,163 @@ Any MCP client gets the tools and connection-lifecycle presence without host hoo
|
|
|
101
191
|
}
|
|
102
192
|
```
|
|
103
193
|
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
to
|
|
194
|
+
---
|
|
195
|
+
|
|
196
|
+
## Task briefing
|
|
197
|
+
|
|
198
|
+
Every Claude Code session starts already knowing the project: a bounded ~5KB brief in context, with
|
|
199
|
+
the full brief written to disk for when broad history or status work needs it.
|
|
200
|
+
|
|
201
|
+
Every other host gets a bounded ~2.8KB task capsule from one `brain_sync` call, plus a compact
|
|
202
|
+
always-loaded `AGENTS.md` block that tells the agent to make that call at task start, when scope
|
|
203
|
+
changes, and on completion. The gateway capsule is lexical-fast by design.
|
|
204
|
+
|
|
205
|
+
Briefs are **not** injected automatically on Cursor, Cline, Copilot, Gemini CLI or Antigravity —
|
|
206
|
+
there are no lifecycle hooks on those hosts.
|
|
207
|
+
|
|
208
|
+
## Capture and corrections
|
|
209
|
+
|
|
210
|
+
On Claude Code, decisions are captured automatically at turn end from inline `🧠 BRAIN [Area]:`
|
|
211
|
+
markers in the transcript, deduped, under a capture lock.
|
|
212
|
+
|
|
213
|
+
On every other host, capture is explicit: `brain_note` runs the same capture engine as the hooks —
|
|
214
|
+
dedup, supersession, `✓` resolve, `~` update in place, `+` skill, `closes:` — and stamps which
|
|
215
|
+
agent wrote the card. (If you install the git commit hook from the KLYPIX app, commit messages also
|
|
216
|
+
capture automatically, for any agent. That hook has no CLI installer.)
|
|
217
|
+
|
|
218
|
+
`brain_challenge` is the other direction: propose a decision and the brain answers with receipts —
|
|
219
|
+
prior decisions that deterministically contradict it, standing rules that dispute it, and
|
|
220
|
+
approaches tried and reversed, flagged when a different agent wrote them. Evidence is deterministic
|
|
221
|
+
only (explicit correction cues, opposite-polarity pairs), never mere topical similarity. Silence
|
|
222
|
+
means no contradiction signal was found — not verified consistency. A memory that cannot disagree
|
|
223
|
+
with you is flattery.
|
|
224
|
+
|
|
225
|
+
## Presence and task intent
|
|
226
|
+
|
|
227
|
+
An active session means an authorized MCP connection or host lifecycle adapter that heartbeated
|
|
228
|
+
within the TTL. A row in a recent-chat list is history, not presence.
|
|
229
|
+
|
|
230
|
+
Each MCP connection registers itself at initialization and removes itself on disconnect; the TTL
|
|
231
|
+
covers crashes. Optional host adapters merge into that same logical session rather than
|
|
232
|
+
double-counting it, enrich it with intent and files, and remove only their own channel. Sessions
|
|
233
|
+
that never declared a task are still counted, but are shown separately as scope-unknown rather than
|
|
234
|
+
padding the peer list.
|
|
235
|
+
|
|
236
|
+
Future hosts get baseline support merely by connecting the MCP server. A deeper adapter can import
|
|
237
|
+
`klypix-mcp/presence` and map lifecycle events onto `upsertSession`, `removeSession`,
|
|
238
|
+
`peekMessages` and `receiveMessages`. The shared contract accepts `id`, `client`, `surface`,
|
|
239
|
+
`model`, `branch`, `intent`, touched `files`, and adapter `channel`.
|
|
240
|
+
|
|
241
|
+
## Overlap warnings
|
|
242
|
+
|
|
243
|
+
When two sessions declare overlapping expected files, `brain_sync` surfaces it: the peer, its
|
|
244
|
+
declared task, and the exact paths in common. A one-time alert is queued to whichever session got
|
|
245
|
+
there first, so a late arrival is not the only one who knows.
|
|
246
|
+
|
|
247
|
+
This warns. It does not prevent. Nothing blocks an edit, matching is exact-path, and both sides
|
|
248
|
+
have to have declared their files for the overlap to be visible at all.
|
|
249
|
+
|
|
250
|
+
## Handoffs and messages
|
|
251
|
+
|
|
252
|
+
`brain_message` leaves one-time coordination notes for other sessions. They arrive on the peer's
|
|
253
|
+
next KLYPIX action, expire after 24 hours, and are never written into the brain. Delivery is
|
|
254
|
+
best-effort-proactive through MCP logging (which some hosts hide) and in-band on the peer's next
|
|
255
|
+
action. A peer that stays offline past the TTL misses the note.
|
|
256
|
+
|
|
257
|
+
Durable handoffs go in the brain itself — decisions, findings, open questions and skills captured
|
|
258
|
+
as cards, each stamped with the agent that wrote it.
|
|
259
|
+
|
|
260
|
+
## Human control in Klypix
|
|
261
|
+
|
|
262
|
+
> **Not a second brain. A shared one.**
|
|
263
|
+
|
|
264
|
+
A brain nobody can inspect is a database with good marketing. The
|
|
265
|
+
[KLYPIX desktop app](https://klypix.com) renders the same `brain.klypix` as a living spatial map,
|
|
266
|
+
with health, freshness, provenance and orrery lenses, an unresolved-questions triage view, and a
|
|
267
|
+
one-click flow that connects a folder's brain to six coding agents. You can read, correct, archive
|
|
268
|
+
and re-link what your agents recorded.
|
|
269
|
+
|
|
270
|
+
The file is co-owned. When the app saves a brain it re-reads the disk copy inside the same capture
|
|
271
|
+
lock the agent hooks use and union-merges instead of overwriting, so a card an agent captured while
|
|
272
|
+
you had the file open is kept. The merge verifies its own output and aborts rather than emit a file
|
|
273
|
+
missing a card. Deletes require an explicit tombstone, so a card that is merely absent is never
|
|
274
|
+
inferred as deleted.
|
|
275
|
+
|
|
276
|
+
The app is a separate, proprietary Windows product. The format, this server and the hooks are
|
|
277
|
+
Apache-2.0 and work with no app installed. The app's interface is available in English and Arabic
|
|
278
|
+
(some newer panels are still English-only).
|
|
279
|
+
|
|
280
|
+
## Git and concurrency
|
|
281
|
+
|
|
282
|
+
One file in your repo, committed with your code — versioned, branchable, portable.
|
|
283
|
+
|
|
284
|
+
Be precise about what git does here: `brain.klypix` is a binary ZIP. Git shows
|
|
285
|
+
`Bin 1308328 -> 1309005 bytes`, produces zero line diffs, and a merge conflict on it is an
|
|
286
|
+
all-or-nothing take-ours or take-theirs. You cannot review a brain change in a PR diff. **All
|
|
287
|
+
card-level merge safety comes from the KLYPIX engine, not from git.**
|
|
288
|
+
|
|
289
|
+
Concurrent sessions serialize behind a capture lock, and each write is a temp file plus an atomic
|
|
290
|
+
rename, so a crash mid-write leaves the previous good file intact. The lock is advisory with a
|
|
291
|
+
~3.6-second budget: past that, a writer proceeds anyway and flags it in the health log, so
|
|
292
|
+
sustained contention can still lose an update. That is a deliberate trade — dropping the markers
|
|
293
|
+
was judged worse — but it is a real limit, not a guarantee.
|
|
294
|
+
|
|
295
|
+
---
|
|
110
296
|
|
|
111
297
|
## The 18 verbs
|
|
112
298
|
|
|
113
299
|
| Tool | What it does |
|
|
114
300
|
|---|---|
|
|
115
|
-
| `brain_ask` | Whole-brain question answering — correction-aware, `as_of` time
|
|
301
|
+
| `brain_ask` | Whole-brain question answering — correction-aware, `as_of` time travel |
|
|
116
302
|
| `brain_challenge` | The brain argues back: contradictions with receipts, tried-and-reversed chains, standing rules, other-agent provenance flags |
|
|
117
|
-
| `brain_note` | Capture with the full lifecycle — supersede / ✓ resolve / ~ update / 🛠 skill / closes
|
|
118
|
-
| `brain_reconcile` |
|
|
303
|
+
| `brain_note` | Capture with the full lifecycle — supersede / ✓ resolve / ~ update / 🛠 skill / `closes:` |
|
|
304
|
+
| `brain_reconcile` | Proposes stale-vs-correction pairs and unrecorded migrations for a human to confirm |
|
|
119
305
|
| `brain_insights` | Hubs, orphaned decisions, stale questions, area sizes |
|
|
120
|
-
| `brain_lens` | Machine-readable freshness, provenance, activity, timeline, orrery
|
|
121
|
-
| `brain_garden` | Maintenance pass
|
|
122
|
-
| `brain_doctor` | Self-diagnosis: version, core/enhanced host adapters, active sessions, projection drift |
|
|
123
|
-
| `brain_message` | Session-to-session coordination notes |
|
|
124
|
-
| `brain_sync` | Context Gateway:
|
|
125
|
-
| `brain_connect` | Find
|
|
126
|
-
| `canvas_view` |
|
|
306
|
+
| `brain_lens` | Machine-readable freshness, provenance, activity, timeline, orrery and unresolved views |
|
|
307
|
+
| `brain_garden` | Maintenance pass — proposes first, and cannot apply without an approval code the human generates |
|
|
308
|
+
| `brain_doctor` | Self-diagnosis: version, core/enhanced host adapters, active sessions, tool count, projection drift |
|
|
309
|
+
| `brain_message` | Session-to-session coordination notes (24h TTL, never written into the brain) |
|
|
310
|
+
| `brain_sync` | Context Gateway: task capsule, active-task peers, exact-file overlap, one-time alerts, timing |
|
|
311
|
+
| `brain_connect` | Find and draw related-but-unlinked cards |
|
|
312
|
+
| `canvas_view` | Returns the board as a structured render spec plus a text summary, and declares an MCP Apps (SEP-1865) UI resource |
|
|
127
313
|
| `read_canvas` | A canvas as markdown (cards, connection graph, `[[links]]`, `#tags`) |
|
|
128
|
-
| `search_canvases` | Search across canvases by name
|
|
129
|
-
| `search_all_brains` | Cross-project memory search across every registered brain |
|
|
314
|
+
| `search_canvases` | Search across canvases by name and content |
|
|
315
|
+
| `search_all_brains` | Cross-project memory search across every registered brain on this machine |
|
|
130
316
|
| `create_canvas` | New `.klypix` from cards + connections |
|
|
131
317
|
| `add_to_canvas` | Append cards/connections (positions preserved) |
|
|
132
318
|
| `list_canvases` | List every `.klypix` in the vault |
|
|
133
319
|
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
This package is the **agent-neutral read/write surface** — any MCP client gets the tools above on demand (*pull*), automatically registers presence for the lifetime of its authorized connection, and receives the Context Gateway workflow through standard MCP server instructions. `install` wires Claude Code's existing capture path and installs the local runtime; `link` projects repository-level MCP and instruction files for Codex and other coding agents. Codex and other clients retrieve relevant project memory and coordinate task intent/files through one `brain_sync` call, while `brain_note` captures durable decisions explicitly; optional host hooks add mechanically guaranteed lifecycle capture.
|
|
137
|
-
|
|
138
|
-
### Agent-neutral live presence
|
|
320
|
+
Exactly 18, machine-verifiable with `npx klypix-mcp doctor`.
|
|
139
321
|
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
Optional host adapters merge into that same logical session rather than double-counting
|
|
144
|
-
it, enrich it with intent/files, and remove only their own channel. The TTL covers crashes.
|
|
322
|
+
> **`canvas_view`:** no MCP Apps host has been observed rendering the UI resource yet — there is no
|
|
323
|
+
> screenshot and no host-level test. Hosts without the extension get clean text, which is the path
|
|
324
|
+
> that is actually verified.
|
|
145
325
|
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
`
|
|
149
|
-
`surface`, `model`, `branch`, `intent`, touched `files`, and adapter `channel`;
|
|
150
|
-
host-specific transcript parsing stays outside the protocol.
|
|
326
|
+
`brain_doctor`, `brain_lens`, `brain_insights` and `brain_reconcile` are read-only introspection.
|
|
327
|
+
`brain_garden`, `brain_reconcile` and `brain_connect` always propose before they apply.
|
|
328
|
+
`npx klypix-mcp doctor` gives one verdict and exits non-zero on drift, so it doubles as a CI gate.
|
|
151
329
|
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
`install` lays the whole brain (hooks + engine + local MCP runtime) into `~/.claude/project-brain` and binds the current brain project's Codex config to that exact project on the current machine. `brain_sync` also accepts the current project root, providing a host-independent fallback when an IDE starts MCP from its own install directory.
|
|
155
|
-
|
|
156
|
-
Updates are host-neutral. The MCP supervisor performs one machine-wide npm check per 24 hours, no matter how many Codex, Claude, Cursor, Cline, Antigravity, or generic MCP sessions are open. It installs an exact stable same-major release in `--runtime-only` mode, preserving host settings and project files. The check is detached and fail-open, developer-owned installs are protected, concurrent sessions collapse behind one lock, new major versions require a deliberate manual install, and `KLYPIX_AUTO_UPDATE=0` opts out. The Claude session-start updater remains as a compatible bootstrap path for older installations.
|
|
157
|
-
|
|
158
|
-
The MCP entry point is a stable stdio supervisor. It keeps the host-owned connection open while a replaceable worker runs the brain core. A staged update is hash-verified, initialized in parallel, checked for backward-compatible tool schemas, and given the current `brain_sync` task scope before the supervisor switches between requests. Added tools use the standard `notifications/tools/list_changed` signal. A failed or breaking candidate is rejected while the old worker continues serving.
|
|
330
|
+
## One file you can hold
|
|
159
331
|
|
|
160
|
-
|
|
332
|
+
The whole brain — layout, cards, arrows, and the actual bytes (images, PDFs, audio, code) — is a
|
|
333
|
+
single `.klypix` file: a plain ZIP with `manifest.json`, `canvas.json`, one JSON file per card, and
|
|
334
|
+
an `assets/` folder. Email it. Git it. Hand it to an agent. A folder of markdown points at its
|
|
335
|
+
attachments; this file carries them.
|
|
161
336
|
|
|
162
|
-
|
|
337
|
+
The parser is this package, Apache-2.0, so any tool or agent can read and write the format. Full
|
|
338
|
+
spec: [FORMAT.md](FORMAT.md).
|
|
163
339
|
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
```
|
|
340
|
+
Markdown export, JSON Canvas 1.0 export and direct opening of Obsidian `.canvas` files are features
|
|
341
|
+
of the **KLYPIX desktop app**, not of this package — there is no export command among this
|
|
342
|
+
package's binaries.
|
|
168
343
|
|
|
169
|
-
|
|
344
|
+
**"Project" means any project.** Two showcase brains ship in the GitHub repo under
|
|
345
|
+
[`examples/`](examples/), identical in engine, different in life:
|
|
346
|
+
[`showcase-brain.klypix`](examples/showcase-brain.klypix) is *Aurora*, a fictional weather app
|
|
347
|
+
mid-build (radar tiles, API caps, a correction with its receipt), and
|
|
348
|
+
[`showcase-wedding.klypix`](examples/showcase-wedding.klypix) is *Our Wedding* (venue, vendors,
|
|
349
|
+
guest list, the same correction machinery pointed at a caterer). Same 📌 Focus, same arrows, same
|
|
350
|
+
brief. If it has decisions worth keeping, it gets a brain.
|
|
170
351
|
|
|
171
352
|
## Use it as a library
|
|
172
353
|
|
|
@@ -180,18 +361,142 @@ echo '{ "title": "Plan", "cards": [{ "text": "kickoff" }] }' \
|
|
|
180
361
|
| npx -p klypix-mcp klypix-write --out plan.klypix
|
|
181
362
|
```
|
|
182
363
|
|
|
183
|
-
##
|
|
364
|
+
## Also speaks A2A (Agent-to-Agent) — experimental
|
|
365
|
+
|
|
366
|
+
```bash
|
|
367
|
+
npx -p klypix-mcp klypix-a2a --vault ./canvases # 127.0.0.1:41241
|
|
368
|
+
# Agent Card: http://127.0.0.1:41241/.well-known/agent-card.json
|
|
369
|
+
```
|
|
370
|
+
|
|
371
|
+
Nine skills: `make_board`, `remember`, `learn_skill`, `recall`, `read_canvas`, `list_canvases`,
|
|
372
|
+
`brain_insights`, `search_all_brains`, `brain_connect`. Unlike a typical A2A agent that returns
|
|
373
|
+
text, KLYPIX returns the `.klypix` board itself as a multimodal artifact. Details:
|
|
374
|
+
[A2A.md](A2A.md).
|
|
375
|
+
|
|
376
|
+
Treat this as a preview: the A2A smoke test is not in the default `npm test` chain, and it has not
|
|
377
|
+
been exercised against a third-party A2A client.
|
|
378
|
+
|
|
379
|
+
## Updates — the propagation contract
|
|
380
|
+
|
|
381
|
+
The MCP entry point is a stable stdio supervisor that keeps the host-owned connection open while a
|
|
382
|
+
replaceable worker runs the brain core. A staged update is hash-verified, initialized in parallel,
|
|
383
|
+
checked for backward-compatible tool schemas, and handed the current `brain_sync` task scope before
|
|
384
|
+
the supervisor switches between requests. Added tools use the standard
|
|
385
|
+
`notifications/tools/list_changed` signal. A failed or breaking candidate is rejected while the old
|
|
386
|
+
worker keeps serving.
|
|
387
|
+
|
|
388
|
+
Compatible engine updates therefore activate behind the same live connection — no reconnect, no
|
|
389
|
+
host restart. Three cases still require a deliberate reconnect or manual install: the one-time
|
|
390
|
+
legacy→supervisor migration, a supervisor-code change, and a major or tool-removing release.
|
|
391
|
+
`brain_doctor` reports the live supervisor and the automatic-update receipt explicitly.
|
|
392
|
+
|
|
393
|
+
The supervisor performs **one machine-wide npm version check per 24 hours**, however many sessions
|
|
394
|
+
are open. It installs an exact stable same-major release in `--runtime-only` mode, preserving host
|
|
395
|
+
settings and project files. The check is detached and fail-open, developer-owned installs are
|
|
396
|
+
protected, concurrent sessions collapse behind one lock, and `KLYPIX_AUTO_UPDATE=0` opts out
|
|
397
|
+
entirely.
|
|
398
|
+
|
|
399
|
+
## Security and permissions
|
|
400
|
+
|
|
401
|
+
- **Apache-2.0, source public** at [github.com/dahshanlabs/klypix-mcp](https://github.com/dahshanlabs/klypix-mcp).
|
|
402
|
+
- **The brain engine makes no network calls and sends no telemetry.** All engine intelligence is
|
|
403
|
+
deterministic and local; the only LLM anywhere is *your* agent. The one exception in this package
|
|
404
|
+
is the supervisor's once-per-24h npm version check described above — turn it off with
|
|
405
|
+
`KLYPIX_AUTO_UPDATE=0`.
|
|
406
|
+
- **The optional semantic model runs on device.** No cloud inference on any retrieval path.
|
|
407
|
+
- **Coordination state is local files.** The brain is a file in your repo; the presence lane is a
|
|
408
|
+
file under your home directory. Nothing is uploaded.
|
|
409
|
+
- **`install` writes to your home directory:** `~/.claude/project-brain` (engine + runtime),
|
|
410
|
+
`~/.claude/settings.json` (four hooks — written even if Claude Code is not installed) and Codex
|
|
411
|
+
config. **`link` writes 14 files inside the project** you run it in; `link --check` audits them
|
|
412
|
+
without writing.
|
|
413
|
+
- **Codex hooks require Codex's own trust approval** and are opt-in via `--codex-hooks`.
|
|
414
|
+
|
|
415
|
+
## Current limitations
|
|
416
|
+
|
|
417
|
+
Read this section before you build on any of it.
|
|
418
|
+
|
|
419
|
+
- **Coordination is machine-local and OS-user-local.** The presence lane is a file in your home
|
|
420
|
+
directory. Two developers on two machines do not see each other's sessions, peers, overlaps or
|
|
421
|
+
messages. There is no cross-machine or cross-team coordination today.
|
|
422
|
+
- **Overlap matching is exact-path, and both sides must declare.** A session that never declares
|
|
423
|
+
its expected files is invisible to overlap detection, and `src/auth/token.ts` does not match a
|
|
424
|
+
rename or a parent directory.
|
|
425
|
+
- **Overlap warnings are advisory.** Nothing is blocked. One severity string in the payload reads
|
|
426
|
+
`blocking`; the mechanism is not.
|
|
427
|
+
- **Codex has no automatic capture**, with or without `--codex-hooks`. The Codex hook never writes
|
|
428
|
+
the brain.
|
|
429
|
+
- **There is no uninstall command.** Removing Klypix means hand-editing `~/.claude/settings.json`,
|
|
430
|
+
`~/.codex/config.toml` and `~/.codex/hooks.json`, deleting `~/.claude/project-brain`, and
|
|
431
|
+
deleting the 14 per-project files. The removal primitives exist in the source but no CLI reaches
|
|
432
|
+
them yet.
|
|
433
|
+
- **Drift detection is single-host and opt-in per card.** It needs an `ev:` anchor written by the
|
|
434
|
+
card's author, and it runs only in the Claude Code hook path — the MCP tools do not compute
|
|
435
|
+
freshness.
|
|
436
|
+
- **`search_all_brains` finds nothing for a Cursor-only or Codex-only setup.** The cross-project
|
|
437
|
+
registry is written by the Claude Code hook and only by it. This is a silent empty result, not an
|
|
438
|
+
error.
|
|
439
|
+
- **`npx klypix-mcp link` does not manage `CLAUDE.md`.** It manages `AGENTS.md` and seven other
|
|
440
|
+
rules files. Only the desktop app writes `CLAUDE.md`.
|
|
441
|
+
- **A fresh `npx klypix-mcp install` gets lexical retrieval.** The optional on-device model is
|
|
442
|
+
deliberately not installed.
|
|
443
|
+
- **The capture lock is fail-open** past ~3.6 seconds of contention (see *Git and concurrency*).
|
|
444
|
+
- **Tests are developer-run, not CI-gated.** The npm publish workflow runs no tests, and `test/` is
|
|
445
|
+
not in the published tarball.
|
|
446
|
+
- **`canvas_view`'s MCP Apps UI has never been verified on a real Apps host.**
|
|
447
|
+
|
|
448
|
+
## Numbers and methodology
|
|
449
|
+
|
|
450
|
+
Every number here is measured on our own project brain. Nothing below is published, benchmarked or
|
|
451
|
+
independently validated.
|
|
452
|
+
|
|
453
|
+
- **Dogfood scale.** KLYPIX itself is built with its own brain: **1,523 cards and 1,404
|
|
454
|
+
connections**, written by multiple concurrent agent sessions, receipts in the file. Current as of
|
|
455
|
+
2026-07-30.
|
|
456
|
+
- **Recall.** 73% of past decisions recovered with one search round, 55% brief-only, 0% cold.
|
|
457
|
+
Caveat that travels with it: n=20, our own brain, self-authored questions, LLM-judged.
|
|
458
|
+
- **Ranker.** recall@5 of the true source card went **15% → 40%** across two upgrades (n=20 frozen
|
|
459
|
+
human-paraphrase questions), measured with the optional on-device reranker enabled. The
|
|
460
|
+
experiment that *regressed* — contextual prefixes on short cards — is recorded next to the wins.
|
|
461
|
+
- **What we do not publish.** No download count: this package's own 24-hour auto-updater generates
|
|
462
|
+
most of it, so it is not a user count. No adoption, team or customer figures. No brief-token
|
|
463
|
+
figure — the last one was measured at ~600 cards and is stale at 1,523.
|
|
464
|
+
- **The eval harness is not in this repo.** It lives in the private KLYPIX desktop repository. The
|
|
465
|
+
numbers above are ours to defend, not yours to reproduce from here — treat them accordingly.
|
|
466
|
+
|
|
467
|
+
## Uninstall
|
|
468
|
+
|
|
469
|
+
There is no uninstall command yet. To remove Klypix by hand:
|
|
470
|
+
|
|
471
|
+
```bash
|
|
472
|
+
rm -rf ~/.claude/project-brain
|
|
473
|
+
# then remove the klypix hook entries from ~/.claude/settings.json
|
|
474
|
+
# and the klypix MCP entry from ~/.codex/config.toml (and ~/.codex/hooks.json if you used --codex-hooks)
|
|
475
|
+
npx klypix-mcp link --check # lists the 14 managed files in a project, so you know what to delete
|
|
476
|
+
```
|
|
477
|
+
|
|
478
|
+
Your `brain.klypix` is yours — it is a plain ZIP and stays readable with or without this package.
|
|
184
479
|
|
|
185
|
-
|
|
480
|
+
## Contributing
|
|
186
481
|
|
|
187
|
-
|
|
482
|
+
Issues and pull requests: [github.com/dahshanlabs/klypix-mcp](https://github.com/dahshanlabs/klypix-mcp).
|
|
188
483
|
|
|
189
|
-
|
|
190
|
-
-
|
|
191
|
-
|
|
484
|
+
The repository carries 28 test files covering the presence lane, Context Gateway, supervisor
|
|
485
|
+
hot-swap, auto-update, retrieval quality, decay, challenge, lenses and conformance. Run them with
|
|
486
|
+
`npm test` from a clone — they are not in the published tarball and the publish workflow does not
|
|
487
|
+
run them. There is a known intermittent Windows `EPERM` flake on rename in
|
|
488
|
+
`test/mcp-supervisor.mjs`.
|
|
192
489
|
|
|
193
490
|
## Why this exists
|
|
194
491
|
|
|
195
|
-
|
|
492
|
+
A model provider can fix continuity inside its own sessions, and several are. None of them will
|
|
493
|
+
ever carry a competitor's context. Cross-tool, cross-agent and cross-provider understanding is the
|
|
494
|
+
seam that stays open — so it should live in a file you own, in your repo, that any agent can read
|
|
495
|
+
and write.
|
|
496
|
+
|
|
497
|
+
**Your project, your file, any supported agent, offline.**
|
|
498
|
+
|
|
499
|
+
---
|
|
196
500
|
|
|
197
|
-
Apache-2.0 © [Dahshan Labs](https://klypix.com). The KLYPIX desktop app is a separate, proprietary
|
|
501
|
+
Apache-2.0 © [Dahshan Labs](https://klypix.com). The KLYPIX desktop app is a separate, proprietary
|
|
502
|
+
product — the format and this server are fully open and work without it.
|
package/package.json
CHANGED
|
@@ -1,12 +1,18 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "klypix-mcp",
|
|
3
|
-
"version": "1.43.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "1.43.1",
|
|
4
|
+
"description": "Shared project brain and MCP coordination server for multi-agent coding.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "Apache-2.0",
|
|
7
7
|
"keywords": [
|
|
8
8
|
"mcp",
|
|
9
9
|
"model-context-protocol",
|
|
10
|
+
"multi-agent",
|
|
11
|
+
"agent-coordination",
|
|
12
|
+
"project-memory",
|
|
13
|
+
"project-continuity",
|
|
14
|
+
"coding-agent",
|
|
15
|
+
"context-engineering",
|
|
10
16
|
"a2a",
|
|
11
17
|
"agent2agent",
|
|
12
18
|
"agent-interoperability",
|
|
@@ -15,8 +21,6 @@
|
|
|
15
21
|
"agent-memory",
|
|
16
22
|
"local-first",
|
|
17
23
|
"klypix",
|
|
18
|
-
"whiteboard",
|
|
19
|
-
"spatial",
|
|
20
24
|
"ai"
|
|
21
25
|
],
|
|
22
26
|
"homepage": "https://klypix.com",
|