superlocalmemory 2.8.5 → 3.0.0

package/docs/migration-from-v2.md

@@ -0,0 +1,170 @@
+# Migration from V2
+> SuperLocalMemory V3 Documentation
+> https://superlocalmemory.com | Part of Qualixar
+
+Upgrade from SuperLocalMemory V2 to V3. Zero data loss, one command, rollback available.
+
+---
+
+## What Changed in V3
+
+| Area | V2 | V3 |
+|------|----|----|
+| **Retrieval** | Single-channel semantic search | 4-channel: Semantic + BM25 + Entity Graph + Temporal |
+| **Modes** | One mode (cloud required for smart features) | Three modes: A (zero-cloud), B (local LLM), C (cloud LLM) |
+| **Math layer** | None | Fisher-Rao similarity, Sheaf consistency, Langevin lifecycle |
+| **Ingestion** | Basic text storage | 11-step pipeline: entities, facts, emotions, beliefs, graph, and more |
+| **Data directory** | `~/.claude-memory/` | `~/.superlocalmemory/` (symlink preserves old path) |
+| **Consistency** | Manual | Automatic contradiction detection |
+| **Recall quality** | Good | Significantly better on complex queries (multi-hop, temporal) |
+
+**What stays the same:** All CLI commands, MCP tools, IDE integrations, profiles, trust scores, and learned patterns carry forward.
+
+## Before You Migrate
+
+1. **Update to the latest version:**
+
+```bash
+npm update -g superlocalmemory
+```
+
+2. **Check your current version:**
+
+```bash
+slm --version
+# Should show 3.x.x
+```
+
+3. **(Optional) Preview changes:**
+
+```bash
+slm migrate --dry-run
+```
+
+This shows exactly what will change without modifying anything.
+
+## Run the Migration
+
+```bash
+slm migrate
+```
+
+The migration:
+
+1. Creates a full backup of your V2 database
+2. Moves data from `~/.claude-memory/` to `~/.superlocalmemory/`
+3. Creates a symlink (`~/.claude-memory/ -> ~/.superlocalmemory/`) so old IDE configs still work
+4. Extends the database schema with V3 tables (15 new tables)
+5. Re-indexes existing memories for 4-channel retrieval
+6. Sets Mode A as default (zero breaking changes)
+7. Verifies integrity
+
+**Duration:** Under 30 seconds for most databases. Large databases (10,000+ memories) may take 1-2 minutes.
+
+## What Gets Preserved
+
+Everything:
+
+- All stored memories (content, timestamps, metadata)
+- All profiles and their isolation boundaries
+- Trust scores and provenance data
+- Learned patterns and behavioral data
+- Compliance settings and retention policies
+- Audit trail (hash-chain intact)
+- IDE configurations (via symlink)
+
+## What Gets Added
+
+The migration adds V3 capabilities to your existing data:
+
+- BM25 token index for keyword search
+- Entity graph nodes and edges
+- Temporal event entries
+- Fisher-Rao similarity metadata
+- Sheaf consistency sections
+- Langevin lifecycle state
+
+These are computed from your existing memories during migration.
+
+## After Migration
+
+### Verify
+
+```bash
+slm status
+```
+
+Confirm:
+- Mode shows `A` (default after migration)
+- Memory count matches your V2 count
+- Health shows all green
+- Profile is your previous active profile
+
+### Try a recall
+
+```bash
+slm recall "something you stored in V2"
+```
+
+Results should match or exceed V2 quality. V3's 4-channel retrieval finds memories that V2's single-channel search might have missed.
+
+### Explore V3 features
+
+```bash
+slm trace "your query"       # See channel-by-channel breakdown
+slm health                   # Check math layer status
+slm consistency              # Run contradiction detection
+slm mode b                   # Try local LLM mode (if Ollama installed)
+```
+
+## Rollback
+
+If anything goes wrong, roll back within 30 days:
+
+```bash
+slm migrate --rollback
+```
+
+This restores your V2 database from the backup created during migration. The symlink is removed and the original `~/.claude-memory/` directory is restored.
+
+**After 30 days:** The backup is automatically cleaned up. If you need to roll back after 30 days, restore from your own backups.
+
+## IDE Configuration Updates
+
+### Automatic (recommended)
+
+The migration preserves your IDE configs via symlink. No IDE reconfiguration needed.
+
+### Manual (optional)
+
+If you want to update your IDE configs to use the new path directly:
+
+```bash
+slm connect
+```
+
+This updates all detected IDE configs to point to `~/.superlocalmemory/` instead of relying on the symlink.
+
+## FAQ
+
+**Q: Will my IDE break during migration?**
+No. The symlink ensures old paths still work. Your IDE will not notice the change.
+
+**Q: Do I need to reconfigure my API keys?**
+No. API keys are migrated to the new config location automatically.
+
+**Q: Can I run V2 and V3 side by side?**
+No. The migration converts your database in place (with backup). Use `--rollback` if you want to return to V2.
+
+**Q: What if migration fails halfway?**
+The migration is transactional. If any step fails, everything is rolled back automatically. Your V2 data remains untouched.
+
+**Q: I have multiple profiles. Are they all migrated?**
+Yes. All profiles are migrated together. Profile isolation is preserved.
+
+**Q: How big will my database get after migration?**
+The V3 schema adds approximately 20-40% to database size due to the entity graph, BM25 index, and math layer metadata. A 50MB V2 database becomes roughly 60-70MB.
+
+---
+
+*SuperLocalMemory V3 — Copyright 2026 Varun Pratap Bhardwaj. MIT License. Part of Qualixar.*

