superlocalmemory 3.4.17 → 3.4.19

package/docs/ide-setup.md

@@ -1,261 +0,0 @@
-# IDE Setup
-> SuperLocalMemory V3 Documentation
-> https://superlocalmemory.com | Part of Qualixar
-
-Connect SuperLocalMemory to your AI coding tool. Once connected, memories are captured and recalled automatically.
-
----
-
-## Auto-Detection
-
-The fastest way to connect all your IDEs:
-
-```bash
-slm connect
-```
-
-This scans your system for installed IDEs, configures each one, and verifies the connection. Run it once after installing SLM.
-
-To connect a specific IDE:
-
-```bash
-slm connect claude
-slm connect cursor
-slm connect vscode
-```
-
-## Claude Code
-
-**Auto:**
-
-```bash
-slm connect claude
-```
-
-**Manual:** Add to `~/.claude.json`:
-
-```json
-{
-  "mcpServers": {
-    "superlocalmemory": {
-      "command": "npx",
-      "args": ["-y", "superlocalmemory", "mcp"],
-      "env": {}
-    }
-  }
-}
-```
-
-Restart Claude Code. Verify with: `slm status` in a Claude Code session.
-
-## Cursor
-
-**Auto:**
-
-```bash
-slm connect cursor
-```
-
-**Manual:** Add to `~/.cursor/mcp.json`:
-
-```json
-{
-  "mcpServers": {
-    "superlocalmemory": {
-      "command": "npx",
-      "args": ["-y", "superlocalmemory", "mcp"],
-      "env": {}
-    }
-  }
-}
-```
-
-Restart Cursor. The memory tools appear in the tool list automatically.
-
-## VS Code / GitHub Copilot
-
-**Auto:**
-
-```bash
-slm connect vscode
-```
-
-**Manual:** Add to VS Code settings (JSON):
-
-```json
-{
-  "mcp": {
-    "servers": {
-      "superlocalmemory": {
-        "command": "npx",
-        "args": ["-y", "superlocalmemory", "mcp"]
-      }
-    }
-  }
-}
-```
-
-## Windsurf
-
-**Auto:**
-
-```bash
-slm connect windsurf
-```
-
-**Manual:** Add to `~/.windsurf/mcp.json`:
-
-```json
-{
-  "mcpServers": {
-    "superlocalmemory": {
-      "command": "npx",
-      "args": ["-y", "superlocalmemory", "mcp"],
-      "env": {}
-    }
-  }
-}
-```
-
-## Gemini CLI
-
-**Auto:**
-
-```bash
-slm connect gemini
-```
-
-**Manual:** Add to `~/.gemini/settings.json`:
-
-```json
-{
-  "mcpServers": {
-    "superlocalmemory": {
-      "command": "npx",
-      "args": ["-y", "superlocalmemory", "mcp"]
-    }
-  }
-}
-```
-
-## JetBrains (IntelliJ, PyCharm, WebStorm, etc.)
-
-**Auto:**
-
-```bash
-slm connect jetbrains
-```
-
-**Manual:** Open **Settings > Tools > AI Assistant > MCP Servers** and add:
-
-| Field | Value |
-|-------|-------|
-| Name | `superlocalmemory` |
-| Command | `npx` |
-| Arguments | `-y superlocalmemory mcp` |
-
-Restart the IDE after adding the server.
-
-## Continue.dev
-
-**Auto:**
-
-```bash
-slm connect continue
-```
-
-**Manual:** Add to `~/.continue/config.json`:
-
-```json
-{
-  "mcpServers": [
-    {
-      "name": "superlocalmemory",
-      "command": "npx",
-      "args": ["-y", "superlocalmemory", "mcp"]
-    }
-  ]
-}
-```
-
-## Zed
-
-**Auto:**
-
-```bash
-slm connect zed
-```
-
-**Manual:** Add to `~/.config/zed/settings.json`:
-
-```json
-{
-  "context_servers": {
-    "superlocalmemory": {
-      "command": {
-        "path": "npx",
-        "args": ["-y", "superlocalmemory", "mcp"]
-      }
-    }
-  }
-}
-```
-
-## Verifying the Connection
-
-After connecting any IDE, verify it works:
-
-1. Open a chat/prompt session in your IDE
-2. Ask: "What do you know about my preferences?"
-3. If SLM is connected, the AI will check your memories before responding
-
-Or run from the terminal:
-
-```bash
-slm status
-```
-
-Look for `Connected IDEs: claude, cursor, ...` in the output.
-
-## Troubleshooting
-
-### "slm command not found"
-
-The npm global bin directory is not in your PATH.
-
-```bash
-# Find where npm installs global packages
-npm root -g
-
-# Add the bin directory to your PATH
-# For zsh (~/.zshrc):
-export PATH="$(npm root -g)/../bin:$PATH"
-
-# For bash (~/.bashrc):
-export PATH="$(npm root -g)/../bin:$PATH"
-```
-
-### IDE does not detect SLM tools
-
-1. Ensure SLM is installed globally: `npm list -g superlocalmemory`
-2. Restart the IDE completely (not just reload)
-3. Check the MCP config file has correct JSON syntax
-4. Run `slm connect <ide>` to regenerate the config
-
-### "Connection refused" or timeout errors
-
-```bash
-# Test the MCP server directly
-npx superlocalmemory mcp --test
-
-# Check for port conflicts
-slm status --verbose
-```
-
-### Multiple IDE configs conflicting
-
-Each IDE has its own config file. They do not conflict. All IDEs share the same memory database at `~/.superlocalmemory/memory.db`.
-
----
-
-*SuperLocalMemory V3 — Copyright 2026 Varun Pratap Bhardwaj. Elastic License 2.0. Part of Qualixar.*

