cortexdb-langchain 0.1.0__tar.gz

cortexdb_langchain-0.1.0/.gitignore

@@ -0,0 +1,79 @@
+# Rust
+/target
+**/*.rs.bk
+
+# Environment / secrets
+.env
+.env.local
+.env*.local
+*.pem
+*.key
+.npmrc
+
+# SQLite database
+*.sqlite
+*.sqlite-wal
+*.sqlite-shm
+
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Data directories
+cortexdb_data*/
+/data/
+# Per-bench tenant stores (RocksDB + Tantivy + HNSW state; regeneratable per run)
+/data_*/
+# Experimental per-branch stores (not tracked on this branch but left gitignored
+# so checkout from other branches doesn't surface them in git status)
+/event_memory_store/
+/llm_cache/
+
+# Benchmark inputs and per-run outputs (kept local, regenerated each run)
+benchmarks/longmemeval/data/
+benchmarks/longmemeval/server_results/
+benchmarks/longmemeval/fast_results/
+benchmarks/longmemeval/micro_results/
+benchmarks/longmemeval/server_logs/
+benchmarks/longmemeval/*.log
+benchmarks/locomo/locomo_results*.json
+benchmarks/locomo/server_results/
+benchmarks/locomo/*.log
+/answer_out.json
+
+# Local Claude Code state
+.claude/
+.tmp/
+
+# Python
+__pycache__/
+*.pyc
+.venv/
+venv/
+
+# Node
+node_modules/
+dist/
+.next/
+
+# Egg info
+*.egg-info/
+
+# Scratch/debug text files at root
+/*.txt
+/*.log
+
+# Local debug / marketing / private content (not for repo)
+harness/.reports/
+harness_data_*/
+blog/
+sales/
+videos/
+local-instance/

cortexdb_langchain-0.1.0/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: cortexdb-langchain
+Version: 0.1.0
+Summary: LangChain integration for CortexDB — long-term memory for AI systems
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Requires-Dist: cortexdbai>=0.1.0
+Requires-Dist: langchain-core>=0.3
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cortexdb-langchain
+
+LangChain integration for CortexDB long-term memory.
+
+> **LLM provider note (audit BLK-2):** the canonical quickstart uses
+> `from langchain_openai import ChatOpenAI` for the example agent. CortexDB
+> itself is LLM-agnostic — the LangChain example just needs *some* model to
+> drive the agent. Swap with one line:
+>
+> ```python
+> # OpenAI (default in the docs)
+> from langchain_openai import ChatOpenAI
+> llm = ChatOpenAI(model="gpt-4o")
+>
+> # Anthropic
+> from langchain_anthropic import ChatAnthropic
+> llm = ChatAnthropic(model="claude-sonnet-4-6")
+>
+> # Google
+> from langchain_google_genai import ChatGoogleGenerativeAI
+> llm = ChatGoogleGenerativeAI(model="gemini-1.5-pro")
+>
+> # Local / Ollama (no API key)
+> from langchain_community.chat_models import ChatOllama
+> llm = ChatOllama(model="llama3.1")
+> ```
+>
+> Nothing in `cortexdb-langchain` reads `OPENAI_API_KEY`. The retriever and
+> memory classes only talk to the CortexDB v1 surface.
+
+## Install
+
+```bash
+pip install cortexdb-langchain
+```
+
+## API base URL
+
+The SDK and integration default to `https://api-v1.cortexdb.ai` (audit FRI-8).
+Override with `CORTEXDB_API_URL` if you self-host.

cortexdb_langchain-0.1.0/README.md

