klypix-mcp 1.25.0 → 1.29.0

package/FORMAT.md

@@ -2,7 +2,7 @@
 
 `.klypix` is an **open, local-first, agent-neutral** canvas file. It's a plain
 **ZIP** of JSON + assets — no proprietary binary, fully inspectable (`unzip
-your.klypix`), and parseable with the MIT library in this package. You own it;
+your.klypix`), and parseable with the Apache-2.0 library in this package. You own it;
 any agent or app can read and write it.
 
 ## Container layout

package/LICENSE

@@ -1,21 +1,202 @@
-MIT License
-
-Copyright (c) 2026 Abdullah Aldahshan — Dahshan Labs
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,35 +1,54 @@
-# klypix-mcp
+# Every project gets a brain.
 
-**An open, local-first, agent-neutral canvas file your AI reads and writes over MCP — works with Claude, Cursor, Cline, any model.**
+### Not a *second* brain. A **shared** one.
 
-Your AI forgets everything between sessions, and you can't hand it your *whole*
-messy project at once. `klypix-mcp` fixes that with a single portable file:
+You've seen the setup: point an AI at a folder of notes, watch the graph fill up, call it a brain. Look closer — **the human never touches anything.** Even the pattern's inventor says it: *"you never write the wiki yourself… I browse the results in real time."* The human is a reader. The AI is the sole writer. That's not a brain — that's an aquarium.
 
-- **`.klypix`** is one file that holds your whole project spatially — text, PDFs,
-  screenshots, audio, code, links — arranged and connected on an infinite canvas.
-- This package is an **MCP server**: any MCP-capable agent (Claude Desktop,
-  Cursor, Cline, …) can **list, read, search, create, and append** to your
-  `.klypix` canvases — so your agent gets durable, multimodal, *spatial* memory.
-- **Local-first + agent-neutral.** The file lives on *your* disk. No lab is in
-  the loop — read it with Claude today, GPT tomorrow, a local model next week.
-  No vendor can take it away.
+**`klypix-mcp` gives your project a brain you're allowed inside while it works.** One file — `brain.klypix` — in your repo, versioned with git, that your AI agents read, write, and argue from. And in the [KLYPIX app](https://klypix.com), you work *in* it while they do: your cursor typing in one card while agent decisions land beside your hands, each in its area, with an arrow explaining why — and the save refuses to write a file that lost a card.
 
-> **The shared memory layer for your multi-agent stack.** A2A moves the messages
-> between agents; MCP connects an agent to its tools; **`.klypix` is the owned,
-> multimodal context both layers read and write.** KLYPIX ships *two* faces over
-> one engine — an **MCP server** (`klypix-mcp`) and an **A2A agent**
-> (`klypix-a2a`) — so whichever protocol your stack speaks, the memory node is
-> the same portable file you own. See **[A2A.md](A2A.md)**.
+> *Their AI keeps a diary about your project. Ours works in the same room as you — and the room remembers.*
 
-## Quick start (60 seconds)
+## Quick start
+
+**Claude Code (native — live hooks, zero effort):**
+
+```bash
+npx klypix-mcp install
+```
+
+Every repo on your machine with a `brain.klypix` now auto-briefs each session with the project's state and auto-captures decisions as you work. Give a project a brain by dropping a `brain.klypix` in it — the [KLYPIX app](https://klypix.com) does it in one click (*Save canvas as project brain*), or `create_canvas` makes one from any agent.
+
+**Every other agent tool (one command per project):**
 
 ```bash
