superlocalmemory 2.6.0 → 2.6.5

package/docs/ACCESSIBILITY.md

@@ -0,0 +1,291 @@
+# 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/varun369/SuperLocalMemoryV2/issues
+- **Label:** Use `accessibility` tag
+- **Include:** Browser, screen reader (if applicable), and steps to reproduce
+
+---
+
+**Copyright © 2026 Varun Pratap Bhardwaj - MIT License**

package/docs/FRAMEWORK-INTEGRATIONS.md

@@ -0,0 +1,300 @@
+# Framework Integrations
+
+SuperLocalMemory V2 integrates with popular AI frameworks as a memory backend — 100% local, zero cloud dependencies.
+
+---
+
+## LangChain Integration
+
+Use SuperLocalMemory as a chat message history store in LangChain applications.
+
+### Installation
+
+```bash
+pip install langchain-superlocalmemory
+```
+
+### Basic Usage
+
+```python
+from langchain_superlocalmemory import SuperLocalMemoryChatMessageHistory
+from langchain_core.runnables.history import RunnableWithMessageHistory
+from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
+from langchain_openai import ChatOpenAI
+
+# Create chat history with session-based memory
+history = SuperLocalMemoryChatMessageHistory(session_id="my-session")
+
+# Build a conversational chain
+prompt = ChatPromptTemplate.from_messages([
+    ("system", "You are a helpful assistant."),
+    MessagesPlaceholder(variable_name="history"),
+    ("human", "{input}"),
+])
+
+chain = prompt | ChatOpenAI()
+
+# Wrap with message history
+chain_with_history = RunnableWithMessageHistory(
+    chain,
+    lambda session_id: SuperLocalMemoryChatMessageHistory(session_id=session_id),
+    input_messages_key="input",
+    history_messages_key="history",
+)
+
+# Use the chain
+response = chain_with_history.invoke(
+    {"input": "What is AI?"},
+    config={"configurable": {"session_id": "my-session"}}
+)
+```
+
+### Advanced Features
+
+**Session Isolation:**
+```python
+# Different sessions have isolated message histories
+history_user1 = SuperLocalMemoryChatMessageHistory(session_id="user-1")
+history_user2 = SuperLocalMemoryChatMessageHistory(session_id="user-2")
+```
+
+**Profile Support:**
+```python
+# Use different memory profiles for different contexts
+history_work = SuperLocalMemoryChatMessageHistory(
+    session_id="work-chat",
+    profile="work"
+)
+history_personal = SuperLocalMemoryChatMessageHistory(
+    session_id="personal-chat",
+    profile="personal"
+)
+```
+
+**Message Filtering:**
+```python
+# Retrieve messages with limits
+recent_messages = history.get_messages(limit=10)
+
+# Clear session history
+history.clear()
+```
+
+### Storage Details
+
+- Messages persist in `~/.claude-memory/memory.db`
+- Each message stored as a memory with tags: `langchain`, `chat`, `session:<session_id>`
+- Supports all LangChain message types (HumanMessage, AIMessage, SystemMessage)
+- Automatic timestamp and metadata tracking
+
+---
+
+## LlamaIndex Integration
+
+Use SuperLocalMemory as a chat store for LlamaIndex's memory system.
+
+### Installation
+
+```bash
+pip install llama-index-storage-chat-store-superlocalmemory
+```
+
+### Basic Usage
+
+```python
+from llama_index.storage.chat_store.superlocalmemory import SuperLocalMemoryChatStore
+from llama_index.core.memory import ChatMemoryBuffer
+from llama_index.core.chat_engine import SimpleChatEngine
+from llama_index.llms.openai import OpenAI
+
+# Create chat store
+chat_store = SuperLocalMemoryChatStore()
+
+# Create memory with chat store
+memory = ChatMemoryBuffer.from_defaults(
+    chat_store=chat_store,
+    chat_store_key="user-1"
+)
+
+# Use with a chat engine
+llm = OpenAI(model="gpt-4")
+chat_engine = SimpleChatEngine.from_defaults(
+    llm=llm,
+    memory=memory
+)
+
+# Chat
+response = chat_engine.chat("What is machine learning?")
+print(response)
+```
+
+### Advanced Features
+
+**Multiple Users:**
+```python
+# Separate memory for each user
+memory_user1 = ChatMemoryBuffer.from_defaults(
+    chat_store=chat_store,
+    chat_store_key="user-1"
+)
+memory_user2 = ChatMemoryBuffer.from_defaults(
+    chat_store=chat_store,
+    chat_store_key="user-2"
+)
+```
+
+**Profile Support:**
+```python
+# Use different profiles for different contexts
+chat_store_work = SuperLocalMemoryChatStore(profile="work")
+chat_store_personal = SuperLocalMemoryChatStore(profile="personal")
+
+memory_work = ChatMemoryBuffer.from_defaults(
+    chat_store=chat_store_work,
+    chat_store_key="project-x"
+)
+```
+
+**Message Management:**
+```python
+# Get messages for a specific chat
+messages = chat_store.get_messages("user-1")
+
+# Set messages
+from llama_index.core.base.llms.types import ChatMessage
+chat_store.set_messages(
+    "user-1",
+    [ChatMessage(role="user", content="Hello")]
+)
+
+# Delete messages
+chat_store.delete_messages("user-1")
+
+# List all chat keys
+all_chats = chat_store.get_keys()
+```
+
+### Storage Details
+
+- Messages persist in `~/.claude-memory/memory.db`
+- Each message stored as a memory with tags: `llamaindex`, `chat`, `key:<chat_store_key>`
+- Supports all LlamaIndex ChatMessage roles (user, assistant, system)
+- Automatic timestamp tracking
+- Full profile isolation support
+
+---
+
+## Why Use SuperLocalMemory with Frameworks?
+
+| Benefit | Description |
+|---------|-------------|
+| **100% Local** | No cloud dependencies, all data stays on your machine |
+| **Zero Configuration** | Works with default settings, no API keys needed |
+| **Cross-Framework** | Same local database used by all frameworks and tools |
+| **Profile Isolation** | Separate memories for work, personal, clients |
+| **Persistent** | Memories survive across sessions and reboots |
+| **Free Forever** | No usage limits, no subscriptions |
+
+---
+
+## Common Patterns
+
+### Multi-Context Applications
+
+```python
+# LangChain for customer support
+support_history = SuperLocalMemoryChatMessageHistory(
+    session_id="customer-123",
+    profile="customer-support"
+)
+
+# LlamaIndex for internal documentation
+docs_store = SuperLocalMemoryChatStore(profile="internal-docs")
+docs_memory = ChatMemoryBuffer.from_defaults(
+    chat_store=docs_store,
+    chat_store_key="team-wiki"
+)
+```
+
+### Session Management
+
+```python
+# Create sessions with metadata
+from langchain_core.messages import HumanMessage, AIMessage
+
+history = SuperLocalMemoryChatMessageHistory(session_id="session-123")
+history.add_user_message("What is Python?")
+history.add_ai_message("Python is a high-level programming language...")
+
+# Later, retrieve full conversation
+messages = history.get_messages()
+```
+
+### Memory Cleanup
+
+```python
+# LangChain: Clear specific session
+history.clear()
+
+# LlamaIndex: Delete specific chat
+chat_store.delete_messages("user-1")
+
+# CLI: Reset entire profile
+# superlocalmemoryv2:reset soft --profile customer-support
+```
+
+---
+
+## Troubleshooting
+
+### Import Errors
+
+If you get import errors, ensure packages are installed:
+
+```bash
+# For LangChain
+pip install langchain-superlocalmemory langchain-core
+
+# For LlamaIndex
+pip install llama-index-storage-chat-store-superlocalmemory llama-index-core
+```
+
+### Database Locked
+
+If you see "database is locked" errors:
+
+```bash
+# Check if SuperLocalMemory is running correctly
+superlocalmemoryv2:status
+
+# Restart any MCP servers
+# (Close and reopen Cursor/Windsurf)
+```
+
+### Profile Not Found
+
+If a profile doesn't exist:
+
+```bash
+# List available profiles
+superlocalmemoryv2:profile list
+
+# Create the profile
+superlocalmemoryv2:profile create work
+```
+
+---
+
+## Learn More
+
+- **[LangChain Wiki Guide](https://github.com/varun369/SuperLocalMemoryV2/wiki/LangChain-Integration)** — Full integration tutorial
+- **[LlamaIndex Wiki Guide](https://github.com/varun369/SuperLocalMemoryV2/wiki/LlamaIndex-Integration)** — Complete setup guide
+- **[API Reference](API-REFERENCE.md)** — Python API documentation
+- **[Profiles Guide](PROFILES-GUIDE.md)** — Multi-context management
+
+---
+
+<p align="center">
+  <strong>Built by <a href="https://github.com/varun369">Varun Pratap Bhardwaj</a></strong><br/>
+  MIT License • <a href="https://superlocalmemory.com">superlocalmemory.com</a>
+</p>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlocalmemory",
-  "version": "2.6.0",
+  "version": "2.6.5",
   "description": "Your AI Finally Remembers You - Local-first intelligent memory system for AI assistants. Works with Claude, Cursor, Windsurf, VS Code/Copilot, Codex, and 17+ AI tools. 100% local, zero cloud dependencies.",
   "keywords": [
     "ai-memory",