superlocalmemory 3.4.17 → 3.4.19

package/docs/v2-archive/UI-SERVER.md

@@ -1,262 +0,0 @@
-# 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 with animated stat counters (ease-out cubic on page load)
-- **Memory Detail Modal**: Click any memory row to see full content, metadata, and tags in an overlay modal
-- **Dark Mode Toggle**: Sun/moon icon in the navbar; preference saved to localStorage and respects system preference (`prefers-color-scheme`)
-- **Export Functionality**:
-  - **Export All**: Download entire memory database as JSON or JSONL
-  - **Export Search Results**: Export current search results to JSON
-  - **Export as Markdown**: Export an individual memory as a Markdown file
-- **Search Score Bars**: Color-coded relevance bars in search results (red for low, yellow for medium, green for high relevance)
-- **Loading Spinners and Empty States**: Professional loading feedback and informative empty states across all tabs
-
-## 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 ~/.superlocalmemory/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: `~/.superlocalmemory/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
-- Create memory editing interface
-- Build cluster visualization with hierarchical layout
-- Add CSV export format alongside existing JSON/JSONL/Markdown exports
-
-## Support
-
-For issues or questions:
-1. Check the main README: `README.md`
-2. Review architecture docs: `docs/architecture/`
-3. Examine demo: `README.md`