mindlink 1.2.0 → 2.0.0

package/README.md

@@ -18,11 +18,13 @@ Git gave every developer a shared version history. MindLink gives your AI team a
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey)](#installation)
 
+![MindLink demo](demo.gif)
+
 ---
 
-> ### ◉ Latest — v1.2.0
-> **Auto-bootstrap on init · `mindlink diff` · Team onboarding mode · Memory timestamps · Windows hook warning · Propagating update system**
-> [→ Full release notes](https://github.com/404-not-found/mindlink/releases/tag/v1.2.0)
+> ### ◉ Latest — v2.0.0
+> **MCP integration for 6 agents · Smart loading · `mindlink verify` · `mindlink profile` · `mindlink prune`**
+> [→ Full release notes](https://github.com/404-not-found/mindlink/releases/tag/v2.0.0)
 
 ---
 
@@ -34,7 +36,7 @@ Git gave every developer a shared version history. MindLink gives your AI team a
 - [Supported Agents](#supported-agents)
 - [Commands](#commands)
 - [Can My AI Run These Commands?](#can-my-ai-run-these-commands-itself)
-- [What's New in v1.2](#whats-new-in-v12)
+- [What's New in v2.0](#whats-new-in-v20)
 - [Best with Claude Code](#best-with-claude-code)
 - [License](#license)
 - [Contributing](#contributing)
@@ -166,6 +168,9 @@ mindlink import      # unzip into this project — merge or overwrite your exist
 
 **Run in your terminal only — maintenance tasks:**
 ```bash
+mindlink verify      # check that .brain/ memory is healthy and up to date
+mindlink prune       # review and retire stale MEMORY.md entries
+mindlink profile     # manage your global user profile (imported into every new project)
 mindlink doctor      # health check — verify your setup is working correctly
 mindlink update      # check for a newer version, refreshes agent files in all projects
 mindlink uninstall   # remove MindLink from this project
@@ -179,9 +184,11 @@ Every command supports `--help`. Full CLI reference: [commands/](commands/index.
 
 Yes — and it should, for the read-only ones. Your AI has a terminal. Tell it to run `mindlink summary` or `mindlink status` and it reads the output directly. This is the cleanest way to brief a mid-session agent without copying files around.
 
-**AI can run:** `status`, `summary`, `log`, `diff`, `sync --once`
+**AI can run:** `status`, `summary`, `log`, `diff`, `sync --once`, `verify`
+
+**Run yourself:** `init`, `clear`, `reset`, `config`, `profile`, `prune`, `export`, `import`, `update`, `uninstall` — these are interactive, change settings, or modify files. Keep human hands on them.
 
-**Run yourself:** `init`, `clear`, `reset`, `config`, `export`, `import`, `update`, `uninstall` — these are interactive, change settings, or modify files. Keep human hands on them.
+**Launched automatically (not by hand):** `mcp` — started by Claude Code, Cursor, and other MCP-capable agents as a background process. Never run this yourself.
 
 The one exception: `mindlink sync` in watch mode runs continuously — keep it in a separate terminal tab.
 
@@ -207,22 +214,25 @@ Claude Code gets both the instruction file **and** an OS-level hook that fires b
 | Enforced on every message | ✗ | ✓ OS-level hook |
 | Post-response memory verification | ✗ | ✓ shell check |
 | Context compaction recovery | ✓ instruction | ✓ instruction + hook |
+| MCP tool integration | ✓ Cursor, Continue, Copilot, Kiro, Windsurf | ✓ Claude Code |
 
 If you're choosing an agent specifically to use with MindLink, Claude Code gives you the most reliable memory behavior. Other agents work well — Claude Code works harder.
 
+**v2.0: MCP support for more agents.** Cursor, Continue.dev, GitHub Copilot, Kiro, and Windsurf now also get an MCP server configured automatically on `mindlink init`. This gives those agents structured, schema-validated reads and writes instead of raw file operations — the same feedback loop Claude Code users have had since v1.
+
 ---
 
-## What's New in v1.2
+## What's New in v2.0
 
-**`mindlink init` now pre-fills your memory on day 1.** It scans your project — `package.json`, `README.md`, recent git commits, top-level directories — and writes a populated Core section into `MEMORY.md` before your first session. No more blank slate.
+**MCP integration — structured, auditable memory operations.** `mindlink mcp` is a stdio MCP server. `mindlink init` configures it automatically for Claude Code, Cursor, Continue.dev, GitHub Copilot, Kiro, and Windsurf. Agents call `mindlink_read_memory()`, `mindlink_write_memory()`, and `mindlink_session_update()` as proper tool calls — with structured inputs, structured results, and a verify loop to confirm writes actually landed.
 
-**Team onboarding mode.** When a teammate runs `mindlink init` in a project that already has `.brain/` memory, MindLink detects it and offers "set up agent files only" — writing just the instruction files without touching memory or config. One command, AI fully briefed.
+**Smart loading — only load what you need.** Agent templates now load Core + User Profile only by default. Architecture, Decisions, Conventions, and Important Context sections are loaded on demand, based on what the agent is about to do. Less context used per session; faster session starts.
 
-**`mindlink diff` — see what your AI learned this session.** Shows which `.brain/` files changed since the session started. If `.brain/` is git-tracked, shows line-level additions and removals.
+**`mindlink verify` — memory health check.** Scans `.brain/` and reports: is Core filled? Is SESSION.md fresh? Is MEMORY.md under the size limit? Is every agent file present? Flags errors and warnings. `--fix` auto-regenerates missing agent files.
 
-**Memory timestamps.** Agent instruction files now tell the AI to append `<!-- added: YYYY-MM-DD -->` to every new entry — so you can see how old a fact is and spot stale decisions.
+**`mindlink profile` — global user profile.** Write once in `~/.mindlink/USER.md`, automatically imported into every new project. Tells your AI who you are, how you like to work, and what your preferences are — without re-explaining it in every project.
 
-**`mindlink update` now propagates everything.** When a new version adds a section to MEMORY.md or changes a template, running `mindlink update` applies those changes to all your initialized projects — without touching your existing memory content.
+**`mindlink prune` — retire stale memory.** Reviews every timestamped entry in MEMORY.md and asks: keep, archive, or delete? Entries past their freshness threshold are surfaced first. `--dry-run` shows what would be flagged without touching anything.
 
 ---
 

package/commands/index.md

@@ -23,6 +23,7 @@ Commands are grouped by when and how you run them.
 | [summary](summary.md) | Full briefing — everything MindLink knows, in one view |
 | [log](log.md) | View full session history |
 | [diff](diff.md) | Show what changed in `.brain/` since the current session started |
+| [verify](verify.md) | Health check — are memory files filled in and up to date? |
 
 ### Keep running in a background terminal tab (while sessions are active)
 
@@ -32,6 +33,14 @@ Commands are grouped by when and how you run them.
 
 `mindlink sync` runs in **watch mode by default** — it stays alive and prints a notification whenever another session appends to `.brain/SHARED.md`. Use `--once` to check a single time and exit.
 
+### Launched automatically by Claude Code — not by hand
+
+| Command | Description |
+|---|---|
+| [mcp](mcp.md) | Start the MindLink MCP server (stdio transport for AI tool integration) |
+
+`mindlink mcp` is started automatically when Claude Code launches a session. It exposes 4 MCP tools (`mindlink_read_memory`, `mindlink_write_memory`, `mindlink_session_update`, `mindlink_verify`) for schema-validated memory reads and writes.
+
 ### Run in your terminal between sessions — not via AI
 
 These commands are interactive, change settings, or modify files. Keep human hands on them.
@@ -53,6 +62,8 @@ These commands are interactive, change settings, or modify files. Keep human han
 
 | Command | Description |
 |---|---|
+| [profile](profile.md) | Manage your global user profile (auto-imported into every new project) |
+| [prune](prune.md) | Review and retire stale MEMORY.md entries interactively |
 | [update](update.md) | Check for a newer version — never installs without asking |
 | [uninstall](uninstall.md) | Remove MindLink from the current project |
 

package/commands/mcp.md

@@ -0,0 +1,126 @@
+# mindlink mcp
+
+Start the MindLink MCP server for AI tool integration.
+
+---
+
+## Synopsis
+
+```bash
+mindlink mcp
+```
+
+---
+
+## Description
+
+`mindlink mcp` starts a local [Model Context Protocol](https://modelcontextprotocol.io) server over stdio. It exposes 4 tools that AI agents (like Claude Code) can call to read and write memory with schema validation and structured responses.
+
+This command is **launched automatically** by Claude Code — you do not need to run it yourself. When you run `mindlink init` and select Claude Code, MindLink adds the MCP server entry to `.claude/settings.json` so Claude Code starts it on every session.
+
+**Why MCP?**
+- **Schema-validated writes** — the AI can't accidentally overwrite the wrong section
+- **Structured reads** — returns only the sections needed for the current task (token-efficient)
+- **Verify loop** — the AI can call `mindlink_verify()` after writing to confirm the write succeeded
+
+---
+
+## Tools
+
+### `mindlink_read_memory(section?)`
+
+Read a section of this project's `MEMORY.md`.
+
+- **No argument**: returns Core + User Profile only (the recommended default at session start)
+- **With section**: returns just that section
+
+| Section value | Content |
+|---|---|
+| `Core` | Project identity, stack, top decisions |
+| `Architecture` | System design decisions |
+| `Decisions` | Key choices made and why |
+| `Conventions` | Team patterns and coding standards |
+| `User Profile` | Personal facts about the user |
+| `Important Context` | Business context, deadlines, preferences |
+
+---
+
+### `mindlink_write_memory(section, content)`
+
+Append a fact or decision to a section of `MEMORY.md`.
+
+Never overwrites existing content — always appends. Always include a `<!-- added: YYYY-MM-DD -->` timestamp in the content.
+
+---
+
+### `mindlink_session_update(summary)`
+
+Overwrite `SESSION.md` with a summary of the current session.
+
+Call this as the **last action** of every response. SESSION.md is temporary; it gets cleared between sessions. MEMORY.md is permanent.
+
+---
+
+### `mindlink_verify()`
+
+Run a health check on `.brain/`. Returns the same JSON as `mindlink verify --json`.
+
+Use this after writing to confirm the write succeeded and memory is in good shape.
+
+---
+
+## Configuration
+
+`mindlink init` (with Claude Code selected) writes this to `.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "mindlink": {
+      "command": "mindlink",
+      "args": ["mcp"],
+      "env": {
+        "MINDLINK_PROJECT_PATH": "/absolute/path/to/your/project"
+      }
+    }
+  }
+}
+```
+
+The `MINDLINK_PROJECT_PATH` env var tells the MCP server which project's `.brain/` to use. If not set, the server walks up from the working directory looking for a `.brain/` folder.
+
+`mindlink update` refreshes this entry in all registered projects whenever you update MindLink.
+
+---
+
+## Project Resolution
+
+The MCP server resolves the project root in this order:
+
+1. `MINDLINK_PROJECT_PATH` environment variable (set by Claude Code via `settings.json`)
+2. Walk up from the current working directory, looking for a `.brain/` folder (up to 10 levels)
+
+If no project is found, all tool calls return an error with instructions to run `mindlink init`.
+
+---
+
+## Examples
+
+**See all available tools:**
+```bash
+mindlink mcp --help
+```
+
+**Ask your AI to run a memory health check:**
+> "Run mindlink_verify and tell me if anything needs attention."
+
+**Ask your AI to read a specific section:**
+> "Call mindlink_read_memory with section 'Decisions' and summarize what decisions we've made."
+
+---
+
+## Related Commands
+
+- [`mindlink init`](init.md) — sets up `.brain/` and writes the MCP server entry
+- [`mindlink update`](update.md) — refreshes the MCP entry in all registered projects
+- [`mindlink verify`](verify.md) — same health checks, available as a CLI command

package/commands/profile.md

@@ -0,0 +1,104 @@
+# mindlink profile
+
+Manage your global user profile — imported into every new project automatically.
+
+---
+
+## Synopsis
+
+```bash
+mindlink profile [--show] [--path]
+```
+
+---
+
+## Description
+
+Your global user profile lives at `~/.mindlink/USER.md`. It stores personal facts about you — role, experience, preferences, communication style — that are true regardless of which project you're working in.
+
+When you run `mindlink init` on a new project, your profile is automatically imported into the `## User Profile` section of `.brain/MEMORY.md`. Your AI starts the first session already knowing who you are.
+
+When you run `mindlink update`, the profile is synced to all registered projects — any changes you make are propagated everywhere.
+
+---
+
+## Commands
+
+**Open profile in your `$EDITOR`:**
+```bash
+mindlink profile
+```
+
+**Print profile to stdout:**
+```bash
+mindlink profile --show
+```
+
+**Print profile file path:**
+```bash
+mindlink profile --path
+```
+
+---
+
+## Profile Format
+
+```markdown
+# MindLink — Global User Profile
+
+> This file is imported into every new project's MEMORY.md on `mindlink init`.
+> Edit it with `mindlink profile`. Run `mindlink update` to sync changes to all projects.
+
+Senior full-stack engineer, 8 years. Primary: TypeScript, Python.
+Prefers functional patterns, minimal abstraction.
+Direct communication — skip preamble, lead with the answer.
+macOS + zsh. Editor: VS Code + Claude Code.
+<!-- added: 2026-04-13 -->
+```
+
+Write anything your AI should know about you in plain Markdown. The more specific, the better — role, experience level, communication preferences, tools, and how you like problems explained.
+
+---
+
+## How It Works
+
+1. **On `mindlink init`:** if `~/.mindlink/USER.md` exists with real content, it is injected into the `## User Profile` section of the new project's `MEMORY.md`.
+2. **On `mindlink update`:** the current profile replaces the `## User Profile` section in all registered projects — keeping them in sync as your profile evolves.
+
+---
+
+## Options
+
+| Flag | Description |
+|---|---|
+| `--show` | Print current profile to stdout instead of opening editor |
+| `--path` | Print `~/.mindlink/USER.md` path only (for scripting) |
+
+---
+
+## Examples
+
+**Set up your profile for the first time:**
+```bash
+mindlink profile
+# Opens $EDITOR (nano, vim, code, etc.) — write your facts, save and exit
+```
+
+**Sync changes to all registered projects:**
+```bash
+mindlink profile       # edit and save
+mindlink update        # propagate to all projects
+```
+
+**Read profile in a script:**
+```bash
+cat "$(mindlink profile --path)"
+```
+
+---
+
+## Related Commands
+
+- [`mindlink update`](update.md) — sync profile (and agent files) to all registered projects
+- [`mindlink verify`](verify.md) — check that User Profile is filled in across projects
+- [`mindlink init`](init.md) — sets up memory for a new project (imports profile)

package/commands/prune.md

@@ -0,0 +1,117 @@
+# mindlink prune
+
+Review and retire stale MEMORY.md entries interactively.
+
+---
+
+## Synopsis
+
+```bash
+mindlink prune [--dry-run] [--all]
+```
+
+---
+
+## Description
+
+MEMORY.md entries accumulate over time. A decision made six months ago that was later reversed, a "current focus" entry that describes work completed three months ago — these entries linger and degrade the quality of your AI's context.
+
+`mindlink prune` surfaces entries by age and lets you decide what to do with each one. Entries can be kept, moved to an `## Archive` section, or permanently deleted.
+
+**MindLink never auto-deletes content.** Archived entries are moved to `## Archive` at the bottom of MEMORY.md — they are always kept for reference unless you explicitly delete them.
+
+Entries are identified by `<!-- added: YYYY-MM-DD -->` timestamps, which your AI appends to every new entry it writes.
+
+---
+
+## Staleness Thresholds
+
+| Section | Warn after |
+|---|---|
+| `## Current Focus` | 14 days |
+| `## Decisions` | 180 days |
+| `## Conventions` | 180 days |
+| `## Architecture` | 365 days |
+| `## User Profile` | Never |
+| `## Important Context` | Never |
+
+Entries without a timestamp are not flagged (no reference date to compare against).
+
+---
+
+## Interactive Flow
+
+```
+  ◉ MindLink Prune
+  /Users/you/my-project/.brain/MEMORY.md
+
+  Scanning MEMORY.md for stale entries...
+  Found 2 entries to review.
+
+  ───────────────────────────────────────────────────────
+  Section: Current Focus
+  Entry:
+    Building billing integration in src/api/billing.ts
+  Added: 2026-01-15 (87 days ago) — threshold: 14 days
+
+  ❯ Keep     (leave as-is)
+    Archive  (move to ## Archive section)
+    Delete   (remove permanently)
+    Skip remaining
+
+  ───────────────────────────────────────────────────────
+
+  ✓  1 entry archived
+  ·  1 entry kept
+  ✓  MEMORY.md updated.
+```
+
+---
+
+## Options
+
+| Flag | Description |
+|---|---|
+| `--dry-run` | Show what would be flagged without making any changes |
+| `--all` | Show all timestamped entries regardless of age |
+
+---
+
+## Archive Section
+
+Archived entries are appended to `## Archive` at the bottom of MEMORY.md:
+
+```markdown
+## Archive
+
+<!-- Entries moved here by mindlink prune — kept for reference -->
+
+Building billing integration in src/api/billing.ts <!-- added: 2026-01-15 --> <!-- archived: 2026-04-13 -->
+```
+
+---
+
+## Examples
+
+**Interactive review of stale entries:**
+```bash
+mindlink prune
+```
+
+**See what would be flagged without changing anything:**
+```bash
+mindlink prune --dry-run
+```
+
+**Review all timestamped entries (not just stale ones):**
+```bash
+mindlink prune --all
+```
+
+---
+
+## Related Commands
+
+- [`mindlink verify`](verify.md) — check if MEMORY.md is getting too large
+- [`mindlink diff`](diff.md) — see what the AI wrote this session
+- [`mindlink summary`](summary.md) — view full contents of all `.brain/` files

package/commands/verify.md

@@ -0,0 +1,122 @@
+# mindlink verify
+
+Check that `.brain/` memory is healthy and up to date.
+
+---
+
+## Synopsis
+
+```bash
+mindlink verify [--json] [--fix]
+```
+
+---
+
+## Description
+
+Runs a health check on the current project's `.brain/` directory. Answers: "is my AI's memory in good shape right now?"
+
+Unlike `mindlink doctor` (which checks setup correctness), `mindlink verify` checks **content quality** — whether memory files are actually filled in, whether the AI is actively writing session state, and whether MEMORY.md is getting too large to be useful.
+
+**Your AI can run this.** Ask it to run `mindlink verify` to check its own work before closing a session.
+
+---
+
+## Checks
+
+| Check | Pass | Warn | Fail |
+|---|---|---|---|
+| **Core section** | Has real content | — | Empty or placeholder only |
+| **User Profile** | Has real content | — | Empty or placeholder only |
+| **SESSION.md freshness** | Updated < 3 days ago | 3–7 days | > 7 days |
+| **LOG.md present** | Exists | — | Missing |
+| **MEMORY.md size** | < 100 real lines | 100–200 lines | > 200 lines |
+| **Agent files** | All present | Some missing | None present |
+
+---
+
+## Output
+
+```
+  ◉ MindLink Verify
+  /Users/you/my-project
+
+  ✓  Core section — filled
+  ✓  User Profile — filled
+  ⚠  SESSION.md — last updated 5 days ago
+       SESSION.md is getting stale...
+  ✓  LOG.md — 14 sessions logged
+  ✗  MEMORY.md — 217 lines (target: under 200)
+       Run mindlink prune to consolidate stale entries.
+  ✓  Agent files — all 2 present
+
+  1 error, 1 warning.
+  Run mindlink verify --fix to auto-repair 0 issues.
+```
+
+---
+
+## Options
+
+| Flag | Description |
+|---|---|
+| `--json` | Output results as JSON — useful for scripting or AI consumption |
+| `--fix` | Auto-fix recoverable issues (regenerate missing agent files) |
+
+---
+
+## `--fix` Behavior
+
+Auto-fix only applies to recoverable issues. It **never touches user-written memory content**.
+
+| Check | `--fix` action |
+|---|---|
+| `agent_files` missing | Re-generate from current templates |
+| `core` / `user_profile` empty | Print actionable message — no auto-fill |
+| `memory_size` too large | Print actionable message — run `mindlink prune` |
+| `session_fresh` stale | No auto-fix — AI must update SESSION.md |
+
+---
+
+## Examples
+
+**Check memory health:**
+```bash
+mindlink verify
+```
+
+**Machine-readable output:**
+```bash
+mindlink verify --json
+```
+
+**Auto-fix missing agent files:**
+```bash
+mindlink verify --fix
+```
+
+---
+
+## JSON Output
+
+```json
+{
+  "ok": false,
+  "checks": [
+    { "id": "core",         "label": "Core section — filled",       "status": "pass", "message": "", "fixable": false },
+    { "id": "user_profile", "label": "User Profile — filled",       "status": "pass", "message": "", "fixable": false },
+    { "id": "session_fresh","label": "SESSION.md — last updated 5 days ago", "status": "warn", "message": "...", "fixable": false },
+    { "id": "log_present",  "label": "LOG.md — 14 sessions logged", "status": "pass", "message": "", "fixable": false },
+    { "id": "memory_size",  "label": "MEMORY.md — 217 lines (target: under 200)", "status": "fail", "message": "Run mindlink prune...", "fixable": false },
+    { "id": "agent_files",  "label": "Agent files — all 2 present", "status": "pass", "message": "", "fixable": false }
+  ]
+}
+```
+
+---
+
+## Related Commands
+
+- [`mindlink prune`](prune.md) — retire stale MEMORY.md entries interactively
+- [`mindlink doctor`](doctor.md) — check setup correctness (files, hooks, config)
+- [`mindlink diff`](diff.md) — see what the AI wrote this session

package/dist/chunk-2H7UOFLK.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+export {
+  __export
+};
+//# sourceMappingURL=chunk-2H7UOFLK.js.map

package/dist/chunk-2H7UOFLK.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}