memorylink 1.0.0

package/CURSOR_AI_INTEGRATION_GUIDE.md

@@ -0,0 +1,775 @@
+# MemoryLink v1.5.1 - Cursor AI Integration Guide
+
+**Purpose**: Complete end-to-end integration guide for Cursor AI developers  
+**Version**: 1.5.1  
+**Date**: 2025-12-19
+
+---
+
+## 🎯 What MemoryLink Is (For Cursor)
+
+MemoryLink is a **Git-native, local memory and safety layer** for AI coding assistants.
+
+**Key Principle**: Cursor does **NOT** implement memory or safety itself. Instead:
+
+- ✅ Reads context **from** MemoryLink (`memorylink get-context ...`)
+- ✅ Runs **Buddy-Check** before and after agents (`memorylink doctor ...`)
+- ✅ Lets MemoryLink own checkpoints, locks, scopes, and stats
+
+**Architecture**: **Storage + Guardrails outside Cursor; UI + agent orchestration inside Cursor**
+
+---
+
+## 📋 Core Responsibilities for Cursor
+
+### 1. Before an Agent Runs (Preflight)
+
+**When**: User starts an AI task in Cursor (e.g., "Refactor auth flow")
+
+**Step 1: Run Buddy-Check Preflight**
+
+```bash
+memorylink doctor --preflight --json
+```
+
+**Parse the JSON Response**:
+```json
+{
+  "status": "GREEN" | "YELLOW" | "RED",
+  "summary": "Preflight check completed",
+  "issues": [
+    {
+      "type": "SECRET_DETECTED" | "BROKEN_REF" | "STALE_MEMORY" | "ACTIVE_LOCK",
+      "severity": "error" | "warning",
+      "message": "API key found in memory entry",
+      "file": ".memorylink/memory.log",
+      "entryId": "mem_abc123"
+    }
+  ],
+  "recordsUsed": 42,
+  "trust": { "high": 10, "medium": 25, "low": 7 },
+  "timestamp": "2025-12-19T16:00:00Z"
+}
+```
+
+**Step 2: Use Status in Cursor UI/Behavior**
+
+#### If Status = GREEN
+```typescript
+// Show in status bar
+statusBar.text = "MemoryLink: ● GREEN – Safe to run";
+statusBar.tooltip = "Last check: 2 minutes ago";
+
+// Proceed with agent
+allowAgentStart = true;
+```
+
+#### If Status = YELLOW
+```typescript
+// Show warning in status bar
+statusBar.text = "MemoryLink: ● YELLOW – Some stale or low-trust memories";
+statusBar.tooltip = "Warnings detected. Review issues panel.";
+
+// Show issues in panel
+showIssuesPanel(issues);
+
+// Allow agent but show warnings
+allowAgentStart = true;
+showWarning = true;
+```
+
+#### If Status = RED (Strict/Enterprise Mode)
+```typescript
+// Block agent start
+allowAgentStart = false;
+
+// Show blocking message
+showBlockingDialog({
+  title: "MemoryLink: RED – Agent Blocked",
+  message: "Critical issues detected. Fix before proceeding.",
+  issues: issues,
+  actions: [
+    { label: "Fix Issues", action: () => openFixDialog() },
+    { label: "Override with Reason", action: () => showOverrideDialog() }
+  ]
+});
+
+// If override, log to MemoryLink
+if (userOverrides) {
+  // Set environment variable or use --override flag
+  process.env.MEMORYLINK_OVERRIDE = "true";
+  process.env.MEMORYLINK_OVERRIDE_REASON = userReason;
+  process.env.MEMORYLINK_OVERRIDE_BY = userEmail;
+  
+  // MemoryLink will log to .memorylink/overrides.log
+}
+```
+
+**Implementation Example**:
+```typescript
+async function runPreflightCheck(): Promise<BuddyCheckResult> {
+  const { execSync } = require('child_process');
+  
+  try {
+    const output = execSync('memorylink doctor --preflight --json', {
+      encoding: 'utf-8',
+      cwd: workspaceRoot
+    });
+    
+    // Extract JSON from output (may have non-JSON text)
+    const jsonMatch = output.match(/\{[\s\S]*\}/);
+    if (!jsonMatch) {
+      throw new Error('No JSON found in preflight output');
+    }
+    
+    const result = JSON.parse(jsonMatch[0]);
+    return result;
+  } catch (error) {
+    // Handle error (MemoryLink not installed, not initialized, etc.)
+    console.error('Preflight check failed:', error);
+    return { status: 'RED', issues: [{ type: 'CHECK_FAILED', message: error.message }] };
+  }
+}
+```
+
+---
+
+### 2. While an Agent Runs (Context + Safety)
+
+**When**: Agent needs context for current task
+
+**Step 1: Request Context from MemoryLink**
+
+```bash
+memorylink get-context --smart --scope "<scope>" --format json --limit 50
+```
+
+**Options**:
+- `--smart`: Uses weighted scoring (trust, status, recency, file, task)
+- `--scope`: Filters to project area (e.g., `auth`, `frontend`, `billing`)
+- `--task`: Task description for relevance scoring
+- `--format json`: Machine-readable output
+- `--limit 50`: Maximum entries per section
+
+**Step 2: Feed Context into Agent Prompt**
+
+```typescript
+async function getMemoryLinkContext(options: {
+  scope?: string;
+  task?: string;
+  file?: string;
+}): Promise<ContextData> {
+  const { execSync } = require('child_process');
+  
+  let command = 'memorylink get-context --smart --format json --limit 50';
+  
+  if (options.scope) {
+    command += ` --scope "${options.scope}"`;
+  }
+  
+  if (options.task) {
+    command += ` --task "${options.task}"`;
+  }
+  
+  if (options.file) {
+    command += ` "${options.file}"`;
+  }
+  
+  try {
+    const output = execSync(command, { encoding: 'utf-8', cwd: workspaceRoot });
+    const jsonMatch = output.match(/\{[\s\S]*\}/);
+    
+    if (jsonMatch) {
+      return JSON.parse(jsonMatch[0]);
+    }
+    
+    // Fallback: parse human-readable output
+    return parseHumanReadableContext(output);
+  } catch (error) {
+    console.error('Context retrieval failed:', error);
+    return { memory: [], learnings: [], changes: [], protected: [] };
+  }
+}
+
+// Use in agent prompt
+const context = await getMemoryLinkContext({
+  scope: currentFileScope,
+  task: userRequest,
+  file: currentFile
+});
+
+const prompt = `
+${context.memory.map(m => `Memory: ${m.details}`).join('\n')}
+${context.learnings.map(l => `Learning: ${l.problem} -> ${l.solution} (${l.outcome})`).join('\n')}
+${context.protected.map(p => `Protected: ${p} - DO NOT MODIFY`).join('\n')}
+
+User Request: ${userRequest}
+`;
+```
+
+**Step 3: Respect Locks (Optional but Recommended)**
+
+Before making large, multi-file edits:
+
+```typescript
+async function acquireLockIfNeeded(files: string[]): Promise<boolean> {
+  const { execSync } = require('child_process');
+  
+  try {
+    const fileList = files.join(',');
+    const sessionId = `cursor-${Date.now()}`;
+    
+    execSync(`memorylink lock acquire --agent "${sessionId}" --files "${fileList}" --timeout 30`, {
+      encoding: 'utf-8',
+      cwd: workspaceRoot
+    });
+    
+    return true;
+  } catch (error) {
+    // Lock already held or other error
+    const lockStatus = execSync('memorylink lock status --json', {
+      encoding: 'utf-8',
+      cwd: workspaceRoot
+    });
+    
+    const status = JSON.parse(lockStatus);
+    if (status.locked) {
+      showWarning(`Lock held by ${status.agentId}. Proceed anyway?`);
+      return userConfirms;
+    }
+    
+    return false;
+  }
+}
+
+// For long-running operations
+async function renewLock(): Promise<void> {
+  execSync('memorylink lock renew --timeout 60', {
+    encoding: 'utf-8',
+    cwd: workspaceRoot
+  });
+}
+
+// When done
+async function releaseLock(): Promise<void> {
+  execSync('memorylink lock release', {
+    encoding: 'utf-8',
+    cwd: workspaceRoot
+  });
+}
+```
+
+---
+
+### 3. After an Agent Proposes Changes (Postflight)
+
+**When**: Cursor has a set of staged edits (changed files + any MemoryLink log writes)
+
+**Step 1: Run Buddy-Check Postflight**
+
+```bash
+memorylink doctor --postflight --changed --json
+```
+
+**Parse the JSON Response** (same format as preflight)
+
+**Step 2: Use Results to Gate "Apply/Commit"**
+
+#### If Status = GREEN
+```typescript
+// Show success
+statusBar.text = "MemoryLink: ● GREEN – Safe to apply/commit";
+showSuccessNotification("MemoryLink validated changes. Safe to proceed.");
+
+// Allow apply/commit
+allowApply = true;
+allowCommit = true;
+```
+
+#### If Status = YELLOW
+```typescript
+// Show warning
+statusBar.text = "MemoryLink: ● YELLOW – Minor issues detected";
+showWarningNotification("MemoryLink found warnings. Review before committing.");
+
+// Show issues in panel
+showIssuesPanel(issues);
+
+// Allow but warn
+allowApply = true;
+allowCommit = true;
+showWarning = true;
+```
+
+#### If Status = RED (Strict/Enterprise Mode)
+```typescript
+// Block apply/commit
+allowApply = false;
+allowCommit = false;
+
+// Show blocking dialog
+showBlockingDialog({
+  title: "MemoryLink: RED – Changes Blocked",
+  message: "Critical issues detected. Fix before committing.",
+  issues: issues,
+  actions: [
+    {
+      label: "Fix with MemoryLink",
+      action: () => {
+        // Run fix command
+        execSync('memorylink doctor --fix', { cwd: workspaceRoot });
+        // Re-run postflight
+        runPostflightCheck();
+      }
+    },
+    {
+      label: "Cancel Changes",
+      action: () => revertChanges()
+    },
+    {
+      label: "Override with Reason",
+      action: () => showOverrideDialog()
+    }
+  ]
+});
+```
+
+**Implementation Example**:
+```typescript
+async function runPostflightCheck(): Promise<BuddyCheckResult> {
+  const { execSync } = require('child_process');
+  
+  try {
+    const output = execSync('memorylink doctor --postflight --changed --json', {
+      encoding: 'utf-8',
+      cwd: workspaceRoot
+    });
+    
+    const jsonMatch = output.match(/\{[\s\S]*\}/);
+    if (!jsonMatch) {
+      throw new Error('No JSON found in postflight output');
+    }
+    
+    const result = JSON.parse(jsonMatch[0]);
+    return result;
+  } catch (error) {
+    console.error('Postflight check failed:', error);
+    return { status: 'RED', issues: [{ type: 'CHECK_FAILED', message: error.message }] };
+  }
+}
+
+// Call before allowing commit
+async function validateBeforeCommit(): Promise<boolean> {
+  const result = await runPostflightCheck();
+  const config = readMemoryLinkConfig();
+  const isStrict = config.mode === 'enterprise' || config.strict === true;
+  
+  if (result.status === 'RED' && isStrict) {
+    showBlockingDialog(result);
+    return false;
+  }
+  
+  if (result.status === 'YELLOW') {
+    showWarning(result);
+  }
+  
+  return true;
+}
+```
+
+---
+
+## 🎨 How Cursor Should Surface MemoryLink in the UI
+
+### 1. Status Bar
+
+**Display**:
+```
+MemoryLink: ● GREEN / ● YELLOW / ● RED
+```
+
+**Implementation**:
+```typescript
+class MemoryLinkStatusBar {
+  private statusBar: StatusBarItem;
+  
+  constructor() {
+    this.statusBar = window.createStatusBarItem(StatusBarAlignment.Right, 100);
+    this.statusBar.command = 'memorylink.showPanel';
+    this.updateStatus();
+  }
+  
+  async updateStatus() {
+    const result = await runPreflightCheck();
+    
+    let text = 'MemoryLink: ';
+    let color = '';
+    
+    switch (result.status) {
+      case 'GREEN':
+        text += '● GREEN';
+        color = '#00ff00';
+        break;
+      case 'YELLOW':
+        text += '● YELLOW';
+        color = '#ffff00';
+        break;
+      case 'RED':
+        text += '● RED';
+        color = '#ff0000';
+        break;
+    }
+    
+    this.statusBar.text = text;
+    this.statusBar.color = color;
+    this.statusBar.tooltip = `Last check: ${formatTime(result.timestamp)}\n${result.summary}`;
+    this.statusBar.show();
+  }
+}
+```
+
+### 2. Sidebar / Panel
+
+**Create Three Tabs**:
+
+#### Tab 1: Buddy-Check
+```typescript
+class BuddyCheckPanel {
+  render() {
+    return {
+      title: 'Buddy-Check',
+      content: `
+        <div class="buddy-check-panel">
+          <div class="status">
+            <span class="status-indicator ${lastResult.status}"></span>
+            <span>${lastResult.status}</span>
+          </div>
+          <div class="issues">
+            ${lastResult.issues.map(issue => `
+              <div class="issue ${issue.severity}">
+                <strong>${issue.type}</strong>
+                <p>${issue.message}</p>
+                ${issue.file ? `<small>${issue.file}</small>` : ''}
+              </div>
+            `).join('')}
+          </div>
+          <div class="actions">
+            <button onclick="runPreflight()">Run Preflight</button>
+            <button onclick="runPostflight()">Run Postflight</button>
+          </div>
+        </div>
+      `
+    };
+  }
+}
+```
+
+#### Tab 2: Memory
+```typescript
+class MemoryPanel {
+  async render() {
+    const context = await getMemoryLinkContext({
+      scope: currentScope,
+      file: currentFile
+    });
+    
+    return {
+      title: 'Memory',
+      content: `
+        <div class="memory-panel">
+          <div class="filters">
+            <input placeholder="Filter by scope..." onchange="filterByScope(this.value)">
+            <select onchange="filterByTrust(this.value)">
+              <option>All Trust Levels</option>
+              <option>High Trust</option>
+              <option>Medium Trust</option>
+              <option>Low Trust</option>
+            </select>
+          </div>
+          <div class="memory-list">
+            ${context.memory.map(entry => `
+              <div class="memory-entry">
+                <div class="badges">
+                  <span class="trust-${entry.trustLevel}">${entry.trustLevel}</span>
+                  <span class="sensitivity-${entry.sensitivity}">${entry.sensitivity}</span>
+                  ${entry.memoryStatus === 'VERIFIED' ? '<span class="verified">✓</span>' : ''}
+                </div>
+                <div class="content">${entry.details}</div>
+                <div class="meta">
+                  <small>${entry.ts} • ${entry.agent}</small>
+                  ${entry.projectScope ? `<small>Scope: ${entry.projectScope}</small>` : ''}
+                </div>
+              </div>
+            `).join('')}
+          </div>
+        </div>
+      `
+    };
+  }
+}
+```
+
+#### Tab 3: Stats (Optional)
+```typescript
+class StatsPanel {
+  async render() {
+    const { execSync } = require('child_process');
+    const statsOutput = execSync('memorylink stats --format json --since 7d', {
+      encoding: 'utf-8',
+      cwd: workspaceRoot
+    });
+    
+    const stats = JSON.parse(statsOutput.match(/\{[\s\S]*\}/)[0]);
+    
+    return {
+      title: 'Stats',
+      content: `
+        <div class="stats-panel">
+          <div class="overview">
+            <div class="stat">
+              <strong>${stats.totalRuns}</strong>
+              <small>Total Runs</small>
+            </div>
+            <div class="stat">
+              <strong>${stats.statusCounts.GREEN}</strong>
+              <small>GREEN</small>
+            </div>
+            <div class="stat">
+              <strong>${stats.statusCounts.YELLOW}</strong>
+              <small>YELLOW</small>
+            </div>
+            <div class="stat">
+              <strong>${stats.statusCounts.RED}</strong>
+              <small>RED</small>
+            </div>
+          </div>
+          ${stats.recommendations && stats.recommendations.length > 0 ? `
+            <div class="recommendations">
+              <h3>Recommendations</h3>
+              ${stats.recommendations.map(rec => `<p>• ${rec}</p>`).join('')}
+            </div>
+          ` : ''}
+        </div>
+      `
+    };
+  }
+}
+```
+
+---
+
+## ⚙️ How Cursor Should Treat Modes and Policies
+
+### Reading Configuration
+
+```typescript
+function readMemoryLinkConfig(): MemoryLinkConfig {
+  const fs = require('fs');
+  const path = require('path');
+  
+  const configPath = path.join(workspaceRoot, '.memorylink', 'config.json');
+  
+  if (!fs.existsSync(configPath)) {
+    return { mode: 'developer', strict: false };
+  }
+  
+  const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+  return {
+    mode: config.mode || 'developer',
+    strict: config.strict || false
+  };
+}
+```
+
+### Mode Behavior
+
+#### Developer Mode (Default)
+```typescript
+const config = readMemoryLinkConfig();
+
+if (config.mode === 'developer' || !config.strict) {
+  // Warnings only
+  if (result.status === 'RED') {
+    showWarning(result);
+    allowAgentStart = true; // Still allow
+  }
+}
+```
+
+#### Enterprise / Strict Mode
+```typescript
+if (config.mode === 'enterprise' || config.strict === true) {
+  // Hard blocks
+  if (result.status === 'RED') {
+    blockAgentStart(result);
+    allowAgentStart = false;
+  }
+  
+  // Override requires explicit reason
+  if (userOverrides) {
+    const reason = await promptForReason();
+    const approver = await promptForApprover();
+    
+    // Log override
+    logOverride({
+      status: 'RED',
+      reason: reason,
+      approvedBy: approver,
+      timestamp: new Date().toISOString()
+    });
+  }
+}
+```
+
+**Key Point**: Cursor does **NOT** own policy logic. It:
+- Reads mode and status from MemoryLink's JSON
+- Enforces behavior in UI and flows accordingly
+
+---
+
+## 🔄 CI and Multi-Tool Story
+
+### How Cursor Fits into the Bigger Picture
+
+Even if an agent runs outside Cursor (e.g., in GitHub Actions or another IDE):
+
+- MemoryLink + CI ensures Buddy-Check runs on PRs/pushes
+- Cursor's pre/postflight behaves the same way locally as CI does in pipelines
+
+**Example GitHub Action**:
+```yaml
+name: MemoryLink Preflight
+
+on:
+  pull_request:
+    branches: [main, develop]
+  push:
+    branches: [main, develop]
+
+jobs:
+  preflight:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+      - run: npm install -g memorylink
+      - run: memorylink doctor --preflight --json > preflight.json
+      - name: Check Status
+        run: |
+          STATUS=$(jq -r '.status' preflight.json)
+          if [ "$STATUS" = "RED" ]; then
+            echo "❌ MemoryLink preflight failed"
+            exit 1
+          fi
+      - uses: actions/upload-artifact@v3
+        with:
+          name: preflight-report
+          path: preflight.json
+```
+
+**Result**: One story for all tools:
+- "No matter which tool the agent runs in (Cursor, VS Code, CI), MemoryLink Buddy-Check is the **single source of truth** for:
+  - Is the repo safe to run agents?
+  - Did the last agent change introduce unsafe memory or code?"
+
+---
+
+## 📝 Complete Integration Flow Example
+
+### Full Agent Workflow
+
+```typescript
+class MemoryLinkAgentOrchestrator {
+  async runAgentTask(userRequest: string, files: string[]) {
+    // 1. Preflight
+    const preflight = await runPreflightCheck();
+    const config = readMemoryLinkConfig();
+    
+    if (preflight.status === 'RED' && (config.mode === 'enterprise' || config.strict)) {
+      await showBlockingDialog(preflight);
+      return; // Blocked
+    }
+    
+    if (preflight.status === 'YELLOW' || preflight.status === 'RED') {
+      await showWarningDialog(preflight);
+    }
+    
+    // 2. Acquire Lock (optional)
+    const lockAcquired = await acquireLockIfNeeded(files);
+    
+    // 3. Get Context
+    const context = await getMemoryLinkContext({
+      scope: detectScope(files),
+      task: userRequest,
+      file: files[0]
+    });
+    
+    // 4. Run Agent
+    const agentResult = await runAgent({
+      prompt: buildPrompt(context, userRequest),
+      files: files
+    });
+    
+    // 5. Postflight
+    const postflight = await runPostflightCheck();
+    
+    if (postflight.status === 'RED' && (config.mode === 'enterprise' || config.strict)) {
+      await showBlockingDialog(postflight);
+      await revertChanges();
+      return; // Blocked
+    }
+    
+    if (postflight.status === 'YELLOW') {
+      await showWarningDialog(postflight);
+    }
+    
+    // 6. Release Lock
+    if (lockAcquired) {
+      await releaseLock();
+    }
+    
+    // 7. Show Success
+    await showSuccessNotification("Agent completed. MemoryLink validated changes.");
+  }
+}
+```
+
+---
+
+## 🎯 In One Sentence for Cursor
+
+**MemoryLink v1.5.1 gives Cursor a ready-made guardrail + memory layer**: Cursor only needs to call the CLI at three points (preflight, get-context, postflight), show GREEN/YELLOW/RED in the UI, and respect locks and modes; all safety, governance, and memory intelligence stays in MemoryLink.
+
+---
+
+## 📚 Additional Resources
+
+- **Buddy-Check Guide**: `CURSOR_AI_BUDDY_CHECK_GUIDE.md`
+- **Master Validation**: `MASTER_VALIDATION_DOCUMENT.md`
+- **CLI Documentation**: Run `memorylink --help`
+- **Example Integration**: See `extensions/vscode/` for reference implementation
+
+---
+
+## ✅ Integration Checklist
+
+- [ ] Install MemoryLink CLI
+- [ ] Initialize MemoryLink in workspace
+- [ ] Implement preflight check before agent runs
+- [ ] Implement context retrieval during agent work
+- [ ] Implement postflight check after agent changes
+- [ ] Add status bar indicator
+- [ ] Add sidebar panels (Buddy-Check, Memory, Stats)
+- [ ] Read and respect mode configuration
+- [ ] Handle GREEN/YELLOW/RED status appropriately
+- [ ] Implement override flow with logging
+- [ ] Test with developer mode
+- [ ] Test with enterprise/strict mode
+- [ ] Test error handling (MemoryLink not installed, etc.)
+
+---
+
+**Status**: ✅ **Complete Integration Guide Ready**
+
+**Next Step**: Implement integration in Cursor AI following this guide.
+