superlocalmemory 3.4.17 → 3.4.18

package/docs/troubleshooting.md

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

package/docs/v2-archive/ACCESSIBILITY.md

@@ -1,291 +0,0 @@
-# Accessibility Features - SuperLocalMemory V2.6.5
-
-**Last Updated:** February 16, 2026
-**Author:** Varun Pratap Bhardwaj
-
----
-
-## Overview
-
-SuperLocalMemory V2.6.5 includes comprehensive keyboard navigation and screen reader support for the interactive knowledge graph, making it fully accessible to users with disabilities.
-
-## Keyboard Navigation
-
-### Graph Container Focus
-
-The graph container (`#graph-container`) is focusable via keyboard:
-
-- **Focus method:** Click graph OR press `Tab` from controls above
-- **Visual indicator:** Browser native focus outline + first node highlighted with blue border
-- **ARIA role:** `role="application"` signals custom keyboard handling
-
-### Node Navigation
-
-| Key | Action |
-|-----|--------|
-| **Tab** | Move to next node (cycles through all nodes) |
-| **Shift+Tab** | Move to previous node |
-| **→** (Right Arrow) | Move to nearest node on the right |
-| **←** (Left Arrow) | Move to nearest node on the left |
-| **↓** (Down Arrow) | Move to nearest node below |
-| **↑** (Up Arrow) | Move to nearest node above |
-| **Home** | Jump to first node |
-| **End** | Jump to last node |
-
-**Arrow Key Algorithm:**
-- Finds nodes in specified direction (based on X/Y coordinates)
-- Prioritizes nodes closer to current position
-- Combines Euclidean distance with directional score
-- Ensures no "stuck" states (always finds a valid next node)
-
-### Actions
-
-| Key | Action |
-|-----|--------|
-| **Enter** or **Space** | Open modal for focused node |
-| **Escape** | Clear active filter OR blur graph (if no filter) |
-
-### Visual Focus Indicator
-
-Focused nodes have the CSS class `.keyboard-focused` with:
-
-```css
-border-width: 5px;
-border-color: #0066ff;
-border-style: solid;
-box-shadow: 0 0 15px #0066ff;
-```
-
-The graph smoothly animates to center the focused node in the viewport.
-
----
-
-## Screen Reader Support
-
-### ARIA Attributes
-
-#### Graph Container
-
-```html
-<div id="graph-container"
-     role="application"
-     aria-label="Interactive knowledge graph - use Tab to navigate nodes, Enter to view details, Arrow keys to move between adjacent nodes, Escape to clear filters"
-     aria-describedby="graph-stats">
-</div>
-```
-
-- **`role="application"`** - Signals custom keyboard handling
-- **`aria-label`** - Provides usage instructions
-- **`aria-describedby`** - Links to graph statistics (node/edge count)
-
-#### Status Regions
-
-```html
-<div id="graph-status-full" role="status" aria-live="polite">
-    Showing all memories
-</div>
-
-<div id="graph-status-filtered" role="status" aria-live="polite">
-    Viewing Cluster X (Y memories)
-</div>
-```
-
-- **`role="status"`** - Semantic status information
-- **`aria-live="polite"`** - Announces changes when user is idle
-
-#### Hidden Status Region
-
-An off-screen status region announces keyboard navigation events:
-
-```html
-<div id="graph-sr-status"
-     role="status"
-     aria-live="polite"
-     aria-atomic="true"
-     style="position:absolute; left:-10000px; width:1px; height:1px; overflow:hidden;">
-</div>
-```
-
-This element is invisible but screen readers announce its content changes.
-
-#### Buttons
-
-All interactive buttons have `aria-label` attributes:
-
-```html
-<button aria-label="Refresh graph data">...</button>
-<button aria-label="Clear filter and show all memories">...</button>
-<button aria-label="Toggle dark mode">...</button>
-```
-
-#### Dropdowns
-
-Form controls have proper labels:
-
-```html
-<label for="graph-layout-selector">Layout Algorithm:</label>
-<select id="graph-layout-selector" aria-label="Select graph layout algorithm">
-```
-
-### Screen Reader Announcements
-
-The `updateScreenReaderStatus()` function announces:
-
-1. **Graph load:** "Graph loaded with X memories and Y connections"
-2. **Node navigation:** "Memory 123: SuperLocalMemory Project, Cluster 2, Importance 8 out of 10"
-3. **Filter cleared:** "Filters cleared, showing all memories"
-
-These announcements are sent to the hidden `#graph-sr-status` region.
-
----
-
-## Modal Focus Management
-
-### Opening Modal
-
-When `openMemoryModal()` is called:
-
-1. **Store last focused element:** `window.lastFocusedElement = document.activeElement`
-2. **Bootstrap modal shown event:** Focus moves to first button in modal
-3. **Tab order:** Close button → Modal content → Action buttons → Footer buttons
-
-### Closing Modal
-
-When modal closes (via Bootstrap `hidden.bs.modal` event):
-
-1. **Restore focus:** `window.lastFocusedElement.focus()`
-2. **Clear stored element:** `window.lastFocusedElement = null`
-3. **User can continue:** Keyboard navigation resumes from same node
-
-This ensures users don't lose their place in the graph when opening/closing modals.
-
----
-
-## Skip Links
-
-A skip link is provided for keyboard users:
-
-```html
-<a href="#memories-pane" class="visually-hidden-focusable">Skip to Memories list</a>
-```
-
-This link is invisible until focused (via Tab), allowing users to bypass the graph and jump directly to the Memories tab.
-
----
-
-## Testing with Screen Readers
-
-### macOS VoiceOver
-
-1. **Enable:** Press `Cmd+F5`
-2. **Navigate:** `Control+Option+Arrow keys`
-3. **Read current element:** `Control+Option+A`
-4. **Test focus:** Tab through graph → Verify announcements
-
-### Windows NVDA
-
-1. **Install:** Download from [nvaccess.org](https://www.nvaccess.org/)
-2. **Start:** `Control+Alt+N`
-3. **Navigate:** Arrow keys
-4. **Browse mode:** Press `Insert+Space` to toggle
-
-### Windows JAWS
-
-1. **Commercial software:** Most widely used screen reader
-2. **Navigate:** Arrow keys + Tab
-3. **Read mode:** Virtual cursor navigation
-
-### Linux Orca
-
-1. **Enable:** `Alt+F2`, type "orca"
-2. **Configure:** `orca --setup`
-3. **Navigate:** Arrow keys
-
----
-
-## Compliance
-
-### WCAG 2.1 AA Compliance
-
-| Criterion | Status | Implementation |
-|-----------|--------|----------------|
-| **1.3.1 Info and Relationships** | ✅ Pass | Semantic HTML, ARIA roles |
-| **2.1.1 Keyboard** | ✅ Pass | Full keyboard navigation |
-| **2.1.2 No Keyboard Trap** | ✅ Pass | Escape key blurs graph |
-| **2.4.3 Focus Order** | ✅ Pass | Logical tab order |
-| **2.4.7 Focus Visible** | ✅ Pass | Blue outline on focused nodes |
-| **3.2.1 On Focus** | ✅ Pass | No unexpected context changes |
-| **4.1.2 Name, Role, Value** | ✅ Pass | ARIA labels on all controls |
-| **4.1.3 Status Messages** | ✅ Pass | aria-live regions |
-
-### Section 508 Compliance
-
-- ✅ **(a) Keyboard access** - All graph functions accessible via keyboard
-- ✅ **(c) Color contrast** - Blue focus indicator meets 4.5:1 contrast ratio
-- ✅ **(d) Screen reader compatible** - ARIA labels and live regions
-
----
-
-## Developer Notes
-
-### Code Location
-
-- **Keyboard navigation:** `/ui/js/graph-cytoscape.js` (lines 950-1150)
-- **Modal focus management:** `/ui/js/modal.js` (lines 10-18, 142-160)
-- **ARIA attributes:** `/ui/index.html` (graph-pane section)
-
-### Key Functions
-
-| Function | Purpose |
-|----------|---------|
-| `setupKeyboardNavigation()` | Attaches keyboard event handlers to graph container |
-| `focusNodeAtIndex(index)` | Highlights node and centers viewport |
-| `moveToAdjacentNode(direction, currentNode)` | Finds nearest node in specified direction |
-| `announceNode(node)` | Sends node info to screen reader |
-| `updateScreenReaderStatus(message)` | Updates hidden status region |
-
-### Global State Variables
-
-```javascript
-var focusedNodeIndex = 0;              // Currently focused node index
-var keyboardNavigationEnabled = false; // Is keyboard nav active?
-var lastFocusedElement = null;         // For modal focus return
-```
-
-### Cytoscape.js Style Class
-
-```javascript
-{
-    selector: 'node.keyboard-focused',
-    style: {
-        'border-width': 5,
-        'border-color': '#0066ff',
-        'border-style': 'solid',
-        'box-shadow': '0 0 15px #0066ff'
-    }
-}
-```
-
----
-
-## Future Enhancements (v2.7+)
-
-1. **Voice commands:** Integrate Web Speech API for voice navigation
-2. **Braille support:** Test with refreshable Braille displays
-3. **High contrast mode:** Additional theme for low vision users
-4. **Keyboard shortcuts help:** Press `?` to show keyboard shortcuts overlay
-5. **Focus trapping in modal:** Prevent Tab from leaving modal when open
-
----
-
-## Feedback
-
-If you encounter accessibility issues, please report them:
-
-- **GitHub Issues:** https://github.com/qualixar/superlocalmemory/issues
-- **Label:** Use `accessibility` tag
-- **Include:** Browser, screen reader (if applicable), and steps to reproduce
-
----
-
-**Copyright © 2026 Varun Pratap Bhardwaj - AGPL-3.0**