superlocalmemory 2.6.0 → 2.7.0

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/docs/MCP-MANUAL-SETUP.md

@@ -683,7 +683,7 @@ python3 ~/.claude-memory/mcp_server.py
 ```
 ============================================================
 SuperLocalMemory V2 - MCP Server
-Version: 2.4.1
+Version: 2.7.0
 ============================================================
 
 Transport: stdio
@@ -692,10 +692,16 @@ Database: /Users/yourusername/.claude-memory/memory.db
 MCP Tools Available:
   - remember(content, tags, project, importance)
   - recall(query, limit, min_score)
+  - search(query)          [ChatGPT Connector]
+  - fetch(id)              [ChatGPT Connector]
   - list_recent(limit)
   - get_status()
   - build_graph()
   - switch_profile(name)
+  - backup_status()        [Auto-Backup]
+  - memory_used(...)       [v2.7 Learning]
+  - get_learned_patterns(...)  [v2.7 Learning]
+  - correct_pattern(...)   [v2.7 Learning]
 
 ...
 ```
@@ -731,7 +737,7 @@ In your IDE/app, check:
 
 ## Available MCP Tools
 
-Once configured, these 8 tools are available:
+Once configured, these 12 tools are available:
 
 | Tool | Purpose | Example Usage |
 |------|---------|---------------|
@@ -743,10 +749,14 @@ Once configured, these 8 tools are available:
 | `switch_profile()` | Change profile | "Switch to work profile" |
 | `search()` | Search memories (OpenAI MCP spec) | Used by ChatGPT Connectors and Deep Research |
 | `fetch()` | Fetch memory by ID (OpenAI MCP spec) | Used by ChatGPT Connectors and Deep Research |
+| `backup_status()` | Auto-backup status | "What's the backup status?" |
+| `memory_used()` | Feedback for learning (v2.7) | Implicit — called when a recalled memory is used |
+| `get_learned_patterns()` | Retrieve learned patterns (v2.7) | "What patterns have you learned about me?" |
+| `correct_pattern()` | Correct a learned pattern (v2.7) | "I actually prefer Vue, not React" |
 
-**Note:** `search()` and `fetch()` are required by OpenAI's MCP specification for ChatGPT Connectors. They are available in all transports but primarily used by ChatGPT.
+**Note:** `search()` and `fetch()` are required by OpenAI's MCP specification for ChatGPT Connectors. They are available in all transports but primarily used by ChatGPT. The 3 learning tools (`memory_used`, `get_learned_patterns`, `correct_pattern`) require v2.7's optional learning dependencies.
 
-Plus **2 MCP prompts** and **4 MCP resources** for advanced use.
+Plus **2 MCP prompts** and **6 MCP resources** for advanced use.
 
 ---
 

package/install.sh

@@ -57,18 +57,87 @@ if [ "$NON_INTERACTIVE" = true ]; then
     echo ""
 fi
 
-# Check Python version
+# Check Python version — install if missing (non-tech user friendly)
 echo "Checking Python version..."