package/docs/mcp-tools.md

@@ -1,220 +0,0 @@
-# MCP Tools Reference
-> SuperLocalMemory V3 Documentation
-> https://superlocalmemory.com | Part of Qualixar
-
-SuperLocalMemory exposes 24 tools and 6 resources via the Model Context Protocol (MCP). Any MCP-compatible AI assistant can use these automatically.
-
----
-
-## Core Tools
-
-### `remember`
-
-Store a new memory.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `content` | string | Yes | The text to remember |
-| `tags` | string | No | Comma-separated tags |
-| `metadata` | object | No | Additional key-value metadata |
-
-### `recall`
-
-Search memories by natural language query.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `query` | string | Yes | Natural language search query |
-| `limit` | number | No | Max results (default: 10) |
-
-### `search`
-
-Search memories with filters. More control than `recall`.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `query` | string | Yes | Search query |
-| `limit` | number | No | Max results (default: 10) |
-| `tags` | string | No | Filter by tags |
-| `before` | string | No | Filter by date (ISO format) |
-| `after` | string | No | Filter by date (ISO format) |
-
-### `fetch`
-
-Retrieve a specific memory by ID.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `id` | number | Yes | Memory ID |
-
-### `list_recent`
-
-List the most recently stored memories.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `limit` | number | No | Max results (default: 20) |
-
-### `get_status`
-
-Returns system status: mode, profile, memory count, health, database path.
-
-*No parameters.*
-
-### `build_graph`
-
-Rebuild the entity relationship graph from stored memories. Useful after bulk imports.
-
-*No parameters.*
-
-### `switch_profile`
-
-Switch to a different memory profile.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `profile` | string | Yes | Profile name to switch to |
-
-### `backup_status`
-
-Check the status of automatic backups.
-
-*No parameters.*
-
-### `memory_used`
-
-Return memory usage statistics: total memories, database size, per-profile counts.
-
-*No parameters.*
-
-### `get_learned_patterns`
-
-Return patterns the system has learned from your usage (e.g., preferred technologies, coding conventions).
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `limit` | number | No | Max patterns to return (default: 10) |
-
-### `correct_pattern`
-
-Correct a learned pattern that is wrong or outdated.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `pattern_id` | number | Yes | ID of the pattern to correct |
-| `correction` | string | Yes | The corrected pattern text |
-
-### `get_attribution`
-
-Return attribution and provenance information for a specific memory.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `id` | number | Yes | Memory ID |
-
-## V2.8 Tools
-
-### `report_outcome`
-
-Report the outcome of using a memory (was it helpful?). Feeds the learning system.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `memory_id` | number | Yes | ID of the memory used |
-| `outcome` | string | Yes | `"helpful"`, `"wrong"`, or `"outdated"` |
-| `context` | string | No | Additional context about the outcome |
-
-### `get_lifecycle_status`
-
-Return lifecycle status for memories (Active, Warm, Cold, Archived).
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `limit` | number | No | Max results (default: 20) |
-| `status` | string | No | Filter by lifecycle stage |
-
-### `set_retention_policy`
-
-Apply a retention policy to the current profile.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `policy` | string | Yes | Policy name: `"indefinite"`, `"gdpr-30d"`, `"hipaa-7y"`, or `"custom"` |
-| `days` | number | No | Days for custom policy |
-
-### `compact_memories`
-
-Merge redundant memories and optimize storage.
-
-*No parameters.*
-
-### `get_behavioral_patterns`
-
-Return behavioral patterns observed across your usage (e.g., you always check docs before coding).
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `limit` | number | No | Max patterns to return (default: 10) |
-
-### `audit_trail`
-
-Return audit log entries. Each entry is hash-chained for tamper detection.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `limit` | number | No | Max entries (default: 50) |
-| `action` | string | No | Filter by action type: `"store"`, `"recall"`, `"delete"` |
-
-## V3 Tools
-
-### `set_mode`
-
-Switch the operating mode.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `mode` | string | Yes | `"a"`, `"b"`, or `"c"` |
-
-### `get_mode`
-
-Return the current operating mode and its configuration.
-
-*No parameters.*
-
-### `health`
-
-Return health diagnostics for mathematical layers (Fisher-Rao, Sheaf, Langevin), embedding model, and database.
-
-*No parameters.*
-
-### `consistency_check`
-
-Run contradiction detection across stored memories. Returns pairs of memories that may conflict.
-
-*No parameters.*
-
-### `recall_trace`
-
-Recall with a full breakdown of how each retrieval channel scored each result.
-
-| Parameter | Type | Required | Description |
-|-----------|------|:--------:|-------------|
-| `query` | string | Yes | Search query |
-| `limit` | number | No | Max results (default: 10) |
-
-## Resources
-
-MCP resources provide read-only data that AI assistants can access passively.
-
-| Resource URI | Description |
-|-------------|-------------|
-| `slm://recent` | The 20 most recently stored memories |
-| `slm://stats` | Memory count, database size, mode, profile |
-| `slm://clusters` | Topic clusters detected across memories |
-| `slm://identity` | Learned user preferences and patterns |
-| `slm://learning` | Current state of the adaptive learning system |
-| `slm://engagement` | Usage statistics and interaction patterns |
-
----
-
-*SuperLocalMemory V3 — Copyright 2026 Varun Pratap Bhardwaj. Elastic License 2.0. Part of Qualixar.*

package/docs/migration-from-v2.md

@@ -1,170 +0,0 @@
-# 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** | `~/.superlocalmemory/` | `~/.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 `~/.superlocalmemory/` to `~/.superlocalmemory/`
-3. Creates a symlink (`~/.superlocalmemory/ -> ~/.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 `~/.superlocalmemory/` 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. Elastic License 2.0. Part of Qualixar.*