superlocalmemory 2.3.0

package/docs/CLI-COMMANDS-REFERENCE.md

@@ -0,0 +1,425 @@
+# SuperLocalMemory V2 - CLI Commands Reference
+
+**Quick reference for all CLI commands**
+
+**Version 2.3.0-universal** - Universal integration across 16+ IDEs and CLI tools
+
+SuperLocalMemory V2 offers three access methods:
+1. **Universal CLI** - Simple `slm` commands (NEW in v2.1.0)
+2. **Original CLI** - Full `superlocalmemoryv2:*` commands
+3. **MCP/Skills** - IDE-specific integration (auto-configured)
+
+All methods use the same local SQLite database.
+
+---
+
+## 🎯 Universal CLI Commands (NEW)
+
+**Simple syntax for everyday use:**
+
+### Memory Operations
+
+```bash
+# Save memory
+slm remember "content" --tags tag1,tag2
+
+# Search memories
+slm recall "query"
+
+# List recent memories
+slm list
+
+# System status
+slm status
+
+# Get project context
+slm context
+```
+
+### Profile Management
+
+```bash
+# List profiles
+slm profile list
+
+# Create profile
+slm profile create work --description "Work projects"
+
+# Switch profile
+slm profile switch work
+
+# Delete profile
+slm profile delete old-project
+
+# Show current profile
+slm profile current
+```
+
+### Knowledge Graph
+
+```bash
+# Build graph
+slm graph build
+
+# View statistics
+slm graph stats
+
+# Find related memories
+slm graph related --id 5
+
+# View cluster
+slm graph cluster --id 1
+```
+
+### Pattern Learning
+
+```bash
+# Update patterns
+slm patterns update
+
+# List patterns
+slm patterns list 0.5
+
+# Get coding identity
+slm patterns context 0.7
+
+# Pattern statistics
+slm patterns stats
+```
+
+### Aider Integration
+
+```bash
+# Launch Aider with auto-context injection
+aider-smart "Add authentication to the API"
+
+# Regular Aider works too
+aider
+```
+
+---
+
+## 📊 Original CLI Commands (Still Supported)
+
+All original commands continue to work unchanged. Use these if you prefer explicit paths or are scripting.
+
+### Check System Status
+```bash
+superlocalmemoryv2:status
+# OR
+~/.claude-memory/bin/superlocalmemoryv2:status
+```
+Shows: total memories, graph stats, clusters, patterns, database size
+
+---
+
+## 👤 Profile Management (Original Commands)
+
+**Default profile is always available.** Use profiles to maintain separate memory contexts for different projects, clients, or AI personalities.
+
+### List All Profiles
+```bash
+superlocalmemoryv2:profile list
+# OR
+~/.claude-memory/bin/superlocalmemoryv2:profile list
+```
+Shows all profiles with active marker (→)
+
+### Show Current Active Profile
+```bash
+superlocalmemoryv2:profile current
+# OR
+~/.claude-memory/bin/superlocalmemoryv2:profile current
+```
+Shows current profile details and memory count
+
+### Create New Profile
+```bash
+# Empty profile
+superlocalmemoryv2:profile create work --description "Work projects"
+
+# Copy from current profile
+superlocalmemoryv2:profile create personal --from-current
+```
+
+### Switch Profile
+```bash
+superlocalmemoryv2:profile switch work
+```
+**⚠️ Restart your IDE after switching if using MCP integration.**
+
+### Delete Profile
+```bash
+superlocalmemoryv2:profile delete old-project
+```
+- Cannot delete "default" profile
+- Cannot delete currently active profile
+- Creates backup before deletion
+- Requires typing profile name to confirm
+
+---
+
+## 🔄 Reset Commands (Destructive - Use with Caution)
+
+### Check Status First
+```bash
+slm status
+# OR
+superlocalmemoryv2:status
+```
+**Always check status before any reset operation!**
+
+### Soft Reset
+```bash
+superlocalmemoryv2:reset soft
+# OR
+~/.claude-memory/bin/superlocalmemoryv2:reset soft
+```
+- Clears all memories from current profile
+- Clears graph, patterns, tree structure
+- Keeps V2 schema intact
+- Creates automatic backup
+- Prompt: "Proceed with soft reset? (yes/no)"
+
+### Hard Reset
+```bash
+superlocalmemoryv2:reset hard --confirm
+# OR
+~/.claude-memory/bin/superlocalmemoryv2:reset hard --confirm
+```
+- ⚠️ **NUCLEAR OPTION** ⚠️
+- Deletes entire database file
+- Reinitializes fresh V2 schema
+- Creates automatic backup
+- Prompt: Type "DELETE EVERYTHING" to confirm
+
+### Layer Reset (Surgical)
+```bash
+superlocalmemoryv2:reset layer --layers graph patterns
+# OR
+~/.claude-memory/bin/superlocalmemoryv2:reset layer --layers graph patterns
+```
+Available layers:
+- `graph` - Clear graph nodes, edges, clusters
+- `patterns` - Clear learned identity patterns
+- `tree` - Clear hierarchical tree structure
+- `archive` - Clear compressed memory archives
+
+Prompt: "Proceed with layer reset? (yes/no)"
+
+---
+
+## 🔍 Graph Operations
+
+### Build Knowledge Graph
+```bash
+~/.claude-memory/venv/bin/python ~/.claude-memory/graph_engine.py build
+```
+Builds graph from all memories using TF-IDF + Leiden clustering
+
+### Show Graph Statistics
+```bash
+~/.claude-memory/venv/bin/python ~/.claude-memory/graph_engine.py stats
+```
+Shows: nodes, edges, clusters with names and member counts
+
+### Find Related Memories
+```bash
+~/.claude-memory/venv/bin/python ~/.claude-memory/graph_engine.py related --memory-id 5
+```
+Shows memories connected in the knowledge graph
+
+### View Cluster Members
+```bash
+~/.claude-memory/venv/bin/python ~/.claude-memory/graph_engine.py cluster --cluster-id 1
+```
+Lists all memories in a specific cluster
+
+---
+
+## 🧠 Pattern Learning
+
+### Update Patterns
+```bash
+~/.claude-memory/venv/bin/python ~/.claude-memory/pattern_learner.py update
+```
+Analyzes all memories and learns new identity patterns
+
+### List Learned Patterns
+```bash
+~/.claude-memory/venv/bin/python ~/.claude-memory/pattern_learner.py list 0.1
+```
+Shows patterns with confidence >= 0.1 (10%)
+
+### Get Claude Context
+```bash
+~/.claude-memory/venv/bin/python ~/.claude-memory/pattern_learner.py context 0.7
+```
+Outputs patterns formatted for Claude with confidence >= 0.7 (70%)
+
+### Show Pattern Statistics
+```bash
+~/.claude-memory/venv/bin/python ~/.claude-memory/pattern_learner.py stats
+```
+Shows pattern count, avg confidence, types, categories
+
+---
+
+## 📦 Traditional Memory Operations
+
+### Add Memory
+```bash
+python ~/.claude-memory/memory_store_v2.py add "content" --tags tag1,tag2
+```
+
+### Search Memories
+```bash
+python ~/.claude-memory/memory_store_v2.py search "query"
+```
+
+### List Recent Memories
+```bash
+python ~/.claude-memory/memory_store_v2.py list 20
+```
+
+### Get Stats
+```bash
+python ~/.claude-memory/memory_store_v2.py stats
+```
+
+---
+
+## ⚙️ Adding Commands to Shell
+
+### Option 1: Bash Aliases
+Add to `~/.bashrc` or `~/.zshrc`:
+
+```bash
+# SuperLocalMemory V2 aliases
+alias memory-status='~/.claude-memory/bin/memory-status'
+alias memory-reset='~/.claude-memory/bin/memory-reset'
+alias memory-profile='~/.claude-memory/bin/memory-profile'
+alias memory-graph='~/.claude-memory/venv/bin/python ~/.claude-memory/graph_engine.py'
+alias memory-patterns='~/.claude-memory/venv/bin/python ~/.claude-memory/pattern_learner.py'
+```
+
+Then reload: `source ~/.bashrc` or `source ~/.zshrc`
+
+### Option 2: Add to PATH
+Add to `~/.bashrc` or `~/.zshrc`:
+
+```bash
+export PATH="$HOME/.claude-memory/bin:$PATH"
+```
+
+Then reload and use short commands:
+```bash
+memory-status
+memory-reset status
+memory-profile list
+```
+
+---
+
+## 🔐 Safety Features
+
+All destructive commands include:
+- ✅ Confirmation prompts
+- ✅ Automatic backups
+- ✅ Clear warnings
+- ✅ Cannot delete default profile
+- ✅ Cannot delete active profile
+
+### Backup Location
+```bash
+~/.claude-memory/backups/
+```
+
+Format: `pre-reset-YYYYMMDD-HHMMSS.db`
+
+### Restore from Backup
+```bash
+cp ~/.claude-memory/backups/pre-reset-20260205-143000.db \
+   ~/.claude-memory/memory.db
+```
+
+---
+
+## 📝 Help Commands
+
+### Memory Status
+```bash
+~/.claude-memory/bin/memory-status
+# No --help flag, just shows status
+```
+
+### Memory Reset
+```bash
+~/.claude-memory/bin/memory-reset --help
+```
+
+### Memory Profile
+```bash
+~/.claude-memory/bin/memory-profile --help
+```
+
+---
+
+## 🎯 Common Workflows
+
+### Daily Usage
+```bash
+# Standalone: Use Python commands directly
+python ~/.claude-memory/memory_store_v2.py add "content" --tags tag1
+
+# Optional Claude CLI: Use /remember skill
+# /remember "content"
+```
+
+### Weekly Maintenance
+```bash
+# Rebuild graph (as memories grow)
+~/.claude-memory/venv/bin/python ~/.claude-memory/graph_engine.py build
+
+# Update patterns
+~/.claude-memory/venv/bin/python ~/.claude-memory/pattern_learner.py update
+```
+
+### Switching Contexts
+```bash
+# Check current profile
+memory-profile current
+
+# Switch to work profile
+memory-profile switch work
+
+# If using Claude CLI integration, restart it
+# If using standalone, no restart needed
+
+# Verify switch
+memory-profile current
+```
+
+### Fresh Start
+```bash
+# Check what you have
+memory-status
+
+# Soft reset (keeps schema)
+memory-reset soft
+# Type: yes
+
+# Or create new profile instead
+memory-profile create fresh
+memory-profile switch fresh
+```
+
+---
+
+**All commands are safe by default with warnings and confirmations for destructive operations.**
+
+For complete documentation, see:
+- `~/.claude-memory/docs/README.md` - Main documentation
+- `~/.claude-memory/RESET-GUIDE.md` - Reset procedures
+- `~/.claude-memory/PROFILES-GUIDE.md` - Profile management
+- `docs/ARCHITECTURE.md` - All features