package/docs/profiles.md

@@ -0,0 +1,173 @@
+# Profiles
+> SuperLocalMemory V3 Documentation
+> https://superlocalmemory.com | Part of Qualixar
+
+Profiles let you maintain completely isolated memory contexts. Work memories never mix with personal memories. Client A never sees Client B's data.
+
+---
+
+## What Profiles Are
+
+A profile is an isolated memory namespace. Each profile has its own:
+
+- Memories and knowledge graph
+- Learned patterns and behavioral data
+- Trust scores and provenance records
+- Retention policies
+- Audit trail
+
+There is zero data leakage between profiles. Searching in one profile never returns results from another.
+
+## Default Profile
+
+After installation, you have one profile called `default`. All memories go here unless you create and switch to another profile.
+
+## Managing Profiles
+
+### List profiles
+
+```bash
+slm profile list
+```
+
+Output:
+
+```
+Profiles:
+  * default     (142 memories, active)
+    work        (89 memories)
+    personal    (34 memories)
+    client-acme (67 memories)
+```
+
+The `*` marks the active profile.
+
+### Create a profile
+
+```bash
+slm profile create work
+slm profile create client-acme
+slm profile create personal
+```
+
+### Switch profiles
+
+```bash
+slm profile switch work
+```
+
+All subsequent `remember`, `recall`, and auto-memory operations use this profile until you switch again.
+
+### Delete a profile
+
+```bash
+slm profile delete old-project
+```
+
+This permanently deletes all memories in that profile. You will be prompted for confirmation.
+
+### Export a profile
+
+```bash
+slm profile export work > work-backup.json
+```
+
+### Import a profile
+
+```bash
+slm profile import < work-backup.json
+```
+
+## Use Cases
+
+### Work vs Personal
+
+```bash
+# Morning: switch to work
+slm profile switch work
+# Work memories are captured and recalled all day
+
+# Evening: switch to personal
+slm profile switch personal
+# Personal project memories are now active
+```
+
+### Per-Client Isolation
+
+For consultants and agencies working across multiple clients:
+
+```bash
+slm profile create client-alpha
+slm profile create client-beta
+
+# Working on Alpha's project
+slm profile switch client-alpha
+# Only Alpha's architecture, decisions, and context are available
+
+# Switch to Beta
+slm profile switch client-beta
+# Alpha's data is completely invisible
+```
+
+### Per-Project Isolation
+
+```bash
+slm profile create mobile-app
+slm profile create backend-api
+slm profile create infrastructure
+```
+
+### Temporary Profiles
+
+For experiments or short-term work:
+
+```bash
+slm profile create experiment-graphql
+slm profile switch experiment-graphql
+# ... do your experiment ...
+
+# Done — delete it
+slm profile switch default
+slm profile delete experiment-graphql
+```
+
+## Profile-Specific Settings
+
+Each profile can have its own retention policy:
+
+```bash
+slm profile switch client-acme
+slm retention set gdpr-30d        # GDPR compliance for this client
+
+slm profile switch internal
+slm retention set indefinite       # Keep internal memories forever
+```
+
+## Using Profiles With CLI Commands
+
+Most commands operate on the active profile. You can override this per-command:
+
+```bash
+# Recall from a specific profile without switching
+slm recall "database config" --profile client-acme
+
+# Store to a specific profile without switching
+slm remember "Acme uses Aurora PostgreSQL" --profile client-acme
+```
+
+## How Profiles Work Internally
+
+Each profile stores memories in the same SQLite database but with a profile identifier on every row. Queries are filtered by profile at the database level, ensuring complete isolation.
+
+The entity graph, BM25 index, and all math layer state are also per-profile. Building the graph for one profile does not affect another.
+
+## Limits
+
+- No hard limit on the number of profiles
+- Each profile adds minimal overhead (a few KB for metadata)
+- Performance is determined by per-profile memory count, not total profiles
+- Switching profiles is instant (no data loading required)
+
+---
+
+*SuperLocalMemory V3 — Copyright 2026 Varun Pratap Bhardwaj. MIT License. Part of Qualixar.*

