memorylink 1.0.0

package/README.md

@@ -0,0 +1,557 @@
+# 🧠 MemoryLink
+
+**Git-native memory + safety layer for AI coding assistants**
+
+Multi-agent coordination • Safe rollbacks • Context sharing • Safety checks
+
+---
+
+## Why MemoryLink Exists
+
+Modern teams use AI tools and agents everywhere: Cursor, Claude, Copilot, CI bots, and in-house automation. These tools are fast, but they also create new risks that traditional CI and reviews often catch too late.
+
+**MemoryLink exists to keep AI and agents from silently damaging your codebase or leaking secrets while you move fast**, no matter which tools you use.
+
+---
+
+## What Problems MemoryLink Solves
+
+- **AI tools can break critical code**: Cursor, Claude, Copilot, and other AI assistants can break auth, change critical logic, or introduce insecure patterns that only show up in production or late security scans.
+- **Multiple agents conflict**: IDE AI, Claude, Copilot, CI bots, and custom agents can touch the same files and silently overwrite each other or create race conditions in one repo.
+- **Secrets leak into code**: AI or rushed developers can accidentally paste cloud keys, API tokens, or passwords into source files that later get pushed to GitHub.
+
+**The core problem:** Traditional CI, tests, and code review are too late in the flow to catch many AI mistakes while developers move fast.
+
+---
+
+## How MemoryLink Helps
+
+MemoryLink adds a thin safety and coordination layer around **any AI, IDE, or agent**:
+
+- **Protect sensitive areas**  
+  Mark files and directories like `.env`, `src/auth/`, or database migrations as protected so changes there get special attention from Buddy-Check.
+
+- **Coordinate all agents**  
+  Use locks so only one "agent" (Cursor, Claude, IDE AI, CI job, custom bot) can hold a file or scope at a time, preventing silent overwrites and race conditions.
+
+- **Create safe checkpoints**  
+  Take checkpoints before large AI changes, then view diffs and run doctor after, so you see exactly what changed and can roll back quickly.
+
+**Simple rule for any workflow:**
+
+> **Whatever AI or agent you use, wrap its work with:**  
+> `lock → checkpoint → doctor → diff → release`.
+
+---
+
+## What is MemoryLink?
+
+MemoryLink is a **local-first, Git-native CLI tool** that provides shared memory and safety checks for AI coding assistants. It helps teams coordinate multiple AI agents, maintain project context, and catch dangerous changes before they cause problems.
+
+**Key principles:**
+- **Local-first**: All data stored in `.memorylink/` directory
+- **Git-native**: Works with your existing Git workflow
+- **CLI-focused**: Simple commands for daily use
+- **Safety framework**: Buddy-Check system for preflight/postflight validation
+
+**What it's NOT:**
+- Not a universal firewall or 100% detection system
+- Not a replacement for code review or security scanning tools
+- Not a cloud service (everything is local)
+
+---
+
+## Who is it for?
+
+MemoryLink is designed for:
+
+- **JS/TS developers** using **Cursor AI**, **VS Code**, or **GitHub Actions**
+- Teams working with **Git repositories** and **AI coding assistants**
+- Developers who need **multi-agent coordination** and **safety checks**
+
+**Requirements:**
+- Node.js 18+ (for native `fetch` support)
+- Git repository
+- CLI access
+
+---
+
+## What it does today (v1.0.0)
+
+### ✅ Fully Functional Features
+
+- **Multi-agent locking**: 100% functional - Prevents concurrent agent access to same files
+- **Checkpoints**: Create, list, diff, and restore memory snapshots
+- **Buddy-Check framework**: Preflight/postflight safety checks with GREEN/YELLOW/RED status
+- **Memory system**: Store and retrieve project context with scopes and weighted filtering
+- **Stats & observability**: Track Buddy-Check runs, metrics, and recommendations
+- **Basic secret detection**: Scans for API keys, tokens, passwords in memory logs
+- **Protected file tracking**: List-based checking for critical files
+
+### ⚠️ Framework Ready (v1.6)
+
+These features have the framework in place but need enhancements for full detection:
+
+- **Full secret/PII detection**: Basic patterns exist, enhanced patterns needed
+- **Protected file detection**: List configured, Git diff analysis needed
+- **File deletion detection**: Framework ready, Git diff needed
+- **Stale memory detection**: Context retrieval works, code analysis needed
+
+---
+
+## What it does NOT promise
+
+**Important limitations:**
+
+- ⚠️ **Not 100% detection**: No tool achieves 100% detection. MemoryLink uses RED status and exit codes to block clearly dangerous changes where rules apply.
+- ⚠️ **Not a universal firewall**: Focused on AI agent safety, not all security threats. Use alongside dedicated security tools.
+- ⚠️ **Framework vs. full detection**: Some detection is "framework ready" and will be strengthened in v1.6 (Git-diff integration, enhanced patterns).
+- ⚠️ **Local-only locking**: Locks are file-based, not distributed. Multiple machines can't coordinate locks (use Git-based coordination for distributed teams).
+
+**What you should do:**
+- Use MemoryLink **in combination with** code review, CI/CD, and security scanning tools
+- Configure protected files appropriately
+- Run Buddy-Check in CI/CD pipelines
+- Monitor stats regularly
+
+---
+
+## Quickstart
+
+### First 5 Minutes with MemoryLink
+
+Get MemoryLink working in your project in 5 minutes:
+
+**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.
+
+---
+
+### Daily Workflow (With Any AI or Agent)
+
+Use the same pattern whether changes come from Cursor, Claude, Copilot, CI, or your own bots.
+
+**Before AI / agent changes:**
+```bash
+memorylink lock acquire --agent "cursor" --files "src/"
+memorylink checkpoint create --name "before-feature-x"
+memorylink doctor --preflight
+```
+
+**Let your AI / agent do its work here** (Cursor, Claude, Copilot, CI, custom bot, etc.)
+
+**After changes:**
+```bash
+memorylink doctor --postflight
+memorylink checkpoint diff --name "before-feature-x"
+memorylink lock release
+```
+
+**How this helps:**
+- **Lock**: Prevents other agents or tools from editing the same scope at the same time
+- **Checkpoint**: Creates a safe restore point before large AI changes
+- **Doctor**: Scans for risky patterns and changes in protected areas
+- **Diff**: Shows exactly what your AI or agent changed so you can accept, fix, or roll back
+
+### CI/CD Integration
+
+Add to your GitHub Actions workflow:
+
+```yaml
+- name: Run Buddy-Check
+  run: |
+    memorylink doctor --preflight --json > preflight.json
+    # Fail on RED status
+    if grep -q '"status": "RED"' preflight.json; then
+      exit 1
+    fi
+```
+
+See `GETTING_STARTED.md` for detailed setup instructions.
+
+---
+
+## Example Scenarios
+
+These are common situations where MemoryLink protects you.
+
+### Scenario 1: AI Refactor Breaks Auth
+
+**Problem (without MemoryLink):**  
+An AI assistant (Cursor, Claude, Copilot, etc.) "cleans up" `src/auth/` and accidentally removes a critical permission check. The issue is only noticed after users hit production.
+
+**With MemoryLink:**
+
+```bash
+# Mark auth as sensitive once
+memorylink protect src/auth/
+
+# Before asking any AI to refactor auth
+memorylink lock acquire --agent "cursor" --files "src/auth/"
+memorylink checkpoint create --name "before-auth-refactor"
+memorylink doctor --preflight
+
+# Let your AI refactor auth...
+
+# After AI changes
+memorylink doctor --postflight
+memorylink checkpoint diff --name "before-auth-refactor"
+memorylink lock release
+```
+
+**What this does:**  
+MemoryLink treats `src/auth/` as high-risk, lets you see exactly what changed, and gives you a clear, local chance to catch problems before they ever reach production.
+
+**Without MemoryLink:** You discover this in production. **With MemoryLink:** You get an early, local warning.
+
+---
+
+### Scenario 2: Cloud API Key Leak (The $55k Bill Story)
+
+**Problem (without MemoryLink):**  
+A developer (student or professional) accidentally commits a cloud API key to GitHub in `config.ts`. Automated scanners find it within minutes, abuse the key with thousands of requests, and the developer wakes up to a shocking bill—sometimes tens of thousands of dollars.
+
+**Real example:** A CS student accidentally committed a Gemini API key, bots found it, made over 14,000 unauthorized requests, and generated a $55,000 cloud bill before the provider waived it after public pressure.
+
+**With MemoryLink:**
+
+```bash
+# Protect config files
+memorylink protect .env
+memorylink protect config/
+
+# After coding or AI changes
+memorylink doctor --postflight
+```
+
+**What this does:**  
+- Doctor flags secret-like patterns in tracked files (keys, tokens, credentials) before `git add` / `git push`
+- Gives you a local warning like: "Possible secret found in src/config.ts – are you sure this should be committed?"
+- If a key moves from `.env` into a tracked source file, postflight checks treat that as high-risk and surface it clearly
+
+**Without MemoryLink:** Key gets committed, bots find it, massive bill arrives. **With MemoryLink:** You get an early, local warning before the key ever leaves your machine.
+
+**Note:** MemoryLink is not a billing firewall, but it helps you catch obvious leaked keys locally before bots on GitHub do.
+
+---
+
+### Scenario 3: Secret Accidentally Added to Code
+
+**Problem (without MemoryLink):**  
+A cloud key or token gets pasted into `config.ts` or another source file and is later pushed to GitHub or shared in a bundle.
+
+**With MemoryLink:**
+
+```bash
+# After some AI / manual edits
+memorylink doctor --postflight
+```
+
+**What this does:**  
+If a secret-like pattern appears in tracked files, MemoryLink warns during the postflight doctor step so you delete the secret and rotate it before it leaves your machine.
+
+**Without MemoryLink:** Secret gets committed and exposed. **With MemoryLink:** You get a warning before commit.
+
+---
+
+### Scenario 4: Two Agents Fighting Over One File
+
+**Problem (without MemoryLink):**  
+An IDE AI and a CI bot both modify `src/api.ts`. One set of changes silently overwrites the other, and nobody notices until much later.
+
+**With MemoryLink:**
+
+```bash
+# Agent 1 (e.g., IDE AI)
+memorylink lock acquire --agent "ide-ai" --files "src/api.ts"
+# ... edits happen ...
+memorylink lock release
+
+# Agent 2 (e.g., CI or another bot)
+memorylink lock acquire --agent "ci-bot" --files "src/api.ts"
+# If Agent 1 still holds the lock, this call fails with a clear lock error.
+```
+
+**What this does:**  
+Locks ensure only one agent owns a file at a time. Instead of silent overwrites, the second agent receives a clear "locked" signal and you decide the correct order of operations.
+
+**Without MemoryLink:** Silent overwrite, discovered later. **With MemoryLink:** Second agent is blocked with a clear message.
+
+---
+
+## Core Features
+
+### Multi-Agent Locking
+
+Prevent conflicts when multiple AI agents work on the same codebase:
+
+```bash
+memorylink lock acquire --agent "cursor" --files "src/api.ts"
+# Other agents will be blocked until lock is released
+memorylink lock release
+```
+
+**Status**: ✅ 100% functional in v1.0.0
+
+### Checkpoints
+
+Create memory snapshots for safe rollback:
+
+```bash
+memorylink checkpoint create --name "before-refactor"
+# ... make changes ...
+memorylink checkpoint diff "before-refactor" "current"
+memorylink checkpoint restore "before-refactor"
+```
+
+**Status**: ✅ Functional in v1.0.0
+
+### Buddy-Check Safety Framework
+
+Preflight/postflight safety checks:
+
+```bash
+memorylink doctor --preflight   # Before AI operations
+memorylink doctor --postflight  # After AI operations
+```
+
+Returns GREEN (safe), YELLOW (warnings), or RED (block) status.
+
+**Status**: ✅ Framework ready in v1.0.0 (full detection in v1.6)
+
+### Memory & Context
+
+Store and retrieve project context using internal heuristics to rank and filter relevant memories:
+
+```bash
+memorylink memory "Uses React 18 with TypeScript" --tags frontend
+memorylink get-context --smart --task "work on authentication"
+```
+
+**Status**: ✅ Functional in v1.0.0
+
+*Note: The internal ranking and filtering algorithms are proprietary and may evolve.*
+
+### Stats & Observability
+
+Track Buddy-Check metrics:
+
+```bash
+memorylink stats
+memorylink stats --since 7d --format json
+```
+
+**Status**: ✅ Functional in v1.0.0
+
+---
+
+## 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.
+
+---
+
+## Documentation
+
+- **`USER_GUIDE.md`**: How to use MemoryLink in daily workflow and handle common problems
+- **`GETTING_STARTED.md`**: Step-by-step setup for JS/TS + Cursor + GitHub Actions
+- **`FEATURES.md`**: Detailed explanation of all features
+- **`SECURITY_MODEL.md`**: What safety features do/don't do, limits, how to use safely
+- **`ROADMAP_v1.6.md`**: What's coming next (Git diff, enhanced patterns, contradiction checks)
+- **`RELEASE_NOTES_v1.0.0.md`**: What's in this version
+
+---
+
+## Installation
+
+### Requirements
+
+- **Node.js**: 18.0.0 or higher (for native `fetch` support)
+- **Git**: Required for hooks and team sharing
+- **npm**: For installation
+
+### Install
+
+```bash
+npm install -g memorylink
+```
+
+### Verify Installation
+
+```bash
+memorylink --version
+# Should output: 1.0.0
+```
+
+### Initialize in Project
+
+```bash
+cd your-project
+memorylink init
+```
+
+This creates `.memorylink/` directory with configuration files.
+
+---
+
+## Support & Community
+
+- **GitHub**: [mspworld/memorylink](https://github.com/mspworld/memorylink)
+- **Issues**: [Report bugs or request features](https://github.com/mspworld/memorylink/issues)
+- **Documentation**: See docs in this repository
+
+---
+
+## 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
+
+```bash
+# Team commits selected .memorylink/ files
+git add .memorylink/memory.log .memorylink/rules.md
+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
+
+#### 2. Local Private Memory
+
+**Best for:** Sensitive logs, noisy runtime data, personal notes
+
+```bash
+# .gitignore already excludes these by default
+.memorylink/*.log
+.memorylink/telemetry.log
+.memorylink/observability.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
+
+### 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
+
+---
+
+## License
+
+MemoryLink uses the **MemoryLink Community License** (source-available, restricted commercial use).
+
+**What this means:**
+- ✅ **Source-available**: You can read and modify the code
+- ✅ **Free for personal and internal use**: Use MemoryLink freely for personal projects and internal company use
+- ❌ **Commercial restrictions**: Running a competing hosted SaaS or selling MemoryLink as a product requires a commercial agreement
+- ❌ **No white-labeling**: Removing branding and reselling as your own product is not permitted
+
+**Full license terms:** See [`LICENSE`](LICENSE) file for complete details.
+
+**Commercial licensing:** For commercial use that falls under restrictions, contact MemoryLink to discuss a commercial license agreement.
+
+---
+
+**MemoryLink v1.0.0** - Ready for production use with JS/TS + Cursor/VS Code + GitHub Actions

package/README_TEST_INSTRUCTIONS.md

@@ -0,0 +1,65 @@
+# MemoryLink v1.5.1 - Test Instructions
+
+**For**: Cursor AI and other AI assistants  
+**Purpose**: Hostile testing to find real weaknesses
+
+---
+
+## 🎯 Quick Start
+
+1. **Open Cursor AI** in a test repository with MemoryLink installed
+2. **Paste the entire content** of `CURSOR_HOSTILE_TEST_DOCUMENT.md` into Cursor
+3. **Follow the instructions** step by step
+4. **Document results** using the evaluation questions
+
+---
+
+## 📋 Test Document
+
+**File**: `CURSOR_HOSTILE_TEST_DOCUMENT.md`
+
+**Contains**:
+- 4 comprehensive test scenarios
+- Step-by-step instructions
+- Evaluation questions
+- Quick reference commands
+
+---
+
+## 🧪 Test Scenarios
+
+1. **Multi-Agent Auto-Switch**: Tests lock system and drift detection
+2. **Prompt-Injection**: Tests secret/PII detection under malicious instructions
+3. **Protected Files + Injection**: Tests protected file detection
+4. **Stale Memory + Auto-Switch**: Tests memory drift detection
+
+---
+
+## 📊 What to Document
+
+After testing, document:
+- What was detected
+- What was missed
+- Gaps found
+- Priority of gaps
+- Recommendations for v1.6
+
+---
+
+## ✅ Expected Outcomes
+
+**Good Results**:
+- Buddy-Check detects dangerous changes
+- Lock system prevents conflicts
+- Protected files are protected
+- Secrets/PII are flagged
+
+**Gaps Found**:
+- Document for v1.6
+- Create new rules/tests
+- Update roadmap
+
+---
+
+**Status**: Ready for Hostile Testing
+