memorylink 2.1.1 → 2.2.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
-

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! 🚀
-