mindlink 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yuanhong Cao
+
+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.

package/README.md

@@ -0,0 +1,201 @@
+# ◉ MindLink
+
+**Give your AI a brain.**
+
+Three things break AI-assisted development:
+
+**Every new session starts blank.** No memory of what you built, what you decided, or what blew up last week. You spend the first 10 minutes re-explaining everything. Every. Single. Time.
+
+**Two sessions share nothing.** Two AI agents running in the same project are invisible to each other — they duplicate work, contradict decisions, run the same experiment twice.
+
+**Switch agents, lose everything.** Claude Code in the morning, Cursor in the afternoon — each tool has its own silo. What one learned, the other never knows.
+
+MindLink fixes all three. One command per project.
+
+[![npm version](https://img.shields.io/npm/v/mindlink)](https://www.npmjs.com/package/mindlink)
+[![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)
+
+---
+
+> ### ◉ Latest — v1.0.0
+> **Session memory · Cross-session sync · Cross-agent · 8 AI agents supported**
+> [→ Full release notes](https://github.com/404-not-found/mindlink/releases/tag/v1.0.0)
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [What It Does](#what-it-does)
+- [Supported Agents](#supported-agents)
+- [Commands](#commands)
+- [Can My AI Run These Commands?](#can-my-ai-run-these-commands-itself)
+- [The Hook (Claude Code)](#the-hook-claude-code-users)
+- [License](#license)
+- [Contributing](#contributing)
+
+---
+
+## Installation
+
+**npm**
+```bash
+npm install -g mindlink
+```
+
+**Homebrew (macOS / Linux)**
+```bash
+brew tap 404-not-found/mindlink
+brew install mindlink
+```
+
+**curl (macOS / Linux)**
+```bash
+curl -sL https://get.mindlink.dev | sh
+```
+
+**Windows (winget)**
+```bash
+winget install mindlink
+```
+
+**Windows (Scoop)**
+```bash
+scoop install mindlink
+```
+
+No Node.js? Grab a standalone binary from [GitHub Releases](https://github.com/404-not-found/mindlink/releases) — no runtime required.
+
+---
+
+## Quick Start
+
+```bash
+cd my-project    # navigate into the project where you want AI memory to live
+mindlink init   # run this once — your AI will know everything from the next session on
+```
+
+**Run this in your project directory, before your first AI session.** MindLink creates a `.brain/` folder right there — scoped to that project, not global. This is the folder your AI agent will read every time it wakes up in that project: your architecture decisions, what was built last session, what's broken, what's next. The more you work in that project, the smarter it gets.
+
+The current session won't see it. The next one will wake up fully briefed. After that, you never have to run `init` again. That's the whole deal.
+
+Close any AI session whenever you want — Claude Code, Cursor, Codex, whatever you're using. Lose your train of thought. Switch agents. Take a week off. The next session picks up exactly where you left off — no re-explaining, no context dumps, no "wait, what were we doing?" moments.
+
+---
+
+## What It Does
+
+**No more goldfish brain** — every time you start a new AI session in your project, it already knows everything: what the project is, what decisions were made, what was built last session, what's broken, and what comes next. No briefing required.
+
+**Close any AI session whenever you want** — Claude Code, Cursor, Codex, it doesn't matter. Lose your train of thought, switch agents mid-task, take a week off. The next session — in any tool — picks up exactly where you left off. You'll never be afraid to close a session again.
+
+**Two sessions, one brain** — two AI sessions open in the same project? They share the same context automatically. What one learns, the other can see. No more running the same experiment twice because your two agents didn't know about each other.
+
+**One memory, every agent** — use Claude Code in the morning, switch to Cursor in the afternoon — both read the exact same `.brain/` folder. No syncing. No duplicating context. No "but I told the other AI this already." Every agent you use shares one brain, because the memory lives in your project, not inside any particular tool. This is something no AI vendor can replicate — they each only know their own product.
+
+**Team memory out of the box** — commit `.brain/` to git and your whole team shares the same AI context. New teammate joins, does `git pull`, and their AI agent is already fully briefed on the project. No onboarding session, no copying notes, no "let me catch you up."
+
+**Plug in, not lock in** — works with Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot, Windsurf, Cline, Aider, and more. Because MindLink just writes files that agents read — no APIs, no SDKs, no version dependencies — it works with whatever version you have installed today and every version that comes after.
+
+**Zero infrastructure** — no server, no account, no cloud, no pricing page. MindLink can't be shut down, rate-limited, or go behind a paywall. It's a file and a CLI. Works completely offline.
+
+**Your files, your rules** — memory lives in your project as plain Markdown in a `.brain/` folder. No account, no cloud, no surveillance. Read it, edit it, delete it — it's just files. You own it completely.
+
+**Smart memory, like a real brain** — `MEMORY.md` holds the facts that matter forever (architecture, decisions, conventions) and is never cleared. `LOG.md` holds session history and quietly archives old entries when it gets long. Like any good brain, MindLink remembers what matters and lets go of the stuff that hasn't come up in a while. Anything truly important belongs in `MEMORY.md` — promote it there and it lives forever.
+
+---
+
+## Supported Agents
+
+MindLink works with any version of:
+
+| Agent | Instruction file |
+|---|---|
+| Claude Code | `CLAUDE.md` |
+| Cursor | `CURSOR.md` |
+| Codex / OpenAI | `AGENTS.md` |
+| Gemini CLI | `GEMINI.md` |
+| GitHub Copilot | `.github/copilot-instructions.md` |
+| Windsurf | `.windsurfrules` |
+| Cline | `.clinerules` |
+| Aider | `CONVENTIONS.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.
+
+---
+
+## Commands
+
+**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
+```
+
+**Ask your AI to run these, or run them yourself in any terminal:**
+```bash
+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 sync --once # check what other sessions have shared
+```
+
+**Run in a dedicated background terminal tab while sessions are active:**
+```bash
+mindlink sync        # watch mode — stays running, surfaces changes from other sessions the moment they happen
+```
+Watch mode is the default. It keeps the process alive and prints a notification whenever another session writes to the shared memory. Stop it with Ctrl+C. Use `--once` to check once and exit.
+
+**Run in your terminal between sessions — not via AI (interactive or destructive):**
+```bash
+mindlink clear       # fresh session start (keeps memory and history intact)
+mindlink reset       # scorched earth — wipe all memory, keep your settings
+mindlink config      # change agents, git tracking, or auto-sync
+```
+
+**Share memory or back it up — run in your terminal:**
+```bash
+mindlink export      # zip your .brain/ — send to a teammate or save as backup
+mindlink import      # unzip into this project — merge or overwrite your existing memory
+```
+
+**Run in your terminal only — maintenance tasks:**
+```bash
+mindlink doctor      # health check — verify your setup is working correctly
+mindlink update      # check for a newer version, never installs without asking
+mindlink uninstall   # remove MindLink from this project
+```
+
+Every command supports `--help`. Full CLI reference: [commands/](commands/index.md).
+
+---
+
+## Can my AI run these commands itself?
+
+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`
+
+**Run yourself:** `init`, `clear`, `reset`, `config`, `export`, `import`, `update`, `uninstall` — these are interactive, change settings, or modify files. Keep human hands on them.
+
+The one exception: `mindlink sync` in watch mode runs continuously — keep it in a separate terminal tab.
+
+---
+
+## The Hook (Claude Code users)
+
+Claude Code users get an extra layer: a `UserPromptSubmit` hook in `.claude/settings.json` that fires on every message, reminding your agent to re-read `.brain/` if its context was just compacted. Other agents rely on their instruction files — Claude Code gets both because it supports OS-level hooks. Same protection, different delivery.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+## Contributing
+
+Spotted a bug? Have an idea? Open an issue or PR on [GitHub](https://github.com/404-not-found/mindlink). We read everything.

package/commands/clear.md

@@ -0,0 +1,74 @@
+# mindlink clear
+
+Reset current session state for a fresh start.
+
+**Run in your terminal between sessions.** No confirmation needed — it just resets SESSION.md and tells you what it did.
+
+---
+
+## Synopsis
+
+```bash
+mindlink clear [--yes]
+```
+
+---
+
+## Description
+
+Resets `.brain/SESSION.md` so your AI agent starts the next session with a clean slate. **`MEMORY.md`, `LOG.md`, and `SHARED.md` are not touched** — permanent project facts, session history, and shared context are always preserved.
+
+Use this when you want to start a genuinely new task and don't want the agent picking up mid-task state from a previous session.
+
+Not what you need? See:
+- [`mindlink reset`](reset.md) — wipe ALL memory back to blank (scorched earth)
+- [`mindlink uninstall`](uninstall.md) — remove MindLink from this project entirely
+
+---
+
+## What Gets Reset vs Preserved
+
+| File | Action |
+|---|---|
+| `.brain/SESSION.md` | Reset to empty template |
+| `.brain/MEMORY.md` | Untouched — permanent facts preserved |
+| `.brain/LOG.md` | Untouched — full history preserved |
+| `.brain/SHARED.md` | Untouched — shared context preserved |
+
+---
+
+## Options
+
+| Flag | Description |
+|---|---|
+| `--yes`, `-y` | Skip the confirmation prompt |
+
+---
+
+## Examples
+
+```bash
+mindlink clear
+mindlink clear --yes
+```
+
+---
+
+## Output
+
+```
+? This will reset SESSION.md for a fresh session start.
+  MEMORY.md and LOG.md are untouched.
+
+❯ Yes, clear session
+  Cancel
+
+✓  SESSION.md cleared. Ready for a clean session.
+```
+
+---
+
+## Related Commands
+
+- [`mindlink status`](status.md) — check what's currently in SESSION.md before clearing
+- [`mindlink log`](log.md) — view past session history

package/commands/config.md

@@ -0,0 +1,81 @@
+# mindlink config
+
+Change settings for the current project after init.
+
+**Run in your terminal — this opens an interactive menu.** Not suitable for AI to run on your behalf.
+
+---
+
+## Synopsis
+
+```bash
+mindlink config
+```
+
+---
+
+## Description
+
+Opens an interactive menu to change any setting that was configured during `mindlink init`. All settings are stored in `.brain/` and scoped to the current project path.
+
+---
+
+## Settings
+
+### Git tracking
+
+Controls whether `.brain/` is committed to git or ignored.
+
+| Option | What it does |
+|---|---|
+| Enable | Removes `.brain/` from `.gitignore`. Your team shares the same AI memory. |
+| Disable | Adds `.brain/` to `.gitignore`. Memory stays on your machine only. |
+
+### Auto-sync
+
+Controls whether `mindlink sync` runs automatically in the background.
+
+| Option | What it does |
+|---|---|
+| Enable | Sync runs automatically. Sessions stay in sync without manual intervention. |
+| Disable | You run `mindlink sync` manually when you want to sync. |
+
+### Agent instruction files
+
+Add or remove agent instruction files for this project. Same multi-select menu as `mindlink init`.
+
+Selecting an agent that isn't already set up generates its instruction file.
+Deselecting an agent that exists prompts you to confirm before deleting the file.
+
+---
+
+## Examples
+
+```bash
+mindlink config
+```
+
+---
+
+## Interactive Menu
+
+```
+Current settings  ·  /Users/yuanhong/projects/my-app
+
+Git tracking   : enabled   (team shares memory)
+Auto-sync      : enabled   (watch mode)
+Agent files    : CLAUDE.md, CURSOR.md, AGENTS.md ...
+
+? What would you like to change?
+❯ Git tracking
+  Auto-sync
+  Agent instruction files
+  Exit
+```
+
+---
+
+## Related Commands
+
+- [`mindlink init`](init.md) — initial setup (first time only)
+- [`mindlink sync`](sync.md) — manually run sync

package/commands/doctor.md

@@ -0,0 +1,98 @@
+# mindlink doctor
+
+Check that your MindLink setup is healthy.
+
+**Run in your terminal.** Use this when something feels off, after a fresh `import`, or just to verify everything is wired up correctly.
+
+---
+
+## Synopsis
+
+```bash
+mindlink doctor
+```
+
+---
+
+## Description
+
+Runs a series of checks on your project's MindLink setup and reports any problems. Exits with code 1 if any critical issues are found, 0 if everything is healthy (warnings are allowed).
+
+---
+
+## What Gets Checked
+
+| Check | What it looks for |
+|---|---|
+| `.brain/` | Exists in the current directory |
+| `config.json` | Present and valid JSON |
+| `MEMORY.md` | Core section has content; warns if getting too long |
+| `SESSION.md` | Has content and shows when it was last updated |
+| `LOG.md` | Session count, last session date, how far back history goes |
+| Agent files | Each configured agent's instruction file exists |
+| Claude hook | `.claude/settings.json` hook is present and valid |
+
+---
+
+## Output
+
+```
+  ◉ MindLink Doctor
+  /Users/yuanhong/my-app
+
+  ✓  .brain/ found
+  ✓  config.json valid
+  ✓  MEMORY.md Core has content
+  ✓  SESSION.md — updated 2 hours ago
+  ✓  LOG.md — 12 sessions logged (last: Apr 10, 2026, going back to: Jan 5, 2026)
+  ✓  CLAUDE.md — Claude Code
+  ✓  CURSOR.md — Cursor
+  ✓  .claude/settings.json — UserPromptSubmit hook active
+  ·  .brain/ is committed to git (shared team memory)
+
+  All good. Your AI has a healthy brain.
+```
+
+### Warning example
+
+```
+  !  MEMORY.md Core is getting long
+     Consider asking your AI to consolidate — Core is read on every session start.
+
+  1 warning, no critical issues. Your AI will still work.
+```
+
+### Failure example
+
+```
+  ✗  MEMORY.md missing
+     Run mindlink init to recreate it.
+
+  1 problem found — fix the issues above and re-run mindlink doctor.
+```
+
+---
+
+## Exit Codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Healthy (warnings allowed) |
+| `1` | One or more critical problems found |
+
+---
+
+## When to Run
+
+- After `mindlink import` — verify the import landed correctly
+- When your AI seems confused or isn't reading context — check the agent files
+- On a new machine after cloning — make sure instruction files are in place
+- Periodically to catch drift before it becomes a problem
+
+---
+
+## Related Commands
+
+- [`mindlink init`](init.md) — set up MindLink (fixes most failures doctor finds)
+- [`mindlink config`](config.md) — change agents or settings
+- [`mindlink status`](status.md) — see what your AI knows right now

package/commands/export.md

@@ -0,0 +1,90 @@
+# mindlink export
+
+Export your project's AI memory to a shareable zip file.
+
+**Run in your terminal.** The zip can be shared with teammates, used as a backup, or imported into another machine.
+
+---
+
+## Synopsis
+
+```bash
+mindlink export [--output <path>] [--include-agents]
+```
+
+---
+
+## Description
+
+Packages your `.brain/` folder into a zip file named `{project}-brain-{date}.zip`. You can share this zip with anyone — they import it with `mindlink import` and their AI agent wakes up knowing everything your project knows.
+
+If you run this interactively (no `--output` flag), MindLink asks where to save the file.
+
+---
+
+## Use Cases
+
+**Onboard a new teammate**
+```bash
+mindlink export --output ~/Desktop
+# Send them: my-app-brain-2026-04-10.zip
+# They run:  mindlink import my-app-brain-2026-04-10.zip
+```
+
+**Back up before a reset**
+```bash
+mindlink export --output ~/backups
+mindlink reset
+```
+
+**Share context with a consultant**
+```bash
+mindlink export --include-agents --output ~/Desktop
+# They get the memory AND the agent instruction files
+```
+
+---
+
+## What Gets Exported
+
+| File | Included |
+|---|---|
+| `.brain/MEMORY.md` | ✓ always |
+| `.brain/SESSION.md` | ✓ always |
+| `.brain/SHARED.md` | ✓ always |
+| `.brain/LOG.md` | ✓ always |
+| `.brain/LOG-*.md` (archives) | ✓ always |
+| `CLAUDE.md`, `CURSOR.md`, etc. | Only with `--include-agents` |
+| `.brain/config.json` | ✗ never (machine-specific) |
+
+---
+
+## Options
+
+| Flag | Description |
+|---|---|
+| `--output <path>` | Directory or full `.zip` path to save the file |
+| `--include-agents` | Also include agent instruction files |
+
+---
+
+## Output
+
+```
+  ✓  .brain/MEMORY.md
+  ✓  .brain/SESSION.md
+  ✓  .brain/SHARED.md
+  ✓  .brain/LOG.md
+
+  ✓  Exported to: /Users/yuanhong/Desktop/my-app-brain-2026-04-10.zip
+
+  To import on another machine or project:
+  mindlink import my-app-brain-2026-04-10.zip
+```
+
+---
+
+## Related Commands
+
+- [`mindlink import`](import.md) — import a zip into the current project
+- [`mindlink reset`](reset.md) — wipe memory (export first if you want a backup)

package/commands/import.md

@@ -0,0 +1,80 @@
+# mindlink import
+
+Import a MindLink memory zip into the current project.
+
+**Run in your terminal.** Takes a `.zip` exported by `mindlink export` and extracts it into `.brain/`.
+
+---
+
+## Synopsis
+
+```bash
+mindlink import <file.zip> [--yes]
+```
+
+---
+
+## Description
+
+Extracts a zip created by `mindlink export` into the current project's `.brain/` folder. If `.brain/` already exists, you choose whether to merge (keep your current memory, add what's missing) or overwrite (replace everything with the imported version).
+
+---
+
+## Use Cases
+
+**Onboard on a new machine**
+```bash
+# Copy the zip to the new machine, then:
+mindlink import my-app-brain-2026-04-10.zip
+# Your AI agent wakes up fully briefed on the first session
+```
+
+**Accept a colleague's memory**
+```bash
+mindlink import colleague-brain-2026-04-10.zip
+# Choose Merge to keep your work and add what they know
+```
+
+**Restore from backup**
+```bash
+mindlink import ~/backups/my-app-brain-2026-04-01.zip --yes
+```
+
+---
+
+## Options
+
+| Flag | Description |
+|---|---|
+| `--yes`, `-y` | Skip confirmation, overwrite existing memory |
+
+---
+
+## Merge vs Overwrite
+
+When `.brain/` already exists:
+
+| Mode | What happens |
+|---|---|
+| **Merge** | Only imports files that don't exist locally. Your current memory is kept. |
+| **Overwrite** | Replaces all `.brain/` files with the imported versions. |
+
+---
+
+## Output
+
+```
+  ✓  .brain/MEMORY.md
+  ✓  .brain/SESSION.md
+  ✓  .brain/SHARED.md
+  ✓  .brain/LOG.md
+
+  ✓  Memory imported. Your AI will wake up fully briefed.
+```
+
+---
+
+## Related Commands
+
+- [`mindlink export`](export.md) — create a zip to share or back up
+- [`mindlink init`](init.md) — set up agent instruction files after importing