@@ -0,0 +1,40 @@
+# cortexdb-langchain
+
+LangChain integration for CortexDB long-term memory.
+
+> **LLM provider note (audit BLK-2):** the canonical quickstart uses
+> `from langchain_openai import ChatOpenAI` for the example agent. CortexDB
+> itself is LLM-agnostic — the LangChain example just needs *some* model to
+> drive the agent. Swap with one line:
+>
+> ```python
+> # OpenAI (default in the docs)
+> from langchain_openai import ChatOpenAI
+> llm = ChatOpenAI(model="gpt-4o")
+>
+> # Anthropic
+> from langchain_anthropic import ChatAnthropic
+> llm = ChatAnthropic(model="claude-sonnet-4-6")
+>
+> # Google
+> from langchain_google_genai import ChatGoogleGenerativeAI
+> llm = ChatGoogleGenerativeAI(model="gemini-1.5-pro")
+>
+> # Local / Ollama (no API key)
+> from langchain_community.chat_models import ChatOllama
+> llm = ChatOllama(model="llama3.1")
+> ```
+>
+> Nothing in `cortexdb-langchain` reads `OPENAI_API_KEY`. The retriever and
+> memory classes only talk to the CortexDB v1 surface.
+
+## Install
+
+```bash
+pip install cortexdb-langchain
+```
+
+## API base URL
+
+The SDK and integration default to `https://api-v1.cortexdb.ai` (audit FRI-8).
+Override with `CORTEXDB_API_URL` if you self-host.

cortexdb_langchain-0.1.0/cortexdb_langchain/__init__.py

@@ -0,0 +1,29 @@
+"""CortexDB integration for LangChain.
+
+Provides chat-message history, retrievers, and tools that connect LangChain
+applications to CortexDB's long-term memory system.
+"""
+
+from cortexdb_langchain.memory import CortexDBChatMessageHistory
+from cortexdb_langchain.retriever import CortexDBRetriever
+from cortexdb_langchain.tools import (
+    CortexDBForgetTool,
+    CortexDBSearchTool,
+    CortexDBStoreTool,
+)
+
+__all__ = [
+    "CortexDBChatMessageHistory",
+    "CortexDBRetriever",
+    "CortexDBForgetTool",
+    "CortexDBSearchTool",
+    "CortexDBStoreTool",
+]
+
+# Legacy BaseMemory backend — only present on langchain-core < 1.0.
+try:
+    from cortexdb_langchain.memory import CortexDBMemory  # noqa: F401
+
+    __all__.append("CortexDBMemory")
+except ImportError:
+    pass

cortexdb_langchain-0.1.0/cortexdb_langchain/memory.py

