mentedb-langchain 0.1.0__tar.gz

mentedb_langchain-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+target/
+*.so
+*.dylib
+*.pyd
+*.egg-info/
+__pycache__/
+dist/
+build/
+.eggs/

mentedb_langchain-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: mentedb-langchain
+Version: 0.1.0
+Summary: MenteDB integration for LangChain and LangGraph
+License-Expression: Apache-2.0
+Requires-Python: >=3.9
+Requires-Dist: langchain-core>=0.3
+Requires-Dist: mentedb>=0.7.0

mentedb_langchain-0.1.0/README.md

@@ -0,0 +1,114 @@
+# mentedb-langchain
+
+MenteDB integration for LangChain and LangGraph. Gives your agents persistent, cognitive memory that goes beyond simple vector retrieval.
+
+## Installation
+
+```bash
+pip install mentedb-langchain
+```
+
+## Components
+
+### MenteDBMemory
+
+A LangChain compatible memory backend that stores conversation context in MenteDB. Unlike buffer or summary memory, MenteDBMemory uses hybrid search (vector similarity, tag filtering, temporal decay) to assemble the most relevant context for each turn.
+
+```python
+from mentedb_langchain import MenteDBMemory
+from langchain.chains import ConversationChain
+from langchain_openai import ChatOpenAI
+
+memory = MenteDBMemory(
+    data_dir="./agent-memory",
+    agent_id="my-agent",
+    token_budget=4096,
+)
+
+chain = ConversationChain(
+    llm=ChatOpenAI(),
+    memory=memory,
+)
+
+chain.predict(input="What database should I use for time series data?")
+chain.predict(input="Tell me more about that recommendation")
+```
+
+### MenteDBRetriever
+
+A LangChain compatible retriever that uses MenteDB hybrid search. Supports optional tag filtering and agent scoping to narrow results.
+
+```python
+from mentedb_langchain import MenteDBRetriever
+from langchain.chains import RetrievalQA
+from langchain_openai import ChatOpenAI
+
+retriever = MenteDBRetriever(
+    data_dir="./agent-memory",
+    k=10,
+    tags=["backend", "architecture"],
+)
+
+chain = RetrievalQA.from_chain_type(
+    llm=ChatOpenAI(),
+    retriever=retriever,
+)
+
+chain.invoke("What were the key decisions about our database migration?")
+```
+
+### MenteDBChatHistory
+
+Persistent chat history with cognitive tracking. MenteDB stores messages alongside reasoning trajectories, knowledge gaps, and contradiction signals so the agent's memory improves over time.
+
+```python
+from mentedb_langchain import MenteDBChatHistory
+
+history = MenteDBChatHistory(
+    session_id="session-123",
+    data_dir="./agent-memory",
+)
+
+history.add_user_message("What database should I use?")
+history.add_ai_message("I recommend PostgreSQL for your use case.")
+
+messages = history.messages
+```
+
+## Usage with LangGraph
+
+MenteDB works naturally with LangGraph. Use `MenteDBMemory` as a checkpointer or context source within graph nodes:
+
+```python
+from mentedb_langchain import MenteDBMemory
+
+memory = MenteDBMemory(data_dir="./graph-memory", agent_id="planner")
+
+def plan_node(state):
+    context = memory.load_memory_variables({"input": state["task"]})
+    # Use context to inform planning
+    return {**state, "context": context}
+
+def reflect_node(state):
+    memory.save_context(
+        inputs={"input": state["task"]},
+        outputs={"output": state["result"]},
+    )
+    return state
+```
+
+## Configuration
+
+All components accept `data_dir` to specify where MenteDB stores its data. For multi agent setups, use `agent_id` to isolate each agent's memory space.
+
+| Parameter | Default | Description |
+|---|---|---|
+| `data_dir` | `./mentedb-data` | Path to the MenteDB data directory |
+| `agent_id` | `None` | Optional agent identifier for memory isolation |
+| `token_budget` | `4096` | Maximum tokens for assembled context (MenteDBMemory) |
+| `k` | `10` | Number of results to return (MenteDBRetriever) |
+| `tags` | `None` | Tag filter for retrieval (MenteDBRetriever) |
+
+## License
+
+Apache 2.0

mentedb_langchain-0.1.0/mentedb_langchain/__init__.py

@@ -0,0 +1,5 @@
+from mentedb_langchain.memory import MenteDBMemory
+from mentedb_langchain.retriever import MenteDBRetriever
+from mentedb_langchain.chat_history import MenteDBChatHistory
+
+__all__ = ["MenteDBMemory", "MenteDBRetriever", "MenteDBChatHistory"]

mentedb_langchain-0.1.0/mentedb_langchain/chat_history.py