package/docs/troubleshooting.md

@@ -0,0 +1,310 @@
+# Troubleshooting
+> SuperLocalMemory V3 Documentation
+> https://superlocalmemory.com | Part of Qualixar
+
+Solutions for common issues. If your problem is not listed here, run `slm status --verbose` and check the output for clues.
+
+---
+
+## Installation Issues
+
+### "slm: command not found"
+
+The npm global bin directory is not in your shell's PATH.
+
+**Fix:**
+
+```bash
+# Find where npm puts global binaries
+npm root -g
+# Example output: /usr/local/lib/node_modules
+
+# The bin directory is one level up
+# Add to your shell profile (~/.zshrc, ~/.bashrc, or ~/.bash_profile):
+export PATH="$(npm prefix -g)/bin:$PATH"
+
+# Reload your shell
+source ~/.zshrc   # or source ~/.bashrc
+```
+
+**Alternative — use npx:**
+
+```bash
+npx superlocalmemory status
+```
+
+### "Python not found" during setup
+
+SLM V3 requires Python 3.10 or later for the math engine.
+
+```bash
+# Check Python version
+python3 --version
+
+# Install if missing
+# macOS:
+brew install python@3.12
+
+# Ubuntu/Debian:
+sudo apt install python3.12
+
+# Windows:
+winget install Python.Python.3.12
+```
+
+### "Permission denied" during install
+
+```bash
+# Option 1: Fix npm permissions (recommended)
+mkdir -p ~/.npm-global
+npm config set prefix '~/.npm-global'
+export PATH=~/.npm-global/bin:$PATH
+npm install -g superlocalmemory
+
+# Option 2: Use sudo (not recommended)
+sudo npm install -g superlocalmemory
+```
+
+## Recall Issues
+
+### "No memories found" when you know they exist
+
+**Check your active profile:**
+
+```bash
+slm profile list
+```
+
+Memories are profile-scoped. If you stored a memory in the `work` profile but are currently in `default`, it will not appear.
+
+```bash
+slm profile switch work
+slm recall "your query"
+```
+
+**Check your mode:**
+
+```bash
+slm mode
+```
+
+Mode A uses math-based retrieval. If you recently switched from Mode C, the retrieval behavior changes. Both modes search the same memories, but ranking differs.
+
+**Try a broader query:**
+
+```bash
+slm recall "database"          # Instead of "PostgreSQL 16 configuration on staging"
+slm list --limit 20            # Browse recent memories directly
+```
+
+### Recall returns irrelevant results
+
+**Lower your result count:**
+
+```bash
+slm recall "your query" --limit 3
+```
+
+Fewer results means only the highest-confidence matches are returned.
+
+**Use trace to debug:**
+
+```bash
+slm trace "your query"
+```
+
+This shows which channels contributed what. If BM25 is dominating with weak keyword matches, the query may need different terms.
+
+**Rebuild the graph:**
+
+```bash
+slm build_graph
+```
+
+If entity relationships seem wrong, rebuilding the graph can fix ranking issues.
+
+## Mode C Issues
+
+### "API key not set" or authentication errors
+
+```bash
+# Check your provider configuration
+slm provider
+
+# Reset your provider and key
+slm provider set openai
+# Enter your API key when prompted
+
+# Or set via environment variable
+export OPENAI_API_KEY="sk-..."
+```
+
+### "Connection timeout" or network errors
+
+```bash
+# Test connectivity to your provider
+slm status --verbose
+
+# Check if you're behind a proxy
+echo $HTTP_PROXY
+echo $HTTPS_PROXY
+```
+
+If behind a corporate proxy, set the proxy variables:
+
+```bash
+export HTTPS_PROXY="http://proxy.company.com:8080"
+```
+
+### Mode C is slow
+
+Cloud LLM calls add latency. If speed matters more than maximum recall quality:
+
+```bash
+slm mode b    # Local LLM (fast, no network)
+slm mode a    # Math-only (fastest)
+```
+
+## Migration Issues
+
+### Migration failed or was interrupted
+
+```bash
+# Check if backup exists
+ls ~/.superlocalmemory/backups/
+
+# Roll back to V2
+slm migrate --rollback
+
+# Try migration again
+slm migrate
+```
+
+### "Database is locked"
+
+Close all IDE sessions that might be accessing SLM, then retry:
+
+```bash
+# Check for processes using the database
+lsof ~/.superlocalmemory/memory.db
+
+# Close IDEs, then retry
+slm migrate
+```
+
+### Migration succeeded but recall quality seems worse
+
+After migration, the entity graph and BM25 index are rebuilt from existing data. This process is automatic but can take a moment for large databases.
+
+```bash
+# Force a full re-index
+slm build_graph
+slm compact
+```
+
+## IDE Connection Issues
+
+### IDE does not show SLM tools
+
+1. **Verify SLM is installed:**
+
+```bash
+npm list -g superlocalmemory
+```
+
+2. **Check the IDE config file has correct JSON:**
+
+```bash
+slm connect <your-ide>    # Regenerates the config
+```
+
+3. **Restart the IDE completely** (not just reload the window).
+
+4. **Test the MCP server directly:**
+
+```bash
+npx superlocalmemory mcp --test
+```
+
+### "Connection refused" in IDE
+
+The MCP server failed to start. Common causes:
+
+- Node.js version too old (need 18+)
+- Port conflict with another service
+- Corrupted installation
+
+```bash
+# Reinstall
+npm uninstall -g superlocalmemory
+npm install -g superlocalmemory
+
+# Verify
+slm status
+```
+
+### Multiple IDEs conflicting
+
+Each IDE has its own MCP config file. They do not conflict. All IDEs share the same underlying database. Concurrent access is safe (SQLite WAL mode handles this).
+
+## Database Issues
+
+### Database corruption
+
+Extremely rare with SQLite WAL mode, but if it happens:
+
+```bash
+# Check integrity
+slm status --verbose
+
+# Restore from automatic backup
+ls ~/.superlocalmemory/backups/
+cp ~/.superlocalmemory/backups/memory-2026-03-15.db ~/.superlocalmemory/memory.db
+```
+
+### Database is too large
+
+```bash
+# Check size
+slm memory_used
+
+# Compact (merges redundant memories, reclaims space)
+slm compact
+
+# Apply a retention policy to auto-delete old memories
+slm retention set custom --days 180
+```
+
+## Health Check
+
+Run a full diagnostic:
+
+```bash
+slm health
+```
+
+This reports the status of:
+
+| Component | What it checks |
+|-----------|---------------|
+| Database | Integrity, size, table counts |
+| Embedding model | Loaded, version, dimension |
+| Fisher-Rao | Similarity layer active |
+| Sheaf | Consistency layer active |
+| Langevin | Lifecycle layer active |
+| BM25 index | Token count, index health |
+| Entity graph | Node count, edge count |
+
+If any component shows an error, the output includes a suggested fix.
+
+## Getting Help
+
+If none of the above resolves your issue:
+
+1. Run `slm status --verbose` and note the output
+2. Check the [GitHub Issues](https://github.com/qualixar/superlocalmemory/issues)
+3. Open a new issue with your `slm status --verbose` output
+
+---
+
+*SuperLocalMemory V3 — Copyright 2026 Varun Pratap Bhardwaj. MIT License. Part of Qualixar.*

package/{configs → ide/configs}/antigravity-mcp.json

@@ -1,13 +1,13 @@
 {
   "mcpServers": {
-    "superlocalmemory-v2": {
+    "superlocalmemory": {
       "command": "python3",
-      "args": ["{{INSTALL_DIR}}/mcp_server.py"],
+      "args": ["-m", "superlocalmemory.mcp.server"],
       "env": {
         "PYTHONPATH": "{{INSTALL_DIR}}"
       },
       "cwd": "{{INSTALL_DIR}}",
-      "description": "SuperLocalMemory V2 - 100% local memory system"
+      "description": "SuperLocalMemory V3 - 100% local memory system"
     }
   }
 }

package/ide/configs/chatgpt-desktop-mcp.json

@@ -0,0 +1,16 @@
+{
+  "_README": "ChatGPT Integration -- SuperLocalMemory V3 as ChatGPT Connector",
+  "_requires": "ChatGPT Pro/Plus/Business/Enterprise with Developer Mode enabled",
+  "_tools": "search(query) and fetch(id) -- required by OpenAI MCP spec for Connectors",
+  "_setup": {
+    "step1": "Start MCP server: slm serve --port 8417",
+    "step2": "Expose via tunnel: ngrok http 8417",
+    "step3": "Copy the HTTPS URL from ngrok (e.g. https://abc123.ngrok.app)",
+    "step4": "In ChatGPT: Settings -> Connectors -> Advanced -> Enable Developer Mode",
+    "step5": "Create new Connector -> paste URL with /sse/ suffix (e.g. https://abc123.ngrok.app/sse/)",
+    "step6": "Name it 'SuperLocalMemory' and click Create",
+    "step7": "In any chat, click + -> More -> select SuperLocalMemory connector"
+  },
+  "_alternative_transport": "For Streamable HTTP (recommended): slm serve --transport streamable-http --port 8417",
+  "_note": "100% local -- your MCP server runs on YOUR machine. The tunnel just makes it reachable by ChatGPT servers. All data stays in ~/.superlocalmemory/memory.db"
+}

package/{configs → ide/configs}/claude-desktop-mcp.json

@@ -1,15 +1,15 @@
 {
   "mcpServers": {
-    "superlocalmemory-v2": {
+    "superlocalmemory": {
       "command": "python3",
       "args": [
-        "{{INSTALL_DIR}}/mcp_server.py"
+        "-m", "superlocalmemory.mcp.server"
       ],
       "cwd": "{{INSTALL_DIR}}",
       "env": {
         "PYTHONPATH": "{{INSTALL_DIR}}"
       },
-      "description": "SuperLocalMemory V2 - 100% local memory system for AI assistants"
+      "description": "SuperLocalMemory V3 - 100% local memory system for AI assistants"
     }
   }
 }