memorylink 2.1.0 → 2.2.0

package/docs/USER_GUIDE.md

@@ -0,0 +1,181 @@
+# MemoryLink User Guide
+
+> **The Active Gatekeeper for AI Agents**
+> Version 1.7.0
+
+---
+
+## What is MemoryLink?
+
+MemoryLink is a **governance layer** for AI coding assistants. It provides:
+
+1. **Memory** - Persistent knowledge that survives across sessions
+2. **Gates** - Security checks that block dangerous code before commit
+
+### Why You Need This
+
+| Problem | Solution |
+|:---|:---|
+| AI forgets fixes after 20 days | `ml capture` stores rules permanently |
+| AI commits API keys accidentally | **Red Gate** blocks secrets |
+| AI writes code with syntax errors | **Blue Gate** blocks broken code |
+| Different AI tools have different rules | `.agent/constitution.md` = single truth |
+
+---
+
+## Installation
+
+```bash
+npm install -g memorylink
+```
+
+## Quick Start
+
+```bash
+cd your-project
+ml init              # Initialize MemoryLink
+ml scan              # Scan for existing secrets
+ml hooks --install   # Install Git hooks (blocks bad commits)
+```
+
+---
+
+## Core Commands
+
+### Memory Commands
+
+```bash
+# Capture a memory
+ml capture -t "api_guidelines" -c "Always use environment variables for API keys"
+
+# Query a memory
+ml query -t "api_guidelines"
+
+# List all memories
+ml list
+ml list --since 7d        # Only recent
+ml list --before 30d      # Only old
+
+# Delete a memory
+ml delete -t "api_guidelines" -f
+ml delete --id "mem_abc123" -f
+```
+
+### Gate Commands
+
+```bash
+# Check for secrets (Red Gate)
+ml gate --rule block-quarantined
+
+# Check for syntax errors (Blue Gate)
+ml gate --rule valid-syntax
+
+# Scan entire project
+ml scan
+```
+
+### Management Commands
+
+```bash
+ml mode active     # Block mode (strict)
+ml mode inactive   # Warn mode (permissive)
+ml self-check      # Verify installation
+ml doctor          # Health check
+```
+
+---
+
+## How Memory Works
+
+**The Recency Rule:** If you have multiple memories for the same topic, the newest one wins.
+
+```bash
+# Day 1
+ml capture -t "framework" -c "Use React Class components"
+
+# Day 30
+ml capture -t "framework" -c "Use React Hooks"
+
+# Query returns "Use React Hooks" (newer)
+ml query -t "framework"
+```
+
+**Update:** Just capture again with the same topic.
+**Delete:** Use `ml delete -t "topic" -f`
+
+---
+
+## How Gates Work
+
+### Red Gate (Secrets)
+- Detects API keys, passwords, private keys
+- Blocks commits with `ml gate --rule block-quarantined`
+- Installed automatically via `ml hooks --install`
+
+### Blue Gate (Syntax)
+- Detects broken code (parse errors)
+- Blocks commits with `ml gate --rule valid-syntax`
+
+---
+
+## Universal Context (.agent/ folder)
+
+Create a `.agent/` folder in your project root:
+
+```
+.agent/
+├── memory/
+│   └── constitution.md    # Project rules (ALL agents read this)
+└── context.md             # Current project context
+```
+
+All AI tools (Cursor, Antigravity, VS Code) will read these files automatically.
+
+---
+
+## Time-Based Memory Management
+
+```bash
+# See memories from last week
+ml list --since 7d
+
+# Clean up old memories (older than 60 days)
+ml delete --before 60d -f
+
+# Delete all memories for old project
+ml delete -t "old_project_name" -f
+```
+
+---
+
+## Troubleshooting
+
+### "No memories found"
+- Run `ml init` first
+- Check that `.memorylink/` folder exists
+
+### "Gate fails but I want to commit anyway"
+- Use `git commit --no-verify` (emergency bypass)
+- Or run `ml mode inactive` to switch to warn-only mode
+
+### "False positive on secret detection"
+- Run `ml gate --mark-false <id>` to whitelist it
+
+---
+
+## Summary
+
+| Command | Purpose |
+|:---|:---|
+| `ml init` | Setup MemoryLink |
+| `ml capture` | Save a memory |
+| `ml query` | Retrieve a memory |
+| `ml list` | Show all memories |
+| `ml delete` | Remove a memory |
+| `ml gate` | Run security checks |
+| `ml scan` | Scan for secrets |
+| `ml mode` | Switch active/inactive |
+
+---
+
+**Built with love for the AI-First Developer.** 🚀

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "memorylink",
-  "version": "2.1.0",
-  "description": "MemoryLink - Prevent secret leaks in AI-assisted development. 120+ patterns including India-specific (Aadhaar, PAN, UPI).",
+  "version": "2.2.0",
+  "description": "MemoryLink - Prevent secret leaks in AI-assisted development. 127 patterns including India-specific (Aadhaar, PAN, UPI).",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -72,4 +72,4 @@
   "engines": {
     "node": ">=18.0.0"
   }
