superlocalmemory 2.3.0

package/docs/UI-SERVER.md

@@ -0,0 +1,254 @@
+# SuperLocalMemory V2 - UI Server
+
+Web-based visualization interface for exploring the SuperLocalMemory knowledge graph.
+
+## Features
+
+### 8 REST API Endpoints
+
+1. **GET /api/memories** - List memories with filtering (category, project, cluster, importance)
+2. **GET /api/graph** - Graph data for D3.js force-directed visualization
+3. **GET /api/clusters** - Cluster information with themes and members
+4. **GET /api/patterns** - Learned user preferences and coding patterns
+5. **GET /api/stats** - System statistics overview
+6. **POST /api/search** - Semantic search using TF-IDF similarity
+7. **GET /api/timeline** - Temporal view of memory creation
+8. **GET /api/tree** - Hierarchical tree structure
+
+### UI Features
+
+- **Knowledge Graph**: Interactive D3.js force-directed graph showing memory relationships
+- **Memory Browser**: Searchable table with filtering by category/project
+- **Cluster Analysis**: Visual breakdown of thematic clusters with top entities
+- **Pattern Viewer**: Display learned preferences and coding styles
+- **Timeline**: Chart showing memory creation over time
+- **Statistics Dashboard**: Real-time system metrics
+
+## Quick Start
+
+### 1. Install Dependencies
+
+```bash
+cd ~/Documents/AGENTIC_Official/SuperLocalMemoryV2-repo
+pip install -r requirements-ui.txt
+```
+
+### 2. Ensure Memory Database Exists
+
+The UI server requires an existing memory database. If you haven't created one yet:
+
+```bash
+# Create demo database with sample data
+python create_demo_db.py
+
+# OR use your existing ~/.claude-memory/memory.db
+```
+
+### 3. Start the Server
+
+```bash
+python ui_server.py
+```
+
+The server will start on **http://localhost:8765**
+
+### 4. Open UI
+
+Navigate to: **http://localhost:8765**
+
+Interactive API documentation: **http://localhost:8765/docs**
+
+## Usage
+
+### Exploring the Knowledge Graph
+
+1. Click **Knowledge Graph** tab
+2. Hover over nodes to see memory details
+3. Drag nodes to rearrange the layout
+4. Change max nodes using the dropdown (50/100/200)
+
+Node colors represent different clusters. Node size represents importance.
+
+### Searching Memories
+
+1. Click **Memories** tab
+2. Enter search query in the search box
+3. Or use filters: category, project
+4. View results in the table
+
+### Analyzing Clusters
+
+1. Click **Clusters** tab
+2. View thematic groupings of related memories
+3. Top entities show dominant concepts in each cluster
+
+### Viewing Learned Patterns
+
+1. Click **Patterns** tab
+2. See extracted preferences (tech stack, coding style, etc.)
+3. Confidence % shows pattern strength
+
+### Timeline Analysis
+
+1. Click **Timeline** tab
+2. View memory creation over last 30 days
+3. Identify activity patterns
+
+## API Examples
+
+### Get Memories (with filters)
+
+```bash
+curl "http://localhost:8765/api/memories?category=Frontend&limit=10"
+```
+
+### Search Memories
+
+```bash
+curl -X POST "http://localhost:8765/api/search" \
+  -H "Content-Type: application/json" \
+  -d '{"query": "react components", "limit": 10, "min_score": 0.3}'
+```
+
+### Get Graph Data
+
+```bash
+curl "http://localhost:8765/api/graph?max_nodes=100"
+```
+
+### Get Statistics
+
+```bash
+curl "http://localhost:8765/api/stats"
+```
+
+## Configuration
+
+### Database Path
+
+By default, the server uses:
+- Demo mode: `demo-memory.db` in the repo
+- Production: `~/.claude-memory/memory.db`
+
+To change the database path, modify `DB_PATH` in `ui_server.py`.
+
+### Server Port
+
+To change the port from the default (8765):
+
+```python
+# In ui_server.py, line ~650
+uvicorn.run(app, host="0.0.0.0", port=8080)  # Change 8765 to 8080
+```
+
+Or use command line:
+
+```bash
+uvicorn api_server:app --port 8080
+```
+
+### CORS (for external access)
+
+If accessing from a different domain, add CORS middleware:
+
+```python
+from fastapi.middleware.cors import CORSMiddleware
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+```
+
+## Architecture
+
+```
+ui_server.py           # FastAPI backend (8 endpoints)
+ui/
+  ├── index.html        # Single-page UI
+  └── app.js            # Frontend JavaScript (D3.js + Bootstrap)
+```
+
+### Tech Stack
+
+**Backend:**
+- FastAPI - Modern Python web framework
+- Uvicorn - ASGI server
+- SQLite - Database queries
+
+**Frontend:**
+- Bootstrap 5 - UI framework
+- D3.js v7 - Force-directed graph visualization
+- Vanilla JavaScript - No build step required
+
+## Troubleshooting
+
+### Server won't start
+
+**Error: `Memory database not found`**
+
+Solution: Create database first:
+```bash
+python create_demo_db.py
+```
+
+**Error: `ModuleNotFoundError: No module named 'fastapi'`**
+
+Solution: Install requirements:
+```bash
+pip install -r requirements-ui.txt
+```
+
+### Graph not displaying
+
+Check browser console for errors. Common issues:
+- Database has no graph data (run graph engine first)
+- No memories with cluster_id set
+
+To build graph:
+```bash
+python -c "from src.graph_engine import GraphEngine; GraphEngine().build_graph()"
+```
+
+### Search returns no results
+
+TF-IDF search requires:
+1. Multiple memories in database
+2. Diverse vocabulary
+3. Query matching content keywords
+
+Try broader search terms or check if vectors are built.
+
+## Performance Notes
+
+- **Graph rendering**: Limited to 200 nodes max to ensure smooth interaction
+- **Memory list**: Paginated (50 per page default)
+- **Search**: O(n) vector similarity, fast for <10k memories
+- **Timeline**: Cached for 5 minutes
+
+## Security
+
+This UI server is intended for **local development** only.
+
+**Do NOT expose to public internet without:**
+- Authentication (OAuth, API keys)
+- Input validation and sanitization
+- Rate limiting
+- HTTPS/TLS
+
+## Next Steps
+
+- Add authentication for multi-user access
+- Implement real-time updates via WebSockets
+- Add export functionality (JSON, CSV)
+- Create memory editing interface
+- Build cluster visualization with hierarchical layout
+
+## Support
+
+For issues or questions:
+1. Check the main README: `README.md`
+2. Review architecture docs: `docs/architecture/`
+3. Examine demo: `README.md`

