langchain-mimir 0.1.0__tar.gz

langchain_mimir-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,45 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install build
+        run: pip install build==1.2.2.post1
+
+      - name: Build
+        run: python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/langchain-mimir
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

langchain_mimir-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,28 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ['3.10', '3.12']
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install
+        run: pip install -e ".[test]"
+
+      - name: Run tests
+        run: python -m pytest tests/ -q

langchain_mimir-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+*.db
+*.db-shm
+*.db-wal
+.venv/
+venv/

langchain_mimir-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Perseus Computing LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

langchain_mimir-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: langchain-mimir
+Version: 0.1.0
+Summary: Mimir persistent, local, encrypted memory for LangChain — tools and a retriever backed by the Mimir MCP engine.
+Project-URL: Homepage, https://github.com/Perseus-Computing-LLC/langchain-mimir
+Project-URL: Repository, https://github.com/Perseus-Computing-LLC/langchain-mimir
+Project-URL: Bug Tracker, https://github.com/Perseus-Computing-LLC/langchain-mimir/issues
+Project-URL: Mimir, https://github.com/Perseus-Computing-LLC/mimir
+Author-email: Perseus Computing LLC <hermes@perseus.observer>
+License: MIT
+License-File: LICENSE
+Keywords: agents,langchain,llm,mcp,memory,mimir,retriever
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: langchain-core>=0.3.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# langchain-mimir
+
+Persistent, local-first, encrypted memory for [LangChain](https://www.langchain.com/),
+backed by [Mimir](https://github.com/Perseus-Computing-LLC/mimir) — an open-source
+(MIT) memory engine with FTS5 + dense hybrid search and optional AES-256-GCM
+encryption, exposed over the Model Context Protocol (MCP) stdio transport.
+
+It gives a LangChain agent durable memory that survives across runs and
+processes, stored in a single local SQLite file you control — no external
+service, no cloud.
+
+## What you get
+
+This package wraps Mimir using the modern `langchain-core` interfaces:
+
+- **`create_mimir_tools(client)`** — a pair of `StructuredTool`s
+  (`mimir_remember` / `mimir_recall`) you give to an agent so it can manage its
+  own long-term memory via tool calls. This is the current-recommended LangChain
+  pattern (the legacy `Memory` / `ConversationBufferMemory` classes are
+  deprecated).
+- **`MimirRetriever`** — a `BaseRetriever` returning `Document`s, for drop-in use
+  in RAG chains and anywhere LangChain accepts a retriever (`.invoke(query)`).
+- **`MimirClient`** — the low-level MCP stdio client, if you want direct access.
+
+## Prerequisite: the `mimir` binary
+
+This package talks to a local `mimir` executable via JSON-RPC over stdio. You
+must have it installed:
+
+- Download a release from
+  <https://github.com/Perseus-Computing-LLC/mimir/releases>, or build from source
+  (`cargo build --release`), and put `mimir` on your `$PATH`.
+- Or pass an absolute path: `MimirClient(mimir_binary="/path/to/mimir")`.
+
+On Windows the binary may be named `mimir.exe`; ensure its directory is on
+`PATH`, or pass the full path.
+
+## Install
+
+```bash
+pip install langchain-mimir
+```
+
+## Usage
+
+### As agent tools
+
+```python
+from langchain_mimir import MimirClient, create_mimir_tools
+
+client = MimirClient(db_path="~/.langchain/mimir.db")
+tools = create_mimir_tools(client)  # [mimir_remember, mimir_recall]
+
+# Bind to any tool-calling model / agent:
+from langchain.chat_models import init_chat_model
+
+llm = init_chat_model("anthropic:claude-sonnet-4-5")
+llm_with_memory = llm.bind_tools(tools)
+
+resp = llm_with_memory.invoke("Remember that my favorite language is Rust.")
+# ... the model will call mimir_remember; execute the tool call as usual.
+```
+
+### As a retriever
+
+```python
+from langchain_mimir import MimirClient, MimirRetriever
+
+client = MimirClient(db_path="~/.langchain/mimir.db")
+client.remember("The capital of France is Paris.")
+
+retriever = MimirRetriever(client=client, k=5)
+docs = retriever.invoke("What is the capital of France?")
+print(docs[0].page_content)  # -> "The capital of France is Paris."
+```
+
+### Direct client
+
+```python
+from langchain_mimir import MimirClient
+
+client = MimirClient(db_path="~/.langchain/mimir.db")
+client.remember("Project deadline is July 15.", tags=["project", "deadline"])
+items = client.recall("when is the deadline")
+print(items[0]["text"])
+```
+
+## How it works
+
+`MimirClient` spawns `mimir --db <path>` as a subprocess and speaks JSON-RPC 2.0
+(MCP) over its stdin/stdout. A background reader thread and a lock make calls
+thread-safe and timeout-bounded. Memories are stored via `mimir_remember` and
+retrieved via `mimir_recall`.
+
+## License
+
+MIT © 2026 Perseus Computing LLC

langchain_mimir-0.1.0/README.md

@@ -0,0 +1,97 @@
+# langchain-mimir
+
+Persistent, local-first, encrypted memory for [LangChain](https://www.langchain.com/),
+backed by [Mimir](https://github.com/Perseus-Computing-LLC/mimir) — an open-source
+(MIT) memory engine with FTS5 + dense hybrid search and optional AES-256-GCM
+encryption, exposed over the Model Context Protocol (MCP) stdio transport.
+
+It gives a LangChain agent durable memory that survives across runs and
+processes, stored in a single local SQLite file you control — no external
+service, no cloud.
+
+## What you get
+
+This package wraps Mimir using the modern `langchain-core` interfaces:
+
+- **`create_mimir_tools(client)`** — a pair of `StructuredTool`s
+  (`mimir_remember` / `mimir_recall`) you give to an agent so it can manage its
+  own long-term memory via tool calls. This is the current-recommended LangChain
+  pattern (the legacy `Memory` / `ConversationBufferMemory` classes are
+  deprecated).
+- **`MimirRetriever`** — a `BaseRetriever` returning `Document`s, for drop-in use
+  in RAG chains and anywhere LangChain accepts a retriever (`.invoke(query)`).
+- **`MimirClient`** — the low-level MCP stdio client, if you want direct access.
+
+## Prerequisite: the `mimir` binary
+
+This package talks to a local `mimir` executable via JSON-RPC over stdio. You
+must have it installed:
+
+- Download a release from
+  <https://github.com/Perseus-Computing-LLC/mimir/releases>, or build from source
+  (`cargo build --release`), and put `mimir` on your `$PATH`.
+- Or pass an absolute path: `MimirClient(mimir_binary="/path/to/mimir")`.
+
+On Windows the binary may be named `mimir.exe`; ensure its directory is on
+`PATH`, or pass the full path.
+
+## Install
+
+```bash
+pip install langchain-mimir
+```
+
+## Usage
+
+### As agent tools
+
+```python
+from langchain_mimir import MimirClient, create_mimir_tools
+
+client = MimirClient(db_path="~/.langchain/mimir.db")
+tools = create_mimir_tools(client)  # [mimir_remember, mimir_recall]
+
+# Bind to any tool-calling model / agent:
+from langchain.chat_models import init_chat_model
+
+llm = init_chat_model("anthropic:claude-sonnet-4-5")
+llm_with_memory = llm.bind_tools(tools)
+
+resp = llm_with_memory.invoke("Remember that my favorite language is Rust.")
+# ... the model will call mimir_remember; execute the tool call as usual.
+```
+
+### As a retriever
+
+```python
+from langchain_mimir import MimirClient, MimirRetriever
+
+client = MimirClient(db_path="~/.langchain/mimir.db")
+client.remember("The capital of France is Paris.")
+
+retriever = MimirRetriever(client=client, k=5)
+docs = retriever.invoke("What is the capital of France?")
+print(docs[0].page_content)  # -> "The capital of France is Paris."
+```
+
+### Direct client
+
+```python
+from langchain_mimir import MimirClient
+
+client = MimirClient(db_path="~/.langchain/mimir.db")
+client.remember("Project deadline is July 15.", tags=["project", "deadline"])
+items = client.recall("when is the deadline")
+print(items[0]["text"])
+```
+
+## How it works
+
+`MimirClient` spawns `mimir --db <path>` as a subprocess and speaks JSON-RPC 2.0
+(MCP) over its stdin/stdout. A background reader thread and a lock make calls
+thread-safe and timeout-bounded. Memories are stored via `mimir_remember` and
+retrieved via `mimir_recall`.
+
+## License
+
+MIT © 2026 Perseus Computing LLC

langchain_mimir-0.1.0/langchain_mimir/__init__.py

@@ -0,0 +1,34 @@
+"""langchain-mimir — Mimir persistent memory for LangChain.
+
+Mimir (github.com/Perseus-Computing-LLC/mimir) is an open-source (MIT),
+local-first, encrypted persistent memory engine that speaks MCP JSON-RPC over
+stdio. This package exposes it to LangChain via the modern ``langchain-core``
+interfaces:
+
+- :class:`MimirClient` — low-level stdio client for the ``mimir`` binary.
+- :func:`create_mimir_tools` — ``StructuredTool``s (remember / recall) for agents.
+- :class:`MimirRetriever` — a ``BaseRetriever`` for RAG chains.
+
+Requirements:
+    A ``mimir`` binary must be on ``$PATH`` or passed via ``mimir_binary=``.
+    Download from https://github.com/Perseus-Computing-LLC/mimir/releases
+"""
+
+from .client import MimirClient, MimirError
+from .integration import (
+    MimirRetriever,
+    create_mimir_tools,
+    create_recall_tool,
+    create_remember_tool,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "MimirClient",
+    "MimirError",
+    "MimirRetriever",
+    "create_mimir_tools",
+    "create_remember_tool",
+    "create_recall_tool",
+]

langchain_mimir-0.1.0/langchain_mimir/client.py

@@ -0,0 +1,327 @@
+"""Mimir MCP stdio client.
+
+Spawns a local ``mimir`` binary and speaks JSON-RPC 2.0 over its stdin/stdout
+(MCP stdio transport).  This is the low-level transport reused by the LangChain
+tools and retriever; it has no LangChain dependency of its own.
+
+The subprocess/JSON-RPC machinery here is adapted from the proven
+``adk-mimir-memory`` client (github.com/Perseus-Computing-LLC/adk-mimir-memory):
+a background reader thread pumps stdout lines into a queue so RPC calls can wait
+with a timeout and correlate responses by id, and a lock serializes
+request/response exchanges so they never interleave.
+
+Requirements:
+    A ``mimir`` binary must be on ``$PATH`` or passed explicitly via
+    ``mimir_binary``.  Download from:
+    https://github.com/Perseus-Computing-LLC/mimir/releases
+"""
+
+from __future__ import annotations
+
+import atexit
+import json
+import os
+import queue
+import shutil
+import subprocess
+import threading
+import time
+
+__all__ = ["MimirClient", "MimirError"]
+
+
+class MimirError(RuntimeError):
+    """Raised when the Mimir subprocess errors, crashes, or times out."""
+
+
+class MimirClient:
+    """Thread-safe JSON-RPC client for a local Mimir MCP stdio server.
+
+    Starts ``mimir --db <db_path>`` as a subprocess, performs the MCP
+    ``initialize`` handshake, and exposes :meth:`call_tool` for invoking any of
+    Mimir's MCP tools (``mimir_remember``, ``mimir_recall``, ...).
+
+    Attributes:
+        db_path: Filesystem path to the Mimir SQLite database.
+    """
+
+    def __init__(
+        self,
+        db_path: str = "~/.langchain/mimir.db",
+        mimir_binary: str = "mimir",
+        timeout_s: float = 30.0,
+        encryption_key: str | None = None,
+    ) -> None:
+        """Initializes and starts the Mimir client.
+
+        Args:
+            db_path: Path to the Mimir database file.  Defaults to
+                ``~/.langchain/mimir.db``.
+            mimir_binary: Name or absolute path of the ``mimir`` executable.
+                Defaults to ``mimir`` (resolved from ``$PATH``).
+            timeout_s: Maximum time to wait for any single RPC response.
+            encryption_key: Optional path to an AES-256-GCM key file; if given,
+                passed to the binary via ``--encryption-key``.
+
+        Raises:
+            MimirError: If the binary cannot be found or the subprocess fails to
+                start or complete the MCP handshake.
+        """
+        self.db_path = os.path.expanduser(db_path)
+        self._timeout_s = timeout_s
+
+        # Resolve the mimir binary.
+        if os.path.isabs(mimir_binary) and os.path.exists(mimir_binary):
+            self._mimir_binary = mimir_binary
+        else:
+            resolved = shutil.which(mimir_binary)
+            if resolved is None and os.path.exists(mimir_binary):
+                resolved = mimir_binary
+            if resolved is None:
+                raise MimirError(
+                    f"mimir binary not found (looked for '{mimir_binary}'). "
+                    "Install Mimir from "
+                    "https://github.com/Perseus-Computing-LLC/mimir/releases "
+                    "or pass the absolute path via mimir_binary=."
+                )
+            self._mimir_binary = resolved
+
+        # Ensure the database directory exists.
+        os.makedirs(os.path.dirname(self.db_path) or ".", exist_ok=True)
+
+        argv = [self._mimir_binary, "--db", self.db_path]
+        if encryption_key:
+            argv += ["--encryption-key", encryption_key]
+
+        # Start the MCP stdio subprocess. stderr is discarded: nothing drains
+        # it, so a chatty server filling the OS pipe buffer would block on its
+        # stderr write while we wait on stdout (a two-pipe deadlock).
+        try:
+            self._proc = subprocess.Popen(
+                argv,
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.DEVNULL,
+                text=True,
+            )
+        except OSError as e:
+            raise MimirError(f"failed to start mimir subprocess: {e}") from e
+
+        self._lock = threading.Lock()
+        self._request_id = 0
+        self._closed = False
+
+        # Background reader: pump stdout lines into a queue so _rpc can wait with
+        # a timeout and correlate responses by id, rather than blocking forever
+        # on a bare readline().
+        self._recv: queue.Queue = queue.Queue()
+        proc_stdout = self._proc.stdout
+
+        def _pump() -> None:
+            try:
+                for line in proc_stdout:
+                    self._recv.put(line)
+            except Exception:
+                pass
+            finally:
+                self._recv.put(None)  # EOF sentinel
+
+        self._reader = threading.Thread(target=_pump, daemon=True)
+        self._reader.start()
+
+        # MCP handshake: initialize, then the required initialized notification
+        # before any tools/call.
+        self._rpc(
+            "initialize",
+            {
+                "protocolVersion": "2024-11-05",
+                "capabilities": {},
+                "clientInfo": {"name": "langchain-mimir", "version": "0.1.0"},
+            },
+        )
+        self._notify("notifications/initialized", {})
+
+        atexit.register(self.close)
+
+    # ── lifecycle ──────────────────────────────────────────────────────────
+
+    def close(self) -> None:
+        """Terminates the Mimir subprocess.  Safe to call multiple times."""
+        if self._closed:
+            return
+        self._closed = True
+        try:
+            self._proc.terminate()
+            self._proc.wait(timeout=5)
+        except Exception:
+            try:
+                self._proc.kill()
+            except Exception:
+                pass
+
+    def __enter__(self) -> "MimirClient":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+    # ── JSON-RPC core ──────────────────────────────────────────────────────
+
+    def _next_id(self) -> int:
+        self._request_id += 1
+        return self._request_id
+
+    def _rpc(self, method: str, params: object) -> dict:
+        """Sends a JSON-RPC request and returns the ``result`` dict.
+
+        The lock is held for the whole exchange so request/response pairs never
+        interleave.  Replies with a non-matching id (notifications, stale
+        replies) are skipped.
+
+        Raises:
+            MimirError: On transport failure, RPC error, or timeout.
+        """
+        with self._lock:
+            req_id = self._next_id()
+            req = {
+                "jsonrpc": "2.0",
+                "id": req_id,
+                "method": method,
+                "params": params,
+            }
+            payload = json.dumps(req, default=str)
+            try:
+                self._proc.stdin.write(payload + "\n")
+                self._proc.stdin.flush()
+            except (BrokenPipeError, OSError) as e:
+                raise MimirError(
+                    f"mimir communication failed: {e}. The process may have crashed."
+                ) from e
+
+            deadline = time.monotonic() + self._timeout_s
+            while True:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    raise MimirError(
+                        f"mimir RPC '{method}' timed out after {self._timeout_s}s."
+                    )
+                try:
+                    raw = self._recv.get(timeout=remaining)
+                except queue.Empty:
+                    raise MimirError(
+                        f"mimir RPC '{method}' timed out after {self._timeout_s}s."
+                    )
+                if raw is None:
+                    raise MimirError(
+                        "mimir closed its output stream (it may have crashed)."
+                    )
+                raw = raw.strip()
+                if not raw:
+                    continue
+                try:
+                    resp = json.loads(raw)
+                except json.JSONDecodeError:
+                    continue  # non-JSON noise on stdout
+                if resp.get("id") != req_id:
+                    continue  # notification or a stale/other reply
+
+                if "error" in resp:
+                    err = resp["error"]
+                    raise MimirError(
+                        f"mimir RPC error [{err.get('code')}]: {err.get('message')}"
+                    )
+                return resp.get("result", {})
+
+    def _notify(self, method: str, params: object) -> None:
+        """Sends a JSON-RPC notification (no id, no response expected)."""
+        payload = json.dumps({"jsonrpc": "2.0", "method": method, "params": params})
+        with self._lock:
+            try:
+                self._proc.stdin.write(payload + "\n")
+                self._proc.stdin.flush()
+            except (BrokenPipeError, OSError):
+                pass
+
+    # ── public API ─────────────────────────────────────────────────────────
+
+    def call_tool(self, name: str, arguments: dict) -> dict:
+        """Calls a Mimir MCP tool and returns its structured result.
+
+        Args:
+            name: The Mimir tool name (e.g. ``mimir_remember``).
+            arguments: The tool's arguments dict.
+
+        Returns:
+            The tool's ``structuredContent`` if present, otherwise the parsed
+            text content, otherwise ``{}``.
+        """
+        result = self._rpc("tools/call", {"name": name, "arguments": arguments})
+        # MCP result: {content: [{type: "text", text: "..."}], structuredContent: {...}}
+        sc = result.get("structuredContent")
+        if sc is not None:
+            return sc
+        content = result.get("content", [])
+        if content:
+            try:
+                return json.loads(content[0].get("text", "{}"))
+            except (json.JSONDecodeError, IndexError, KeyError, AttributeError):
+                pass
+        return {}
+
+    # convenience wrappers ---------------------------------------------------
+
+    def remember(
+        self,
+        text: str,
+        *,
+        category: str = "langchain-memory",
+        key: str | None = None,
+        tags: list[str] | None = None,
+        extra_body: dict | None = None,
+    ) -> dict:
+        """Stores a memory.  Returns the ``mimir_remember`` result.
+
+        Args:
+            text: The natural-language memory content.
+            category: Mimir category (namespace) for the entity.
+            key: Stable key within the category; autogenerated if omitted.
+                Reusing a key updates that entity (idempotent upsert).
+            tags: Optional tags stored on the entity.
+            extra_body: Extra fields merged into the stored JSON body.
+        """
+        if key is None:
+            key = f"mem-{int(time.time() * 1000)}-{self._next_id()}"
+        body = {"text": text}
+        if extra_body:
+            body.update(extra_body)
+        args = {
+            "category": category,
+            "key": key,
+            "body_json": json.dumps(body),
+        }
+        if tags:
+            args["tags"] = tags
+        return self.call_tool("mimir_remember", args)
+
+    def recall(
+        self,
+        query: str,
+        *,
+        limit: int = 5,
+        category: str | None = None,
+    ) -> list[dict]:
+        """Searches memories.  Returns the list of raw Mimir items.
+
+        Args:
+            query: Natural-language / keyword query (FTS5; terms OR'd).
+            limit: Maximum number of items to return.
+            category: Optional category to scope the search.
+        """
+        args: dict = {"query": query, "limit": limit}
+        if category is not None:
+            args["category"] = category
+        result = self.call_tool("mimir_recall", args)
+        items = result.get("items")
+        if items is None:
+            items = result.get("results", [])
+        return items or []

langchain_mimir-0.1.0/langchain_mimir/integration.py

@@ -0,0 +1,189 @@
+"""LangChain integration surface for the Mimir memory engine.
+
+Two complementary, current-recommended ``langchain-core`` surfaces are exposed:
+
+1. **Tools** — :func:`create_mimir_tools` returns a pair of ``StructuredTool``s
+   (``mimir_remember`` / ``mimir_recall``) that an agent can call to persist and
+   retrieve long-term memory. Tool-calling is the modern LangChain pattern for
+   giving an agent agency over its own memory (the legacy ``Memory`` /
+   ``ConversationBufferMemory`` classes are deprecated).
+
+2. **Retriever** — :class:`MimirRetriever` is a ``BaseRetriever`` that turns a
+   query into ``Document`` objects, for drop-in use in RAG chains and anywhere a
+   LangChain retriever is accepted (``.invoke(query)``).
+
+Both are thin wrappers over :class:`langchain_mimir.client.MimirClient`.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from langchain_core.callbacks import CallbackManagerForRetrieverRun
+from langchain_core.documents import Document
+from langchain_core.retrievers import BaseRetriever
+from langchain_core.tools import StructuredTool
+from pydantic import BaseModel, Field
+
+from .client import MimirClient
+
+__all__ = [
+    "MimirRetriever",
+    "create_mimir_tools",
+    "create_remember_tool",
+    "create_recall_tool",
+]
+
+
+# ── helpers ──────────────────────────────────────────────────────────────────
+
+
+def _item_to_text(item: dict) -> str:
+    """Extracts the best human-readable text from a Mimir recall item."""
+    text = item.get("text")
+    if text:
+        return text
+    body = item.get("body_json")
+    if isinstance(body, str):
+        try:
+            body = json.loads(body)
+        except json.JSONDecodeError:
+            return body
+    if isinstance(body, dict):
+        return body.get("text") or body.get("content") or json.dumps(body)
+    return ""
+
+
+def _item_to_document(item: dict) -> Document:
+    """Converts a raw Mimir recall item into a LangChain ``Document``."""
+    return Document(
+        page_content=_item_to_text(item),
+        metadata={
+            "id": item.get("id"),
+            "category": item.get("category"),
+            "key": item.get("key"),
+            "tags": item.get("tags", []),
+            "decay_score": item.get("decay_score"),
+            "created_at_unix_ms": item.get("created_at_unix_ms"),
+        },
+    )
+
+
+# ── retriever ────────────────────────────────────────────────────────────────
+
+
+class MimirRetriever(BaseRetriever):
+    """Retriever backed by Mimir's FTS5 keyword search.
+
+    Example::
+
+        from langchain_mimir import MimirClient, MimirRetriever
+
+        client = MimirClient(db_path="~/.langchain/mimir.db")
+        client.remember("The capital of France is Paris.")
+
+        retriever = MimirRetriever(client=client)
+        docs = retriever.invoke("What is the capital of France?")
+    """
+
+    client: MimirClient
+    k: int = 5
+    category: str | None = None
+
+    # MimirClient is an arbitrary (non-pydantic) type.
+    model_config = {"arbitrary_types_allowed": True}
+
+    def _get_relevant_documents(
+        self,
+        query: str,
+        *,
+        run_manager: CallbackManagerForRetrieverRun | None = None,
+    ) -> list[Document]:
+        items = self.client.recall(query, limit=self.k, category=self.category)
+        return [_item_to_document(it) for it in items]
+
+
+# ── tools ────────────────────────────────────────────────────────────────────
+
+
+class _RememberInput(BaseModel):
+    text: str = Field(description="The fact or memory to store for later recall.")
+    tags: list[str] | None = Field(
+        default=None, description="Optional tags to label this memory."
+    )
+
+
+class _RecallInput(BaseModel):
+    query: str = Field(description="What to search the memory for.")
+    limit: int = Field(default=5, description="Max number of memories to return.")
+
+
+def create_remember_tool(
+    client: MimirClient,
+    *,
+    category: str = "langchain-memory",
+) -> StructuredTool:
+    """Builds a ``StructuredTool`` that stores a memory in Mimir."""
+
+    def _remember(text: str, tags: list[str] | None = None) -> str:
+        result = client.remember(text, category=category, tags=tags)
+        action = result.get("action", "stored")
+        key = result.get("key", "")
+        return f"Memory {action} (key={key})."
+
+    return StructuredTool.from_function(
+        func=_remember,
+        name="mimir_remember",
+        description=(
+            "Store a fact or memory in long-term persistent memory so it can be "
+            "recalled in future conversations. Use this whenever the user shares "
+            "durable information worth remembering."
+        ),
+        args_schema=_RememberInput,
+    )
+
+
+def create_recall_tool(
+    client: MimirClient,
+    *,
+    category: str | None = "langchain-memory",
+) -> StructuredTool:
+    """Builds a ``StructuredTool`` that searches Mimir's memory."""
+
+    def _recall(query: str, limit: int = 5) -> str:
+        items = client.recall(query, limit=limit, category=category)
+        if not items:
+            return "No relevant memories found."
+        lines = [f"- {_item_to_text(it)}" for it in items if _item_to_text(it)]
+        return "\n".join(lines) if lines else "No relevant memories found."
+
+    return StructuredTool.from_function(
+        func=_recall,
+        name="mimir_recall",
+        description=(
+            "Search long-term persistent memory for facts relevant to a query. "
+            "Use this to recall things the user told you in past conversations."
+        ),
+        args_schema=_RecallInput,
+    )
+
+
+def create_mimir_tools(
+    client: MimirClient,
+    *,
+    category: str = "langchain-memory",
+) -> list[StructuredTool]:
+    """Returns ``[remember_tool, recall_tool]`` bound to ``client``.
+
+    Pass the result to any LangChain agent / ``bind_tools`` call to give the
+    model agency over its own persistent memory.
+
+    Args:
+        client: An initialized :class:`MimirClient`.
+        category: The Mimir category (namespace) used for both tools.
+    """
+    return [
+        create_remember_tool(client, category=category),
+        create_recall_tool(client, category=category),
+    ]

langchain_mimir-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "langchain-mimir"
+version = "0.1.0"
+authors = [
+    { name = "Perseus Computing LLC", email = "hermes@perseus.observer" },
+]
+description = "Mimir persistent, local, encrypted memory for LangChain — tools and a retriever backed by the Mimir MCP engine."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+keywords = ["langchain", "mimir", "memory", "mcp", "retriever", "agents", "llm"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Intended Audience :: Developers",
+]
+dependencies = [
+    "langchain-core>=0.3.0",
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=7.0"]
+
+[project.urls]
+Homepage = "https://github.com/Perseus-Computing-LLC/langchain-mimir"
+Repository = "https://github.com/Perseus-Computing-LLC/langchain-mimir"
+"Bug Tracker" = "https://github.com/Perseus-Computing-LLC/langchain-mimir/issues"
+Mimir = "https://github.com/Perseus-Computing-LLC/mimir"
+
+[tool.hatch.build.targets.wheel]
+packages = ["langchain_mimir"]

langchain_mimir-0.1.0/tests/test_langchain_mimir.py

@@ -0,0 +1,336 @@
+"""Tests for langchain-mimir.
+
+The unit tests monkeypatch ``subprocess.Popen`` with an in-process fake that
+speaks JSON-RPC 2.0 over fake stdin/stdout pipes and models Mimir's
+remember/recall behavior, so they run with no real ``mimir`` binary. They
+exercise the real RPC, threading, tool, and retriever code paths.
+
+A final smoke test runs a real remember->recall round trip if (and only if) a
+``mimir`` binary is discoverable; otherwise it is skipped.
+"""
+
+from __future__ import annotations
+
+import json
+import queue
+import shutil
+
+import pytest
+
+from langchain_core.documents import Document
+from langchain_core.retrievers import BaseRetriever
+from langchain_core.tools import StructuredTool
+
+import langchain_mimir.client as client_mod
+from langchain_mimir import (
+    MimirClient,
+    MimirError,
+    MimirRetriever,
+    create_mimir_tools,
+)
+
+
+# ── Fake Mimir MCP stdio server ──────────────────────────────────────────────
+
+
+class _FakeStdin:
+    def __init__(self, on_line):
+        self._on_line = on_line
+
+    def write(self, s):
+        for line in s.splitlines():
+            if line.strip():
+                self._on_line(line)
+
+    def flush(self):
+        pass
+
+    def close(self):
+        pass
+
+
+class _FakeStdout:
+    """Blocking, iterable line source fed by the fake server."""
+
+    def __init__(self):
+        self._q = queue.Queue()
+
+    def put(self, line):
+        self._q.put(line)
+
+    def __iter__(self):
+        return self
+
+    def __next__(self):
+        item = self._q.get()
+        if item is None:
+            raise StopIteration
+        return item
+
+    def close(self):
+        self._q.put(None)
+
+
+class FakeMimir:
+    """Minimal Popen-compatible fake of the Mimir MCP stdio server.
+
+    Models remember as an upsert into ``self.store`` and recall as a naive
+    OR-of-terms substring match over stored text, returning Mimir-shaped items.
+    """
+
+    def __init__(self, *, answer_tools=True):
+        self.store: dict[tuple, dict] = {}  # (category, key) -> item
+        self._counter = 0
+        self.stdout = _FakeStdout()
+        self.stdin = _FakeStdin(self._handle)
+        self._alive = True
+        self._answer_tools = answer_tools
+
+    # Popen-compatible surface -------------------------------------------------
+    def terminate(self):
+        self._alive = False
+        self.stdout.close()
+
+    def wait(self, timeout=None):
+        return 0
+
+    def kill(self):
+        self._alive = False
+        self.stdout.close()
+
+    # JSON-RPC handling --------------------------------------------------------
+    def _reply(self, rid, result):
+        self.stdout.put(json.dumps({"jsonrpc": "2.0", "id": rid, "result": result}))
+
+    def _handle(self, line):
+        req = json.loads(line)
+        rid = req.get("id")
+        method = req.get("method")
+        if rid is None:
+            return  # notification, no response
+        if method == "initialize":
+            self._reply(rid, {"protocolVersion": "2024-11-05", "capabilities": {}})
+            return
+        if method == "tools/call":
+            if not self._answer_tools:
+                return  # simulate a hang -> RPC timeout
+            self._handle_tool(rid, req["params"])
+            return
+        self._reply(rid, {})
+
+    def _handle_tool(self, rid, params):
+        name = params["name"]
+        args = params["arguments"]
+        if name == "mimir_remember":
+            self._counter += 1
+            ckey = (args["category"], args["key"])
+            existed = ckey in self.store
+            body = args.get("body_json", "{}")
+            try:
+                text = json.loads(body).get("text", "")
+            except json.JSONDecodeError:
+                text = ""
+            self.store[ckey] = {
+                "id": f"mem-{self._counter}",
+                "category": args["category"],
+                "key": args["key"],
+                "text": text,
+                "body_json": body,
+                "tags": args.get("tags", []),
+                "decay_score": 0.5,
+                "created_at_unix_ms": 1000 + self._counter,
+            }
+            sc = {
+                "action": "updated" if existed else "created",
+                "category": args["category"],
+                "key": args["key"],
+                "id": self.store[ckey]["id"],
+            }
+            self._mcp_reply(rid, sc)
+        elif name == "mimir_recall":
+            query = args.get("query", "").lower()
+            terms = [t for t in query.split() if t]
+            cat = args.get("category")
+            limit = args.get("limit", 5)
+            items = []
+            for (c, _k), item in self.store.items():
+                if cat is not None and c != cat:
+                    continue
+                hay = item["text"].lower()
+                if any(t in hay for t in terms):
+                    items.append(item)
+            items = items[:limit]
+            self._mcp_reply(rid, {"items": items, "total": len(items)})
+        else:
+            self._mcp_reply(rid, {})
+
+    def _mcp_reply(self, rid, structured):
+        # Mirror real MCP tools/call result shape.
+        self._reply(
+            rid,
+            {
+                "content": [{"type": "text", "text": json.dumps(structured)}],
+                "structuredContent": structured,
+            },
+        )
+
+
+# ── fixtures ─────────────────────────────────────────────────────────────────
+
+
+@pytest.fixture
+def fake_client(monkeypatch, tmp_path):
+    """A MimirClient wired to an in-process FakeMimir (no real binary)."""
+    fake = FakeMimir()
+
+    def fake_popen(argv, **kwargs):
+        return fake
+
+    monkeypatch.setattr(client_mod.subprocess, "Popen", fake_popen)
+    # Make binary resolution succeed without a real executable.
+    monkeypatch.setattr(client_mod.shutil, "which", lambda name: "/fake/mimir")
+
+    client = MimirClient(db_path=str(tmp_path / "mimir.db"))
+    client._fake = fake  # for assertions
+    yield client
+    client.close()
+
+
+# ── client tests ─────────────────────────────────────────────────────────────
+
+
+def test_binary_not_found(monkeypatch, tmp_path):
+    monkeypatch.setattr(client_mod.shutil, "which", lambda name: None)
+    with pytest.raises(MimirError, match="mimir binary not found"):
+        MimirClient(db_path=str(tmp_path / "x.db"), mimir_binary="definitely-missing")
+
+
+def test_remember_then_recall(fake_client):
+    r = fake_client.remember("The capital of France is Paris.", key="k1")
+    assert r["action"] == "created"
+
+    items = fake_client.recall("capital France")
+    assert len(items) == 1
+    assert "Paris" in items[0]["text"]
+
+
+def test_remember_is_idempotent_upsert(fake_client):
+    fake_client.remember("first", key="dup")
+    r2 = fake_client.remember("second", key="dup")
+    assert r2["action"] == "updated"
+    assert len(fake_client._fake.store) == 1
+
+
+def test_recall_respects_limit(fake_client):
+    for i in range(5):
+        fake_client.remember(f"alpha memory number {i}", key=f"k{i}")
+    items = fake_client.recall("alpha", limit=2)
+    assert len(items) == 2
+
+
+def test_recall_no_match_returns_empty(fake_client):
+    fake_client.remember("something unrelated", key="k1")
+    assert fake_client.recall("nonexistent zebra") == []
+
+
+def test_rpc_timeout(monkeypatch, tmp_path):
+    fake = FakeMimir(answer_tools=True)
+    monkeypatch.setattr(client_mod.subprocess, "Popen", lambda *a, **k: fake)
+    monkeypatch.setattr(client_mod.shutil, "which", lambda name: "/fake/mimir")
+    client = MimirClient(db_path=str(tmp_path / "m.db"), timeout_s=0.3)
+    # Flip the fake to stop answering tool calls -> the next call must time out.
+    fake._answer_tools = False
+    with pytest.raises(MimirError, match="timed out"):
+        client.recall("anything")
+    client.close()
+
+
+# ── tools tests ──────────────────────────────────────────────────────────────
+
+
+def test_create_mimir_tools_shape(fake_client):
+    tools = create_mimir_tools(fake_client)
+    assert len(tools) == 2
+    assert all(isinstance(t, StructuredTool) for t in tools)
+    names = {t.name for t in tools}
+    assert names == {"mimir_remember", "mimir_recall"}
+
+
+def test_remember_tool_invoke(fake_client):
+    remember, recall = create_mimir_tools(fake_client)
+    out = remember.invoke({"text": "I love Rust.", "tags": ["pref"]})
+    assert "created" in out or "stored" in out
+    # And it is recallable through the recall tool.
+    recalled = recall.invoke({"query": "Rust"})
+    assert "Rust" in recalled
+
+
+def test_recall_tool_no_results(fake_client):
+    _, recall = create_mimir_tools(fake_client)
+    out = recall.invoke({"query": "nothing here"})
+    assert out == "No relevant memories found."
+
+
+def test_tool_args_schema_present(fake_client):
+    remember, recall = create_mimir_tools(fake_client)
+    assert "text" in remember.args
+    assert "query" in recall.args
+
+
+# ── retriever tests ──────────────────────────────────────────────────────────
+
+
+def test_retriever_is_base_retriever(fake_client):
+    r = MimirRetriever(client=fake_client)
+    assert isinstance(r, BaseRetriever)
+
+
+def test_retriever_returns_documents(fake_client):
+    fake_client.remember("The capital of France is Paris.", key="k1")
+    retriever = MimirRetriever(client=fake_client, k=3)
+    docs = retriever.invoke("What is the capital of France?")
+    assert len(docs) == 1
+    assert isinstance(docs[0], Document)
+    assert "Paris" in docs[0].page_content
+    assert docs[0].metadata["key"] == "k1"
+    assert docs[0].metadata["category"] == "langchain-memory"
+
+
+def test_retriever_empty(fake_client):
+    retriever = MimirRetriever(client=fake_client)
+    assert retriever.invoke("zebra unicorn") == []
+
+
+def test_retriever_category_scoping(fake_client):
+    fake_client.remember("scoped fact apple", category="catA", key="a")
+    fake_client.remember("other fact apple", category="catB", key="b")
+    retriever = MimirRetriever(client=fake_client, category="catA")
+    docs = retriever.invoke("apple")
+    assert len(docs) == 1
+    assert docs[0].metadata["category"] == "catA"
+
+
+# ── real binary smoke test (skipped if mimir is unavailable) ─────────────────
+
+
+def _find_mimir():
+    return shutil.which("mimir") or shutil.which("mimir.exe")
+
+
+@pytest.mark.skipif(_find_mimir() is None, reason="no real mimir binary on PATH")
+def test_real_roundtrip(tmp_path):
+    """Real remember -> recall against an actual mimir subprocess."""
+    binary = _find_mimir()
+    client = MimirClient(db_path=str(tmp_path / "real.db"), mimir_binary=binary)
+    try:
+        client.remember(
+            "The capital of France is Paris.", category="lc-smoke", key="smoke1"
+        )
+        items = client.recall("capital France", category="lc-smoke")
+        assert any("Paris" in (it.get("text") or "") for it in items)
+
+        retriever = MimirRetriever(client=client, category="lc-smoke")
+        docs = retriever.invoke("capital of France")
+        assert any("Paris" in d.page_content for d in docs)
+    finally:
+        client.close()