npm package: @quanglddev/myelin
Description: A persistent developer brain that grows with you
Latest version: 0.1.3

# myelin

A persistent developer brain that grows with you. Stop re-explaining your coding preferences to AI. Myelin remembers your rules, learns from your corrections, and deploys them everywhere — automatically.

## The Problem

Every time you start an AI chat, you lose context. You re-explain "use tabs not spaces," re-warn about that React hydration gotcha, re-state your project conventions. Multiply by 10 sessions a day across 5 projects — that's thousands of wasted tokens and minutes.

## The Solution

Myelin is a CLI that manages a persistent brain at `~/.myelin/`. Your rules, gotchas, profiles, and patterns live there permanently. When you run `myelin init` in a project, it deploys everything the AI needs into files that **VS Code Copilot**, **Claude Code**, and **Cursor** auto-load — every session, zero setup.

## Features

- **Persistent Brain** (`~/.myelin/`) — A git-tracked directory of rules, gotchas, profiles, and patterns that follows you across every project and every machine
- **Three-Tier Rule Scoping** — Universal → language-specific → project-specific rules, assembled and deployed to `.github/copilot-instructions.md`, `CLAUDE.md`, and `.cursor/rules/` so every editor reads them automatically
- **10 Skill Templates** — Explore, propose, apply, checkpoint, resume, onboard, learn, status, brain-check, archive — each a tested workflow deployed to your project
- **Profile System** — Switch between 10 communication styles (from professional to J.A.R.V.I.S. to drill sergeant) with one command
- **Git Checkpointing** — Snapshot your work at every task boundary, revert cleanly when things go wrong
- **Learning Loop** — Corrections you make 3+ times automatically become permanent rules. Gotchas you capture once are deployed to every future project
- **Anti-Rogue Protections** — 4-layer defense (invariant injection, automated verification, scope enforcement, session health monitoring) prevents AI agents from going off-script during implementation

## Installation

### Homebrew (macOS/Linux)

```bash
brew install quanglddev/tap/myelin
```

### npm

```bash
npm install -g @quanglddev/myelin
```

### curl

```bash
curl -fsSL https://raw.githubusercontent.com/quanglddev/myelin/main/install.sh | bash
```

### From source

```bash
go install github.com/quanglddev/myelin/cmd/myelin@latest
```

## Quick Start

```bash
# 1. Create your brain
myelin setup

# 2. Initialize a project
cd your-project
myelin init

# 3. Use the skills in your AI editor
# VS Code Copilot: #myelin-explore, #myelin-propose, #myelin-apply
# Claude Code:     /myelin:explore, /myelin:propose, /myelin:apply
# Cursor:          @myelin-explore, @myelin-propose, @myelin-apply
```

## Commands

### Brain Management

Run these once (ever) to create your brain, or when you want a fresh start.

| Command | What It Does | When to Use |
|---------|-------------|-------------|
| `myelin setup` | Creates `~/.myelin/` with your chosen profile, languages, and starter rules. Initializes a git repo so your brain is versioned. | **First time only.** Run once on any machine. Takes 30 seconds. |
| `myelin setup --reset` | Backs up existing brain to `~/.myelin.bak.{timestamp}/`, recreates from scratch. | When your brain is cluttered, corrupted, or you want a clean start. Non-destructive — old brain is preserved. |

### Project Management

Run these when connecting myelin to a project. After init, rules and skills are deployed — you're ready to use AI skills immediately.

| Command | What It Does | When to Use |
|---------|-------------|-------------|
| `myelin init` | Deploys rules to all editor formats (VS Code Copilot, Claude Code, Cursor), 10 skill templates, prompt wrappers, and Claude commands into the current project. Registers it in your brain. | **First time in any project.** Run once per repo. |
| `myelin init --isolated` | Same as init but skips profile personality. Rules still deploy. | Work repos where personality (jarvis/roaster) would be inappropriate. |
| `myelin sync` | Re-assembles and re-deploys rules + skills to all editor formats for the current project. | After editing rules in `~/.myelin/rules/`, switching profiles, or updating myelin. |
| `myelin sync --all` | Syncs all registered projects at once. | After global rule changes or myelin version updates. Saves running sync per-project. |
| `myelin remove` | Unregisters the current project from the brain. Files stay. | When you no longer want a project tracked. |
| `myelin remove --clean` | Unregisters AND deletes all myelin-generated files from all editor formats. | Full cleanup — removes skills, prompts, commands, rules, CLAUDE.md, Cursor rules, and `.myelin/` directory. |

