mindlink 1.1.5 → 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.1.5
-> **Stronger memory enforcement · MEMORY.md trigger checklist · mtime-based session verification · "git for AI memory" positioning · Claude Code best-in-class section**
-> [→ Full release notes](https://github.com/404-not-found/mindlink/releases/tag/v1.1.5)
+> ### ◉ 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,6 +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 v2.0](#whats-new-in-v20)
 - [Best with Claude Code](#best-with-claude-code)
 - [License](#license)
 - [Contributing](#contributing)
@@ -118,6 +121,10 @@ MindLink works with any version of:
 | Windsurf | `.windsurfrules` |
 | Cline | `.clinerules` |
 | Aider | `CONVENTIONS.md` |
+| Zed | `.rules` |
+| Kiro | `.kiro/steering/mindlink.md` |
+| Continue.dev | `.continue/rules/mindlink.md` |
+| Trae | `.trae/rules/mindlink.md` |
 
 MindLink works by writing instruction files that agents read at startup — no API calls, no SDKs, no version pinning. It works with whatever version you have today and any version released tomorrow. If your agent isn't listed, `mindlink init` lets you add a custom one.
 
@@ -128,7 +135,7 @@ MindLink works by writing instruction files that agents read at startup — no A
 **Run once per project — in your terminal, inside the project directory:**
 ```bash
 cd my-project
-mindlink init        # creates .brain/ here — this is where your AI's memory lives
+mindlink init        # creates .brain/ here — pre-filled from your project on day 1
 ```
 
 **Ask your AI to run these, or run them yourself in any terminal:**
@@ -136,6 +143,7 @@ mindlink init        # creates .brain/ here — this is where your AI's memory l
 mindlink status      # what happened last session, what's next
 mindlink summary     # full briefing — everything your AI knows, in one view
 mindlink log         # complete session history
+mindlink diff        # what changed in .brain/ since last session
 mindlink sync --once # check what other sessions have shared
 ```
 
@@ -160,8 +168,11 @@ 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, never installs without asking
+mindlink update      # check for a newer version, refreshes agent files in all projects
 mindlink uninstall   # remove MindLink from this project
 ```
 
@@ -173,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`, `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.
 
@@ -201,9 +214,26 @@ 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 v2.0
+
+**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.
+
+**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 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.
+
+**`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 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.
+
 ---
 
 ## License

package/commands/diff.md

@@ -0,0 +1,115 @@
+# mindlink diff
+
+Show what changed in `.brain/` since the current session started.
+
+---
+
+## Synopsis
+
+```bash
+mindlink diff [--since <ref>] [--json]
+```
+
+---
+
+## Description
+
+Shows a per-file summary of `.brain/` changes since the session began — which files were modified, how many lines they contain, and when they were last touched.
+
+If `.brain/` is committed to git, `mindlink diff` also shows line-level additions and removals so you can see exactly what the AI wrote.
+
+This command is useful for:
+- Verifying that your AI actually wrote to MEMORY.md during the session (not just claimed to)
+- Reviewing what context was captured before closing a session
+- Debugging why a follow-up session is missing context
+
+**Your AI can run this.** Ask it to run `mindlink diff` to check its own work.
+
+---
+
+## Output
+
+**Without git tracking:**
+```
+  .brain/ changes
+  Session started 12m ago
+  .brain/ is not git-tracked — showing modification times only
+
+  ●  MEMORY.md   94 lines · modified 3m ago
+  ○  SESSION.md  32 lines · modified 12m ago
+  ○  LOG.md      24 lines · modified 12m ago
+  ○  SHARED.md   21 lines · modified 12m ago
+
+  ✓  1 file updated this session.
+```
+
+`●` = modified this session · `○` = not modified this session
+
+**With git tracking (`.brain/` committed):**
+```
+  .brain/ changes
+  Session started 12m ago
+  Git diff against: HEAD~1
+
+  ●  MEMORY.md   97 lines · modified 3m ago
+       + TypeScript + Node.js <!-- added: 2026-04-12 -->
+       + Use mtime-based session verification for Stop hook
+
+  ○  SESSION.md  32 lines · modified 12m ago
+       no changes since last commit
+```
+
+---
+
+## Options
+
+| Flag | Description |
+|---|---|
+| `--since <ref>` | Git ref or date to diff against. Default: `HEAD~1`. Examples: `HEAD~3`, `"2026-04-10"` |
+| `--json` | Output as JSON — useful for scripting or AI consumption |
+
+---
+
+## Examples
+
+**Check what changed this session:**
+```bash
+mindlink diff
+```
+
+**Diff against 3 commits ago:**
+```bash
+mindlink diff --since HEAD~3
+```
+
+**Machine-readable output:**
+```bash
+mindlink diff --json
+```
+
+---
+
+## JSON Output
+
+```json
+{
+  "MEMORY.md": {
+    "exists": true,
+    "mtime": 1776041234567,
+    "sizeLines": 97,
+    "added": ["TypeScript + Node.js"],
+    "removed": []
+  },
+  "SESSION.md": { "exists": true, "mtime": 1776041117345, "sizeLines": 32, "added": [], "removed": [] },
+  "LOG.md":     { "exists": true, "mtime": 1776041117346, "sizeLines": 24, "added": [], "removed": [] },
+  "SHARED.md":  { "exists": true, "mtime": 1776041117346, "sizeLines": 21, "added": [], "removed": [] }
+}
+```
+
+---
+
+## Related Commands
+
+- [`mindlink status`](status.md) — high-level view of current session state
+- [`mindlink summary`](summary.md) — full contents of all `.brain/` files in one view
+- [`mindlink clear`](clear.md) — reset SESSION.md for a fresh start

package/commands/index.md

@@ -22,6 +22,8 @@ Commands are grouped by when and how you run them.
 | [status](status.md) | Show last session summary and what's next |
 | [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)
 
@@ -31,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.
@@ -52,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/init.md

@@ -18,6 +18,8 @@ Creates a `.brain/` folder in the current directory and generates agent instruct
 
 **Run this before starting your AI session.** The agent reads the instruction files on startup. If you init after a session has already started, the current session won't see it — the next one will.
 
+**MEMORY.md is pre-filled on day 1.** `mindlink init` scans your project and auto-populates the Core section with what it finds: project name and description from `package.json`, detected tech stack, top-level directory structure, and recent git commits. Your first AI session starts already briefed — no manual setup required.
+
 ---
 
 ## What Gets Created
@@ -56,6 +58,10 @@ Select the agents you use in this project. MindLink generates the right instruct
 | Windsurf | `.windsurfrules` |
 | Cline | `.clinerules` |
 | Aider | `CONVENTIONS.md` |
+| Zed | `.rules` |
+| Kiro | `.kiro/steering/mindlink.md` |
+| Continue.dev | `.continue/rules/mindlink.md` |
+| Trae | `.trae/rules/mindlink.md` |
 | Add custom agent | file name of your choice |
 
 **To change this later:** `mindlink config` → Agent instruction files
@@ -105,7 +111,7 @@ mindlink init --yes
 
 ## Already Initialized
 
-If `.brain/` already exists, `mindlink init` shows a recovery menu instead of an error:
+If `.brain/` already exists **and agent files are present**, `mindlink init` shows a recovery menu:
 
 ```
 .brain/ already exists at this path. What would you like to do?
@@ -118,6 +124,25 @@ With `--yes`, exits immediately and tells you to run `mindlink config` to change
 
 ---
 
+## Team Onboarding Mode
+
+If `.brain/` exists with real memory content **but no agent instruction files** — the typical state after `git pull` on a team project — `mindlink init` detects this automatically and offers a lighter flow:
+
+```
+◉  MindLink memory found in this project.
+   MEMORY.md has content — this looks like a team project.
+
+❯ Set up agent files    recommended for new team members
+  Full re-init          recreate everything, reconfigure settings
+  Cancel
+```
+
+**"Set up agent files"** skips all configuration prompts and writes only the instruction files (CLAUDE.md, .cursorrules, etc.) for the agents you select. The existing `.brain/` memory, session state, and config are untouched. Your AI is immediately briefed from the team's shared memory.
+
+This is the intended workflow for new team members joining a project that already uses MindLink.
+
+---
+
 ## Related Commands
 
 - [`mindlink config`](config.md) — change any setting made during init

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