superlocalmemory 2.8.5 → 3.0.0

package/ide/integrations/llamaindex/llama_index/storage/chat_store/superlocalmemory/base.py

@@ -0,0 +1,316 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
+"""SuperLocalMemory V2 - LlamaIndex Chat Store Backend
+
+Implements LlamaIndex's BaseChatStore backed by SuperLocalMemory V2's
+local SQLite storage. All data stays on-device — zero cloud, zero telemetry.
+
+Usage:
+    from llama_index.storage.chat_store.superlocalmemory import SuperLocalMemoryChatStore
+    from llama_index.core.memory import ChatMemoryBuffer
+
+    chat_store = SuperLocalMemoryChatStore()
+    memory = ChatMemoryBuffer.from_defaults(chat_store=chat_store, chat_store_key="user-123")
+"""
+import hashlib
+import json
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from llama_index.core.base.llms.types import ChatMessage, MessageRole
+from llama_index.core.storage.chat_store.base import BaseChatStore
+
+# ---------------------------------------------------------------------------
+# Locate and import SuperLocalMemory V2's MemoryStoreV2
+# ---------------------------------------------------------------------------
+_SLM_PATH = Path.home() / ".claude-memory"
+if str(_SLM_PATH) not in sys.path:
+    sys.path.insert(0, str(_SLM_PATH))
+
+# Also support the source tree layout (for development / tests that pass db_path)
+_SLM_SRC_PATH = Path(__file__).resolve().parents[6] / "src"
+if _SLM_SRC_PATH.exists() and str(_SLM_SRC_PATH) not in sys.path:
+    sys.path.insert(0, str(_SLM_SRC_PATH))
+
+try:
+    from memory_store_v2 import MemoryStoreV2
+except ImportError as exc:
+    raise ImportError(
+        "SuperLocalMemory V2 is not installed. "
+        "Run: curl -fsSL https://raw.githubusercontent.com/varun369/SuperLocalMemoryV2/main/install.sh | bash\n"
+        "Or visit: https://github.com/varun369/SuperLocalMemoryV2"
+    ) from exc
+
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+# Tag format: "li:chat:<hash>" where hash is a 24-char SHA-256 prefix of the key.
+# Total tag length = 8 + 24 = 32 chars, well under SLM's 50-char MAX_TAG_LENGTH.
+# The full session key is stored inside the serialized content JSON so get_keys()
+# can reconstruct the original key even when the tag is hash-based.
+_TAG_PREFIX = "li:chat:"
+_PROJECT_NAME = "llamaindex"
+_IMPORTANCE = 3
+_LIST_LIMIT = 10000  # Upper bound when listing all memories for filtering
+_HASH_LEN = 24  # Characters of SHA-256 hex digest to use in tags
+
+
+def _key_hash(key: str) -> str:
+    """Produce a deterministic short hash of a session key for use in SLM tags."""
+    return hashlib.sha256(key.encode("utf-8")).hexdigest()[:_HASH_LEN]
+
+
+def _make_tag(key: str) -> str:
+    """Build the SLM tag for a chat session key.
+
+    Uses a hash of the key to guarantee the tag never exceeds SLM's
+    50-character limit regardless of key length or content.
+    """
+    return f"{_TAG_PREFIX}{_key_hash(key)}"
+
+
+def _serialize_message(key: str, message: ChatMessage) -> str:
+    """Serialize a ChatMessage to JSON string for SLM content storage.
+
+    The session *key* is embedded in the payload so that ``get_keys()`` can
+    reconstruct the original key from stored memories (the tag only contains
+    a hash).
+    """
+    return json.dumps(
+        {
+            "key": key,
+            "role": message.role.value,
+            "content": message.content or "",
+            "additional_kwargs": message.additional_kwargs,
+        },
+        ensure_ascii=False,
+    )
+
+
+def _deserialize_message(content: str) -> Optional[ChatMessage]:
+    """Deserialize a JSON string back to a ChatMessage.
+
+    Returns None if the content is not valid chat message JSON.
+    """
+    try:
+        data = json.loads(content)
+    except (json.JSONDecodeError, TypeError):
+        return None
+
+    if not isinstance(data, dict) or "role" not in data:
+        return None
+
+    try:
+        role = MessageRole(data["role"])
+    except ValueError:
+        role = MessageRole.USER
+
+    return ChatMessage(
+        role=role,
+        content=data.get("content", ""),
+        additional_kwargs=data.get("additional_kwargs", {}),
+    )
+
+
+def _extract_key(content: str) -> Optional[str]:
+    """Extract the session key from a serialized memory content string."""
+    try:
+        data = json.loads(content)
+    except (json.JSONDecodeError, TypeError):
+        return None
+    if isinstance(data, dict):
+        return data.get("key")
+    return None
+
+
+class SuperLocalMemoryChatStore(BaseChatStore):
+    """LlamaIndex chat store backed by SuperLocalMemory V2.
+
+    Stores chat messages in SuperLocalMemory's local SQLite database,
+    keeping all data on-device with zero cloud calls.
+
+    Each message is stored as a separate SLM memory entry tagged with
+    ``li:chat:<hash>`` so different conversation sessions are cleanly
+    isolated. The full session key is preserved inside the serialized
+    content JSON for lossless round-tripping.
+
+    Args:
+        db_path: Optional path to the SQLite database file.
+                 Defaults to ``~/.claude-memory/memory.db``.
+    """
+
+    # Pydantic fields ---------------------------------------------------
+    # We store the db_path as a string so the model stays JSON-serializable.
+    _db_path: Optional[str] = None
+    _store: Any = None  # MemoryStoreV2 — not serializable, set in __init__
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    def __init__(self, db_path: Optional[str] = None, **kwargs: Any) -> None:
+        """Initialize SuperLocalMemoryChatStore.
+
+        Args:
+            db_path: Optional path to the SLM SQLite database.
+                     If None, uses the default ``~/.claude-memory/memory.db``.
+        """
+        super().__init__(**kwargs)
+        self._db_path = db_path
+        if db_path:
+            self._store = MemoryStoreV2(db_path=Path(db_path))
+        else:
+            self._store = MemoryStoreV2()
+
+    @classmethod
+    def class_name(cls) -> str:
+        """Get class name."""
+        return "SuperLocalMemoryChatStore"
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _get_memories_for_key(self, key: str) -> List[Dict[str, Any]]:
+        """Retrieve all SLM memories that belong to a chat session *key*.
+
+        Returns memories sorted by ``created_at`` ascending (oldest first)
+        to preserve conversation order.
+        """
+        tag = _make_tag(key)
+        all_memories = self._store.list_all(limit=_LIST_LIMIT)
+
+        matched: List[Dict[str, Any]] = []
+        for mem in all_memories:
+            mem_tags = mem.get("tags", [])
+            if isinstance(mem_tags, str):
+                try:
+                    mem_tags = json.loads(mem_tags)
+                except (json.JSONDecodeError, TypeError):
+                    mem_tags = [t.strip() for t in mem_tags.split(",") if t.strip()]
+            if tag in (mem_tags or []):
+                matched.append(mem)
+
+        # Sort by created_at ascending for correct conversation order
+        matched.sort(key=lambda m: m.get("created_at", ""))
+        return matched
+
+    def _memories_to_messages(
+        self, memories: List[Dict[str, Any]]
+    ) -> List[ChatMessage]:
+        """Convert a list of SLM memory dicts to ChatMessage objects."""
+        messages: List[ChatMessage] = []
+        for mem in memories:
+            msg = _deserialize_message(mem.get("content", ""))
+            if msg is not None:
+                messages.append(msg)
+        return messages
+
+    # ------------------------------------------------------------------
+    # BaseChatStore abstract method implementations
+    # ------------------------------------------------------------------
+
+    def set_messages(self, key: str, messages: List[ChatMessage]) -> None:
+        """Set messages for a key (replaces any existing messages)."""
+        self.delete_messages(key)
+        for message in messages:
+            self.add_message(key, message)
+
+    def get_messages(self, key: str) -> List[ChatMessage]:
+        """Get messages for a key, ordered by creation time."""
+        memories = self._get_memories_for_key(key)
+        return self._memories_to_messages(memories)
+
+    def add_message(self, key: str, message: ChatMessage) -> None:
+        """Add a single message for a key."""
+        content = _serialize_message(key, message)
+        tag = _make_tag(key)
+        self._store.add_memory(
+            content=content,
+            tags=[tag],
+            project_name=_PROJECT_NAME,
+            importance=_IMPORTANCE,
+        )
+
+    def delete_messages(self, key: str) -> Optional[List[ChatMessage]]:
+        """Delete all messages for a key.
+
+        Returns the deleted messages, or None if the key had no messages.
+        """
+        memories = self._get_memories_for_key(key)
+        if not memories:
+            return None
+
+        messages = self._memories_to_messages(memories)
+
+        for mem in memories:
+            self._store.delete_memory(mem["id"])
+
+        return messages
+
+    def delete_message(self, key: str, idx: int) -> Optional[ChatMessage]:
+        """Delete specific message for a key by index.
+
+        Args:
+            key: The session key.
+            idx: Zero-based index of the message to delete.
+
+        Returns:
+            The deleted ChatMessage, or None if index is out of range.
+        """
+        memories = self._get_memories_for_key(key)
+        if not memories or idx < 0 or idx >= len(memories):
+            return None
+
+        target = memories[idx]
+        msg = _deserialize_message(target.get("content", ""))
+        self._store.delete_memory(target["id"])
+        return msg
+
+    def delete_last_message(self, key: str) -> Optional[ChatMessage]:
+        """Delete the last (most recent) message for a key.
+
+        Returns:
+            The deleted ChatMessage, or None if the key has no messages.
+        """
+        memories = self._get_memories_for_key(key)
+        if not memories:
+            return None
+
+        last = memories[-1]
+        msg = _deserialize_message(last.get("content", ""))
+        self._store.delete_memory(last["id"])
+        return msg
+
+    def get_keys(self) -> List[str]:
+        """Get all unique session keys that have stored messages.
+
+        Keys are extracted from the serialized content JSON (the ``key``
+        field) rather than from tags, because tags contain only a hash of
+        the key for length-safety.
+        """
+        all_memories = self._store.list_all(limit=_LIST_LIMIT)
+        keys_seen: set[str] = set()
+
+        for mem in all_memories:
+            # Only consider memories whose tags indicate they belong to us
+            mem_tags = mem.get("tags", [])
+            if isinstance(mem_tags, str):
+                try:
+                    mem_tags = json.loads(mem_tags)
+                except (json.JSONDecodeError, TypeError):
+                    mem_tags = [t.strip() for t in mem_tags.split(",") if t.strip()]
+
+            is_ours = any(
+                isinstance(t, str) and t.startswith(_TAG_PREFIX)
+                for t in (mem_tags or [])
+            )
+            if not is_ours:
+                continue
+
+            key = _extract_key(mem.get("content", ""))
+            if key is not None:
+                keys_seen.add(key)
+
+        return sorted(keys_seen)

