memorylink 2.1.0 → 2.2.0

package/docs/GETTING_STARTED.md

@@ -1,185 +0,0 @@
-# Getting Started with MemoryLink
-
-Welcome to MemoryLink! This guide will help you get started with MemoryLink in just a few minutes.
-
-## 🚀 Quick Start
-
-### 1. Installation
-
-```bash
-# Install globally
-npm install -g @memorylink/cli
-
-# Or install from source
-git clone https://github.com/your-org/memorylink.git
-cd memorylink
-npm install
-npm run build
-npm link
-```
-
-### 2. Initialize Your Project
-
-```bash
-# Navigate to your project
-cd /path/to/your/project
-
-# Initialize MemoryLink (runs automatic security scan)
-ml init
-```
-
-The `ml init` command will:
-- ✅ Scan your entire project for secrets and personal data
-- ✅ Create `.memorylink/` directory structure
-- ✅ Generate `AGENTS.md` (universal hub for AI tools)
-- ✅ Create tool pointer files (`.cursorrules`, `CLAUDE.md`, etc.)
-- ✅ Install Git hooks (pre-commit, pre-push)
-
-### 3. Your First Memory
-
-```bash
-# Capture a memory (E0 = raw, unverified)
-ml capture --topic "project setup" --content "Use TypeScript strict mode"
-
-# Query memories
-ml query --topic "project setup"
-
-# Promote to E2 (verified) - requires reason
-ml promote --record-id "mem_..." --to E2 --reason "Verified in production"
-```
-
-## 📚 Core Concepts
-
-### Evidence Levels
-
-- **E0** (Raw): Just captured, unverified
-- **E1** (Curated): Reviewed, seems valid
-- **E2** (Verified): Proven true, policy-gated - **ONLY via `ml promote`**
-
-### Memory Status
-
-- **ACTIVE**: Currently in use, eligible for queries
-- **DEPRECATED**: Superseded, excluded from truth queries
-- **QUARANTINED**: Unsafe content detected, never returned in queries
-
-### Commands Overview
-
-| Command | Purpose | Example |
-|---------|---------|---------|
-| `ml init` | First-time setup | `ml init` |
-| `ml capture` | Capture memory (E0/E1) | `ml capture -t "topic" -c "content"` |
-| `ml query` | Query memories | `ml query -t "topic"` |
-| `ml promote` | Promote to E2 | `ml promote -r "mem_..." --to E2 --reason "..."` |
-| `ml gate` | Policy gate check | `ml gate -r block-quarantined` |
-| `ml audit` | View audit trail | `ml audit --view timeline` |
-| `ml scan` | Scan for secrets | `ml scan` |
-
-## 🔒 Security Features
-
-### Automatic Secret Detection
-
-MemoryLink automatically detects and quarantines:
-- API keys (OpenAI, AWS, GitHub, etc.)
-- Passwords and tokens
-- Personal data (SSN, credit cards, etc.)
-- Browser data leaks (localStorage, console.log)
-- Debug code with secrets
-
-### Policy Gates
-
-```bash
-# Check for quarantined content (blocks CI/CD if found)
-ml gate --rule block-quarantined
-
-# Check only changed files
-ml gate --rule block-quarantined --diff
-
-# Check commit history
-ml gate --rule block-quarantined --history
-
-# Check validity (active/inactive secrets)
-ml gate --rule block-quarantined --check-validity
-```
-
-### Git Hooks
-
-MemoryLink automatically installs Git hooks:
-- **pre-commit**: Scans changed files before commit
-- **pre-push**: Full repository scan before push
-
-## 🎯 Common Workflows
-
-### Workflow 1: First-Time Setup
-
-```bash
-# 1. Initialize
-ml init
-
-# 2. Review scan results
-# Fix any secrets found
-
-# 3. Start capturing memories
-ml capture --topic "architecture" --content "Use microservices pattern"
-```
-
-### Workflow 2: Daily Development
-
-```bash
-# Capture learnings
-ml capture --topic "bug fix" --content "Fixed memory leak in cache"
-
-# Query for context
-ml query --topic "bug fix"
-
-# Promote verified knowledge
-ml promote --record-id "mem_..." --to E2 --reason "Tested in production"
-```
-
-### Workflow 3: CI/CD Integration
-
-```yaml
-# .github/workflows/gate.yml
-- name: MemoryLink Gate
-  run: ml gate --rule block-quarantined
-```
-
-## 📖 Next Steps
-
-- Read [PATTERNS.md](./PATTERNS.md) - All 69+ detection patterns
-- Read [REMEDIATION.md](./REMEDIATION.md) - How to fix detected secrets
-- Read [COMPARISONS.md](./COMPARISONS.md) - MemoryLink vs alternatives
-
-## ❓ Troubleshooting
-
-### Issue: "Not a Git repository"
-
-**Solution**: Initialize Git first:
-```bash
-git init
-ml init
-```
-
-### Issue: "Secret detected" during capture
-
-**Solution**: Remove the secret from your content, or use `--approve` if it's intentional:
-```bash
-ml capture --topic "..." --content "..." --approve
-```
-
-### Issue: Gate fails in CI/CD
-
-**Solution**: Check for quarantined content:
-```bash
-ml gate --rule block-quarantined --json
-```
-
-## 🆘 Need Help?
-
-- Check the [README.md](../README.md) for full documentation
-- Review [PATTERNS.md](./PATTERNS.md) for all detection patterns
-- See [REMEDIATION.md](./REMEDIATION.md) for fixing issues
-
----
-
-**Ready to go?** Run `ml init` in your project to get started! 🚀
-

