superlocalmemory 3.4.16 → 3.4.18

package/docs/cli-reference.md

@@ -1,327 +0,0 @@
-# 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 structured JSON with agent-native envelope (for AI agents, scripts, CI/CD) |
-| `--profile name` | Override the active profile for this command |
-
-## Agent-Native JSON Output
-
-All data-returning commands support `--json` for structured output. The envelope follows the 2026 agent-native CLI standard:
-
-```json
-{
-  "success": true,
-  "command": "recall",
-  "version": "3.0.22",
-  "data": {
-    "results": [
-      {"fact_id": "abc123", "score": 0.87, "content": "Database uses PostgreSQL 16"}
-    ],
-    "count": 1,
-    "query_type": "semantic"
-  },
-  "next_actions": [
-    {"command": "slm list --json", "description": "List recent memories"}
-  ]
-}
-```
-
-### Supported Commands
-
-`recall`, `remember`, `list`, `status`, `health`, `trace`, `forget`, `delete`, `update`, `mode`, `profile`, `connect`
-
-### Usage with jq
-
-```bash
-# Get first result content
-slm recall "auth" --json | jq '.data.results[0].content'
-
-# Get all fact IDs
-slm list --json | jq '.data.results[].fact_id'
-
-# Check current mode
-slm status --json | jq '.data.mode'
-```
-
-### In CI/CD (GitHub Actions)
-
-```yaml
-- name: Store deployment info
-  run: slm remember "Deployed ${{ github.sha }} to production" --json
-
-- name: Check memory health
-  run: slm status --json | jq -e '.success'
-```
-
----
-
-## 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. Elastic License 2.0. Part of Qualixar.*

package/docs/cloud-backup.md