package/ide/integrations/llamaindex/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "llama-index-storage-chat-store-superlocalmemory"
+version = "0.1.0"
+description = "LlamaIndex chat store backed by SuperLocalMemory — 100% local, zero cloud"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+    { name = "Varun Pratap Bhardwaj" },
+]
+keywords = ["llamaindex", "llama-index", "memory", "local-first", "privacy", "sqlite", "chat-store", "mcp"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "llama-index-core>=0.13.0,<0.15",
+]
+
+[project.urls]
+Homepage = "https://github.com/varun369/SuperLocalMemoryV2"
+Documentation = "https://superlocalmemory.com/"
+Repository = "https://github.com/varun369/SuperLocalMemoryV2"
+
+[tool.hatch.build.targets.wheel]
+packages = ["llama_index"]
+
+[tool.llamahub]
+contains_example = false
+import_path = "llama_index.storage.chat_store.superlocalmemory"
+
+[tool.llamahub.class_authors]
+SuperLocalMemoryChatStore = "varun369"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

package/{src/lifecycle → ide/integrations/llamaindex}/tests/__init__.py

@@ -1,4 +1,3 @@
+#!/usr/bin/env python3
 # SPDX-License-Identifier: MIT
 # Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
-"""Tests for lifecycle engine.
-"""