-# point it at any folder of .klypix files (a "vault")
-npx klypix-mcp --vault ./canvases
+npx klypix-mcp link
 ```
 
-Then add it to your MCP client. For **Claude Desktop**, in
-`claude_desktop_config.json`:
+Extends the brain to Cursor & VS Code/Copilot (MCP config + rules) and to Cline, Windsurf, Gemini CLI, Aider, and any AGENTS.md-reading agent — always-on rules that teach the tool to read and capture the brain.
+
+## What a project brain does
+
+The difference from a folder of notes is not the shape — it's that this memory is a **mechanism, not a filing convention**:
+
+- **It briefs every session.** Each agent session starts already knowing the project's decisions, open questions, and standing rules — a compact brief (≈3–5k tokens even at 600+ cards, growing sublinearly). Measured on our own brain: **73% of past decisions recovered with one search round (55% brief-only) vs 0% cold** (n=20).
+- **It argues back.** `brain_challenge`: propose a decision and the brain answers with receipts — *"you reversed this on June 12; here's the correction — captured by a different agent, coordinate before overriding."* Deterministic evidence only (correction-cues, opposite-polarity), never mere topical similarity. A memory that can't disagree with you is flattery.
+- **It knows when it's stale.** Decision cards can anchor to the exact code they were decided against (git blob OID). When that code moves on, the card raises its hand in the next brief. Their notes rot silently; ours confess.
+- **It answers from the past.** `brain_ask` with `as_of: 2026-03-01` answers what the project believed *then* — corrections from the future never leak backwards.
+- **Position means something.** Drag a card into the 📌 Focus area and it leads every future session's brief. Layout is instruction, not decoration.
+- **Many agents, no chaos.** Concurrent sessions take a capture lock (zero captures lost, tested at four simultaneous writers), tag *who* wrote each card, message each other through the brain (`brain_message`), and genuine contradictions surface as red arrows for a human to arbitrate — never auto-resolved.
+- **Retrieval that's measured, failures included.** Hybrid on-device search (semantic + lexical + cross-encoder rerank, no cloud): recall@5 of the true source card went **5% → 15% → 40%** across our upgrades (n=20 frozen human-paraphrase questions) — and the experiment that *regressed* (contextual prefixes on short cards) is recorded next to the wins.
+
+## One file you can hold
+
+The whole brain — layout, decisions, arrows, **and the actual bytes** (images, PDFs, audio, code) — is a single `.klypix` file. Email it. Git it. Hand it to an agent. A folder of markdown points at its attachments; this file *carries* them.
+
+And it's not a cage: everything **exports to Markdown and JSON Canvas** in one command, and **Obsidian `.canvas` files open directly** in KLYPIX. Plain markdown is the most portable text on earth — that's exactly why we export to it. Full spec: [FORMAT.md](FORMAT.md).
+
+**"Project" means any project.** Two showcase brains ship in [`examples/`](examples/), identical in engine, different in life: [`showcase-brain.klypix`](examples/showcase-brain.klypix) is *Aurora*, a fictional weather app mid-build (radar tiles, API caps, a correction with its receipt) — and [`showcase-wedding.klypix`](examples/showcase-wedding.klypix) is *Our Wedding* (venue, vendors, guest list, the same correction machinery pointed at a caterer). Same 📌 Focus, same arrows, same brief. If it has decisions worth keeping, it gets a brain.
+
+## Setup for plain MCP clients
+
+Any MCP client gets the tools without the hooks. For **Claude Desktop**, in `claude_desktop_config.json`:
 
 ```json
 {
@@ -42,71 +61,45 @@ Then add it to your MCP client. For **Claude Desktop**, in
 }
 ```
 
-Now ask your agent things like *"summarize the canvas `roadmap`,"* *"turn these
-notes into a board,"* or *"add a card with the decision we just made."*
+Then ask your agent things like *"what did we decide about auth?"*, *"challenge this: let's switch to polling"*, or *"turn these notes into a board."*
 
-## Tools the server exposes
+## The 16 verbs
 
 | Tool | What it does |
 |---|---|
-| `list_canvases` | List every `.klypix` in the vault |
-| `read_canvas` | Read a canvas as markdown (cards, the connection graph, `[[links]]`, `#tags`) |
+| `brain_ask` | Whole-brain question answering — correction-aware, `as_of` time-travel |
+| `brain_challenge` | The brain argues back: contradictions with receipts, tried-and-reversed chains, standing rules, other-agent provenance flags |
+| `brain_note` | Capture with the full lifecycle — supersede / ✓ resolve / ~ update / 🛠 skill / closes: |
+| `brain_reconcile` | Find stale-vs-correction pairs + unrecorded migrations |
+| `brain_insights` | Hubs, orphaned decisions, stale questions, area sizes |
+| `brain_garden` | Maintenance pass over the brain |
+| `brain_doctor` | Self-diagnosis: version alignment, hooks wired, projection drift |
+| `brain_message` | Session-to-session coordination notes |
+| `brain_connect` | Find + draw related-but-unlinked cards |
+| `canvas_view` | The board as an MCP App — Apps-capable chats get an interactive spatial view; everyone else gets clean text |
+| `read_canvas` | A canvas as markdown (cards, connection graph, `[[links]]`, `#tags`) |
 | `search_canvases` | Search across canvases by name + content |
 | `search_all_brains` | Cross-project memory search across every registered brain |
