superlocalmemory 2.8.6 → 3.0.0

package/docs/cli-reference.md

@@ -0,0 +1,276 @@
+# CLI Reference
+> SuperLocalMemory V3 Documentation
+> https://superlocalmemory.com | Part of Qualixar
+
+Complete reference for the `slm` command-line interface.
+
+---
+
+## Setup & Configuration
+
+### `slm setup`
+
+Run the interactive setup wizard. Guides you through mode selection, IDE connection, and verification.
+
+```bash
+slm setup
+```
+
+### `slm mode [a|b|c]`
+
+Get or set the operating mode.
+
+```bash
+slm mode          # Show current mode
+slm mode a        # Zero-cloud (no LLM, no API key)
+slm mode b        # Local LLM via Ollama
+slm mode c        # Cloud LLM (requires API key)
+```
+
+### `slm provider [set]`
+
+Get or set the LLM provider for Mode B/C.
+
+```bash
+slm provider          # Show current provider
+slm provider set      # Interactive provider selector
+slm provider set openai   # Set provider directly
+```
+
+### `slm connect [ide]`
+
+Configure IDE integrations.
+
+```bash
+slm connect           # Auto-detect and configure all IDEs
+slm connect cursor    # Configure Cursor specifically
+slm connect claude    # Configure Claude Code specifically
+```
+
+Supported IDEs: `claude`, `cursor`, `vscode`, `windsurf`, `gemini`, `jetbrains`, `continue`, `zed`
+
+## Memory Operations
+
+### `slm remember "content" [options]`
+
+Store a memory.
+
+```bash
+slm remember "API rate limit is 100 req/min on staging"
+slm remember "Use camelCase for JS, snake_case for Python" --tags "style,convention"
+slm remember "Maria owns the auth service" --tags "team,ownership"
+```
+
+| Option | Description |
+|--------|-------------|
+| `--tags "a,b"` | Comma-separated tags for categorization |
+| `--profile name` | Store in a specific profile (overrides active profile) |
+
+### `slm recall "query" [options]`
+
+Search your memories. Returns the most relevant results.
+
+```bash
+slm recall "rate limit"
+slm recall "who owns auth" --limit 5
+slm recall "database config" --profile work
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--limit N` | 10 | Maximum results to return |
+| `--profile name` | active | Search in a specific profile |
+
+### `slm search "query" [options]`
+
+Alias for `slm recall`. Same behavior, same options.
+
+### `slm forget "query" [options]`
+
+Delete memories matching a query.
+
+```bash
+slm forget "old staging credentials"
+slm forget --id 42                    # Delete by memory ID
+slm forget --before "2026-01-01"      # Delete memories before a date
+```
+
+| Option | Description |
+|--------|-------------|
+| `--id N` | Delete a specific memory by ID |
+| `--before "date"` | Delete all memories before this date |
+| `--confirm` | Skip the confirmation prompt |
+
+### `slm list [options]`
+
+List recent memories.
+
+```bash
+slm list              # Last 20 memories
+slm list --limit 50   # Last 50 memories
+```
+
+## V3 Features
+
+### `slm trace "query"`
+
+Recall with a channel-by-channel breakdown. Shows how each retrieval channel contributed to the results.
+
+```bash
+slm trace "database port"
+```
+
+Output shows scores from each channel:
+- Semantic (vector similarity)
+- BM25 (keyword matching)
+- Entity Graph (relationship traversal)
+- Temporal (time-based relevance)
+
+### `slm health`
+
+Show diagnostics for the mathematical layers.
+
+```bash
+slm health
+```
+
+Reports status of:
+- Fisher-Rao similarity layer
+- Sheaf consistency layer
+- Langevin lifecycle dynamics
+- Embedding model status
+- Database integrity
+
+### `slm consistency`
+
+Run a consistency check across your memories. Detects contradictions and outdated information.
+
+```bash
+slm consistency
+```
+
+## Migration
+
+### `slm migrate [options]`
+
+Migrate a V2 database to V3 format.
+
+```bash
+slm migrate                # Run migration
+slm migrate --dry-run      # Preview what will change
+slm migrate --rollback     # Undo migration (within 30 days)
+```
+
+| Option | Description |
+|--------|-------------|
+| `--dry-run` | Show what would change without modifying anything |
+| `--rollback` | Revert to V2 format (backup must exist) |
+
+## Profile Management
+
+### `slm profile [command]`
+
+Manage memory profiles (isolated memory contexts).
+
+```bash
+slm profile list                  # List all profiles
+slm profile switch work           # Switch to "work" profile
+slm profile create client-acme    # Create a new profile
+slm profile delete old-project    # Delete a profile
+slm profile export work > backup.json  # Export a profile
+```
+
+## System & Maintenance
+
+### `slm status`
+
+Show system status: mode, profile, memory count, database location, health.
+
+```bash
+slm status
+```
+
+### `slm compact`
+
+Compress and optimize the memory database. Merges redundant memories and reclaims space.
+
+```bash
+slm compact
+```
+
+### `slm backup`
+
+Check backup status or create a manual backup.
+
+```bash
+slm backup              # Show backup status
+slm backup create       # Create a backup now
+```
+
+### `slm audit [options]`
+
+View the audit trail. Shows all memory operations with timestamps and hash-chain verification.
+
+```bash
+slm audit               # Recent audit entries
+slm audit --limit 100   # Last 100 entries
+slm audit --verify      # Verify hash-chain integrity
+```
+
+### `slm retention [policy]`
+
+Manage retention policies.
+
+```bash
+slm retention                          # Show current policy
+slm retention set gdpr-30d            # Apply GDPR 30-day policy
+slm retention set hipaa-7y            # Apply HIPAA 7-year policy
+slm retention set custom --days 90    # Custom retention period
+```
+
+## Global Options
+
+These options work with any command:
+
+| Option | Description |
+|--------|-------------|
+| `--help` | Show help for a command |
+| `--version` | Show SLM version |
+| `--verbose` | Show detailed output |
+| `--json` | Output in JSON format (for scripting) |
+| `--profile name` | Override the active profile for this command |
+
+## Examples
+
+### Daily workflow
+
+```bash
+# Morning: check what you remembered yesterday
+slm list --limit 10
+
+# During work: store a decision
+slm remember "Decided to use WebSocket instead of SSE for real-time updates" --tags "architecture"
+
+# Later: recall the decision
+slm recall "real-time communication approach"
+
+# End of day: check system health
+slm status
+```
+
+### Project setup
+
+```bash
+# Create a profile for a new project
+slm profile create mobile-app
+slm profile switch mobile-app
+
+# Store project context
+slm remember "React Native 0.76 with Expo SDK 52"
+slm remember "Backend is FastAPI on AWS ECS"
+slm remember "CI/CD via GitHub Actions, deploys on merge to main"
+```
+
+---
+
+*SuperLocalMemory V3 — Copyright 2026 Varun Pratap Bhardwaj. MIT License. Part of Qualixar.*

