superlocalmemory 3.4.17 → 3.4.19

package/docs/auto-memory.md

@@ -1,150 +0,0 @@
-# Auto-Memory
-> SuperLocalMemory V3 Documentation
-> https://superlocalmemory.com | Part of Qualixar
-
-SuperLocalMemory captures and recalls context automatically. Install it once, then forget about it — your AI assistant gets smarter over time without any manual effort.
-
----
-
-## How Auto-Capture Works
-
-When you work with an AI assistant that has SLM connected, certain types of information are automatically stored as memories:
-
-| What gets captured | Example |
-|-------------------|---------|
-| **Decisions** | "Let's use WebSocket instead of SSE" |
-| **Bug fixes** | "The crash was caused by a null pointer in the auth middleware" |
-| **Architecture choices** | "We're going with a microservices approach for the payment system" |
-| **Preferences** | "I prefer functional components over class components" |
-| **Project context** | "The staging server is at 10.0.1.50, port 8080" |
-| **People and roles** | "Sarah is the lead on the mobile team" |
-| **Corrections** | "Actually, the deadline is March 20, not March 15" |
-
-### What does NOT get captured
-
-- Raw code blocks (too noisy, changes too fast)
-- Casual conversation ("thanks", "sounds good")
-- Repeated information already in memory
-- Content filtered by the entropy gate (redundant or low-value)
-
-### How the system decides what to capture
-
-The ingestion pipeline scores each candidate memory on:
-
-1. **Information value** — Does this add new knowledge not already stored?
-2. **Specificity** — Is this a concrete fact or a vague statement?
-3. **Reusability** — Is this likely to be useful in a future session?
-
-Memories that score below the threshold are discarded. This keeps your database focused and retrieval quality high.
-
-## How Auto-Recall Works
-
-Before your AI assistant responds to a question, SLM automatically searches for relevant memories and injects them as context.
-
-### The flow
-
-```
-You ask a question
-    |
-    v
-SLM runs a recall query using your question as the search input
-    |
-    v
-Relevant memories are injected into the AI's context window
-    |
-    v
-The AI responds with awareness of your past decisions, preferences, and project context
-```
-
-### What this looks like in practice
-
-**Without SLM:**
-> You: "What database should I use for the new service?"
-> AI: Generic advice about PostgreSQL vs MySQL vs MongoDB...
-
-**With SLM:**
-> You: "What database should I use for the new service?"
-> AI: "Based on your previous decision to standardize on PostgreSQL 16 (stored March 5), and your preference for managed services on AWS (stored February 20), I'd recommend Amazon RDS for PostgreSQL. Your auth service and payment service already use PostgreSQL, so this keeps the stack consistent."
-
-The AI did not "remember" this on its own. SLM injected the relevant memories before the AI generated its response.
-
-## Configuration
-
-### Toggle auto-capture and auto-recall
-
-In `~/.superlocalmemory/config.json`:
-
-```json
-{
-  "auto_capture": true,
-  "auto_recall": true
-}
-```
-
-Set either to `false` to disable. When disabled, you can still use `slm remember` and `slm recall` manually.
-
-### Adjust recall sensitivity
-
-```json
-{
-  "max_recall_results": 10,
-  "recall_threshold": 0.3
-}
-```
-
-| Setting | Default | Description |
-|---------|---------|-------------|
-| `max_recall_results` | `10` | Maximum memories injected per query |
-| `recall_threshold` | `0.3` | Minimum relevance score (0.0 to 1.0). Lower = more memories, possibly less relevant. Higher = fewer but more precise. |
-
-### Adjust capture sensitivity
-
-```json
-{
-  "capture_threshold": 0.5
-}
-```
-
-| Setting | Default | Description |
-|---------|---------|-------------|
-| `capture_threshold` | `0.5` | Minimum information value to auto-capture. Lower = capture more. Higher = capture only high-value statements. |
-
-## Manual Override
-
-You always have full control:
-
-```bash
-# Explicitly store something
-slm remember "The API rate limit on production is 500 req/min, staging is 100 req/min"
-
-# Explicitly recall
-slm recall "rate limits"
-
-# Delete a memory
-slm forget --id 42
-```
-
-Manual operations work regardless of auto-capture/auto-recall settings.
-
-## Learning Over Time
-
-SLM's adaptive learning system observes which memories are recalled frequently, which are marked helpful or outdated, and adjusts its behavior:
-
-- **Frequently helpful memories** get higher ranking in future recalls
-- **Memories marked "outdated"** are deprioritized or flagged for review
-- **Usage patterns** inform what types of information to prioritize for capture
-
-You can see what the system has learned:
-
-```bash
-slm patterns            # Show learned patterns
-slm patterns correct 5  # Correct pattern #5 if it's wrong
-```
-
-## Privacy
-
-Auto-capture and auto-recall happen entirely within SLM on your machine. In Mode A, no data leaves your device at any point. In Mode C, recall queries are sent to your configured LLM provider, but the memories themselves remain local.
-
----
-
-*SuperLocalMemory V3 — Copyright 2026 Varun Pratap Bhardwaj. Elastic License 2.0. Part of Qualixar.*

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`