superlocalmemory 2.8.5 → 3.0.0

package/docs/getting-started.md

@@ -0,0 +1,102 @@
+# Getting Started
+> SuperLocalMemory V3 Documentation
+> https://superlocalmemory.com | Part of Qualixar
+
+Get your AI's memory system running in under 5 minutes.
+
+---
+
+## Prerequisites
+
+- **Node.js** 18 or later
+- **Python** 3.10 or later (installed automatically on most systems)
+- An AI coding tool (Claude Code, Cursor, VS Code, Windsurf, or any MCP-compatible IDE)
+
+## Install
+
+```bash
+npm install -g superlocalmemory
+```
+
+This installs the `slm` command globally.
+
+## Run the Setup Wizard
+
+```bash
+slm setup
+```
+
+The wizard walks you through three choices:
+
+1. **Pick your mode**
+   - **Mode A** (default) — Zero cloud. All memory stays on your machine. No API key needed.
+   - **Mode B** — Local LLM. Uses Ollama on your machine for smarter recall.
+   - **Mode C** — Cloud LLM. Uses OpenAI, Anthropic, or another provider for maximum power.
+
+2. **Connect your IDE** — The wizard detects installed IDEs and configures them automatically.
+
+3. **Verify installation** — A quick self-test confirms everything works.
+
+> **Tip:** Start with Mode A. You can switch to B or C anytime with `slm mode b` or `slm mode c`.
+
+## Store Your First Memory
+
+```bash
+slm remember "The project uses PostgreSQL 16 on port 5433, not the default 5432"
+```
+
+You should see:
+
+```
+Stored memory #1 (Mode A, profile: default)
+```
+
+## Recall a Memory
+
+```bash
+slm recall "what database port do we use"
+```
+
+Output:
+
+```
+[1] The project uses PostgreSQL 16 on port 5433, not the default 5432
+    Score: 0.94 | Stored: 2 minutes ago | Profile: default
+```
+
+## Check System Status
+
+```bash
+slm status
+```
+
+This shows:
+
+- Current mode (A, B, or C)
+- Active profile
+- Total memories stored
+- Database location
+- Health of math layers (Fisher, Sheaf, Langevin)
+
+## How It Works With Your IDE
+
+Once connected, SuperLocalMemory works automatically:
+
+- **Auto-recall** — When your AI assistant responds, relevant memories are injected as context. No manual queries needed.
+- **Auto-capture** — Decisions, bug fixes, architecture choices, and preferences are stored as you work. No manual tagging needed.
+
+You can still use `slm remember` and `slm recall` from the terminal whenever you want explicit control.
+
+## Next Steps
+
+| What you want to do | Guide |
+|---------------------|-------|
+| Set up a specific IDE | [IDE Setup](ide-setup.md) |
+| Switch modes or providers | [Configuration](configuration.md) |
+| Learn all CLI commands | [CLI Reference](cli-reference.md) |
+| Migrate from V2 | [Migration from V2](migration-from-v2.md) |
+| Understand how it works | [Architecture](architecture.md) |
+
+---
+
+*SuperLocalMemory V3 — Copyright 2026 Varun Pratap Bhardwaj. MIT License. Part of Qualixar.*

package/docs/ide-setup.md

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

package/docs/mcp-tools.md

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