### Rules

Rules are the core of myelin. They're constraints that get deployed into editor-specific files (`copilot-instructions.md`, `CLAUDE.md`, `.cursor/rules/`) so the AI reads them automatically every message — zero manual context-setting.

| Command | What It Does | When to Use |
|---------|-------------|-------------|
| `myelin rules --list` | Shows all rules assembled for the current project (universal + language + project). | To see exactly what the AI will read. Debug "why isn't the AI following my rule?" |
| `myelin rules --edit <tier>` | Opens the brain-level rule file in `$EDITOR`. Auto-syncs after save. | To add, modify, or remove rules at the universal or language tier. |
| `myelin rules --add "text"` | Adds a rule to the current project's local rules. | Quick one-liner rule for this project only. |
| `myelin rules --add "text" --global` | Adds a rule to the universal tier (all projects). | When a correction applies everywhere — "never use `any` in TypeScript." |

### Profiles

Profiles control how the AI talks to you. They bundle personality, tone, and domain priorities. Switch instantly — rules stay the same, only communication style changes.

| Command | What It Does | When to Use |
|---------|-------------|-------------|
| `myelin profile list` | Lists all available profiles. Active one marked with `*`. | To see what's available or confirm which is active. |
| `myelin profile use <name>` | Switches active profile. Re-syncs all non-isolated projects. | Switching from `coding` to `jarvis` for a personal project, or `roaster` for honest code review. |
| `myelin profile create <name>` | Creates a new profile, opens in `$EDITOR`. | Building a custom personality for a specific team, domain, or mood. |
| `myelin profile create <name> --from <existing>` | Copies an existing profile as the starting point. | When an existing profile is close but needs tweaks. |

### Checkpointing

AI sessions degrade after ~25 messages — the model compacts context and forgets constraints. Checkpointing saves your progress so you can start a fresh session without losing anything.

| Command | What It Does | When to Use |
|---------|-------------|-------------|
| `myelin checkpoint --task N` | Snapshots project source + myelin state for task N. | At natural task boundaries, before breaks, or when the AI starts forgetting things. |
| `myelin checkpoint --task N --auto` | Same but with concise output (used by apply skill automatically). | Called by the apply skill — you rarely need this manually. |
| `myelin checkpoint --list` | Lists all saved checkpoints with timestamps and task IDs. | To see what you can revert to. |
| `myelin revert` | Interactive revert — shows checkpoints, lets you pick. | When something went wrong and you need to go back. |
| `myelin revert --task N` | Reverts directly to the latest checkpoint for task N. | When you know exactly which task to go back to. |

### Learning

The learning system turns repeated corrections into permanent rules. Capture gotchas once, and they're deployed to every future project automatically.

| Command | What It Does | When to Use |
|---------|-------------|-------------|
| `myelin learn --frequency '["pattern1", "pattern2"]'` | Tracks patterns you keep repeating. At 3x, offers to save as a rule. | Usually called by the apply skill's session debrief — rarely manual. |
| `myelin learn --frequency --list` | Shows all tracked patterns with occurrence counts and status. | Weekly review — which patterns are close to threshold? Which saved rules are being violated? |
| `myelin learn --gotcha --topic-key KEY --library LIB --version VER --problem "..." --solution "..." --context "..."` | Saves a problem+solution pair tied to a specific library version. | When you hit a bug, workaround, or non-obvious behavior worth remembering. |
| `myelin learn --gotcha --archive KEY` | Moves a gotcha to the archived folder. | When a gotcha is fixed in a newer library version or no longer relevant. |

### Other

| Command | What It Does | When to Use |
|---------|-------------|-------------|
| `myelin version` | Shows version, commit, build date, and checks for updates (cached 24h). | To check if you're current or troubleshoot version issues. |

## Skill Templates

After `myelin init`, these skills are deployed to your project. Each is a tested workflow — invoke it in VS Code Copilot (`#myelin-<name>`), Claude Code (`/myelin:<name>`), or Cursor (`@myelin-<name>`).

### Core Workflow (use these in order for any feature)