package/docs/compliance.md

@@ -0,0 +1,191 @@
+# Compliance
+> SuperLocalMemory V3 Documentation
+> https://superlocalmemory.com | Part of Qualixar
+
+SuperLocalMemory is designed for organizations that need to meet data protection and privacy regulations. Mode A satisfies the strictest requirements by keeping all data local.
+
+---
+
+## EU AI Act
+
+The EU AI Act (Regulation 2024/1689) establishes requirements for AI systems operating in the European Union.
+
+### Mode A: Full Compliance by Architecture
+
+In Mode A, SuperLocalMemory operates as a local data retrieval system with zero cloud dependency:
+
+| Requirement | How Mode A satisfies it |
+|-------------|------------------------|
+| **Data sovereignty** | All data stored and processed locally. Nothing leaves the device. |
+| **Right to erasure** | `slm forget` deletes data from the local database. No cloud logs exist to purge. |
+| **Transparency** | The retrieval pipeline is fully auditable. No black-box AI decisions. |
+| **Risk classification** | A local retrieval system with no autonomous decision-making qualifies as minimal risk. |
+
+### Mode B: Full Compliance
+
+Mode B uses a local LLM (Ollama). Data never leaves the device. Same compliance posture as Mode A.
+
+### Mode C: Shared Responsibility
+
+Mode C sends recall queries to a cloud LLM provider. In this mode:
+
+- **Your data** (stored memories) remains local
+- **Queries** are sent to the cloud provider
+- The cloud provider's compliance posture applies to those queries
+- A Data Processing Agreement (DPA) with your provider is recommended
+
+## GDPR
+
+The General Data Protection Regulation applies to personal data of EU residents.
+
+### Right to Erasure (Article 17)
+
+```bash
+# Delete specific memories
+slm forget "John's phone number"
+slm forget --id 42
+
+# Delete all memories before a date
+slm forget --before "2025-01-01"
+
+# Delete an entire profile
+slm profile delete client-eu
+```
+
+Deletion is permanent. In Mode A, there are no cloud copies to worry about.
+
+### Data Portability (Article 20)
+
+```bash
+# Export all memories for a profile
+slm profile export work > work-data.json
+
+# The export is standard JSON — readable by any system
+```
+
+### Data Minimization (Article 5)
+
+The entropy gate in the ingestion pipeline filters out redundant and low-value information automatically. Only memories with sufficient information value are stored.
+
+### Purpose Limitation
+
+Profiles enforce purpose limitation. Client A's data is stored in Client A's profile and is never accessible from another profile.
+
+## Retention Policies
+
+Named retention policies automate data lifecycle management.
+
+### Built-in policies
+
+| Policy | Retention period | Use case |
+|--------|:----------------:|----------|
+| `indefinite` | Forever | Default. No automatic deletion. |
+| `gdpr-30d` | 30 days | GDPR-compliant short retention |
+| `hipaa-7y` | 7 years | HIPAA medical records requirement |
+
+### Apply a policy
+
+```bash
+slm retention set gdpr-30d
+```
+
+This applies to the active profile. Memories older than the retention period are automatically archived and then deleted.
+
+### Custom policies
+
+```bash
+slm retention set custom --days 90
+```
+
+### Per-profile policies
+
+Different profiles can have different policies:
+
+```bash
+slm profile switch client-eu
+slm retention set gdpr-30d
+
+slm profile switch internal
+slm retention set indefinite
+```
+
+## Access Control
+
+SuperLocalMemory uses Attribute-Based Access Control (ABAC) per profile.
+
+- Each profile is an isolated access boundary
+- No cross-profile data access is possible
+- Profile switching requires the `slm profile switch` command
+- The audit trail logs all profile switches
+
+## Audit Trail
+
+Every memory operation is logged in a tamper-evident hash chain.
+
+### View the audit trail
+
+```bash
+slm audit                    # Recent entries
+slm audit --limit 100        # Last 100 entries
+slm audit --action store     # Only store operations
+slm audit --action delete    # Only delete operations
+```
+
+### Verify integrity
+
+```bash
+slm audit --verify
+```
+
+This checks the hash chain for tampering. Each entry contains a hash of the previous entry, creating a blockchain-like chain. Any modification to a past entry breaks the chain and is detected.
+
+### What gets logged
+
+| Action | What is recorded |
+|--------|-----------------|
+| `store` | Memory ID, timestamp, profile, content hash |
+| `recall` | Query, timestamp, profile, result count |
+| `delete` | Memory ID, timestamp, profile, reason |
+| `profile_switch` | From profile, to profile, timestamp |
+| `mode_change` | From mode, to mode, timestamp |
+| `migration` | Source version, target version, timestamp |
+
+## HIPAA
+
+For healthcare applications:
+
+1. Use Mode A (zero cloud) to ensure PHI never leaves the device
+2. Apply the `hipaa-7y` retention policy
+3. Use per-patient or per-case profiles for isolation
+4. Enable audit trail verification for compliance audits
+
+```bash
+slm profile create patient-12345
+slm profile switch patient-12345
+slm retention set hipaa-7y
+```
+
+## SOC 2
+
+SuperLocalMemory supports SOC 2 requirements through:
+
+- **Access controls:** Profile-based isolation with ABAC
+- **Audit logging:** Hash-chained, tamper-evident audit trail
+- **Data encryption:** SQLite database can be encrypted at rest using OS-level encryption (FileVault, BitLocker, LUKS)
+- **Change management:** All configuration changes are logged
+
+## Compliance Checklist
+
+| Requirement | Mode A | Mode B | Mode C |
+|-------------|:------:|:------:|:------:|
+| Data stays on device | Yes | Yes | Partial (queries sent to cloud) |
+| No cloud dependency | Yes | Yes | No |
+| Right to erasure | Yes | Yes | Yes (local); cloud logs depend on provider |
+| Audit trail | Yes | Yes | Yes |
+| Retention policies | Yes | Yes | Yes |
+| Profile isolation | Yes | Yes | Yes |
+| Tamper detection | Yes | Yes | Yes |
+
+---
+
+*SuperLocalMemory V3 — Copyright 2026 Varun Pratap Bhardwaj. MIT License. Part of Qualixar.*