-| `brain_insights` | Hubs, orphaned decisions, stale questions, area sizes |
-| `brain_connect` | Find + draw related-but-unlinked cards (densify the graph) |
-| `brain_reconcile` | Flag committed-but-unrecorded DB migrations (the brain can't see prod) |
-| `create_canvas` | Create a new `.klypix` from cards + connections |
-| `add_to_canvas` | Append cards/connections to an existing canvas (positions preserved) |
+| `create_canvas` | New `.klypix` from cards + connections |
+| `add_to_canvas` | Append cards/connections (positions preserved) |
+| `list_canvases` | List every `.klypix` in the vault |
 
 ### Tools vs. the *automatic* brain
 
-This package is the **agent-neutral read/write surface** — any MCP client (Claude
-Code, Claude Desktop, Cursor, Cline, Windsurf…) gets the **tools** above and can
-read, search, and write canvases on demand (*pull*). That works in any agent, in
-any project.
-
-The **automatic** brain — auto-capturing decisions from your work, injecting the
-relevant cards into each prompt, and coordinating across concurrent sessions
-(*push*) — runs in a host **hook**, which is a Claude Code / KLYPIX-desktop
-feature, not part of this npm package. So `npx klypix-mcp` gives you the tools
-everywhere; the hands-free brain comes with the [KLYPIX desktop app](https://klypix.com)
-or the Claude Code project-brain hook. (`search_all_brains` is also hook-fed — it
-reads the cross-project registry the hook writes, so it stays empty until a hook
-has registered at least one brain.)
+This package is the **agent-neutral read/write surface** — any MCP client gets the tools above on demand (*pull*), in any project. The **automatic** brain — auto-capturing decisions from your work, injecting the brief into each session, coordinating concurrent sessions (*push*) — runs in a host **hook**, which `npx klypix-mcp install` wires for Claude Code (and the [KLYPIX desktop app](https://klypix.com) ships built-in). Other tools get the always-on rules via `link`.
 
 ### Updates — the propagation contract
 
-`npx klypix-mcp install` lays the whole brain (hooks + engine + local MCP server)
-into `~/.claude/project-brain`, and the emitted MCP config runs the server **from
-that installed bundle** (no npx cache to go stale). From then on updates are
-automatic: at session start the hook checks npm (≤ once/24h, fail-open, disable
-with `KLYPIX_AUTO_UPDATE=0`) and self-installs a newer release, so a publish
-reaches every machine by its **next session**.
-
-One honest caveat: a running stdio MCP server can't hot-swap, and **resuming a
-session (or opening a new chat in the same app) does not respawn it** — only a
-full app quit + reopen (or `/mcp` reconnect after the old process exits) starts
-the new binary. `brain_doctor` tells you when that's needed: its RUNNING line
-compares the *live server's* self-reported version against the installed bundle
-and npm, and reads `DRIFTED → /mcp reconnect` instead of pretending a stale
-server is current.
+`install` lays the whole brain (hooks + engine + local MCP server) into `~/.claude/project-brain`, and the emitted config runs the server **from that installed bundle** (no npx cache to go stale). Updates are then automatic: at session start the hook checks npm (≤ once/24h, fail-open, disable with `KLYPIX_AUTO_UPDATE=0`) and self-installs newer releases. One honest caveat: a running stdio server can't hot-swap — a new binary loads on the next full app launch (or `/mcp` reconnect); `brain_doctor`'s RUNNING line tells you when that's needed.
 
 ## Also speaks A2A (Agent-to-Agent)
 
-The same engine is exposed as an **A2A agent** so other agents and orchestrators
-can delegate memory tasks to KLYPIX as a discoverable peer:
-
 ```bash
 npx -p klypix-mcp klypix-a2a --vault ./canvases     # 127.0.0.1:41241
 # Agent Card: http://127.0.0.1:41241/.well-known/agent-card.json
 ```
 
-Skills: `make_board`, `remember`, `recall`, `read_canvas`, `list_canvases`,
-`brain_insights`, `search_all_brains`. Unlike a typical A2A agent that returns
-text, KLYPIX returns the **`.klypix` board itself** as a multimodal artifact.
-Full protocol details (JSON-RPC methods, message shapes, streaming) in
-**[A2A.md](A2A.md)**.
+Skills: `make_board`, `remember`, `recall`, `read_canvas`, `list_canvases`, `brain_insights`, `search_all_brains`. Unlike a typical A2A agent that returns text, KLYPIX returns the **`.klypix` board itself** as a multimodal artifact. Details: [A2A.md](A2A.md).
 
 ## Use it as a library
 
@@ -114,27 +107,24 @@ Full protocol details (JSON-RPC methods, message shapes, streaming) in
 import { parseKlypix, buildKlypix, appendToKlypix, structToMarkdown } from 'klypix-mcp';
 ```
 
-…or read/write from the shell:
-
 ```bash
 npx -p klypix-mcp klypix-read   path/to/board.klypix      # → markdown brief
 echo '{ "title": "Plan", "cards": [{ "text": "kickoff" }] }' \
   | npx -p klypix-mcp klypix-write --out plan.klypix
 ```
 
-## The `.klypix` format
+## The workspace it opens in
+
+The brain is open and free — this package, the hooks, the format. **[KLYPIX](https://klypix.com)** is the Windows app built around it: see the brain as a living spatial map, work inside it while your agents write, capture anything from anywhere, act with agents, share encrypted. Bilingual English/Arabic.
+
+## Honesty notes
 
-A `.klypix` is just a **ZIP** of JSON + assets — open, inspectable, versioned.
-Full spec in [FORMAT.md](FORMAT.md). The point: *you own the file, and any agent
-can drive it.*
+- Dogfooded hard: **KLYPIX itself is built with its own brain** — 600+ cards, multiple concurrent agent sessions, receipts in the file.
+- All engine intelligence is deterministic and local — the only LLM anywhere is *your* agent. No telemetry, no cloud calls, works offline.
+- Every number above is measured on our own project brain; the eval harness ships in the repo.
 
 ## Why this exists
 
-Frontier labs are racing to put your context inside *their* canvas — a roach
-motel your work checks into and never leaves for a competitor. `klypix-mcp` is
-the opposite: **your project, your file, any model, offline.** That's the one
-thing a lab is structurally disincentivized to build.
+Frontier labs are racing to put your context inside *their* memory — a roach motel your work checks into and never leaves for a competitor. `klypix-mcp` is the opposite: **your project, your file, any model, offline.** A brain that any agent reads and writes is the one thing a lab is structurally disincentivized to build.
 
-MIT licensed. Built by [Dahshan Labs](https://klypix.com). The KLYPIX desktop
-app is the spatial editor for these files — but the file and this server are
-fully open and work without it.
+Apache-2.0 © [Dahshan Labs](https://klypix.com). The KLYPIX desktop app is a separate, proprietary product — the file and this server are fully open and work without it.

package/bin/klypix-mcp.mjs

@@ -26,7 +26,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import {
   resolveVault, getEmbedder, buildKlypixMap, cardSchema, connSchema,
   opListCanvases, opReadCanvas, opSearchCanvases, opSearchAllBrains,
-  opBrainInsights, opBrainConnect, opBrainReconcile, opBrainGarden, opCreateCanvas, opAddToCanvas, opBrainNote, opBrainMessage, opBrainAsk, opBrainChallenge, opCanvasView,
+  opBrainInsights, opBrainConnect, opBrainReconcile, opBrainGarden, opCreateCanvas, opAddToCanvas, opBrainNote, opBrainMessage, opBrainAsk, opBrainChallenge, opCanvasView, opBrainLens,
 } from '../src/klypix-core.mjs';
 import { mcpServerEntry } from '../src/agent-rules.mjs';
 
@@ -63,6 +63,7 @@ if (process.argv[2] === 'init') {
   if (fs.existsSync(target)) { console.error(`brain.klypix already exists in ${process.cwd()} — not overwriting.`); process.exit(0); }
   const buf = await buildKlypixMap({
     title: 'project brain',
+    kind: 'brain',   // explicit flag — co-owned merge semantics survive a rename
     areas: [
       { title: 'Goal', cards: [{ text: '❓ What is this project for, and for whom?\nAgent: survey the repo on your first session and replace this with the real goal.' }] },
       { title: 'Architecture', cards: [{ text: '❓ Key components and how they fit.\nAgent: record the actual shape from the repo — only what a new session must know.' }] },
@@ -152,6 +153,18 @@ server.registerTool('brain_insights', {
   },
 }, async ({ canvas, staleDays }) => toContent(await opBrainInsights({ vault: VAULT, canvas, staleDays })));
 
+server.registerTool('brain_lens', {
+  title: 'Brain lens — machine-readable views of a brain (freshness · provenance · activity · timeline · orrery · unresolved)',
+  description: 'The data twin of the desktop app\'s Brain Lenses: ONE structured payload any surface (agent, web viewer, iOS) can render. Views: freshness (age buckets + stale open ❓), provenance (who wrote the brain, by channel: you/claude/cursor/git/gardener/…), activity (last 7 days), timeline (birth-order events — the Replay spine; events included only for view:"timeline"), orrery (focus+context neighborhood of one card: 1/2/3-hop ring-capped nodes + typed edges — pass root as a card title prefix or id, defaults to the most-connected hub), unresolved (open-❓ triage, oldest first, with typed evidence). Read-only by construction — it never writes. Use it to answer "what\'s rotting / who wrote this / what happened this week / what\'s around X / what\'s undecided" with receipts, or to feed a UI.',
+  inputSchema: {
+    canvas: z.string().optional().describe('Canvas filename/path. Defaults to the project brain ("brain").'),
+    view: z.enum(['all', 'freshness', 'provenance', 'activity', 'timeline', 'orrery', 'unresolved']).optional().describe('Which lens to compute (default "all" — every section, timeline events omitted from structured output unless view is "timeline").'),
+    root: z.string().optional().describe('Orrery center: a card title prefix or id. Default: the most-connected hub card.'),
+    staleDays: z.number().optional().describe('Open questions older than this count as stale (default 21).'),
+    limit: z.number().optional().describe('Cap for recent-activity entries (default 30).'),
+  },
+}, async ({ canvas, view, root, staleDays, limit }) => toContent(await opBrainLens({ vault: VAULT, canvas, view, root, staleDays, limit })));
+
 server.registerTool('brain_connect', {
   title: 'Connect related-but-unlinked brain cards (densify the graph)',
   description: 'Finds genuinely related cards that AREN\'T linked yet and proposes connections — semantic similarity when the on-device model is installed, else shared tags + [[mentions]]. Dry-run by default (review the suggestions); pass apply:true to draw them (ADDITIVE — never deletes; the human can remove any arrow). Use after brain_insights flags many orphans, to turn a flat list into a real knowledge graph. To DISMISS a brain_reconcile false-positive contradiction, pass pairs:[{fromId,toId}] (the ids are in the reconcile output) with relationship:"not_contradiction" — a persisted dismissal that stops that pair ever resurfacing as a candidate.',

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "klypix-mcp",
-  "version": "1.25.0",
-  "description": "An open, local-first, agent-neutral canvas file your AI reads and writes over MCP — works with Claude, Cursor, Cline, any model.",
+  "version": "1.29.0",
+  "description": "Every project gets a brain — one open .klypix file your AI agents read, write, and argue from, over MCP. Works with Claude, Cursor, Cline, any model.",
   "type": "module",
-  "license": "MIT",
+  "license": "Apache-2.0",
   "keywords": [
     "mcp",
     "model-context-protocol",
@@ -53,7 +53,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brief-and-recall.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs && node test/brain-challenge.mjs && node test/canvas-view.mjs"
+    "test": "node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brief-and-recall.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs && node test/brain-challenge.mjs && node test/brain-lens.mjs && node test/brain-kind.mjs && node test/rule-drafts.mjs && node test/canvas-view.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.4",