@@ -0,0 +1,58 @@
+"""LangChain chat history backed by MenteDB."""
+from typing import List, Optional
+
+from mentedb import MenteDB
+
+
+class MenteDBChatHistory:
+    """Stores chat message history in MenteDB with persistent recall.
+
+    Each message is stored as an episodic memory, enabling semantic
+    search across conversation history and cross-session continuity.
+
+    Usage:
+        from mentedb_langchain import MenteDBChatHistory
+
+        history = MenteDBChatHistory(
+            session_id="session-123",
+            data_dir="./agent-memory",
+        )
+
+        history.add_user_message("What database should I use?")
+        history.add_ai_message("I recommend PostgreSQL.")
+
+        messages = history.messages
+    """
+
+    def __init__(self, session_id: str, data_dir: str = "./mentedb-data",
+                 agent_id: Optional[str] = None):
+        self.session_id = session_id
+        self.data_dir = data_dir
+        self.agent_id = agent_id
+        self._db = MenteDB(data_dir)
+        self._messages: list = []
+
+    @property
+    def messages(self) -> list:
+        return self._messages
+
+    def add_user_message(self, message: str) -> None:
+        self._messages.append({"role": "user", "content": message})
+        self._db.store(
+            f"[{self.session_id}] User: {message}",
+            memory_type="episodic",
+            agent_id=self.agent_id,
+            tags=["chat_history", self.session_id],
+        )
+
+    def add_ai_message(self, message: str) -> None:
+        self._messages.append({"role": "assistant", "content": message})
+        self._db.store(
+            f"[{self.session_id}] Assistant: {message}",
+            memory_type="episodic",
+            agent_id=self.agent_id,
+            tags=["chat_history", self.session_id],
+        )
+
+    def clear(self) -> None:
+        self._messages.clear()

mentedb_langchain-0.1.0/mentedb_langchain/memory.py

@@ -0,0 +1,63 @@
+"""LangChain memory backed by MenteDB."""
+from typing import Any, Dict, List, Optional
+
+from mentedb import MenteDB
+
+
+class MenteDBMemory:
+    """LangChain compatible memory that stores conversation context in MenteDB.
+
+    Usage with LangChain:
+        from mentedb_langchain import MenteDBMemory
+
+        memory = MenteDBMemory(data_dir="./agent-memory", agent_id="my-agent")
+
+        memory.save_context(
+            inputs={"input": "What database should I use?"},
+            outputs={"output": "I recommend PostgreSQL for your use case."}
+        )
+
+        context = memory.load_memory_variables({"input": "Tell me more about that database"})
+    """
+
+    memory_key: str = "history"
+
+    def __init__(self, data_dir: str = "./mentedb-data", agent_id: Optional[str] = None,
+                 token_budget: int = 4096, return_messages: bool = False):
+        self.data_dir = data_dir
+        self.agent_id = agent_id
+        self.token_budget = token_budget
+        self.return_messages = return_messages
+        self._db = MenteDB(data_dir)
+
+    @property
+    def memory_variables(self) -> List[str]:
+        return [self.memory_key]
+
+    def load_memory_variables(self, inputs: Dict[str, Any]) -> Dict[str, Any]:
+        """Load relevant memories based on the current input."""
+        query = inputs.get("input", "")
+        if not query:
+            return {self.memory_key: ""}
+        results = self._db.search_text(query, k=10)
+        if not results:
+            return {self.memory_key: ""}
+        texts = []
+        for r in results:
+            mem = self._db.get_memory(r.id)
+            if mem:
+                texts.append(mem["content"])
+        return {self.memory_key: "\n".join(texts)}
+
+    def save_context(self, inputs: Dict[str, Any], outputs: Dict[str, str]) -> None:
+        """Save a conversation turn as episodic memory."""
+        input_text = inputs.get("input", "")
+        output_text = outputs.get("output", "")
+        content = f"User: {input_text}\nAssistant: {output_text}"
+        self._db.store(content, memory_type="episodic", agent_id=self.agent_id)
+
+    def clear(self) -> None:
+        """Clear all memories by closing and reopening."""
+        self._db.close()
+        self._db = MenteDB(self.data_dir)
+

mentedb_langchain-0.1.0/mentedb_langchain/retriever.py