@@ -1,174 +0,0 @@
-# Cloud Backup — Google Drive & GitHub
-
-SuperLocalMemory v3.4.10+ can automatically back up your memory databases to **Google Drive** and **GitHub**. All credentials are stored in your OS keychain (macOS Keychain, Windows Credential Locker, or Linux Secret Service) — never in plaintext.
-
-## GitHub Backup (Recommended)
-
-GitHub backup works out of the box. No additional setup needed beyond a Personal Access Token.
-
-### Setup (2 minutes)
-
-1. Open the SLM Dashboard: `http://localhost:8765`
-2. Click the **account widget** in the sidebar (bottom), then click the **GitHub icon**
-3. You'll see the "Connect GitHub" form:
-
-   - **Personal Access Token**: Click [Create one here](https://github.com/settings/tokens/new?scopes=repo&description=SLM+Backup) — this opens GitHub with the `repo` scope pre-selected. Click "Generate token" and copy it.
-   - **Repository Name**: Default is `slm-backup`. Change if you want.
-
-4. Click **Connect**
-
-That's it. SLM will:
-- Verify your token
-- Create a **private** repository (always private — your data is never public)
-- Initialize it with a README
-- Show your GitHub avatar and username in the sidebar
-
-### How It Works
-
-- Each backup creates a **GitHub Release** with your database files as assets
-- ALL databases are included: memory.db, learning.db, audit_chain.db, code_graph.db, pending.db
-- Only the last **5 releases** are kept — older ones are automatically deleted to prevent storage bloat
-- Backups run in the background — the dashboard never freezes
-
-### Restoring from GitHub
-
-1. Go to your `slm-backup` repo on GitHub
-2. Click **Releases** in the sidebar
-3. Download the `.db` files from the latest release
-4. Copy them to `~/.superlocalmemory/`
-5. Run `slm restart`
-
----
-
-## Google Drive Backup
-
-Google Drive backup requires a one-time OAuth client setup through Google Cloud Console. This is a Google requirement for any application that accesses Drive on behalf of users.
-
-### Why Is This Needed?
-
-Google requires every application to register an "OAuth client" before it can access your Drive. This is a security measure — it ensures you know exactly which application is accessing your data. For GitHub, a simple Personal Access Token is enough, but Google's security model is stricter.
-
-### Setup (5 minutes)
-
-#### Step 1: Create a Google Cloud Project
-
-1. Go to [Google Cloud Console](https://console.cloud.google.com/)
-2. Click the project dropdown (top bar) → **New Project**
-3. Name it anything (e.g., `slm-backup`) → **Create**
-4. Select the new project from the dropdown
-
-#### Step 2: Enable APIs
-
-1. Go to **APIs & Services** → **Library**
-2. Search for and enable:
-   - **Google Drive API**
-   - **People API** (for showing your email/name)
-
-#### Step 3: Configure OAuth Consent Screen
-
-1. Go to **APIs & Services** → **OAuth consent screen**
-2. Select **External** → **Create**
-3. Fill in:
-   - **App name**: `SuperLocalMemory` (or anything)
-   - **User support email**: your Gmail
-   - **Developer contact email**: your Gmail
-4. Click **Save and Continue** through the remaining steps
-5. Go to **Test users** → **Add users** → add your Gmail address
-
-#### Step 4: Create OAuth Client
-
-1. Go to **APIs & Services** → **Credentials**
-2. Click **Create Credentials** → **OAuth client ID**
-3. Application type: **Web application**
-4. Name: `SLM Dashboard` (or anything)
-5. Under **Authorized redirect URIs**, add:
-   ```
-   http://localhost:8765/api/backup/oauth/google/callback
-   ```
-6. Click **Create**
-7. Copy the **Client ID** and **Client Secret** (you'll need both)
-
-#### Step 5: Connect in SLM
-
-1. Open the SLM Dashboard: `http://localhost:8765`
-2. Click the **Google icon** in the sidebar account widget
-3. Paste your **Client ID** and **Client Secret**
-4. Click **Save & Connect Google Drive**
-5. Google's login page opens — sign in and click **Allow**
-6. You'll see "Google Drive Connected!" — close the popup
-
-### How It Works
-
-- Backups are uploaded to a `SLM-Backup` folder in your Google Drive
-- Files are **replaced in-place** (no duplicates, no storage bloat)
-- ALL databases are backed up, not just memory.db
-- Your OAuth credentials are stored in your OS keychain
-- Backups run in the background
-
-### Restoring from Google Drive
-
-1. Open Google Drive → `SLM-Backup` folder
-2. Download all `.db` files
-3. Copy them to `~/.superlocalmemory/`
-4. Run `slm restart`
-
----
-
-## Sync & Schedule
-
-### Manual Sync
-
-Click **Sync Now** (cloud upload icon) in the sidebar account widget, or go to **Settings** → **Cloud Backup** → **Sync Now**.
-
-### Auto-Backup
-
-SLM automatically creates local backups on a schedule (default: weekly). When cloud destinations are connected, backups are also pushed to the cloud after each auto-backup.
-
-Configure the schedule in **Settings** → **Backup Configuration**:
-- **Interval**: Daily or Weekly
-- **Max backups**: How many local backups to keep (default: 10)
-
-### Export
-
-Click the **download icon** in the sidebar to export a compressed `.gz` backup file you can store anywhere.
-
----
-
-## What Gets Backed Up
-
-| Database | Contents | Typical Size |
-|---|---|---|
-| `memory.db` | Facts, entities, graph edges, embeddings, sessions | 50 MB — 2 GB |
-| `learning.db` | Learning signals, behavioral patterns, ranker data | 0.5 — 5 MB |
-| `audit_chain.db` | Audit trail, compliance provenance | 0.5 — 2 MB |
-| `code_graph.db` | Code knowledge graph (if used) | 0.1 — 10 MB |
-| `pending.db` | Pending operations queue | 0.1 — 1 MB |
-
-All databases are backed up using SQLite's `sqlite3.backup()` API, which creates a consistent, atomic snapshot even while the daemon is running.
-
----
-
-## Security
-
-- **GitHub repos are always private** — hardcoded, cannot be changed
-- **Credentials stored in OS keychain** — macOS Keychain, Windows Credential Locker, or Linux Secret Service
-- **Fallback**: On systems without a keychain (headless Linux), credentials are stored in `~/.superlocalmemory/.credentials.json` with `chmod 0600` (owner-only)
-- **Google OAuth tokens** are refresh tokens — they can be revoked from your [Google Account Security page](https://myaccount.google.com/permissions)
-- **GitHub PATs** can be revoked from [GitHub Settings → Tokens](https://github.com/settings/tokens)
-
----
-
-## Troubleshooting
-
-### "Sync failed" in the sidebar
-Check the destination status in **Settings** → **Cloud Backup**. Common causes:
-- GitHub: PAT expired or revoked → reconnect with a new token
-- Google: OAuth token expired → click "Connect Google Drive" again to re-authorize
-
-### Google Drive shows "Connection Failed"
-- Make sure you added yourself as a **test user** in the OAuth consent screen
-- Verify the redirect URI matches exactly: `http://localhost:8765/api/backup/oauth/google/callback`
-- Check that the SLM daemon is running on port 8765
-
-### Dashboard freezes during sync
-This was fixed in v3.4.10 — syncs now run in a background thread. If you're on an older version, update: `pip install -U superlocalmemory`

package/docs/compliance.md

@@ -1,191 +0,0 @@
-# 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. Elastic License 2.0. Part of Qualixar.*