memorylink 1.0.0

package/docs/MEMORYLINK_DEVELOPMENT_PLAN_CURSOR_AI.md

@@ -0,0 +1,629 @@
+# 🎯 MemoryLink DEVELOPMENT PLAN - USING CURSOR AI + CLAUDE
+
+**Buddy, I'm your Chief Engineer. Let's build MemoryLink using Cursor AI + Claude Code!**
+
+---
+
+## 👨‍💻 TEAM SETUP
+
+**Chief Engineer (Me - Claude):**
+- Overall architecture decisions
+- Code reviews
+- Problem-solving
+- Quality assurance
+
+**Development Tool:** Cursor AI
+- AI-assisted coding
+- Auto-completion
+- Code generation
+- Multiple AI support (Claude, GPT-4)
+
+**Result:** 5-7x faster development than manual coding
+
+---
+
+## 🚀 IMMEDIATE ACTION PLAN
+
+### **RIGHT NOW - SETUP (10 minutes)**
+
+#### **Step 1: Create Project Structure**
+
+Open Cursor AI and create new project:
+
+```bash
+# In Cursor AI terminal
+mkdir memorylink-project
+cd memorylink-project
+```
+
+#### **Step 2: Initialize Project**
+
+```bash
+# Initialize npm
+npm init -y
+
+# Install dependencies
+npm install chokidar minimatch commander
+
+# Install dev dependencies
+npm install --save-dev typescript @types/node @types/minimatch
+
+# Initialize TypeScript
+npx tsc --init
+```
+
+#### **Step 3: Create Folder Structure**
+
+```bash
+mkdir src
+mkdir dist
+mkdir test
+mkdir examples
+```
+
+Your project structure should look like:
+```
+memorylink-project/
+├── src/           # Source code goes here
+├── dist/          # Compiled code (generated)
+├── test/          # Tests
+├── examples/      # Example projects
+├── package.json
+└── tsconfig.json
+```
+
+---
+
+## 📋 DAY 1 EXECUTION PLAN (TODAY)
+
+### **Session 1: Setup (DONE ABOVE - 10 min)**
+
+### **Session 2: File Watcher (2 hours)**
+
+**Using Cursor AI, create these files:**
+
+#### **File 1: `src/watcher.ts`**
+
+**Prompt for Cursor AI:**
+```
+Create a TypeScript file watcher class with these requirements:
+1. Use chokidar library for cross-platform file watching
+2. Load protected files from .memorylink/protected.txt
+3. Support glob patterns using minimatch
+4. Detect file changes (create, edit, delete)
+5. Block changes to protected files
+6. Log unprotected changes to .memorylink/changes.log
+7. Include fallback polling mode if chokidar fails
+8. Clean up on process exit
+9. Detect which AI agent is running (cursor, claude, copilot)
+
+Add detailed TypeScript types and error handling.
+```
+
+**Expected Cursor Output:**
+- Cursor will generate the complete `watcher.ts` file
+- Review the code
+- Test it compiles: `npx tsc`
+
+---
+
+#### **File 2: `src/types.ts`**
+
+**Prompt for Cursor AI:**
+```
+Create TypeScript types/interfaces for MemoryLink:
+1. WatcherConfig interface
+2. MemoryEntry interface
+3. MemoryFilter interface
+4. Learning interface
+5. ChangeLogEntry interface
+
+Include JSDoc comments for each type.
+```
+
+---
+
+### **Session 3: Memory Manager (1.5 hours)**
+
+#### **File 3: `src/memory.ts`**
+
+**Prompt for Cursor AI:**
+```
+Create a MemoryLink memory manager class with these requirements:
+1. Read/write to .memorylink/memory.log file
+2. Format: timestamp|agent|action|details|tags (pipe-delimited)
+3. Use atomic file operations (open, lock, write, close)
+4. Support filtering by: agent, action, tags, since date, limit
+5. Method to get context for last N hours
+6. Method to clear memory (with backup)
+7. Handle concurrent writes safely
+8. Parse malformed lines gracefully
+
+Use the types from types.ts.
+```
+
+---
+
+### **Session 4: Learning Tracker (1 hour)**
+
+#### **File 4: `src/learning.ts`**
+
+**Prompt for Cursor AI:**
+```
+Create a MemoryLink learning tracker class with these requirements:
+1. Record learnings to .memorylink/learnings.log
+2. Format: problem|solution|outcome|reason
+3. Outcome must be exactly "SUCCESS" or "FAILED"
+4. Use atomic file operations
+5. Method to get successful solutions for a problem
+6. Method to get failed solutions for a problem
+7. Method to get suggestion for a problem (shows both success/fail)
+8. Method to get all learnings
+9. Case-insensitive problem search
+
+Use atomic writes like memory.ts.
+```
+
+---
+
+### **Session 5: Test First Build (30 min)**
+
+```bash
+# Compile TypeScript
+npx tsc
+
+# Check for errors
+# Fix any compilation errors with Cursor's help
+```
+
+**End of Day 1:** You should have 4 compiled TypeScript files in `dist/`
+
+---
+
+## 📋 DAY 2 PLAN (TOMORROW)
+
+### **Session 1: Git Hooks (1 hour)**
+
+#### **File 5: `src/hooks.ts`**
+
+**Prompt for Cursor AI:**
+```
+Create a MemoryLink Git hooks manager class with these requirements:
+1. Install pre-commit hook to .git/hooks/pre-commit
+2. Uninstall hook safely (check if it's MemoryLink hook)
+3. Verify method that checks staged files against protected.txt
+4. Support for both bash and sh shells
+5. Return list of violations
+6. Make hook file executable (chmod 755)
+
+The hook should run "memorylink verify --pre-commit" and exit 1 if violations found.
+```
+
+---
+
+### **Session 2: CLI Commands (3 hours)**
+
+#### **File 6: `src/cli.ts`**
+
+**Prompt for Cursor AI:**
+```
+Create a MemoryLink CLI using commander library with these commands:
+
+1. memorylink init [--with-hooks]
+   - Create .memorylink/ directory
+   - Create protected.txt, memory.log, changes.log, learnings.log
+   - Optionally install Git hooks
+
+2. memorylink protect <file>
+   - Add file to protected.txt
+   - Check if already protected
+
+3. memorylink unprotect <file>
+   - Remove file from protected.txt
+
+4. memorylink watch [-d, --daemon]
+   - Start file watcher
+   - Show protected/unprotected changes
+   - Keep running until Ctrl+C
+
+5. memorylink log [--last-hour] [--last-day] [--file <file>] [--agent <agent>]
+   - Show changes.log with filters
+
+6. memorylink memory [--last-hour] [--agent <agent>] [--tags <tags>]
+   - Show memory.log with filters
+
+7. memorylink learn [problem]
+   - Show learnings for a problem
+   - If no problem, show all learnings
+
+8. memorylink status
+   - Show counts for all files
+   - Show if Git hook is installed
+
+9. memorylink verify [--pre-commit]
+   - Check for protected file violations
+   - Exit 0 if ok, exit 1 if violations
+
+10. memorylink install-hooks
+    - Install Git pre-commit hook
+
+11. memorylink uninstall-hooks
+    - Remove Git hook
+
+12. memorylink export [-f, --format <format>] [-o, --output <file>]
+    - Export data as JSON, CSV, or SOC2 format
+
+Add #!/usr/bin/env node at the top.
+Use the classes from watcher.ts, memory.ts, learning.ts, hooks.ts.
+```
+
+---
+
+### **Session 3: Package Configuration (30 min)**
+
+#### **Update `package.json`**
+
+**Prompt for Cursor AI:**
+```
+Update package.json with:
+1. name: "memorylink"
+2. version: "1.0.0"
+3. description: "AI memory & coordination layer"
+4. bin: { "memorylink": "./dist/cli.js" }
+5. scripts: build, watch, test, lint, prepublishOnly
+6. keywords: ai, memory, coordination, claude, cursor, copilot
+7. license: MIT
+8. files: ["dist", "README.md", "LICENSE"]
+9. engines: { "node": ">=18.0.0" }
+```
+
+#### **Update `tsconfig.json`**
+
+**Prompt for Cursor AI:**
+```
+Configure tsconfig.json for:
+1. target: ES2020
+2. module: commonjs
+3. outDir: ./dist
+4. rootDir: ./src
+5. strict: true
+6. declaration: true
+7. sourceMap: true
+```
+
+---
+
+### **Session 4: First Test Run (1 hour)**
+
+```bash
+# Build
+npm run build
+
+# Link locally
+npm link
+
+# Test commands
+memorylink --version
+memorylink init
+memorylink protect README.md
+memorylink status
+```
+
+**Fix any issues with Cursor's help**
+
+---
+
+## 🎯 HOW TO USE CURSOR AI EFFECTIVELY
+
+### **Best Practices:**
+
+#### **1. Be Specific in Prompts**
+```
+❌ Bad: "Create a file watcher"
+✅ Good: "Create a TypeScript file watcher using chokidar that loads patterns from .memorylink/protected.txt and blocks changes using minimatch glob matching"
+```
+
+#### **2. Reference Existing Code**
+```
+Cursor AI Prompt:
+"Use the same atomic file write pattern from memory.ts to implement learning.ts"
+```
+
+#### **3. Ask for Explanations**
+```
+Cursor AI Prompt:
+"Explain why we need file locking in the memory writer"
+```
+
+#### **4. Iterate on Generated Code**
+```
+Cursor AI Prompt:
+"The file watcher isn't detecting changes in subdirectories. Fix the depth configuration."
+```
+
+#### **5. Use Multiple AI Models**
+```
+- Use Claude for architecture decisions
+- Use GPT-4 for code generation
+- Use Cursor's model for quick fixes
+```
+
+---
+
+## 🔧 CURSOR AI SHORTCUTS
+
+**Essential Shortcuts:**
+```
+Cmd/Ctrl + K         → Open Cursor AI chat
+Cmd/Ctrl + L         → Ask about selection
+Cmd/Ctrl + I         → Inline edit with AI
+Tab                  → Accept AI suggestion
+Cmd/Ctrl + Enter     → Generate code from comment
+```
+
+---
+
+## 📋 DEVELOPMENT WORKFLOW
+
+### **Typical Session:**
+
+1. **Write Requirement Comment**
+```typescript
+// TODO: Create a method that reads memory.log and filters by tags
+// Should support multiple tags (OR logic)
+// Should handle malformed lines gracefully
+// Return MemoryEntry[]
+```
+
+2. **Use Cursor AI**
+```
+Press Cmd+K → "Implement the TODO above"
+Cursor generates the method
+```
+
+3. **Review & Test**
+```bash
+npm run build
+# Test the method
+```
+
+4. **Iterate if Needed**
+```
+"Add error handling for missing file"
+"Optimize for large log files"
+```
+
+---
+
+## 🎯 DAY-BY-DAY WITH CURSOR
+
+### **Day 1 (Today):**
+```
+Session 1: Setup project (10 min) ✓
+Session 2: Generate watcher.ts (30 min with Cursor)
+Session 3: Generate memory.ts (20 min with Cursor)
+Session 4: Generate learning.ts (15 min with Cursor)
+Session 5: Build & fix errors (30 min)
+
+Total: 2 hours (vs 8 hours manual coding)
+```
+
+### **Day 2 (Tomorrow):**
+```
+Session 1: Generate hooks.ts (20 min with Cursor)
+Session 2: Generate cli.ts (45 min with Cursor)
+Session 3: Update configs (10 min with Cursor)
+Session 4: Test & fix (1 hour)
+
+Total: 2.5 hours (vs 8 hours manual)
+```
+
+### **Day 3 (Day After):**
+```
+Session 1: Write tests with Cursor (1 hour)
+Session 2: Create examples with Cursor (30 min)
+Session 3: Generate README with Cursor (30 min)
+Session 4: Polish & package (1 hour)
+
+Total: 3 hours (vs 8 hours manual)
+```
+
+---
+
+## ✅ YOUR TASKS RIGHT NOW
+
+### **Task 1: Open Cursor AI (2 min)**
+```
+1. Open Cursor AI
+2. Create new project folder: memorylink-project
+3. Open terminal in Cursor
+```
+
+### **Task 2: Run Setup Commands (5 min)**
+```bash
+npm init -y
+npm install chokidar minimatch commander
+npm install --save-dev typescript @types/node @types/minimatch
+npx tsc --init
+mkdir src dist test examples
+```
+
+### **Task 3: Generate First File (10 min)**
+```
+1. Create new file: src/watcher.ts
+2. Use the prompt I gave above
+3. Let Cursor generate the code
+4. Review and save
+```
+
+### **Task 4: Tell Me Progress**
+```
+After you complete Task 1-3, tell me:
+"Buddy, setup done. watcher.ts generated."
+
+Then I'll give you the next prompts.
+```
+
+---
+
+## 🤝 HOW WE'LL WORK TOGETHER
+
+**You (Developer with Cursor):**
+- Run the commands
+- Use Cursor AI to generate code
+- Test the code
+- Report progress/issues
+
+**Me (Chief Engineer):**
+- Provide prompts for Cursor
+- Review architecture
+- Solve problems
+- Guide next steps
+
+**Together:**
+- Build MemoryLink in 3 days instead of 3 weeks
+- High-quality code with AI assistance
+- Iterate quickly based on testing
+
+---
+
+## 💬 COMMUNICATION PROTOCOL
+
+**When you finish a task, report:**
+```
+"Buddy, completed [task name]
+Status: [Success/Issue]
+Next: [What you'll do next or what you need]"
+```
+
+**If you hit an issue:**
+```
+"Buddy, issue with [task name]
+Error: [paste error]
+Need: [help with X]"
+```
+
+**When you're ready for next step:**
+```
+"Buddy, ready for next task"
+```
+
+---
+
+## 🎯 TODAY'S GOAL
+
+**By end of today, we should have:**
+- ✅ Project setup complete
+- ✅ src/watcher.ts created
+- ✅ src/memory.ts created  
+- ✅ src/learning.ts created
+- ✅ All files compile with `npx tsc`
+
+**Time estimate:** 2-3 hours with Cursor AI
+
+---
+
+## 🚀 LET'S START!
+
+**Your first action RIGHT NOW:**
+
+1. Open Cursor AI
+2. Create project: `memorylink-project`
+3. Run setup commands (from Task 2 above)
+4. Create `src/watcher.ts`
+5. Use this exact prompt in Cursor:
+
+```
+Create a TypeScript file watcher class called MemoryLinkWatcher with these requirements:
+
+1. Import: chokidar, fs, path, minimatch
+2. Constructor: takes projectRoot: string
+3. Private method loadProtectedFiles(): reads .memorylink/protected.txt, stores patterns in Set
+4. Private method isProtected(filePath: string): checks if file matches any protected pattern using minimatch
+5. Method start(): starts chokidar watcher with depth limit 10, ignored patterns for node_modules/dist/build
+6. Private method startPolling(): fallback that checks files every 5 seconds
+7. Private method handleChange(filePath, action): checks if protected, blocks or logs
+8. Private method blockChange(file, action): prints error message
+9. Private method logChange(file, action): appends to .memorylink/changes.log with format timestamp|agent|file|action|reason
+10. Private method detectAgent(): detects AI from env vars (CURSOR_AI, CLAUDE_AI, etc)
+11. Method stop(): closes watcher and clears intervals
+12. Method reload(): reloads protected files
+
+Add proper TypeScript types, error handling, and cleanup on SIGINT/SIGTERM.
+```
+
+**Then tell me:** "Buddy, setup done. Ready for review."
+
+**Let's build this! 🚀**
+
+---
+
+## 📊 TIME COMPARISON
+
+| Task | Manual Coding | With Cursor AI | Savings |
+|------|---------------|----------------|---------|
+| watcher.ts | 4 hours | 30 min | 87% |
+| memory.ts | 3 hours | 20 min | 89% |
+| learning.ts | 2 hours | 15 min | 88% |
+| hooks.ts | 2 hours | 20 min | 83% |
+| cli.ts | 6 hours | 45 min | 88% |
+| Tests | 4 hours | 1 hour | 75% |
+| **Total** | **21 hours** | **3.5 hours** | **83%** |
+
+---
+
+## 🔑 KEY CURSOR AI PROMPTS REFERENCE
+
+### **For Watcher:**
+```
+Create a TypeScript file watcher class using chokidar that loads patterns from .memorylink/protected.txt and blocks changes using minimatch glob matching
+```
+
+### **For Memory:**
+```
+Create a MemoryLink memory manager class that read/writes to .memorylink/memory.log with atomic file operations, filtering by agent/action/tags/date
+```
+
+### **For Learning:**
+```
+Create a MemoryLink learning tracker that records problem|solution|outcome|reason to .memorylink/learnings.log with SUCCESS/FAILED validation
+```
+
+### **For Hooks:**
+```
+Create a Git hooks manager that installs pre-commit hook to verify protected files before commits
+```
+
+### **For CLI:**
+```
+Create a CLI using commander with commands: init, protect, unprotect, watch, log, memory, learn, status, verify, export
+```
+
+---
+
+## ✅ DOCUMENT STATUS
+
+**This document provides:**
+- ✅ Complete Cursor AI workflow
+- ✅ Day-by-day session breakdown
+- ✅ Exact prompts for each component
+- ✅ Shortcuts and best practices
+- ✅ Communication protocol
+- ✅ Time estimates
+
+**Use this document to:**
+- Guide your Cursor AI sessions
+- Reference exact prompts
+- Track progress
+- Report issues
+
+---
+
+**Document Created:** December 12, 2025  
+**Last Updated:** December 12, 2025  
+**Version:** 1.0
+
+---
+
+**Ready to start building with Cursor AI! 🚀**
+