-}
+}

package/docs/COMPARISONS.md

@@ -1,229 +0,0 @@
-# MemoryLink vs Alternatives
-
-A comprehensive comparison of MemoryLink with similar tools and services.
-
-## 🆚 MemoryLink vs GitHub Secret Scanning
-
-### GitHub Secret Scanning
-
-**What it does**:
-- Scans public repositories automatically
-- Detects secrets in commits
-- Alerts repository owners
-- Integrates with GitHub Actions
-
-**Limitations**:
-- ❌ Only works for public repos (or GitHub Advanced Security)
-- ❌ No local/private repo scanning
-- ❌ No memory governance features
-- ❌ No CI/CD blocking (only alerts)
-- ❌ Limited pattern customization
-- ❌ No false positive management
-
-### MemoryLink
-
-**Advantages**:
-- ✅ Works in **any repository** (public, private, local)
-- ✅ **CI/CD blocking** (gates fail builds)
-- ✅ **Memory governance** (E0/E1/E2 grading)
-- ✅ **69+ patterns** (vs GitHub's ~20)
-- ✅ **Dynamic detection** (catches unknown formats)
-- ✅ **False positive tracking**
-- ✅ **Validity checking** (active/inactive secrets)
-- ✅ **Full audit trail**
-- ✅ **Git hooks** (pre-commit, pre-push)
-- ✅ **Completely free and open source**
-
-**Use Case**: MemoryLink is for teams who want **complete control** over secret detection and memory governance, not just alerts.
-
----
-
-## 🆚 MemoryLink vs Mem0
-
-### Mem0
-
-**What it does**:
-- AI memory management system
-- Stores memories in vector database
-- Semantic search over memories
-- API-based service
-
-**Focus**: AI memory storage and retrieval
-
-**Limitations**:
-- ❌ No secret detection
-- ❌ No security governance
-- ❌ Cloud-based (requires API)
-- ❌ No CI/CD integration
-- ❌ No audit trail
-- ❌ No policy gates
-
-### MemoryLink
-
-**Advantages**:
-- ✅ **Repo-native** (no cloud dependency)
-- ✅ **Secret detection** (69+ patterns)
-- ✅ **Security governance** (quarantine, gates)
-- ✅ **CI/CD integration** (blocks bad merges)
-- ✅ **Full audit trail** (tamper-evident)
-- ✅ **Evidence grading** (E0/E1/E2)
-- ✅ **Conflict resolution** (deterministic)
-- ✅ **Git hooks** (automatic protection)
-
-**Use Case**: MemoryLink is for teams who need **both** memory management **and** security governance in one tool.
-
----
-
-## 🆚 MemoryLink vs TruffleHog
-
-### TruffleHog
-
-**What it does**:
-- Secret scanning tool
-- Scans Git history
-- Detects API keys and tokens
-- CI/CD integration
-
-**Focus**: Secret detection only
-
-**Limitations**:
-- ❌ No memory management
-- ❌ No evidence grading
-- ❌ No conflict resolution
-- ❌ Limited to secret detection
-- ❌ No memory governance
-
-### MemoryLink
-
-**Advantages**:
-- ✅ **Memory management** (capture, query, promote)
-- ✅ **Evidence grading** (E0/E1/E2)
-- ✅ **Conflict resolution** (deterministic truth)
-- ✅ **69+ patterns** (comprehensive)
-- ✅ **Dynamic detection** (catches unknown formats)
-- ✅ **Validity checking** (active/inactive)
-- ✅ **Full audit trail**
-- ✅ **Memory governance** (constitution protection, team isolation)
-
-**Use Case**: MemoryLink is for teams who need **both** secret detection **and** AI memory governance.
-
----
-
-## 🆚 MemoryLink vs GitGuardian
-
-### GitGuardian
-
-**What it does**:
-- Secret scanning (SaaS)
-- Git history scanning
-- Real-time detection
-- Incident management
-
-**Focus**: Enterprise secret detection
-
-**Limitations**:
-- ❌ **Paid service** (expensive for small teams)
-- ❌ Cloud-based (requires internet)
-- ❌ No memory management
-- ❌ No local/offline scanning
-- ❌ No memory governance
-
-### MemoryLink
-
-**Advantages**:
-- ✅ **100% free and open source**
-- ✅ **Works offline** (no cloud dependency)
-- ✅ **Memory management** (capture, query, promote)
-- ✅ **Memory governance** (evidence grading, conflict resolution)
-- ✅ **Self-hosted** (complete control)
-- ✅ **No vendor lock-in**
-
-**Use Case**: MemoryLink is for teams who want **enterprise-grade security** without the enterprise price tag.
-
----
-
-## 🆚 MemoryLink vs Gitleaks
-
-### Gitleaks
-
-**What it does**:
-- Secret scanning tool
-- Git history scanning
-- CI/CD integration
-- Pattern-based detection
-
-**Focus**: Open-source secret detection
-
-**Limitations**:
-- ❌ No memory management
-- ❌ No evidence grading
-- ❌ No conflict resolution
-- ❌ Limited to secret detection
-- ❌ No memory governance
-
-### MemoryLink
-
-**Advantages**:
-- ✅ **Memory management** (capture, query, promote)
-- ✅ **Evidence grading** (E0/E1/E2)
-- ✅ **Conflict resolution** (deterministic truth)
-- ✅ **69+ patterns** (comprehensive)
-- ✅ **Dynamic detection** (catches unknown formats)
-- ✅ **Validity checking** (active/inactive)
-- ✅ **Full audit trail**
-- ✅ **Memory governance** (constitution protection, team isolation)
-
-**Use Case**: MemoryLink is for teams who need **both** secret detection **and** AI memory governance.
-
----
-
-## 📊 Feature Comparison Matrix
-
-| Feature | MemoryLink | GitHub Secret Scanning | Mem0 | TruffleHog | GitGuardian | Gitleaks |
-|---------|-----------|------------------------|------|------------|-------------|----------|
-| **Secret Detection** | ✅ 69+ patterns | ✅ ~20 patterns | ❌ | ✅ | ✅ | ✅ |
-| **Memory Management** | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
-| **Evidence Grading** | ✅ E0/E1/E2 | ❌ | ❌ | ❌ | ❌ | ❌ |
-| **CI/CD Blocking** | ✅ | ⚠️ Alerts only | ❌ | ✅ | ✅ | ✅ |
-| **Git Hooks** | ✅ | ❌ | ❌ | ✅ | ❌ | ✅ |
-| **Validity Checking** | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ |
-| **Dynamic Detection** | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| **False Positive Tracking** | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ |
-| **Audit Trail** | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ |
-| **Conflict Resolution** | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| **Memory Governance** | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| **Open Source** | ✅ | ❌ | ⚠️ Partial | ✅ | ❌ | ✅ |
-| **Free** | ✅ | ⚠️ Public repos only | ⚠️ Limited | ✅ | ❌ | ✅ |
-| **Works Offline** | ✅ | ❌ | ❌ | ✅ | ❌ | ✅ |
-
-## 🎯 When to Use MemoryLink
-
-**Choose MemoryLink if you need**:
-- ✅ Both secret detection **and** memory management
-- ✅ Complete control (self-hosted, offline)
-- ✅ Evidence grading and conflict resolution
-- ✅ Memory governance (constitution protection, team isolation)
-- ✅ Free and open source solution
-- ✅ CI/CD blocking (not just alerts)
-- ✅ Comprehensive pattern detection (69+ patterns)
-
-**Choose alternatives if you need**:
-- **GitHub Secret Scanning**: Public repo scanning only, GitHub integration
-- **Mem0**: AI memory storage only (no security)
-- **TruffleHog/Gitleaks**: Secret detection only (no memory management)
-- **GitGuardian**: Enterprise SaaS with incident management
-
-## 🚀 MemoryLink's Unique Value
-
-MemoryLink is the **only tool** that combines:
-1. **Secret Detection** (69+ patterns, dynamic detection)
-2. **Memory Management** (capture, query, promote)
-3. **Memory Governance** (evidence grading, conflict resolution)
-4. **Security Governance** (quarantine, gates, audit trail)
-
-**Result**: One tool for both **AI memory** and **security** governance.
-
----
-
-**Ready to try MemoryLink?** Start with [GETTING_STARTED.md](./GETTING_STARTED.md)
-

package/docs/FAQ.md

@@ -1,230 +0,0 @@
-# Frequently Asked Questions
-
----
-
-## General
-
-### What is MemoryLink?
-MemoryLink is a CLI tool that prevents secret leaks in AI-assisted development. It scans your code for API keys, passwords, and personal data before they can be committed to Git or leaked through AI coding assistants like Cursor, Copilot, or Claude Code.
-
-### Is MemoryLink free?
-Yes, MemoryLink is 100% free and open source (MIT license).
-
-### Does MemoryLink work offline?
-Yes, MemoryLink runs 100% locally. It never sends your code or secrets to any server.
-
-### Does MemoryLink have telemetry?
-No. MemoryLink has zero telemetry. All operations are local-only. You can verify this with `ml doctor --network`.
-
----
-
-## Installation
-
-### What are the requirements?
-- Node.js 18 or higher
-- npm or pnpm
-- Git (for hook integration)
-
-### How do I install MemoryLink?
-```bash
-npm install -g memorylink
-cd your-project
-ml init
-```
-
-### Does it work on Windows?
-Yes, MemoryLink supports Windows, macOS, and Linux. On Windows, we recommend using Git Bash for the best experience.
-
----
-
-## Usage
-
-### What mode should I use?
-- **Inactive (default)**: Warns about secrets but allows commits. Good for learning.
-- **Active**: Blocks commits if secrets are found. Recommended for production.
-
-```bash
-ml mode inactive  # Warn only
-ml mode active    # Block on secrets
-```
-
-### Will it slow down my commits?
-No. Pre-commit hooks only scan staged files (changed files), which typically takes less than 1 second.
-
-### How do I handle false positives?
-Three options:
-1. **Inline ignore**: Add `// ml:ignore` at the end of the line
-2. **File ignore**: `ml ignore add --file path/to/file.js`
-3. **Pattern ignore**: `ml ignore add --pattern "pattern-id"`
-
-### Can I bypass the hooks temporarily?
-Yes, but use with caution:
-```bash
-git commit --no-verify
-git push --no-verify
-```
-
-Or for a single command:
-```bash
-ML_MODE=inactive git push
-```
-
----
-
-## Security
-
-### Where are encryption keys stored?
-Keys are stored in your home directory: `~/.memorylink/keys/`
-
-Each project gets a unique key based on its path hash. Keys are never stored in your project directory.
-
-### What encryption does MemoryLink use?
-AES-256-GCM (Advanced Encryption Standard with 256-bit key, Galois/Counter Mode). This is industry-standard authenticated encryption.
-
-### Are my secrets safe?
-Yes:
-- Secrets are encrypted at rest in quarantine
-- Full secrets are never printed in output (always masked)
-- No data is sent to external servers
-- Keys are stored with 600 permissions (owner-only)
-
-### Can other users access my quarantined secrets?
-No. The encryption key is in your home directory with restricted permissions. Without the key, quarantined data cannot be decrypted.
-
----
-
-## Patterns
-
-### How many patterns does MemoryLink detect?
-112 patterns including:
-- Cloud providers (AWS, Azure, GCP)
-- AI APIs (OpenAI, Claude, HuggingFace)
-- Payment gateways (Stripe, PayPal, Razorpay)
-- Authentication (GitHub, GitLab, Slack, Discord)
-- Personal data (SSN, credit cards, Aadhaar, PAN)
-- Browser leaks (localStorage, cookies, console.log)
-
-### Does it support India-specific patterns?
-Yes! MemoryLink includes patterns for:
-- Aadhaar numbers
-- PAN cards
-- GSTIN
-- UPI IDs
-- IFSC codes
-- Razorpay keys
-- Paytm merchant keys
-
-### Can I add custom patterns?
-Yes, create a `memorylink.config.js` file:
-```javascript
-module.exports = {
-  customPatterns: [
-    {
-      id: 'my-pattern',
-      name: 'My Custom Pattern',
-      pattern: /my-secret-[a-z0-9]+/i,
-      description: 'Custom secret format'
-    }
-  ]
-};
-```
-
----
-
-## CI/CD
-
-### Does it work in CI/CD?
-Yes! MemoryLink auto-detects CI environments and enforces blocking mode automatically.
-
-### Which CI systems are supported?
-- GitHub Actions
-- GitLab CI
-- Jenkins
-- CircleCI
-- Travis CI
-- Buildkite
-- Azure Pipelines
-- TeamCity
-- Bitbucket Pipelines
-- Drone CI
-- Vercel
-- Netlify
-- And more...
-
-### How do I set it up in GitHub Actions?
-```yaml
-- name: Install MemoryLink
-  run: npm install -g memorylink
-
-- name: Security Scan
-  run: ml gate --enforce
-```
-
----
-
-## Comparison
-
-### How is MemoryLink different from Gitleaks?
-| Feature | MemoryLink | Gitleaks |
-|---------|------------|----------|
-| AI-focused | ✅ | ❌ |
-| Easy ignore system | ✅ Interactive | ❌ YAML config |
-| Memory governance | ✅ | ❌ |
-| India patterns | ✅ | ❌ |
-
-### How is MemoryLink different from TruffleHog?
-| Feature | MemoryLink | TruffleHog |
-|---------|------------|------------|
-| Speed | Fast (<1s hooks) | Slower |
-| Memory usage | Low | High (16GB+) |
-| AI memory layer | ✅ | ❌ |
-| Local-first | ✅ | ✅ |
-
-### How is MemoryLink different from Mem0?
-| Feature | MemoryLink | Mem0 |
-|---------|------------|------|
-| Secret scanning | ✅ | ❌ |
-| Zero telemetry | ✅ Provable | ❌ Has telemetry |
-| Local-first | ✅ | ❌ Cloud-hosted |
-| Free | ✅ | Freemium |
-
----
-
-## Troubleshooting
-
-### Where can I get help?
-1. Check [TROUBLESHOOTING.md](./TROUBLESHOOTING.md)
-2. Run `ml self-check` for diagnostics
-3. Open an issue on GitHub
-
-### How do I report a bug?
-1. Run `ml self-check`
-2. Include the output in your bug report
-3. Open an issue at: [GitHub Issues](https://github.com/memorylink/memorylink/issues)
-
----
-
-## Updates
-
-### How do I update MemoryLink?
-```bash
-npm update -g memorylink
-```
-
-### Where can I see the changelog?
-Check [CHANGELOG.md](../CHANGELOG.md) for version history.
-
----
-
-## Contributing
-
-### Can I contribute?
-Yes! MemoryLink is open source. Check [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines.
-
-### How do I suggest a new pattern?
-Open an issue or PR with:
-- Pattern name
-- Regex
-- Example matches
-- Description
-