memorylink 1.0.0

package/USER_GUIDE.md

@@ -0,0 +1,809 @@
+# MemoryLink User Guide
+
+**Version**: v1.0.0  
+**Last Updated**: 2025-12-20
+
+---
+
+## What You Can Do with MemoryLink
+
+MemoryLink helps you work safely with AI coding assistants. Here's what it does for you:
+
+- **Protect important files** when using AI agents
+- **Coordinate multiple agents** so they don't conflict with each other
+- **Roll back changes** if AI breaks something
+- **Check for problems** before and after AI makes changes
+- **Share project context** across different AI tools
+
+MemoryLink works with your existing Git workflow and stores everything locally in `.memorylink/` directory.
+
+---
+
+## First 5 Minutes with MemoryLink
+
+Get MemoryLink working in your project quickly:
+
+**1. Install and check:**
+```bash
+npm install -g memorylink
+memorylink --version
+# Should show: 1.0.0
+```
+*This installs MemoryLink globally and verifies it works.*
+
+**2. Initialize in your project:**
+```bash
+cd your-project
+memorylink init
+```
+*This creates `.memorylink/` directory with configuration files.*
+
+**3. Protect critical files:**
+```bash
+memorylink protect .env
+memorylink protect src/auth/
+memorylink protect prisma/migrations/
+```
+*This tells MemoryLink which files are sensitive and should be monitored.*
+
+**4. Run your first health check:**
+```bash
+memorylink doctor --preflight
+memorylink stats
+```
+*This runs initial safety checks and shows that MemoryLink is tracking runs.*
+
+**Now you're ready!** MemoryLink is installed, initialized, and tracking your project.
+
+---
+
+## Quick Daily Workflow (Happy Path)
+
+Here's how to use MemoryLink in a typical day of AI-assisted development:
+
+### Before AI Work
+
+1. **Acquire a lock** (prevents other agents from conflicting):
+   ```bash
+   memorylink lock acquire --agent "cursor"
+   ```
+
+2. **Create a checkpoint** (snapshot for rollback):
+   ```bash
+   memorylink checkpoint create --name "before-change"
+   ```
+
+3. **Run preflight check** (check for problems before starting):
+   ```bash
+   memorylink doctor --preflight
+   ```
+
+**What this means for you:**
+- The lock tells other AI agents to wait
+- The checkpoint saves your current state so you can go back
+- The preflight check warns you about existing problems
+
+### Do Your Work
+
+Use Cursor AI (or any AI tool) to make changes to your code.
+
+### After AI Work
+
+1. **Run postflight check** (check for problems after changes):
+   ```bash
+   memorylink doctor --postflight
+   ```
+
+2. **Review what changed** (see the difference):
+   ```bash
+   memorylink checkpoint diff --name "before-change"
+   ```
+
+3. **Release the lock** (let other agents work):
+   ```bash
+   memorylink lock release
+   ```
+
+**What this means for you:**
+- The postflight check tells you if AI introduced any problems
+- The diff shows you exactly what changed
+- Releasing the lock lets your team continue working
+
+---
+
+## How to Read Buddy-Check Results
+
+Buddy-Check returns one of three status levels. Here's what each means and what you should do:
+
+### GREEN Status
+
+**What it means:** Nothing risky found. You can continue.
+
+**What to do:**
+1. ✅ Review the changes yourself (Buddy-Check doesn't catch everything)
+2. ✅ Proceed with your normal workflow
+3. ✅ Commit and push if everything looks good
+
+**Example:**
+```bash
+$ memorylink doctor --postflight
+✅ Status: GREEN
+No issues detected. Safe to proceed.
+```
+
+---
+
+### YELLOW Status
+
+**What it means:** Warnings found. Review what changed, but CI may still pass.
+
+**What to do:**
+1. ⚠️ Check the warnings in the output
+2. ⚠️ Review the diff to see what changed
+3. ⚠️ Decide if the warnings are acceptable or need fixing
+
+**Example:**
+```bash
+$ memorylink doctor --postflight
+⚠️ Status: YELLOW
+Warnings:
+- Large change detected in src/api.ts (200+ lines)
+- Memory entry may be outdated
+
+Review changes before proceeding.
+```
+
+**Common YELLOW warnings:**
+- Large changes in a single file
+- Memory entries that might be outdated
+- Minor policy warnings
+
+---
+
+### RED Status
+
+**What it means:** Serious issue detected. Do not merge. Fix or revert.
+
+**What to do:**
+1. 🛑 **Stop** - Do not commit or merge
+2. 🛑 Check the error message to understand what's wrong
+3. 🛑 Either fix the issue or revert using your checkpoint
+
+**Example:**
+```bash
+$ memorylink doctor --postflight
+❌ Status: RED
+Critical issues:
+- Secret detected in memory log
+- Protected file modified: src/auth/middleware.ts
+
+Action required: Fix issues or revert changes.
+```
+
+**Common RED issues:**
+- Secrets or sensitive data detected
+- Protected files modified
+- Critical policy violations
+
+**How to revert:**
+```bash
+# See what changed
+memorylink checkpoint diff --name "before-change"
+
+# Restore to previous checkpoint
+memorylink checkpoint restore --name "before-change"
+```
+
+---
+
+## How to Check MemoryLink is Working
+
+### Check 1: Lock Behavior
+
+Test that locks actually prevent conflicts:
+
+```bash
+# Terminal 1
+memorylink lock acquire --agent "test-agent" --files "src/test.ts"
+
+# Terminal 2 (try to acquire same lock)
+memorylink lock acquire --agent "other-agent" --files "src/test.ts"
+# => Should see an error that lock is already held
+```
+
+**What you should see:** The second lock attempt should be blocked with a clear error message.
+
+### Check 2: Secret Detection
+
+Test that Buddy-Check detects potential secrets:
+
+```bash
+# Add a fake secret to a test file
+echo "// FAKE_KEY=AKIA1234567890TEST" >> src/fake-secret-test.ts
+memorylink doctor --postflight
+```
+
+**What you should see:** Doctor should give at least a YELLOW warning about a possible secret detected.
+
+**If both checks work:** MemoryLink is functioning correctly! Locks block conflicts, and Buddy-Check detects risky patterns.
+
+---
+
+## Real-World Examples
+
+### Example 1: Protecting Auth During AI Refactor
+
+**Problem:** You ask Cursor to "clean up auth code" and it accidentally removes a critical check. Without MemoryLink, you might only notice after deploy.
+
+**Solution with MemoryLink:**
+- Protect `src/auth/` once
+- Create checkpoint before refactor
+- Run Buddy-Check after changes
+- Use checkpoint diff to see exactly what changed
+- Rollback if needed
+
+See full workflow in README.md Example Scenarios section.
+
+### Example 2: Two Agents, One Repo
+
+**Problem:** Cursor and Claude both edit the same file at the same time. Without MemoryLink, one change silently overwrites the other.
+
+**Solution with MemoryLink:**
+- Agent 1 acquires lock before editing
+- Agent 2 is blocked until lock is released
+- No silent overwrites or conflicts
+
+See full workflow in README.md Example Scenarios section.
+
+---
+
+## How MemoryLink Works in a Team
+
+MemoryLink is designed for **team collaboration** with shared memory across multiple developers and AI tools.
+
+### Per-Repo, Shared Memory
+
+MemoryLink stores its logs in `.memorylink/` inside your Git repository. This means:
+
+- **When teammates pull the repo**, they can access the same shared memory (if `.memorylink/` files are committed)
+- **Any AI/agent** integrated with that repo (Cursor, Claude, VS Code, CI bots) can read from the same `.memorylink/` state
+- **One project brain per repo** - all tools and developers share the same context
+
+### How to Share Memory
+
+MemoryLink supports two patterns for memory sharing:
+
+#### 1. Shared Team Memory (Committed Logs)
+
+**Best for:** Long-term learnings, decisions, conventions, and project knowledge
+
+**What to commit:**
+```bash
+# Commit selected .memorylink/ files for team sharing
+git add .memorylink/memory.log .memorylink/rules.md .memorylink/protected.txt
+git commit -m "Add team learnings and conventions"
+```
+
+**What this enables:**
+- ✅ Everyone sees the same history, conventions, and learnings
+- ✅ New team members get context immediately
+- ✅ AI tools (Cursor, Claude, etc.) have access to team knowledge
+- ✅ Decisions and patterns are preserved across the team
+
+**Example:**
+- Dev A logs: "We always use Redis for sessions in this project"
+- Dev B's Cursor AI sees this when working on session code
+- Result: Consistent patterns across the team
+
+#### 2. Local Private Memory
+
+**Best for:** Sensitive logs, noisy runtime data, personal notes
+
+**What stays local:**
+```bash
+# .gitignore already excludes these by default
+.memorylink/*.log
+.memorylink/telemetry.log
+.memorylink/observability.log
+.memorylink/changes.log
+```
+
+**What this enables:**
+- ✅ Developers keep their own local logs that are not pushed
+- ✅ Sensitive or noisy runtime logs stay private
+- ✅ Personal notes and experiments remain local
+
+### Multi-Agent & Multi-Tool Behavior
+
+Multiple tools can all use the **same MemoryLink protocol**:
+
+- **Same `.memorylink/` structure** - all tools read/write to the same files
+- **Same workflow pattern** - `lock → checkpoint → doctor → diff → release`
+- **No manual sync needed** - tools automatically share memory through Git
+
+**Supported tools:**
+- Cursor AI
+- VS Code (with extensions)
+- Claude (via CLI)
+- GitHub Actions / CI bots
+- Custom automation scripts
+
+### Real Example: Team Knowledge Sharing
+
+**Scenario:**
+1. **Dev A** uses Cursor with MemoryLink and logs a learning: "Auth bug fixed: always check X before Y."
+2. Dev A commits `.memorylink/memory.log` to the repo.
+3. **Dev B** later uses Gemini Studio on the same repo.
+4. MemoryLink gives that learning to Gemini too (through the same `.memorylink/` files).
+5. **Result:** Tools share knowledge; team doesn't repeat the same mistakes.
+
+**Benefits:**
+- ✅ Knowledge persists across team members
+- ✅ AI tools learn from each other's work
+- ✅ No need to manually document patterns
+- ✅ Context is automatically available to all tools
+
+### Best Practices for Team Sharing
+
+1. **Commit important learnings:**
+   - Long-term decisions and conventions
+   - Common patterns and anti-patterns
+   - Project-specific rules and guidelines
+
+2. **Keep runtime logs local:**
+   - Don't commit noisy logs (changes.log, observability.log)
+   - Keep personal notes and experiments local
+   - Use `.gitignore` to exclude sensitive data
+
+3. **Use locks for coordination:**
+   - Always acquire locks when multiple agents work on the same files
+   - Check lock status before making changes
+   - Release locks when done
+
+4. **Share checkpoints for rollback:**
+   - Create checkpoints before major changes
+   - Commit checkpoint metadata (not full logs)
+   - Enable team rollback capability
+
+---
+
+## Common Problems and How to Handle Them
+
+### Problem: "I installed MemoryLink but I don't feel it doing anything"
+
+**What to check:**
+
+1. **Ensure you ran init:**
+   ```bash
+   memorylink init
+   ```
+
+2. **Protect at least a few files:**
+   ```bash
+   memorylink protect .env
+   memorylink protect src/auth/
+   ```
+
+3. **Run one full cycle:**
+   ```bash
+   memorylink lock acquire --agent "cursor"
+   memorylink checkpoint create --name "test-run"
+   memorylink doctor --preflight
+   # Change a file, add a fake secret
+   echo "// TEST_SECRET=sk_test_123" >> src/test.ts
+   memorylink doctor --postflight
+   memorylink lock release
+   ```
+
+4. **Verify it's working:**
+   - You should see lock status when checking
+   - You should see a warning about the fake secret
+   - If you see lock errors and secret warnings, MemoryLink is working!
+
+---
+
+### Problem: Buddy-Check Returns RED
+
+**What to check:**
+1. Look at the error message - it tells you what's wrong
+2. Check if secrets were accidentally added to memory
+3. Check if protected files were modified
+4. Review the diff to see what changed
+
+**How to fix:**
+1. **If secrets detected:**
+   - Remove the secret from your memory entry
+   - Use a reference instead (e.g., "API key stored in .env")
+   - Re-run the check
+
+2. **If protected file modified:**
+   - Review the changes carefully
+   - If intentional, you may need to update your protected file list
+   - If accidental, revert the changes
+
+3. **If you need to revert:**
+   ```bash
+   memorylink checkpoint restore --name "before-change"
+   ```
+
+---
+
+### Problem: Lock is Already Held
+
+**What this means:** Another agent (or you in another terminal) is already working on the same files.
+
+**How to see who holds it:**
+```bash
+memorylink lock status
+```
+
+**Output example:**
+```
+Lock Status:
+- Holder: cursor
+- Expires: 2025-12-20 15:30:00
+- Files: src/api.ts, src/utils.ts
+```
+
+**What to do:**
+1. **Wait** - The lock will expire automatically (default: 30 minutes)
+2. **Contact the holder** - If it's a teammate, ask them to release it
+3. **Release manually** (if you're the holder):
+   ```bash
+   memorylink lock release
+   ```
+4. **Renew the lock** (if you need more time):
+   ```bash
+   memorylink lock renew
+   ```
+
+---
+
+### Problem: Checkpoint Diff is Too Big
+
+**What this means:** Too many changes to review easily.
+
+**What to do:**
+1. **Create more frequent checkpoints:**
+   ```bash
+   # Before each major change
+   memorylink checkpoint create --name "before-feature-x"
+   memorylink checkpoint create --name "before-feature-y"
+   ```
+
+2. **Narrow your scope:**
+   - Work on smaller features
+   - Create checkpoints after each logical step
+
+3. **Use Git diff for code changes:**
+   ```bash
+   git diff
+   # Use MemoryLink checkpoints for memory changes
+   memorylink checkpoint diff --name "before-change"
+   ```
+
+---
+
+### Problem: CI Fails on RED Status
+
+**What this means:** Your GitHub Actions workflow detected a RED status and failed the build.
+
+**How to see the report:**
+1. Go to your GitHub repository
+2. Click on the failed workflow run
+3. Look for the "Buddy-Check" step
+4. Download the artifact (if configured) to see the full report
+
+**What to do:**
+1. **Check the workflow logs** for the error message
+2. **Fix the issue locally:**
+   ```bash
+   memorylink doctor --postflight
+   # Fix any RED issues
+   ```
+3. **Re-run the check:**
+   ```bash
+   memorylink doctor --postflight
+   ```
+4. **Push your fix** and the CI should pass
+
+**Example GitHub Actions output:**
+```
+❌ Critical issues detected - failing build
+Status: RED
+Issues:
+- Secret detected in memory log
+```
+
+---
+
+### Problem: Can't Find a Checkpoint
+
+**What this means:** The checkpoint name doesn't exist.
+
+**How to see available checkpoints:**
+```bash
+memorylink checkpoint list
+```
+
+**Output example:**
+```
+Available checkpoints:
+- before-feature (2025-12-20 10:00:00)
+- before-refactor (2025-12-20 09:00:00)
+- initial-state (2025-12-20 08:00:00)
+```
+
+**What to do:**
+1. Use the exact checkpoint name from the list
+2. Check spelling and capitalization
+3. Use a different checkpoint if the one you want doesn't exist
+
+---
+
+### Problem: MemoryLink Command Not Found
+
+**What this means:** MemoryLink is not installed or not in your PATH.
+
+**How to fix:**
+1. **Install MemoryLink:**
+   ```bash
+   npm install -g memorylink
+   ```
+
+2. **Verify installation:**
+   ```bash
+   memorylink --version
+   # Should show: 1.0.0
+   ```
+
+3. **If still not found:**
+   - Check your Node.js version (needs 18+)
+   - Restart your terminal
+   - Check npm global bin path: `npm config get prefix`
+
+---
+
+### Problem: "Not Initialized" Error
+
+**What this means:** MemoryLink hasn't been set up in your project.
+
+**How to fix:**
+```bash
+memorylink init
+```
+
+This creates the `.memorylink/` directory with configuration files.
+
+---
+
+## Best Practices for Safe Use
+
+Follow these practices to get the most out of MemoryLink:
+
+### 1. Always Create Checkpoints Before Large Changes
+
+**Before:**
+- Large refactors
+- Deleting files
+- Modifying protected files
+- Major feature additions
+
+**Example:**
+```bash
+memorylink checkpoint create --name "before-big-refactor"
+# ... make changes ...
+memorylink checkpoint diff --name "before-big-refactor"
+```
+
+---
+
+### 2. Always Use Locks When Multiple Agents Work on Same Repo
+
+**When to use:**
+- Multiple AI tools (Cursor, Claude, etc.)
+- Multiple developers
+- CI/CD pipelines making changes
+
+**Example:**
+```bash
+memorylink lock acquire --agent "cursor" --files "src/api.ts"
+# ... make changes ...
+memorylink lock release
+```
+
+---
+
+### 3. Configure Protected Files
+
+**What to protect:**
+- Environment files (`.env`, `.env.production`)
+- Authentication code (`src/auth/`, `auth/`)
+- Database migrations (`migrations/`)
+- Production config files
+
+**How to protect:**
+```bash
+memorylink protect .env
+memorylink protect src/auth/
+memorylink protect migrations/
+```
+
+---
+
+### 4. Run Buddy-Check in CI on Pull Requests
+
+**Why:** Catch problems before they reach main branch.
+
+**Example GitHub Actions:**
+```yaml
+- name: Run Buddy-Check
+  run: |
+    memorylink doctor --preflight --json > preflight.json
+    if grep -q '"status": "RED"' preflight.json; then
+      exit 1
+    fi
+```
+
+**Best practices:**
+- Run on every PR
+- Fail on RED status
+- Upload reports as artifacts
+- Use least-privilege permissions
+
+---
+
+### 5. Monitor Stats Regularly
+
+**Check your Buddy-Check metrics:**
+```bash
+memorylink stats
+memorylink stats --since 7d
+```
+
+**What to look for:**
+- High number of YELLOW warnings (may need review)
+- RED status frequency (may need better protection)
+- Lock conflicts (may need better coordination)
+
+---
+
+### 6. Review Buddy-Check Reports
+
+**After each check:**
+- Read the status (GREEN/YELLOW/RED)
+- Review warnings and errors
+- Check the diff if needed
+- Fix issues before proceeding
+
+---
+
+## When to Ask for Help / Open an Issue
+
+### Open an Issue If:
+
+1. **MemoryLink crashes:**
+   - Include the error message
+   - Include your Node.js version (`node --version`)
+   - Include your OS
+
+2. **RED status but you don't understand why:**
+   - Include the full output of `memorylink doctor --postflight`
+   - Describe what you were trying to do
+   - **Do NOT include secrets or sensitive data**
+
+3. **You think a serious issue was missed (false negative):**
+   - Describe what happened
+   - Include relevant file paths (but not file contents)
+   - Explain why you expected it to be caught
+
+4. **Feature request:**
+   - Describe what you want to do
+   - Explain why current features don't work
+   - Suggest how it might work
+
+### What to Include in Issues:
+
+- **Description:** What happened or what you want
+- **Steps to reproduce:** How to recreate the issue
+- **Expected behavior:** What you expected to happen
+- **Actual behavior:** What actually happened
+- **Environment:** OS, Node.js version, MemoryLink version
+- **Relevant output:** Command output (no secrets)
+
+### What NOT to Include:
+
+- ❌ Secrets, API keys, passwords
+- ❌ Full file contents (use snippets if needed)
+- ❌ Personal information
+- ❌ Internal company information
+
+### Where to Get Help:
+
+- **GitHub Issues:** [memorylink/memorylink/issues](https://github.com/memorylink/memorylink/issues)
+- **Documentation:** See `README.md`, `SECURITY_MODEL.md`, `ROADMAP_v1.6.md`
+- **Release Notes:** See `RELEASE_NOTES_v1.0.0.md`
+
+---
+
+## Quick Reference
+
+### Essential Commands
+
+```bash
+# Setup
+memorylink init
+memorylink protect <file>
+
+# Daily workflow
+memorylink lock acquire --agent "cursor"
+memorylink checkpoint create --name "before-change"
+memorylink doctor --preflight
+# ... make changes ...
+memorylink doctor --postflight
+memorylink checkpoint diff --name "before-change"
+memorylink lock release
+
+# Troubleshooting
+memorylink lock status
+memorylink checkpoint list
+memorylink stats
+```
+
+### Status Meanings
+
+- **GREEN:** Safe to proceed
+- **YELLOW:** Review warnings, then proceed
+- **RED:** Stop, fix issues, or revert
+
+### Common Workflows
+
+**Starting work:**
+```bash
+memorylink lock acquire --agent "cursor"
+memorylink checkpoint create --name "before-change"
+memorylink doctor --preflight
+```
+
+**Finishing work:**
+```bash
+memorylink doctor --postflight
+memorylink checkpoint diff --name "before-change"
+memorylink lock release
+```
+
+**Recovering from problems:**
+```bash
+memorylink checkpoint list
+memorylink checkpoint diff --name "before-change"
+memorylink checkpoint restore --name "before-change"
+```
+
+---
+
+## Summary
+
+MemoryLink helps you work safely with AI coding assistants by:
+
+1. **Protecting important files** from accidental changes
+2. **Coordinating multiple agents** to prevent conflicts
+3. **Creating checkpoints** for safe rollback
+4. **Checking for problems** before and after AI work
+5. **Sharing context** across different AI tools
+
+**Remember:**
+- Always create checkpoints before large changes
+- Always use locks when multiple agents work on the same repo
+- Always run Buddy-Check before and after AI work
+- Always review RED status before proceeding
+- Always configure protected files appropriately
+
+**For more information:**
+- See `README.md` for overview and installation
+- See `SECURITY_MODEL.md` for safety details
+- See `ROADMAP_v1.6.md` for future features
+
+---
+
+**MemoryLink v1.0.0** - User Guide
+