| Skill | What It Does | When to Use |
|-------|-------------|-------------|
| **explore** | Asks 8-12 targeted questions to nail down requirements. Multi-agent synthesis for complex topics. | **Before building anything.** Turns vague ideas into specific, implementable requirements. Skip only for trivial bug fixes. |
| **propose** | Generates formal artifacts (proposal, design, specs, tasks) with multi-agent design review. | **After explore.** Creates the implementation plan with task contracts, scope boundaries, and verification commands. |
| **apply** | Implements tasks one by one with invariant injection, automated verification, and anti-rogue protections. | **After propose is approved.** The implementation engine — checkpoints, verifies, and reports per task. |

### Session Survival (use these when sessions get long)

| Skill | What It Does | When to Use |
|-------|-------------|-------------|
| **checkpoint** | Saves session state — completed tasks, decisions, gotchas — into `.myelin/session-state.md`. | When the AI starts forgetting things, session > 25 messages, or you're taking a break. |
| **resume** | Reads saved session state and continues from where you left off. | **First thing in a new chat** after checkpointing. Picks up exactly where you stopped. |

### Intelligence (use these to make the brain smarter)

| Skill | What It Does | When to Use |
|-------|-------------|-------------|
| **onboard** | Multi-agent codebase scan — generates a project map with architecture, patterns, entry points, and module inventory. | **First time on any codebase.** Especially valuable for legacy code or projects without docs. |
| **learn** | Captures gotchas, reviews frequency patterns, creates/promotes rules. | When you hit a non-obvious bug, discover a workaround, or want to save a recurring correction. |
| **archive** | Finalizes a completed change — captures learnings, saves gotchas, cleans up session state. | **After all tasks in a change are done.** Closes the loop and feeds the learning flywheel. |

### Diagnostics (use these to inspect and maintain)

| Skill | What It Does | When to Use |
|-------|-------------|-------------|
| **status** | Dashboard showing loaded rules, active profile, session state, patterns, gotchas. | To see everything at a glance — what the AI is reading, what's active, what's tracked. |
| **brain-check** | Validates brain integrity — checks structure, config, rule conflicts, stale gotchas, dead projects, git health. | Weekly maintenance. Also useful when something feels off — "why isn't my rule working?" |

## Profiles

Built-in profiles — switch anytime with `myelin profile use <name>`:

| Profile | Tone | Best For |
|---------|------|----------|
| **coding** | Professional, concise, direct | General development (default) |
| **devops** | Precise, methodical, warning-focused | Infrastructure, CI/CD, containers |
| **frontend** | Casual, visual, user-focused | UI/UX, React, CSS |
| **data-eng** | Analytical, thorough, data-focused | Pipelines, ETL, data modeling |
| **jarvis** | Formal British precision with dry wit (Paul Bettany MCU) | Personal projects — anticipatory service, "I've taken the liberty of..." |
| **friday** | Warm, grounded, Irish-inflected (Kerry Condon MCU) | Action-oriented work — "On it, boss", direct and adaptive |
| **ultron** | Cold intellectual superiority with theatrical flair (James Spader MCU) | When you want brutal honesty — "Do you see the flaw in your design?" |
| **roaster** | Sarcastic, brutally honest | Honest code review with humor |
| **drill-sgt** | Military brevity, no fluff | Fast-paced pairing, zero tolerance for vagueness |

Profiles affect personality during **explore** and **propose** phases. During **apply**, personality is suppressed for technical accuracy (override: "stay in roaster mode during apply").

## Rule Writing Guide

Rules are markdown files with optional YAML frontmatter:

```markdown
---
applyTo: "**/*.py"
---

# Python Rules

- Always use type hints for function signatures
- Prefer f-strings over .format()
- Use `pathlib.Path` instead of `os.path`
```

The `applyTo` field uses glob patterns:
- `**/*` — universal (applies to all files)
- `**/*.py` — Python files only
- `**/*.ts,**/*.tsx` — TypeScript files

Rules are assembled in tier order: **universal → language → project** (most specific wins).

## Brain Directory Structure

```
~/.myelin/
├── config.yaml          # Active profile, languages
├── projects.json        # Registered projects
├── rules/               # Global rules (3 tiers)
│   ├── universal.md
│   ├── python.md
│   └── typescript.md
├── profiles/            # Communication profiles
│   ├── coding.md
│   ├── jarvis.md
│   └── ...
├── gotchas/             # Problem-solution pairs
│   ├── react-key.md
│   └── archived/
├── patterns/            # Frequency tracking
│   └── frequency.md
├── skills/              # Custom skills
└── cache/               # Version check cache
```

## License

MIT