@@ -0,0 +1,141 @@
+"""LangChain memory backed by CortexDB.
+
+Primary, version-agnostic primitive: :class:`CortexDBChatMessageHistory`, a
+``BaseChatMessageHistory`` (available in langchain-core 0.3 **and** 1.x). Use it
+with ``RunnableWithMessageHistory`` to give a chain/agent long-term memory:
+messages are persisted to CortexDB and relevant context is recalled back.
+
+The legacy :class:`CortexDBMemory` (built on the pre-1.0 ``BaseMemory``) is kept
+only when that base class is importable (langchain-core < 1.0), since 1.x removed
+the ``BaseMemory`` framework entirely.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from langchain_core.chat_history import BaseChatMessageHistory
+from langchain_core.messages import AIMessage, BaseMessage
+
+from cortexdb import Cortex
+
+
+class CortexDBChatMessageHistory(BaseChatMessageHistory):
+    """Chat-message history backed by CortexDB (langchain-core 0.3 + 1.x).
+
+    - ``add_message`` / ``add_messages`` persist each message via ``experience``.
+    - ``messages`` recalls relevant long-term context for ``recall_query`` and
+      surfaces it as a single ``AIMessage`` (CortexDB is semantic memory, not a
+      literal per-session log). Set ``recall_query`` to the current user input.
+    - ``clear`` forgets the scope.
+
+    Example::
+
+        from cortexdb import Cortex
+        from cortexdb_langchain import CortexDBChatMessageHistory
+
+        client = Cortex("https://api-v1.cortexdb.ai", actor="user:app", bearer="v4.public...")
+        history = CortexDBChatMessageHistory(client=client, scope="user:my-app")
+    """
+
+    def __init__(
+        self,
+        client: Cortex,
+        scope: str = "user:default",
+        recall_query: str = "",
+    ) -> None:
+        self._client = client
+        self.scope = scope
+        self.recall_query = recall_query
+
+    @property
+    def messages(self) -> list[BaseMessage]:
+        query = self.recall_query
+        if not query:
+            return []
+        result = self._client.recall(self.scope, query=str(query))
+        block = result.get("context_block", "")
+        return [AIMessage(content=block)] if block else []
+
+    def add_message(self, message: BaseMessage) -> None:
+        self._client.experience(
+            self.scope, text=f"{message.type}: {message.content}"
+        )
+
+    def add_messages(self, messages: list[BaseMessage]) -> None:
+        for message in messages:
+            self.add_message(message)
+
+    def clear(self) -> None:
+        self._client.forget(
+            self.scope,
+            confirm_all=True,
+            cascade="redact_events",
+            reason="LangChain memory clear requested",
+        )
+
+
+# ── Legacy BaseMemory backend (langchain-core < 1.0 only) ────────────────────
+# langchain-core 1.x removed BaseMemory and the classic `memory=` chain hook, so
+# we only define this when the base class is importable.
+try:
+    from langchain_core.memory import BaseMemory as _BaseMemory
+except ImportError:  # langchain-core >= 1.0
+    _BaseMemory = None
+
+if _BaseMemory is not None:
+    from pydantic import PrivateAttr
+
+    class CortexDBMemory(_BaseMemory):  # type: ignore[misc,valid-type]
+        """Deprecated: classic BaseMemory backend (langchain-core < 1.0).
+
+        Prefer :class:`CortexDBChatMessageHistory` with
+        ``RunnableWithMessageHistory`` on langchain-core 1.x.
+        """
+
+        memory_key: str = "cortex_context"
+        input_key: Optional[str] = None
+        output_key: Optional[str] = None
+        scope: str = "user:default"
+
+        _client: Cortex = PrivateAttr()
+
+        def __init__(self, client: Cortex, **kwargs: Any) -> None:
+            super().__init__(**kwargs)
+            self._client = client
+
+        @property
+        def memory_variables(self) -> list[str]:
+            return [self.memory_key]
+
+        def load_memory_variables(self, inputs: dict[str, Any]) -> dict[str, Any]:
+            if self.input_key is not None:
+                query = inputs.get(self.input_key, "")
+            else:
+                query = next(iter(inputs.values()), "") if inputs else ""
+            if not query:
+                return {self.memory_key: ""}
+            result = self._client.recall(self.scope, query=str(query))
+            return {self.memory_key: result.get("context_block", "")}
+
+        def save_context(
+            self, inputs: dict[str, Any], outputs: dict[str, str]
+        ) -> None:
+            if self.output_key is not None:
+                output_text = outputs.get(self.output_key, "")
+            else:
+                output_text = next(iter(outputs.values()), "") if outputs else ""
+            if self.input_key is not None:
+                input_text = inputs.get(self.input_key, "")
+            else:
+                input_text = next(iter(inputs.values()), "") if inputs else ""
+            content = f"User: {input_text}\nAssistant: {output_text}"
+            self._client.experience(self.scope, text=content)
+
+        def clear(self) -> None:
+            self._client.forget(
+                self.scope,
+                confirm_all=True,
+                cascade="redact_events",
+                reason="LangChain memory clear requested",
+            )

cortexdb_langchain-0.1.0/cortexdb_langchain/retriever.py

@@ -0,0 +1,74 @@
+"""LangChain retriever backed by CortexDB.
+
+Provides a standard LangChain retriever interface for semantic search
+over CortexDB's memory store, compatible with retrieval chains and
+retrieval-augmented generation (RAG) pipelines.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from langchain_core.callbacks import CallbackManagerForRetrieverRun
+from langchain_core.documents import Document
+from langchain_core.retrievers import BaseRetriever
+from pydantic import Field, PrivateAttr
+
+from cortexdb import Cortex
+
+
+class CortexDBRetriever(BaseRetriever):
+    """LangChain retriever that queries CortexDB's memory store.
+
+    Wraps CortexDB's ``recall`` API as a standard LangChain retriever,
+    returning results as LangChain ``Document`` objects.
+
+    Args:
+        client: An initialized CortexDB client instance.
+        scope: The scope path for memory isolation (hierarchical string).
+
+    Example::
+
+        from cortexdb import Cortex
+        from cortexdb_langchain import CortexDBRetriever
+
+        client = Cortex(
+            "https://api-v1.cortexdb.ai",
+            actor="user:app",
+            bearer="v4.public...",
+        )
+        retriever = CortexDBRetriever(client=client, scope="user:my-app")
+
+        docs = retriever.invoke("What happened in the last sprint?")
+        for doc in docs:
+            print(doc.page_content)
+    """
+
+    scope: str = "user:default"
+
+    _client: Cortex = PrivateAttr()
+
+    def __init__(self, client: Cortex, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self._client = client
+
+    def _get_relevant_documents(
+        self,
+        query: str,
+        *,
+        run_manager: CallbackManagerForRetrieverRun,
+    ) -> list[Document]:
+        result = self._client.recall(self.scope, query=query)
+
+        metadata = {
+            "source": "cortexdb",
+            "scope": self.scope,
+            "pack_id": result.get("pack_id"),
+        }
+
+        return [
+            Document(
+                page_content=result.get("context_block", ""),
+                metadata=metadata,
+            )
+        ]

cortexdb_langchain-0.1.0/cortexdb_langchain/tools.py

@@ -0,0 +1,121 @@
+"""LangChain tools for interacting with CortexDB.
+
+Provides search, store, and forget tools that allow LangChain agents
+to interact with CortexDB's memory system as part of their tool-use
+capabilities.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional, Type
+
+from langchain_core.callbacks import CallbackManagerForToolRun
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, Field
+
+from cortexdb import Cortex
+
+
+class _SearchInput(BaseModel):
+    query: str = Field(description="The search query to find relevant memories.")
+
+
+class CortexDBSearchTool(BaseTool):
+    """LangChain tool for searching memories in CortexDB."""
+
+    name: str = "cortexdb_search"
+    description: str = (
+        "Search CortexDB for relevant memories and past context. "
+        "Use this when you need to recall information from previous "
+        "conversations or stored knowledge."
+    )
+    args_schema: Type[BaseModel] = _SearchInput
+    scope: str = "user:default"
+
+    _client: Cortex
+
+    def __init__(self, client: Cortex, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self._client = client
+
+    def _run(
+        self,
+        query: str,
+        run_manager: Optional[CallbackManagerForToolRun] = None,
+    ) -> str:
+        result = self._client.recall(self.scope, query=query)
+
+        context = result.get("context_block", "")
+        if not context:
+            return "No relevant memories found."
+
+        return context
+
+
+class _StoreInput(BaseModel):
+    content: str = Field(description="The content to store as a memory.")
+
+
+class CortexDBStoreTool(BaseTool):
+    """LangChain tool for storing memories in CortexDB."""
+
+    name: str = "cortexdb_store"
+    description: str = (
+        "Store information in CortexDB's long-term memory. "
+        "Use this to save important facts, decisions, or context "
+        "that should be remembered for future interactions."
+    )
+    args_schema: Type[BaseModel] = _StoreInput
+    scope: str = "user:default"
+
+    _client: Cortex
+
+    def __init__(self, client: Cortex, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self._client = client
+
+    def _run(
+        self,
+        content: str,
+        run_manager: Optional[CallbackManagerForToolRun] = None,
+    ) -> str:
+        resp = self._client.experience(self.scope, text=content)
+        return f"Memory stored successfully (event_id: {resp.get('event_id')})."
+
+
+class _ForgetInput(BaseModel):
+    query: str = Field(description="Query identifying the memories to forget.")
+    reason: str = Field(description="The reason for forgetting these memories.")
+
+
+class CortexDBForgetTool(BaseTool):
+    """LangChain tool for forgetting memories in CortexDB."""
+
+    name: str = "cortexdb_forget"
+    description: str = (
+        "Forget or remove memories from CortexDB. "
+        "Use this when information should no longer be retained, "
+        "such as for privacy compliance or data correction."
+    )
+    args_schema: Type[BaseModel] = _ForgetInput
+    scope: str = "user:default"
+
+    _client: Cortex
+
+    def __init__(self, client: Cortex, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self._client = client
+
+    def _run(
+        self,
+        query: str,
+        reason: str,
+        run_manager: Optional[CallbackManagerForToolRun] = None,
+    ) -> str:
+        resp = self._client.forget(
+            self.scope,
+            confirm_all=True,
+            cascade="redact_events",
+            reason=reason,
+        )
+        return f"Forget request accepted (audit_id: {resp.get('audit_id')})."

cortexdb_langchain-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cortexdb-langchain"
+version = "0.1.0"
+description = "LangChain integration for CortexDB — long-term memory for AI systems"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+dependencies = [
+    "cortexdbai>=0.1.0",
+    "langchain-core>=0.3",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+]

cortexdb_langchain-0.1.0/tests/test_memory.py

@@ -0,0 +1,80 @@
+"""Tests for CortexDBChatMessageHistory (langchain-core 0.3 + 1.x).
+
+Mocked Cortex client — no running CortexDB. Verifies add/recall/clear map to
+the v1 experience/recall/forget calls.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock
+
+import pytest
+from langchain_core.messages import AIMessage, HumanMessage
+
+from cortexdb_langchain.memory import CortexDBChatMessageHistory
+
+
+@pytest.fixture
+def mock_client() -> MagicMock:
+    client = MagicMock()
+    client.recall.return_value = {"context_block": ""}
+    client.experience.return_value = {"event_id": "evt-1"}
+    client.forget.return_value = None
+    return client
+
+
+@pytest.fixture
+def history(mock_client: MagicMock) -> CortexDBChatMessageHistory:
+    return CortexDBChatMessageHistory(client=mock_client, scope="user:test")
+
+
+class TestCortexDBChatMessageHistory:
+    def test_messages_empty_without_query(
+        self, history: CortexDBChatMessageHistory, mock_client: MagicMock
+    ) -> None:
+        assert history.messages == []
+        mock_client.recall.assert_not_called()
+
+    def test_messages_recalls_context(self, mock_client: MagicMock) -> None:
+        mock_client.recall.return_value = {"context_block": "Past architecture chat."}
+        history = CortexDBChatMessageHistory(
+            client=mock_client, scope="user:test", recall_query="architecture"
+        )
+        msgs = history.messages
+        mock_client.recall.assert_called_once_with("user:test", query="architecture")
+        assert len(msgs) == 1
+        assert msgs[0].content == "Past architecture chat."
+
+    def test_messages_empty_when_no_context(self, mock_client: MagicMock) -> None:
+        mock_client.recall.return_value = {"context_block": ""}
+        history = CortexDBChatMessageHistory(
+            client=mock_client, scope="user:test", recall_query="obscure"
+        )
+        assert history.messages == []
+
+    def test_add_message_persists(
+        self, history: CortexDBChatMessageHistory, mock_client: MagicMock
+    ) -> None:
+        history.add_message(HumanMessage(content="What is CortexDB?"))
+        mock_client.experience.assert_called_once_with(
+            "user:test", text="human: What is CortexDB?"
+        )
+
+    def test_add_messages_persists_each(
+        self, history: CortexDBChatMessageHistory, mock_client: MagicMock
+    ) -> None:
+        history.add_messages(
+            [HumanMessage(content="hi"), AIMessage(content="hello")]
+        )
+        assert mock_client.experience.call_count == 2
+
+    def test_clear_forgets_scope(
+        self, history: CortexDBChatMessageHistory, mock_client: MagicMock
+    ) -> None:
+        history.clear()
+        mock_client.forget.assert_called_once_with(
+            "user:test",
+            confirm_all=True,
+            cascade="redact_events",
+            reason="LangChain memory clear requested",
+        )

cortexdb_langchain-0.1.0/tests/test_retriever.py

@@ -0,0 +1,157 @@
+"""Tests for CortexDB LangChain retriever integration.
+
+Uses a mocked Cortex (v1) client to verify retriever behavior without
+requiring a running CortexDB instance or LangChain framework install.
+"""
+
+from __future__ import annotations
+
+import sys
+from types import ModuleType
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+# ---------------------------------------------------------------------------
+# Mock LangChain modules before importing integration code.
+# We must mock every langchain_core submodule that any cortexdb_langchain
+# module imports (including those pulled in transitively via __init__.py).
+# ---------------------------------------------------------------------------
+
+_mock_langchain_core = ModuleType("langchain_core")
+_mock_callbacks = ModuleType("langchain_core.callbacks")
+_mock_documents = ModuleType("langchain_core.documents")
+_mock_retrievers = ModuleType("langchain_core.retrievers")
+_mock_tools = ModuleType("langchain_core.tools")
+_mock_memory = ModuleType("langchain_core.memory")
+
+
+class _FakeDocument:
+    """Minimal stand-in for langchain_core.documents.Document."""
+
+    def __init__(self, page_content: str = "", metadata: dict | None = None) -> None:
+        self.page_content = page_content
+        self.metadata = metadata or {}
+
+
+class _FakeBaseRetriever:
+    """Minimal stand-in for langchain_core.retrievers.BaseRetriever."""
+
+    def __init__(self, **kwargs):
+        for k, v in kwargs.items():
+            setattr(self, k, v)
+
+
+class _FakeBaseTool:
+    """Minimal stand-in for langchain_core.tools.BaseTool."""
+
+    def __init__(self, **kwargs):
+        for k, v in kwargs.items():
+            setattr(self, k, v)
+
+
+class _FakeBaseMemory:
+    """Minimal stand-in for langchain_core.memory.BaseMemory."""
+
+    def __init__(self, **kwargs):
+        for k, v in kwargs.items():
+            setattr(self, k, v)
+
+
+_mock_documents.Document = _FakeDocument
+_mock_retrievers.BaseRetriever = _FakeBaseRetriever
+_mock_tools.BaseTool = _FakeBaseTool
+_mock_memory.BaseMemory = _FakeBaseMemory
+_mock_callbacks.CallbackManagerForRetrieverRun = MagicMock
+_mock_callbacks.CallbackManagerForToolRun = MagicMock
+
+_mock_modules = {
+    "langchain_core": _mock_langchain_core,
+    "langchain_core.callbacks": _mock_callbacks,
+    "langchain_core.documents": _mock_documents,
+    "langchain_core.retrievers": _mock_retrievers,
+    "langchain_core.tools": _mock_tools,
+    "langchain_core.memory": _mock_memory,
+}
+
+# Clear any previously-cached cortexdb_langchain imports so our mocks apply
+_stale = [k for k in sys.modules if k.startswith("cortexdb_langchain")]
+for k in _stale:
+    del sys.modules[k]
+
+with patch.dict(sys.modules, _mock_modules):
+    from cortexdb_langchain.retriever import CortexDBRetriever
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+@pytest.fixture
+def mock_client() -> MagicMock:
+    """Create a mock CortexDB v1 client."""
+    client = MagicMock()
+    client.recall.return_value = {"context_block": ""}
+    return client
+
+
+@pytest.fixture
+def retriever(mock_client: MagicMock) -> CortexDBRetriever:
+    """Create a CortexDBRetriever with a mocked client."""
+    return CortexDBRetriever(client=mock_client, scope="user:test")
+
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+class TestCortexDBRetriever:
+    """Tests for the CortexDBRetriever class."""
+
+    def test_returns_document_with_content_and_metadata(
+        self, retriever: CortexDBRetriever, mock_client: MagicMock
+    ) -> None:
+        """Retriever should return a Document with page_content and metadata."""
+        mock_client.recall.return_value = {
+            "context_block": "Architecture discussion",
+            "pack_id": "pack-1",
+        }
+
+        docs = retriever._get_relevant_documents(
+            "architecture", run_manager=MagicMock()
+        )
+
+        assert len(docs) == 1
+        assert docs[0].page_content == "Architecture discussion"
+        assert docs[0].metadata["source"] == "cortexdb"
+        assert docs[0].metadata["scope"] == "user:test"
+        assert docs[0].metadata["pack_id"] == "pack-1"
+
+    def test_empty_context_block(
+        self, retriever: CortexDBRetriever, mock_client: MagicMock
+    ) -> None:
+        """Empty context_block should yield an empty-content Document."""
+        mock_client.recall.return_value = {"context_block": ""}
+
+        docs = retriever._get_relevant_documents(
+            "nothing", run_manager=MagicMock()
+        )
+
+        assert len(docs) == 1
+        assert docs[0].page_content == ""
+
+    def test_passes_scope(self, mock_client: MagicMock) -> None:
+        """Retriever should pass the scope (positionally) and query to recall."""
+        r = CortexDBRetriever(client=mock_client, scope="org:acme/projects")
+        mock_client.recall.return_value = {"context_block": ""}
+
+        r._get_relevant_documents("query", run_manager=MagicMock())
+
+        mock_client.recall.assert_called_once_with(
+            "org:acme/projects", query="query"
+        )
+
+    def test_default_scope(self, mock_client: MagicMock) -> None:
+        """Retriever should default scope to 'user:default'."""
+        r = CortexDBRetriever(client=mock_client)
+        assert r.scope == "user:default"

cortexdb_langchain-0.1.0/tests/test_tools.py

@@ -0,0 +1,211 @@
+"""Tests for CortexDB LangChain tools integration.
+
+Uses a mocked Cortex (v1) client to verify search, store, and forget tool
+behavior without requiring a running CortexDB instance.
+"""
+
+from __future__ import annotations
+
+import sys
+from types import ModuleType
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+# ---------------------------------------------------------------------------
+# Mock LangChain modules before importing integration code.
+# We must mock every langchain_core submodule that any cortexdb_langchain
+# module imports (including those pulled in transitively via __init__.py).
+# ---------------------------------------------------------------------------
+
+_mock_langchain_core = ModuleType("langchain_core")
+_mock_callbacks = ModuleType("langchain_core.callbacks")
+_mock_documents = ModuleType("langchain_core.documents")
+_mock_retrievers = ModuleType("langchain_core.retrievers")
+_mock_tools = ModuleType("langchain_core.tools")
+_mock_memory = ModuleType("langchain_core.memory")
+
+
+class _FakeDocument:
+    def __init__(self, page_content="", metadata=None):
+        self.page_content = page_content
+        self.metadata = metadata or {}
+
+
+class _FakeBaseRetriever:
+    def __init__(self, **kwargs):
+        for k, v in kwargs.items():
+            setattr(self, k, v)
+
+
+class _FakeBaseTool:
+    def __init__(self, **kwargs):
+        for k, v in kwargs.items():
+            setattr(self, k, v)
+
+
+class _FakeBaseMemory:
+    def __init__(self, **kwargs):
+        for k, v in kwargs.items():
+            setattr(self, k, v)
+
+
+_mock_documents.Document = _FakeDocument
+_mock_retrievers.BaseRetriever = _FakeBaseRetriever
+_mock_tools.BaseTool = _FakeBaseTool
+_mock_memory.BaseMemory = _FakeBaseMemory
+_mock_callbacks.CallbackManagerForRetrieverRun = MagicMock
+_mock_callbacks.CallbackManagerForToolRun = MagicMock
+
+_mock_modules = {
+    "langchain_core": _mock_langchain_core,
+    "langchain_core.callbacks": _mock_callbacks,
+    "langchain_core.documents": _mock_documents,
+    "langchain_core.retrievers": _mock_retrievers,
+    "langchain_core.tools": _mock_tools,
+    "langchain_core.memory": _mock_memory,
+}
+
+# Clear any previously-cached cortexdb_langchain imports so our mocks apply
+_stale = [k for k in sys.modules if k.startswith("cortexdb_langchain")]
+for k in _stale:
+    del sys.modules[k]
+
+with patch.dict(sys.modules, _mock_modules):
+    from cortexdb_langchain.tools import (
+        CortexDBForgetTool,
+        CortexDBSearchTool,
+        CortexDBStoreTool,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+@pytest.fixture
+def mock_client() -> MagicMock:
+    """Create a mock CortexDB v1 client."""
+    client = MagicMock()
+    client.recall.return_value = {"context_block": ""}
+    client.experience.return_value = {"event_id": "evt-1"}
+    client.forget.return_value = {"audit_id": "aud-1"}
+    return client
+
+
+@pytest.fixture
+def search_tool(mock_client: MagicMock) -> CortexDBSearchTool:
+    return CortexDBSearchTool(client=mock_client, scope="user:test")
+
+
+@pytest.fixture
+def store_tool(mock_client: MagicMock) -> CortexDBStoreTool:
+    return CortexDBStoreTool(client=mock_client, scope="user:test")
+
+
+@pytest.fixture
+def forget_tool(mock_client: MagicMock) -> CortexDBForgetTool:
+    return CortexDBForgetTool(client=mock_client, scope="user:test")
+
+
+# ---------------------------------------------------------------------------
+# Tests — CortexDBSearchTool
+# ---------------------------------------------------------------------------
+
+class TestCortexDBSearchTool:
+    """Tests for the CortexDBSearchTool class."""
+
+    def test_search_returns_context_block(
+        self, search_tool: CortexDBSearchTool, mock_client: MagicMock
+    ) -> None:
+        """Search tool should return the context_block string."""
+        mock_client.recall.return_value = {
+            "context_block": "First memory\nSecond memory"
+        }
+
+        result = search_tool._run(query="architecture")
+
+        assert "First memory" in result
+        assert "Second memory" in result
+
+    def test_search_no_results(
+        self, search_tool: CortexDBSearchTool, mock_client: MagicMock
+    ) -> None:
+        """Search tool should return informative message when no results found."""
+        mock_client.recall.return_value = {"context_block": ""}
+
+        result = search_tool._run(query="nonexistent")
+
+        assert "No relevant memories found" in result
+
+    def test_search_passes_scope(
+        self, search_tool: CortexDBSearchTool, mock_client: MagicMock
+    ) -> None:
+        """Search tool should pass scope positionally and query to recall."""
+        mock_client.recall.return_value = {"context_block": ""}
+
+        search_tool._run(query="test")
+
+        mock_client.recall.assert_called_once_with("user:test", query="test")
+
+    def test_search_tool_name_and_description(
+        self, search_tool: CortexDBSearchTool
+    ) -> None:
+        """Search tool should have correct name and description."""
+        assert search_tool.name == "cortexdb_search"
+        assert "Search CortexDB" in search_tool.description
+
+
+# ---------------------------------------------------------------------------
+# Tests — CortexDBStoreTool
+# ---------------------------------------------------------------------------
+
+class TestCortexDBStoreTool:
+    """Tests for the CortexDBStoreTool class."""
+
+    def test_store_calls_experience(
+        self, store_tool: CortexDBStoreTool, mock_client: MagicMock
+    ) -> None:
+        """Store tool should call experience with the scope and text."""
+        result = store_tool._run(content="Important fact")
+
+        mock_client.experience.assert_called_once_with(
+            "user:test", text="Important fact"
+        )
+        assert "stored successfully" in result
+
+    def test_store_tool_name_and_description(
+        self, store_tool: CortexDBStoreTool
+    ) -> None:
+        """Store tool should have correct name and description."""
+        assert store_tool.name == "cortexdb_store"
+        assert "Store information" in store_tool.description
+
+
+# ---------------------------------------------------------------------------
+# Tests — CortexDBForgetTool
+# ---------------------------------------------------------------------------
+
+class TestCortexDBForgetTool:
+    """Tests for the CortexDBForgetTool class."""
+
+    def test_forget_calls_forget_on_scope(
+        self, forget_tool: CortexDBForgetTool, mock_client: MagicMock
+    ) -> None:
+        """Forget tool should call forget on the scope with the reason."""
+        result = forget_tool._run(query="old data", reason="outdated")
+
+        mock_client.forget.assert_called_once_with(
+            "user:test",
+            confirm_all=True,
+            cascade="redact_events",
+            reason="outdated",
+        )
+        assert "audit_id" in result or "aud-1" in result
+
+    def test_forget_tool_name_and_description(
+        self, forget_tool: CortexDBForgetTool
+    ) -> None:
+        """Forget tool should have correct name and description."""
+        assert forget_tool.name == "cortexdb_forget"
+        assert "Forget" in forget_tool.description