package/docs/configuration.md

@@ -0,0 +1,182 @@
+# Configuration
+> SuperLocalMemory V3 Documentation
+> https://superlocalmemory.com | Part of Qualixar
+
+Control how SuperLocalMemory stores, retrieves, and processes your memories.
+
+---
+
+## Three Operating Modes
+
+SuperLocalMemory runs in one of three modes. You pick the trade-off between privacy and power.
+
+| Mode | What it does | Needs API key? | Data leaves your machine? |
+|------|-------------|:--------------:|:-------------------------:|
+| **A: Zero-Cloud** | Math-based retrieval. No LLM calls. | No | Never |
+| **B: Local LLM** | Mode A + a local LLM via Ollama. | No | Never |
+| **C: Cloud LLM** | Mode B + a cloud LLM for maximum recall quality. | Yes | Yes (queries only) |
+
+### Check your current mode
+
+```bash
+slm mode
+```
+
+### Switch modes
+
+```bash
+slm mode a    # Zero-cloud (default)
+slm mode b    # Local LLM
+slm mode c    # Cloud LLM
+```
+
+Switching modes takes effect immediately. No data is lost.
+
+### Mode A: Zero-Cloud (Default)
+
+All operations run locally. Retrieval uses four channels (semantic similarity, keyword search, entity graph, and temporal context) combined with mathematical scoring. No network calls.
+
+Best for: privacy-sensitive work, air-gapped environments, EU AI Act compliance.
+
+### Mode B: Local LLM
+
+Everything from Mode A, plus a local LLM (via Ollama) that improves recall by understanding query intent and reranking results.
+
+**Setup:**
+
+```bash
+# Install Ollama (if not already installed)
+brew install ollama          # macOS
+curl -fsSL https://ollama.com/install.sh | sh  # Linux
+
+# Pull a model
+ollama pull llama3.2
+
+# Switch to Mode B
+slm mode b
+```
+
+Best for: developers who want better recall without sending data to the cloud.
+
+### Mode C: Cloud LLM
+
+Everything from Mode B, plus a cloud LLM for cross-encoder reranking and agentic multi-round retrieval. Highest recall quality.
+
+**Setup:**
+
+```bash
+slm mode c
+slm provider set openai
+```
+
+You will be prompted for your API key (stored locally in your config file, never transmitted except to the provider you choose).
+
+Best for: maximum recall quality when privacy constraints allow cloud calls.
+
+## Provider Configuration
+
+Mode C supports multiple LLM providers.
+
+### Set your provider
+
+```bash
+slm provider           # Show current provider
+slm provider set       # Interactive provider selector
+```
+
+### Supported providers
+
+| Provider | Command | Env variable |
+|----------|---------|-------------|
+| OpenAI | `slm provider set openai` | `OPENAI_API_KEY` |
+| Anthropic | `slm provider set anthropic` | `ANTHROPIC_API_KEY` |
+| Azure OpenAI | `slm provider set azure` | `AZURE_OPENAI_API_KEY` |
+| Ollama (local) | `slm provider set ollama` | None needed |
+| OpenRouter | `slm provider set openrouter` | `OPENROUTER_API_KEY` |
+
+### Set API keys
+
+You can set keys interactively or via environment variables:
+
+```bash
+# Interactive (stored in config file)
+slm provider set openai
+# Prompts: Enter your OpenAI API key: sk-...
+
+# Via environment variable (takes precedence)
+export OPENAI_API_KEY="sk-..."
+```
+
+## Config File
+
+All settings live in:
+
+```
+~/.superlocalmemory/config.json
+```
+
+### Example config
+
+```json
+{
+  "mode": "a",
+  "profile": "default",
+  "provider": {
+    "name": "openai",
+    "model": "gpt-4o-mini",
+    "api_key_env": "OPENAI_API_KEY"
+  },
+  "auto_capture": true,
+  "auto_recall": true,
+  "embedding_model": "all-MiniLM-L6-v2",
+  "max_recall_results": 10,
+  "retention": {
+    "default_policy": "indefinite"
+  }
+}
+```
+
+### Key settings
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `mode` | `"a"` | Operating mode: `a`, `b`, or `c` |
+| `profile` | `"default"` | Active memory profile |
+| `auto_capture` | `true` | Automatically store decisions and context |
+| `auto_recall` | `true` | Automatically inject relevant memories |
+| `embedding_model` | `"all-MiniLM-L6-v2"` | Sentence transformer for semantic search |
+| `max_recall_results` | `10` | Maximum memories returned per query |
+
+## Environment Variables
+
+These override config file settings when set:
+
+| Variable | Purpose |
+|----------|---------|
+| `SLM_MODE` | Override operating mode |
+| `SLM_PROFILE` | Override active profile |
+| `SLM_DATA_DIR` | Override data directory (default: `~/.superlocalmemory/`) |
+| `OPENAI_API_KEY` | OpenAI API key for Mode C |
+| `ANTHROPIC_API_KEY` | Anthropic API key for Mode C |
+| `AZURE_OPENAI_API_KEY` | Azure OpenAI API key for Mode C |
+| `OPENROUTER_API_KEY` | OpenRouter API key for Mode C |
+
+## Database Location
+
+All data is stored locally in:
+
+```
+~/.superlocalmemory/memory.db    # SQLite database
+~/.superlocalmemory/config.json  # Configuration
+~/.superlocalmemory/backups/     # Automatic backups
+```
+
+To use a custom location:
+
+```bash
+export SLM_DATA_DIR="/path/to/your/data"
+```
+
+---
+
+*SuperLocalMemory V3 — Copyright 2026 Varun Pratap Bhardwaj. MIT License. Part of Qualixar.*