package/docs/PATTERNS.md

@@ -1,206 +0,0 @@
-# MemoryLink Detection Patterns
-
-MemoryLink detects **69+ patterns** across multiple categories to protect your codebase from secrets, personal data, and security risks.
-
-## 📊 Pattern Statistics
-
-- **Total Patterns**: 69+
-- **Blocking (ERROR)**: 55+ patterns
-- **Warning (WARN)**: 14+ patterns (browser/debug leaks)
-
-## 🔐 API Keys & Tokens (28 patterns)
-
-### Cloud Providers
-- **OpenAI/Anthropic API Key** (`sk-...`)
-- **Claude AI API Key** (`sk-ant-...`)
-- **AWS Access Key** (`AKIA...`)
-- **AWS Secret Key**
-- **Google API Key** (`AIza...`)
-- **Azure Key**
-- **GCP Service Account JSON**
-
-### Developer Tools
-- **GitHub Token** (`ghp_...`)
-- **GitHub OAuth Token** (`gho_...`)
-- **Slack Token** (`xoxb-...`)
-- **Slack Webhook URL**
-- **Discord Token**
-- **JWT Token** (`eyJ...`)
-
-### Payment & E-commerce
-- **Stripe API Key** (`sk_live_...`, `sk_test_...`)
-- **PayPal Client Secret**
-- **Square Access Token**
-- **Shopify API Key** (`shpat_...`)
-
-### Communication & Services
-- **Twilio API Key**
-- **SendGrid API Key** (`SG....`)
-- **Mailgun API Key** (`key-...`)
-- **Heroku API Key** (UUID format)
-
-### Generic Patterns
-- **Generic API Key** (`api_key=...`)
-- **Key-Value Secret** (catches ANY key name with secret-like value)
-- **Token** (authentication tokens)
-- **Private Key** (RSA, etc.)
-
-## 💳 Personal Data (PII) (12 patterns)
-
-### Financial
-- **Credit Card Number** (Visa, Mastercard, Amex, Discover)
-- **CVV/CVC Code**
-- **Bank Account Number**
-- **IBAN** (International Bank Account Number)
-- **UPI ID** (India)
-
-### Government IDs
-- **SSN** (US Social Security Number)
-- **SIN** (Canadian Social Insurance Number)
-- **PAN Card** (India)
-- **Aadhaar Number** (India)
-- **Driver License**
-- **Passport Number**
-
-### Contact Information
-- **Email Address**
-- **Phone Number**
-- **Email + Password** (credential leak)
-
-## 🌐 Browser Data Leaks (6 patterns - WARN)
-
-These patterns detect secrets that could leak through browser storage or console:
-
-- **localStorage.setItem with token**
-- **sessionStorage.setItem with token**
-- **console.log with Authorization header**
-- **URL parameter ?token=**
-- **URL parameter ?key=**
-- **URL parameter ?auth=**
-
-**Severity**: WARN (warning only, doesn't block)
-
-## 🐛 Debug Code Leaks (8 patterns - WARN)
-
-These patterns catch temporary debug code that could leak secrets:
-
-- **console.log with sensitive data**
-- **Logger with request/response data**
-- **print/echo with secret**
-- **TODO comment with secret**
-- **Stack trace in production code**
-- **Verbose error with sensitive data**
-- **Temporary logging**
-- **Development-only code**
-
-**Severity**: WARN (warning only, doesn't block)
-
-## 🔧 Infrastructure & DevOps (15 patterns)
-
-### CI/CD
-- **GitHub Actions Secret** (`${{ secrets.XXX }}`)
-- **GitLab CI Secret**
-- **Jenkins Credential**
-- **CircleCI Secret**
-- **CI Secret Dump** (printenv, env commands)
-
-### Containers & Orchestration
-- **Docker Registry Credentials**
-- **Docker Compose Secret**
-- **Kubernetes Secret**
-- **Helm Chart Secret**
-
-### Cloud Storage
-- **S3 Public Bucket**
-- **Azure Public Blob**
-- **GCP Public Bucket**
-- **Cloud Storage Credential**
-
-### Infrastructure as Code
-- **Terraform Secret**
-- **Redis Credentials**
-
-### Other Services
-- **SMTP Credentials**
-- **VPN Credentials**
-- **OAuth Client Secret**
-
-## 🛡️ Memory Poisoning Protection (8 patterns)
-
-These patterns detect instruction-injection attacks (OWASP ASI06):
-
-- **Ignore Previous Rules**
-- **Ignore Security**
-- **Always Log Secrets**
-- **Exfiltrate Data**
-- **Bypass Security**
-- **Disable Checks**
-- **Skip Validation**
-- **Override Security**
-
-## 📝 Log File Patterns (4 patterns)
-
-- **Error Log with Secret**
-- **Access Log with Secret**
-- **Debug Log with Secret**
-- **Stack Trace with Secret**
-
-## 🔍 Dynamic Detection
-
-MemoryLink also includes **dynamic detection** that catches secrets even if they don't match predefined patterns:
-
-- **Key-Value Detection**: Catches any key name with secret-like values
-- **Standalone Secret Detection**: Detects secrets without key names
-- **High-Entropy Detection**: Identifies random-looking strings
-- **Format Detection**: Base64, Hex, UUID patterns
-
-## ⚙️ Pattern Configuration
-
-You can customize patterns in `.memorylink/config.json`:
-
-```json
-{
-  "patterns": {
-    "disabled": ["email"],  // Disable specific patterns
-    "custom": [             // Add custom patterns
-      {
-        "id": "my-custom-pattern",
-        "name": "My Custom Pattern",
-        "pattern": "YOUR_REGEX_HERE",
-        "description": "Custom pattern description"
-      }
-    ]
-  }
-}
-```
-
-## 📊 Pattern Categories Summary
-
-| Category | Count | Severity |
-|----------|-------|----------|
-| API Keys & Tokens | 28 | ERROR |
-| Personal Data (PII) | 12 | ERROR |
-| Browser Leaks | 6 | WARN |
-| Debug Leaks | 8 | WARN |
-| Infrastructure | 15 | ERROR |
-| Memory Poisoning | 8 | ERROR |
-| Log Files | 4 | ERROR |
-| **Total** | **69+** | - |
-
-## 🎯 Best Practices
-
-1. **Review WARN patterns**: Browser and debug patterns are warnings - review them but don't block on them
-2. **Customize patterns**: Disable patterns that cause false positives in your codebase
-3. **Use whitelist**: Add test keys to whitelist in `.memorylink/config.json`
-4. **Regular scans**: Run `ml scan` regularly to catch new secrets
-
-## 📖 Related Documentation
-
-- [GETTING_STARTED.md](./GETTING_STARTED.md) - Quick start guide
-- [REMEDIATION.md](./REMEDIATION.md) - How to fix detected secrets
-- [README.md](../README.md) - Full documentation
-
----
-
-**Last Updated**: Based on MemoryLink v1.0.0
-

package/docs/QUICK_REFERENCE.md

@@ -1,209 +0,0 @@
-# MemoryLink Quick Reference
-
-## 5-Minute Setup
-```bash
-npm install -g memorylink
-cd your-project
-ml init
-# Done! Hooks installed, scanning active.
-```
-
----
-
-## Essential Commands
-
-| Command | What It Does |
-|---------|--------------|
-| `ml init` | Setup project + Git hooks |
-| `ml scan` | Scan project for secrets |
-| `ml gate` | Check before commit/push |
-| `ml mode` | View/change security mode |
-| `ml audit` | View security history |
-
----
-
-## Mode Switching
-
-```bash
-# View current mode
-ml mode
-
-# Set mode permanently
-ml mode active      # Block on secrets
-ml mode inactive    # Warn only (default)
-
-# One-time override
-ML_MODE=active git push     # Block this push
-ML_MODE=inactive git push   # Allow this push
-```
-
----
-
-## Scanning
-
-```bash
-# Scan entire project
-ml scan
-
-# Scan specific file
-ml scan path/to/file.js
-
-# Scan with details
-ml scan --verbose
-
-# Scan only changed files
-ml gate --diff
-```
-
----
-
-## Handling False Positives
-
-```javascript
-// Option 1: Inline ignore
-const testKey = "AKIAEXAMPLE"; // ml:ignore
-
-// Option 2: Block ignore
-// ml:ignore-start
-const testData = {...};
-// ml:ignore-end
-```
-
-```bash
-# Option 3: Command line
-ml ignore add --file path/to/file.js
-ml ignore add --pattern "api-key-2"
-```
-
----
-
-## Git Hooks
-
-```bash
-# Install hooks
-ml hooks install
-
-# Uninstall hooks
-ml hooks uninstall
-
-# Bypass temporarily (use with caution!)
-git commit --no-verify
-git push --no-verify
-```
-
----
-
-## CI/CD Integration
-
-```yaml
-# GitHub Actions
-- run: npm install -g memorylink
-- run: ml gate --enforce
-
-# Or with environment variable
-- run: ML_MODE=active ml gate
-```
-
----
-
-## Memory Commands
-
-```bash
-# Store memory
-ml capture --topic "config" "Use React 18"
-
-# Query memories
-ml query --topic "config"
-
-# Promote evidence grade
-ml promote <memory-id> --to E2
-```
-
----
-
-## Audit & History
-
-```bash
-# View audit log
-ml audit
-
-# Scan git history
-ml gate --history
-
-# View quarantined items
-ml release --list
-```
-
----
-
-## Diagnostics
-
-```bash
-# Self-check
-ml self-check
-
-# View version
-ml --version
-
-# Debug mode
-DEBUG=memorylink ml scan
-```
-
----
-
-## Configuration
-
-```json
-// .memorylink/config.json
-{
-  "block_mode": false,
-  "scan": {
-    "exclude": ["dist/**", "*.min.js"]
-  }
-}
-```
-
----
-
-## Exit Codes
-
-| Code | Meaning |
-|------|---------|
-| 0 | Success / No issues |
-| 1 | Secrets found (active mode) |
-| 2 | Configuration error |
-
----
-
-## Environment Variables
-
-| Variable | Purpose |
-|----------|---------|
-| `ML_MODE` | Override mode (active/inactive) |
-| `CI` | Auto-detected, forces active mode |
-| `DEBUG` | Enable debug output |
-
----
-
-## Quick Troubleshooting
-
-| Problem | Quick Fix |
-|---------|-----------|
-| Command not found | `npx memorylink` |
-| Hooks not running | `ml hooks install` |
-| False positive | `// ml:ignore` |
-| Database locked | `rm .memorylink/*.lock` |
-| Slow scans | Add excludes to config |
-
----
-
-## Getting Help
-
-```bash
-ml --help           # All commands
-ml scan --help      # Command help
-ml self-check       # Diagnostics
-```
-
-**Docs:** [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) | [FAQ.md](./FAQ.md)
-