package/ide/integrations/llamaindex/tests/test_chat_store.py

@@ -0,0 +1,294 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
+"""SuperLocalMemory V2 - LlamaIndex Chat Store Tests
+
+Comprehensive tests for the SuperLocalMemoryChatStore implementation.
+All tests use temporary databases — no production data is touched.
+"""
+import os
+import sys
+import tempfile
+
+import pytest
+
+# Ensure the SLM source tree is importable for tests
+_SLM_SRC = os.path.join(
+    os.path.dirname(__file__), os.pardir, os.pardir, os.pardir, "src"
+)
+_SLM_SRC = os.path.abspath(_SLM_SRC)
+if _SLM_SRC not in sys.path:
+    sys.path.insert(0, _SLM_SRC)
+
+from llama_index.core.base.llms.types import ChatMessage, MessageRole
+from llama_index.storage.chat_store.superlocalmemory import SuperLocalMemoryChatStore
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def tmp_db():
+    """Provide a path to a temporary database file that is cleaned up after use."""
+    with tempfile.TemporaryDirectory() as d:
+        yield os.path.join(d, "test_memory.db")
+
+
+@pytest.fixture
+def store(tmp_db):
+    """Provide a fresh SuperLocalMemoryChatStore backed by a temp database."""
+    return SuperLocalMemoryChatStore(db_path=tmp_db)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_messages(
+    texts: list[str], roles: list[MessageRole] | None = None
+) -> list[ChatMessage]:
+    """Create a list of ChatMessages from plain text strings."""
+    if roles is None:
+        # Alternate user / assistant
+        roles = [
+            MessageRole.USER if i % 2 == 0 else MessageRole.ASSISTANT
+            for i in range(len(texts))
+        ]
+    return [ChatMessage(role=r, content=t) for r, t in zip(roles, texts)]
+
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+
+class TestSetAndGetMessages:
+    """Tests for set_messages / get_messages round-trip."""
+
+    def test_set_and_get_messages(self, store):
+        """Set 3 messages and retrieve them in order."""
+        msgs = _make_messages(["Hello", "Hi there", "How are you?"])
+        store.set_messages("session-1", msgs)
+
+        retrieved = store.get_messages("session-1")
+        assert len(retrieved) == 3
+        assert retrieved[0].content == "Hello"
+        assert retrieved[1].content == "Hi there"
+        assert retrieved[2].content == "How are you?"
+
+    def test_get_messages_empty(self, store):
+        """Getting messages for a non-existent key returns an empty list."""
+        assert store.get_messages("nonexistent") == []
+
+
+class TestAddMessage:
+    """Tests for add_message."""
+
+    def test_add_single_message(self, store):
+        """Add one message and verify it appears in get_messages."""
+        msg = ChatMessage(role=MessageRole.USER, content="solo message")
+        store.add_message("key-a", msg)
+
+        retrieved = store.get_messages("key-a")
+        assert len(retrieved) == 1
+        assert retrieved[0].content == "solo message"
+        assert retrieved[0].role == MessageRole.USER
+
+
+class TestDeleteMessages:
+    """Tests for delete_messages (all messages for a key)."""
+
+    def test_delete_messages(self, store):
+        """Set, delete, verify empty and check return value."""
+        msgs = _make_messages(["A", "B", "C"])
+        store.set_messages("del-key", msgs)
+
+        deleted = store.delete_messages("del-key")
+        assert deleted is not None
+        assert len(deleted) == 3
+        assert deleted[0].content == "A"
+
+        # After deletion, key should be empty
+        assert store.get_messages("del-key") == []
+
+    def test_delete_messages_nonexistent(self, store):
+        """Deleting messages for a key with no data returns None."""
+        assert store.delete_messages("ghost-key") is None
+
+
+class TestDeleteMessageByIndex:
+    """Tests for delete_message (single message by index)."""
+
+    def test_delete_message_by_index(self, store):
+        """Set 3 messages, delete index 1, verify 2 remain in correct order."""
+        msgs = _make_messages(["first", "second", "third"])
+        store.set_messages("idx-key", msgs)
+
+        deleted = store.delete_message("idx-key", 1)
+        assert deleted is not None
+        assert deleted.content == "second"
+
+        remaining = store.get_messages("idx-key")
+        assert len(remaining) == 2
+        assert remaining[0].content == "first"
+        assert remaining[1].content == "third"
+
+    def test_delete_message_out_of_range(self, store):
+        """Deleting an out-of-range index returns None."""
+        msgs = _make_messages(["only"])
+        store.set_messages("range-key", msgs)
+        assert store.delete_message("range-key", 5) is None
+
+    def test_delete_message_negative_index(self, store):
+        """Deleting a negative index returns None."""
+        msgs = _make_messages(["x"])
+        store.set_messages("neg-key", msgs)
+        assert store.delete_message("neg-key", -1) is None
+
+
+class TestDeleteLastMessage:
+    """Tests for delete_last_message."""
+
+    def test_delete_last_message(self, store):
+        """Set 3 messages, delete last, verify 2 remain."""
+        msgs = _make_messages(["alpha", "beta", "gamma"])
+        store.set_messages("last-key", msgs)
+
+        deleted = store.delete_last_message("last-key")
+        assert deleted is not None
+        assert deleted.content == "gamma"
+
+        remaining = store.get_messages("last-key")
+        assert len(remaining) == 2
+        assert remaining[-1].content == "beta"
+
+    def test_delete_last_message_empty(self, store):
+        """Deleting last message on an empty key returns None."""
+        assert store.delete_last_message("empty-key") is None
+
+
+class TestGetKeys:
+    """Tests for get_keys."""
+
+    def test_get_keys(self, store):
+        """Set messages for 3 different keys and verify get_keys returns all 3."""
+        for key in ["alice", "bob", "carol"]:
+            store.add_message(key, ChatMessage(role=MessageRole.USER, content=f"hi from {key}"))
+
+        keys = store.get_keys()
+        assert sorted(keys) == ["alice", "bob", "carol"]
+
+    def test_get_keys_empty(self, store):
+        """No data returns empty list."""
+        assert store.get_keys() == []
+
+
+class TestSessionIsolation:
+    """Tests that different keys don't interfere with each other."""
+
+    def test_session_isolation(self, store):
+        """Messages in key A should not appear in key B."""
+        store.set_messages("sess-A", _make_messages(["A1", "A2"]))
+        store.set_messages("sess-B", _make_messages(["B1", "B2", "B3"]))
+
+        a_msgs = store.get_messages("sess-A")
+        b_msgs = store.get_messages("sess-B")
+
+        assert len(a_msgs) == 2
+        assert len(b_msgs) == 3
+        assert a_msgs[0].content == "A1"
+        assert b_msgs[0].content == "B1"
+
+
+class TestSetOverwrites:
+    """Tests that set_messages replaces previous messages."""
+
+    def test_set_overwrites(self, store):
+        """Setting messages twice replaces the first batch entirely."""
+        store.set_messages("ow-key", _make_messages(["old1", "old2", "old3"]))
+        store.set_messages("ow-key", _make_messages(["new1"]))
+
+        msgs = store.get_messages("ow-key")
+        assert len(msgs) == 1
+        assert msgs[0].content == "new1"
+
+
+class TestPersistence:
+    """Tests that data survives across store instances."""
+
+    def test_persistence(self, tmp_db):
+        """Create store, add data, create NEW store on same db, verify data."""
+        store1 = SuperLocalMemoryChatStore(db_path=tmp_db)
+        store1.set_messages("persist-key", _make_messages(["remember me"]))
+
+        # New store instance pointing at same database
+        store2 = SuperLocalMemoryChatStore(db_path=tmp_db)
+        msgs = store2.get_messages("persist-key")
+        assert len(msgs) == 1
+        assert msgs[0].content == "remember me"
+
+
+class TestContentEdgeCases:
+    """Tests for special content: unicode, long text, multiple roles."""
+
+    def test_unicode_content(self, store):
+        """Unicode characters (CJK, emoji, diacritics) round-trip correctly."""
+        texts = [
+            "Hello, world!",
+            "Hej varlden!",
+            "Bonjour le monde!",
+        ]
+        store.set_messages("unicode-key", _make_messages(texts))
+        msgs = store.get_messages("unicode-key")
+        assert len(msgs) == 3
+        assert msgs[1].content == "Hej varlden!"
+
+    def test_long_content(self, store):
+        """A 10K character message round-trips correctly."""
+        long_text = "x" * 10_000
+        store.add_message(
+            "long-key", ChatMessage(role=MessageRole.USER, content=long_text)
+        )
+        msgs = store.get_messages("long-key")
+        assert len(msgs) == 1
+        assert len(msgs[0].content) == 10_000
+
+    def test_message_roles(self, store):
+        """User, assistant, and system roles all round-trip correctly."""
+        msgs = [
+            ChatMessage(role=MessageRole.SYSTEM, content="You are helpful."),
+            ChatMessage(role=MessageRole.USER, content="Hi"),
+            ChatMessage(role=MessageRole.ASSISTANT, content="Hello!"),
+        ]
+        store.set_messages("roles-key", msgs)
+        retrieved = store.get_messages("roles-key")
+
+        assert retrieved[0].role == MessageRole.SYSTEM
+        assert retrieved[1].role == MessageRole.USER
+        assert retrieved[2].role == MessageRole.ASSISTANT
+
+    def test_empty_content_message(self, store):
+        """A message with empty content still round-trips."""
+        store.add_message(
+            "empty-msg", ChatMessage(role=MessageRole.ASSISTANT, content="")
+        )
+        msgs = store.get_messages("empty-msg")
+        assert len(msgs) == 1
+        # Empty content serializes as "" and deserializes back
+        assert msgs[0].content == "" or msgs[0].content is None
+
+    def test_additional_kwargs(self, store):
+        """additional_kwargs round-trip correctly."""
+        msg = ChatMessage(
+            role=MessageRole.USER,
+            content="with metadata",
+            additional_kwargs={"source": "test", "count": 42},
+        )
+        store.add_message("kwargs-key", msg)
+        msgs = store.get_messages("kwargs-key")
+        assert len(msgs) == 1
+        assert msgs[0].additional_kwargs.get("source") == "test"
+        assert msgs[0].additional_kwargs.get("count") == 42