@@ -0,0 +1,53 @@
+"""LangChain retriever backed by MenteDB vector search."""
+from typing import List, Optional
+
+from mentedb import MenteDB
+
+
+class MenteDBRetriever:
+    """LangChain compatible retriever using MenteDB hybrid search.
+
+    Combines vector similarity, tag filtering, and temporal relevance
+    in a single retrieval call.
+
+    Usage:
+        from mentedb_langchain import MenteDBRetriever
+
+        retriever = MenteDBRetriever(
+            data_dir="./agent-memory",
+            k=10,
+            tags=["backend", "architecture"],
+        )
+
+        docs = retriever.get_relevant_documents("database migration strategy")
+    """
+
+    def __init__(self, data_dir: str = "./mentedb-data", k: int = 10,
+                 tags: Optional[List[str]] = None, agent_id: Optional[str] = None):
+        self.data_dir = data_dir
+        self.k = k
+        self.tags = tags
+        self.agent_id = agent_id
+        self._db = MenteDB(data_dir)
+
+    def get_relevant_documents(self, query: str) -> list:
+        """Retrieve relevant memories as dicts with id, content, and score."""
+        results = self._db.search_text(query, k=self.k, tags=self.tags)
+        docs = []
+        for r in results:
+            mem = self._db.get_memory(r.id)
+            if mem:
+                docs.append({
+                    "page_content": mem["content"],
+                    "metadata": {
+                        "id": r.id,
+                        "score": r.score,
+                        "memory_type": mem.get("memory_type", ""),
+                        "tags": mem.get("tags", []),
+                    },
+                })
+        return docs
+
+    async def aget_relevant_documents(self, query: str) -> list:
+        """Async version of get_relevant_documents."""
+        return self.get_relevant_documents(query)

mentedb_langchain-0.1.0/pyproject.toml

@@ -0,0 +1,14 @@
+[project]
+name = "mentedb-langchain"
+version = "0.1.0"
+description = "MenteDB integration for LangChain and LangGraph"
+license = "Apache-2.0"
+requires-python = ">=3.9"
+dependencies = [
+    "mentedb>=0.7.0",
+    "langchain-core>=0.3",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

mentedb_langchain-0.1.0/tests/test_memory.py

@@ -0,0 +1,96 @@
+"""Tests for mentedb_langchain integration."""
+from mentedb_langchain.memory import MenteDBMemory
+from mentedb_langchain.retriever import MenteDBRetriever
+from mentedb_langchain.chat_history import MenteDBChatHistory
+
+
+class TestMenteDBMemory:
+    def test_default_construction(self):
+        memory = MenteDBMemory()
+        assert memory.data_dir == "./mentedb-data"
+        assert memory.agent_id is None
+        assert memory.token_budget == 4096
+        assert memory.return_messages is False
+
+    def test_custom_construction(self):
+        memory = MenteDBMemory(
+            data_dir="./custom-dir",
+            agent_id="agent-1",
+            token_budget=8192,
+            return_messages=True,
+        )
+        assert memory.data_dir == "./custom-dir"
+        assert memory.agent_id == "agent-1"
+        assert memory.token_budget == 8192
+        assert memory.return_messages is True
+
+    def test_memory_variables(self):
+        memory = MenteDBMemory()
+        assert memory.memory_variables == ["history"]
+
+    def test_load_memory_variables(self):
+        memory = MenteDBMemory()
+        result = memory.load_memory_variables({"input": "test query"})
+        assert "history" in result
+        assert isinstance(result["history"], str)
+
+    def test_save_context(self):
+        memory = MenteDBMemory()
+        memory.save_context(
+            inputs={"input": "hello"},
+            outputs={"output": "world"},
+        )
+
+    def test_clear(self):
+        memory = MenteDBMemory()
+        memory.clear()
+
+
+class TestMenteDBRetriever:
+    def test_default_construction(self):
+        retriever = MenteDBRetriever()
+        assert retriever.data_dir == "./mentedb-data"
+        assert retriever.k == 10
+        assert retriever.tags is None
+        assert retriever.agent_id is None
+
+    def test_custom_construction(self):
+        retriever = MenteDBRetriever(
+            data_dir="./custom-dir",
+            k=20,
+            tags=["backend"],
+            agent_id="agent-1",
+        )
+        assert retriever.k == 20
+        assert retriever.tags == ["backend"]
+
+    def test_get_relevant_documents(self):
+        retriever = MenteDBRetriever()
+        docs = retriever.get_relevant_documents("test query")
+        assert isinstance(docs, list)
+
+
+class TestMenteDBChatHistory:
+    def test_default_construction(self):
+        history = MenteDBChatHistory(session_id="s1")
+        assert history.session_id == "s1"
+        assert history.data_dir == "./mentedb-data"
+        assert history.agent_id is None
+
+    def test_messages_empty(self):
+        history = MenteDBChatHistory(session_id="s1")
+        assert history.messages == []
+
+    def test_add_messages(self):
+        history = MenteDBChatHistory(session_id="s1")
+        history.add_user_message("hello")
+        history.add_ai_message("hi there")
+        assert len(history.messages) == 2
+        assert history.messages[0] == {"role": "user", "content": "hello"}
+        assert history.messages[1] == {"role": "assistant", "content": "hi there"}
+
+    def test_clear(self):
+        history = MenteDBChatHistory(session_id="s1")
+        history.add_user_message("hello")
+        history.clear()
+        assert history.messages == []