package/docs/COMPETITIVE-ANALYSIS.md

@@ -0,0 +1,210 @@
+# Competitive Analysis: AI Memory Solutions (2026)
+
+**Research Date:** February 2026
+**Author:** Varun Pratap Bhardwaj
+
+---
+
+## Executive Summary
+
+After extensive research of the paid/commercial AI memory landscape in 2026, **SuperLocalMemory V2 is the ONLY free solution offering all these features combined**: 7-layer universal architecture, pattern learning, multi-profile support, 100% local operation, and zero setup requirements.
+
+---
+
+## Detailed Competitor Analysis
+
+### 1. Mem0 (mem0.ai)
+
+**Pricing:**
+| Tier | Features | Price |
+|------|----------|-------|
+| Free | 10K memories, limited API calls | $0/month |
+| Pro | Unlimited memories, higher limits | Usage-based |
+| Enterprise | SSO, audit logs, on-prem, SLA | Custom |
+
+**What's MISSING vs SuperLocalMemory V2:**
+- No 7-layer universal architecture (only semantic + graph)
+- No pattern learning with identity profiles
+- No multi-profile support
+- Not 100% local (cloud-first design)
+- Requires API keys and setup
+- Usage-based billing can get expensive
+
+---
+
+### 2. Zep (getzep.com)
+
+**Pricing:**
+| Tier | Features | Price |
+|------|----------|-------|
+| Free | Basic features, limited credits | $0/month |
+| Pro | 20K credits auto-refill | $50/month |
+| Enterprise | BYOK, BYOM, BYOC, SLA | Custom |
+
+**Credit System:** 1 credit = 1 Episode (data object). Episodes >350 bytes billed as multiples.
+
+**What's MISSING vs SuperLocalMemory V2:**
+- No 7-layer universal architecture
+- No pattern learning
+- No multi-profile support natively
+- Not 100% local (cloud-managed)
+- Credit-based billing system
+- Requires significant setup and API integration
+
+---
+
+### 3. Supermemory (supermemory.ai)
+
+**Pricing:**
+| Tier | Limits | Price |
+|------|--------|-------|
+| Free | 1M tokens, 10K search queries | $0/month |
+| Pro | 3M tokens, 100K queries | $19/month |
+| Scale | 80M tokens, 20M queries | $399/month |
+| Enterprise | Custom limits | Custom |
+
+**What's MISSING vs SuperLocalMemory V2:**
+- No 7-layer universal architecture
+- No pattern learning
+- No multi-profile support
+- Not 100% local (cloud-based)
+- Requires setup and API integration
+
+---
+
+### 4. Personal.AI (personal.ai)
+
+**Pricing:**
+| Tier | Description | Price |
+|------|-------------|-------|
+| Premium | Full features | $33.33/month |
+| Custom | Enterprise | Contact sales |
+
+**NO FREE PLAN AVAILABLE**
+
+**What's MISSING vs SuperLocalMemory V2:**
+- No 7-layer universal architecture
+- No pattern learning with confidence scoring
+- Not 100% local (cloud-based)
+- No free tier
+- Closed ecosystem
+
+---
+
+### 5. Letta / MemGPT (letta.com)
+
+**Pricing:**
+| Tier | Description | Price |
+|------|-------------|-------|
+| Open Source | Self-hosted | Free |
+| Letta Cloud | Managed service | Beta (TBD) |
+
+**What's MISSING vs SuperLocalMemory V2:**
+- Different architecture (not 7-layer universal)
+- No explicit pattern learning with identity profiles
+- Limited multi-profile support
+- Requires significant technical setup
+- Complex installation process
+
+---
+
+### 6. Khoj (khoj.dev)
+
+**Pricing:**
+| Tier | Description | Price |
+|------|-------------|-------|
+| Free | Self-hosted, open source | $0 |
+| Cloud | Hosted service | Tiered |
+
+**What's MISSING vs SuperLocalMemory V2:**
+- No 7-layer universal architecture
+- No pattern learning with identity profiles
+- No progressive compression system
+- Not zero-setup
+
+---
+
+## Comprehensive Comparison Matrix
+
+| Feature | Mem0 | Zep | Supermemory | Letta | Personal.AI | Khoj | **SuperLocalMemory V2** |
+|---------|------|-----|-------------|-------|-------------|------|------------------------|
+| **7-Layer Universal Architecture** | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
+| **Pattern Learning** | ❌ | ❌ | ❌ | ❌ | Partial | ❌ | ✅ |
+| **Multi-Profile Support** | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ |
+| **100% Local** | ❌ | ❌ | ❌ | Partial | ❌ | Partial | ✅ |
+| **Zero Setup** | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
+| **Knowledge Graph** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ |
+| **Progressive Compression** | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
+| **Free Tier** | Limited | Limited | Limited | ✅ | ❌ | ✅ | **Unlimited** |
+
+---
+
+## Pricing Summary
+
+| Solution | Free Tier | Entry Paid | Enterprise |
+|----------|-----------|------------|------------|
+| **SuperLocalMemory V2** | **Unlimited (MIT)** | **$0** | **$0** |
+| Mem0 | 10K memories | Usage-based | Custom |
+| Zep | Limited credits | $50/month | Custom |
+| Supermemory | 1M tokens | $19/month | $399+/month |
+| Personal.AI | None | $33.33/month | Custom |
+| Letta | Self-hosted | Beta | TBD |
+| Khoj | Self-hosted | Tiered | Custom |
+
+---
+
+## Key Differentiators: SuperLocalMemory V2
+
+### 1. 7-Layer Universal Architecture (UNIQUE)
+No competitor offers this integrated architecture:
+- Layer 1: Raw Storage (SQLite + FTS + embeddings)
+- Layer 2: Hierarchical Index (PageIndex-style)
+- Layer 3: Knowledge Graph (GraphRAG with Leiden clustering)
+- Layer 4: Pattern Learning (xMemory-style identity profiles)
+
+### 2. Pattern Learning with Confidence Scoring (UNIQUE)
+Learns your:
+- Coding preferences (frameworks, languages)
+- Terminology patterns
+- Style preferences
+- With explicit confidence percentages
+
+### 3. Multi-Profile Support (Rare)
+- Isolated memory contexts per project/client
+- Separate patterns, graphs, and memories
+- Easy profile switching via CLI
+
+### 4. 100% Local + Zero External APIs (Rare)
+- No cloud dependencies
+- No API keys required
+- GDPR/HIPAA compliant by default
+
+### 5. Zero Setup (UNIQUE)
+- 5-minute installation
+- Works immediately after `./install.sh`
+- No Docker, no API keys, no cloud accounts
+
+### 6. MIT License - Completely Free
+- No usage limits
+- No credit systems
+- Commercial use allowed
+
+---
+
+## Conclusion
+
+**SuperLocalMemory V2 is demonstrably unique in the 2026 AI memory market.**
+
+No single competitor offers ALL of:
+1. 7-layer universal architecture
+2. Pattern learning with identity profiles
+3. Multi-profile support
+4. 100% local operation
+5. Zero setup requirements
+6. Completely free (MIT license)
+
+**SuperLocalMemory V2 is the only solution combining all these features together.**
+
+---
+
+*Research conducted February 2026 by Varun Pratap Bhardwaj*