package/docs/UNIVERSAL-INTEGRATION.md

@@ -0,0 +1,432 @@
+# Universal Integration Guide
+
+**Version:** 2.3.0-universal
+**Status:** Production Ready
+**Updated:** February 7, 2026
+
+---
+
+## Overview
+
+SuperLocalMemory V2 now works across **16+ IDEs and CLI tools** with automatic detection and configuration. This guide shows you how to use it in every supported environment.
+
+---
+
+## Quick Start
+
+### Step 1: Install
+```bash
+git clone https://github.com/varun369/SuperLocalMemoryV2.git
+cd SuperLocalMemoryV2
+./install.sh
+```
+
+The installer automatically:
+- ✅ Detects your installed IDEs (Cursor, Windsurf, Claude Desktop, VS Code)
+- ✅ Configures MCP servers where supported
+- ✅ Sets up CLI tools and completions
+- ✅ Configures skills for Continue.dev and Cody
+- ✅ No manual configuration needed!
+
+### Step 2: Restart Your Tools
+After installation, restart any IDE you want to use SuperLocalMemory with.
+
+### Step 3: Start Using It
+- **In Cursor/Windsurf:** Just talk naturally - "Remember that we use FastAPI for APIs"
+- **In Claude Code:** Use `/superlocalmemoryv2:remember` or the new `slm` commands
+- **In Terminal:** Use `slm remember "content"`
+
+---
+
+## Integration by Tool
+
+### Claude Code (Skills) ✅
+
+**How It Works:** Native skills via `/` commands
+
+**Setup:** Automatic during installation
+
+**Usage:**
+```
+/superlocalmemoryv2:remember "Use FastAPI for REST APIs"
+/superlocalmemoryv2:recall "FastAPI"
+/superlocalmemoryv2:list
+/superlocalmemoryv2:status
+/superlocalmemoryv2:profile list
+```
+
+**OR use the simpler CLI:**
+```bash
+slm remember "Use FastAPI for REST APIs"
+slm recall "FastAPI"
+slm list
+slm status
+```
+
+### Cursor IDE (MCP) ✅
+
+**How It Works:** Native MCP integration - AI has direct tool access
+
+**Setup:** Automatic detection and configuration
+
+**Configuration File:** `~/.cursor/mcp_settings.json` (auto-created)
+
+**Usage:**
+```
+User: "Remember that we prefer React hooks over class components"
+AI: [calls remember() tool automatically]
+✓ Memory saved
+
+User: "What did we decide about React?"
+AI: [calls recall() tool automatically]
+✓ Returns: "We prefer React hooks over class components"
+```
+
+**Manual Configuration (if needed):**
+```json
+{
+  "mcpServers": {
+    "superlocalmemory-v2": {
+      "command": "python3",
+      "args": [
+        "/Users/yourname/.claude-memory/mcp_server.py"
+      ]
+    }
+  }
+}
+```
+
+### Windsurf IDE (MCP) ✅
+
+**How It Works:** Native MCP integration with stdio transport
+
+**Setup:** Automatic detection and configuration
+
+**Configuration File:** `~/.windsurf/mcp_settings.json` (auto-created)
+
+**Usage:** Same as Cursor - AI automatically uses memory tools
+
+**Manual Configuration (if needed):**
+```json
+{
+  "mcpServers": {
+    "superlocalmemory-v2": {
+      "command": "python3",
+      "args": ["/Users/yourname/.claude-memory/mcp_server.py"],
+      "transport": "stdio"
+    }
+  }
+}
+```
+
+### Claude Desktop (MCP) ✅
+
+**How It Works:** Native MCP server support
+
+**Setup:** Automatic configuration
+
+**Configuration File:** `~/Library/Application Support/Claude/claude_desktop_config.json` (auto-created)
+
+**Usage:** Natural conversation with AI having memory access
+
+**Manual Configuration (if needed):**
+```json
+{
+  "mcpServers": {
+    "superlocalmemory-v2": {
+      "command": "python3",
+      "args": ["/Users/yourname/.claude-memory/mcp_server.py"],
+      "env": {
+        "PYTHONPATH": "/Users/yourname/.claude-memory"
+      }
+    }
+  }
+}
+```
+
+### VS Code + Continue.dev ✅
+
+**How It Works:** Both MCP tools AND slash commands
+
+**Setup:** Automatic configuration if Continue detected
+
+**Configuration File:** `~/.continue/config.yaml`
+
+**Usage (Slash Commands):**
+```
+/slm-remember Use pytest for all tests
+/slm-recall pytest patterns
+/slm-list
+/slm-status
+```
+
+**Usage (MCP):**
+Continue's AI can also call memory tools directly.
+
+**Manual Configuration (if needed):**
+```yaml
+# For slash commands
+slashCommands:
+  - name: "slm-remember"
+    description: "Save to SuperLocalMemory"
+    run: "~/.claude-memory/bin/superlocalmemoryv2:remember \"{{input}}\""
+
+# For MCP tools
+contextProviders:
+  - name: mcp
+    params:
+      serverName: "superlocalmemory-v2"
+      command: "python3"
+      args:
+        - "/Users/yourname/.claude-memory/mcp_server.py"
+```
+
+### VS Code + Cody ✅
+
+**How It Works:** Custom commands
+
+**Setup:** Automatic configuration if Cody detected
+
+**Configuration File:** `~/.vscode/settings.json`
+
+**Usage:**
+```
+/slm-remember (with text selected)
+/slm-recall search query
+/slm-context (get project context)
+```
+
+**Manual Configuration (if needed):**
+```json
+{
+  "cody.customCommands": {
+    "slm-remember": {
+      "description": "Save to SuperLocalMemory",
+      "prompt": "Save this to SuperLocalMemory",
+      "context": {
+        "selection": true
+      }
+    }
+  }
+}
+```
+
+### Aider CLI ✅
+
+**How It Works:** Smart wrapper with auto-context injection
+
+**Setup:** `aider-smart` command installed automatically
+
+**Usage:**
+```bash
+# Instead of: aider
+# Use: aider-smart
+
+aider-smart "Add authentication to the API"
+```
+
+**What It Does:**
+1. Automatically gathers project context from SuperLocalMemory
+2. Includes your coding patterns
+3. Passes context to Aider
+4. Aider gets relevant memories without you asking
+
+### Any Terminal / Script ✅
+
+**How It Works:** Universal CLI wrapper
+
+**Commands Installed:**
+- `slm` - Main command
+- All original `superlocalmemoryv2:*` commands still work
+
+**Usage:**
+```bash
+# Simple syntax
+slm remember "Use PostgreSQL for this project"
+slm recall "database decisions"
+slm list
+slm status
+slm context  # Get context for current directory
+
+# Profile management
+slm profile list
+slm profile create work
+slm profile switch work
+
+# Knowledge graph
+slm graph build
+slm graph stats
+
+# Pattern learning
+slm patterns update
+slm patterns list 0.6
+```
+
+**Bash Completion:**
+```bash
+slm [TAB]  # Shows: remember, recall, list, status, context, profile, graph, patterns
+slm profile [TAB]  # Shows: list, create, switch, delete, current
+```
+
+---
+
+## Three-Tier Architecture
+
+All access methods use the **SAME local SQLite database**:
+
+```
+┌─────────────────────────────────────────────┐
+│            ACCESS METHODS                   │
+├─────────────────────────────────────────────┤
+│ TIER 1: Skills                              │
+│  • Claude Code: /superlocalmemoryv2:*       │
+│  • Continue: /slm-*                         │
+│  • Cody: /slm-*                            │
+├─────────────────────────────────────────────┤
+│ TIER 2: MCP                                 │
+│  • Cursor: AI tools                         │
+│  • Windsurf: AI tools                       │
+│  • Claude Desktop: AI tools                 │
+│  • Continue: MCP providers                  │
+├─────────────────────────────────────────────┤
+│ TIER 3: CLI                                 │
+│  • slm commands                             │
+│  • aider-smart wrapper                      │
+│  • Any script                              │
+└────────────────┬────────────────────────────┘
+                 │
+                 ▼
+         ┌───────────────────┐
+         │ SuperLocalMemory   │
+         │ Core (Unchanged)   │
+         │ memory.db (SQLite) │
+         └───────────────────┘
+```
+
+**Key Point:** No matter which method you use, all data goes to the same place. You can use `/superlocalmemoryv2:remember` in Claude Code, then `slm recall` in terminal, and see the same memories.
+
+---
+
+## Troubleshooting
+
+### "MCP server won't start"
+
+**Check MCP SDK:**
+```bash
+python3 -c "import mcp" && echo "OK" || echo "Not installed"
+```
+
+**Install if needed:**
+```bash
+pip3 install mcp
+```
+
+### "Skills not working in Claude Code"
+
+**Run skills installer:**
+```bash
+./install-skills.sh
+```
+
+**Restart Claude Code after installation.**
+
+### "Continue.dev doesn't have slash commands"
+
+**Check config:**
+```bash
+cat ~/.continue/config.yaml
+```
+
+**Should contain `slm-remember`, `slm-recall`, etc.**
+
+**Re-run installer if missing:**
+```bash
+./install-skills.sh
+```
+
+### "slm command not found"
+
+**Check PATH:**
+```bash
+echo $PATH | grep claude-memory
+```
+
+**Add to PATH if missing:**
+```bash
+# Add to ~/.zshrc or ~/.bashrc
+export PATH="${HOME}/.claude-memory/bin:${PATH}"
+
+# Then reload
+source ~/.zshrc  # or ~/.bashrc
+```
+
+### "Existing tools not detected during install"
+
+**Install detects tools at installation time only.**
+
+**If you install a new IDE after running install.sh:**
+1. Run the installer again: `./install.sh`
+2. It will detect and configure the new tool
+3. Won't affect existing configurations
+
+---
+
+## Advanced: Manual MCP Server Testing
+
+**Start MCP server manually:**
+```bash
+python3 ~/.claude-memory/mcp_server.py
+```
+
+**Start with HTTP transport:**
+```bash
+python3 ~/.claude-memory/mcp_server.py --transport http --port 8001
+```
+
+**Check MCP server tools:**
+```bash
+# Server outputs available tools on startup
+# Look for: remember, recall, list_recent, get_status, build_graph, switch_profile
+```
+
+---
+
+## Backward Compatibility
+
+**100% backward compatible with v2.0.0:**
+
+| Old Command | Still Works? | New Alternative |
+|-------------|--------------|-----------------|
+| `superlocalmemoryv2:remember` | ✅ Yes | `slm remember` |
+| `superlocalmemoryv2:recall` | ✅ Yes | `slm recall` |
+| `superlocalmemoryv2:list` | ✅ Yes | `slm list` |
+| `superlocalmemoryv2:status` | ✅ Yes | `slm status` |
+| `superlocalmemoryv2:profile` | ✅ Yes | `slm profile` |
+
+**Nothing breaks. Everything gains new capabilities.**
+
+---
+
+## Supported Platforms
+
+- ✅ macOS (tested on macOS 14+)
+- ✅ Linux (tested on Ubuntu 22.04+)
+- ✅ Windows via WSL2
+- ✅ Windows PowerShell (use `install.ps1`)
+
+---
+
+## What's Next?
+
+- **For most users:** Just use it! Works automatically after installation.
+- **For advanced users:** See [MCP-INTEGRATION.md](./MCP-INTEGRATION.md) for deep dive
+- **For CLI users:** See [CLI-UNIVERSAL.md](./CLI-UNIVERSAL.md) for all slm commands
+- **For skill users:** See [SKILLS-EVERYWHERE.md](./SKILLS-EVERYWHERE.md) for multi-tool skills
+
+---
+
+**Questions?** Open an issue: https://github.com/varun369/SuperLocalMemoryV2/issues
+
+**Version:** 2.3.0-universal
+**Author:** Varun Pratap Bhardwaj
+**License:** MIT