+
+install_python() {
+    echo ""
+    echo "Python 3 not found. Attempting automatic installation..."
+    if [ "$(uname)" = "Darwin" ]; then
+        # macOS: try Homebrew first, then Xcode CLI tools
+        if command -v brew &> /dev/null; then
+            echo "Installing Python via Homebrew..."
+            brew install python3 && return 0
+        fi
+        # Try installing Xcode Command Line Tools (includes Python 3)
+        echo "Installing Xcode Command Line Tools (includes Python 3)..."
+        echo "A system dialog may appear — click 'Install' to continue."
+        xcode-select --install 2>/dev/null
+        # Wait for user to complete the install dialog
+        echo "Waiting for Xcode CLI tools installation to complete..."
+        echo "Press Enter after the installation finishes."
+        if [ "$NON_INTERACTIVE" = false ]; then
+            read -r
+        else
+            # In non-interactive mode, wait and retry
+            sleep 30
+        fi
+        if command -v python3 &> /dev/null; then
+            return 0
+        fi
+        # Last resort: direct Python.org installer
+        echo ""
+        echo "Automatic installation could not complete."
+        echo "Please install Python 3.10+ from: https://www.python.org/downloads/"
+        echo "Then re-run this installer."
+        return 1
+    elif [ -f /etc/debian_version ]; then
+        # Debian/Ubuntu
+        echo "Installing Python via apt..."
+        sudo apt-get update -qq && sudo apt-get install -y python3 python3-pip && return 0
+    elif [ -f /etc/redhat-release ]; then
+        # RHEL/CentOS/Fedora
+        echo "Installing Python via dnf..."
+        sudo dnf install -y python3 python3-pip && return 0
+    elif [ -f /etc/arch-release ]; then
+        # Arch Linux
+        sudo pacman -S --noconfirm python python-pip && return 0
+    fi
+    echo "Could not auto-install Python. Please install Python 3.8+ manually."
+    echo "  macOS:  brew install python3"
+    echo "  Ubuntu: sudo apt install python3 python3-pip"
+    echo "  Fedora: sudo dnf install python3 python3-pip"
+    return 1
+}
+
+if ! command -v python3 &> /dev/null; then
+    install_python || exit 1
+fi
+
 PYTHON_VERSION=$(python3 -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')
 PYTHON_MAJOR=$(python3 -c 'import sys; print(sys.version_info.major)')
 PYTHON_MINOR=$(python3 -c 'import sys; print(sys.version_info.minor)')
 
 if [ "$PYTHON_MAJOR" -lt 3 ] || ([ "$PYTHON_MAJOR" -eq 3 ] && [ "$PYTHON_MINOR" -lt 8 ]); then
-    echo "✗ Error: Python 3.8+ required (found $PYTHON_VERSION)"
-    exit 1
+    echo "Python $PYTHON_VERSION found but 3.8+ required."
+    install_python || exit 1
+    # Re-check after install
+    PYTHON_VERSION=$(python3 -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')
+    PYTHON_MAJOR=$(python3 -c 'import sys; print(sys.version_info.major)')
+    PYTHON_MINOR=$(python3 -c 'import sys; print(sys.version_info.minor)')
+    if [ "$PYTHON_MAJOR" -lt 3 ] || ([ "$PYTHON_MAJOR" -eq 3 ] && [ "$PYTHON_MINOR" -lt 8 ]); then
+        echo "✗ Error: Python 3.8+ still not available after install attempt"
+        exit 1
+    fi
 fi
 echo "✓ Python $PYTHON_VERSION"
 
+# Ensure pip3 is available
+if ! command -v pip3 &> /dev/null; then
+    echo "Installing pip..."
+    python3 -m ensurepip --upgrade 2>/dev/null || python3 -c "import urllib.request; urllib.request.urlretrieve('https://bootstrap.pypa.io/get-pip.py', '/tmp/get-pip.py')" && python3 /tmp/get-pip.py 2>/dev/null || true
+fi
+
 # Create installation directory
 echo ""
 echo "Creating installation directory..."
@@ -88,6 +157,13 @@ echo "Copying source files..."
 cp -r "${REPO_DIR}/src/"* "${INSTALL_DIR}/"
 echo "✓ Source files copied"
 
+# Copy learning modules explicitly (v2.7+ — ensures nested dir is handled)
+if [ -d "${REPO_DIR}/src/learning" ]; then
+    mkdir -p "${INSTALL_DIR}/learning"
+    cp -r "${REPO_DIR}/src/learning/"* "${INSTALL_DIR}/learning/"
+    echo "✓ Learning modules copied"
+fi
+
 # Copy hooks
 echo "Copying hooks..."
 mkdir -p "${INSTALL_DIR}/hooks"
@@ -205,6 +281,22 @@ else
     echo "⚠️  requirements-core.txt not found, skipping dependency installation"
 fi
 
+# Install learning dependencies (v2.7+)
+echo ""
+echo "Installing learning dependencies..."
+echo "  Enables intelligent pattern learning and personalized recall"
+
+if [ -f "${REPO_DIR}/requirements-learning.txt" ]; then
+    if pip3 install $PIP_FLAGS -q -r "${REPO_DIR}/requirements-learning.txt" 2>/dev/null; then
+        echo "✓ Learning dependencies installed (personalized ranking enabled)"
+    else
+        echo "○ Learning dependencies skipped (core features unaffected)"
+        echo "  To install later: pip3 install lightgbm scipy"
+    fi
+else
+    echo "○ requirements-learning.txt not found (learning features will use rule-based ranking)"
+fi
+
 # Initialize knowledge graph and pattern learning
 echo ""
 echo "Initializing advanced features..."
@@ -677,6 +769,10 @@ echo "  slm status"
 echo "  slm remember 'My first memory'"
 echo "  slm recall 'first'"
 echo ""
+echo "Learning System (v2.7+):"
+echo "  slm learning status              - Check learning system"
+echo "  slm engagement                   - View engagement metrics"
+echo ""
 # Optional: Offer to install optional features
 if [ "$NON_INTERACTIVE" = true ]; then
     INSTALL_CHOICE="N"