crewai-mimir 0.1.0__tar.gz

crewai_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/crewai-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

crewai_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

crewai_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.

crewai_mimir-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: crewai-mimir
+Version: 0.1.0
+Summary: Mimir long-term memory as CrewAI tools — local-first, encrypted, persistent memory the agent can explicitly call.
+Project-URL: Homepage, https://github.com/Perseus-Computing-LLC/crewai-mimir
+Project-URL: Repository, https://github.com/Perseus-Computing-LLC/crewai-mimir
+Project-URL: Bug Tracker, https://github.com/Perseus-Computing-LLC/crewai-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,crewai,llm,mcp,memory,mimir,tools
+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: crewai>=0.80.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# crewai-mimir
+
+**Long-term, local-first, encrypted memory for [CrewAI](https://crewai.com) agents — as explicit, agent-callable tools.**
+
+`crewai-mimir` wraps [Mimir](https://github.com/Perseus-Computing-LLC/mimir) (an open-source, MIT-licensed persistent memory engine with 40+ MCP tools, FTS5 + dense hybrid search, and optional AES-256-GCM encryption) as standard CrewAI `BaseTool`s. Your agents get two first-class actions they can deliberately call:
+
+- **`mimir_remember`** — persist a fact, decision, insight, or note that survives across runs.
+- **`mimir_recall`** — search what was stored earlier.
+
+### Why tools (and not CrewAI's built-in memory)?
+
+CrewAI ships *implicit* memory (auto-captured short/long-term memory) and a generic MCP adapter. `crewai-mimir` is deliberately different: it exposes **explicit, controllable memory** the agent chooses to invoke, with a typed `args_schema` so the LLM sees exactly what each call needs. Use it when you want the agent to reason about *what* to remember and *when* to recall — backed by a durable, encryptable store you own on disk.
+
+## Prerequisite: the `mimir` binary
+
+The tools talk to a local `mimir` process over JSON-RPC (MCP stdio). You need the `mimir` binary on your `PATH` (or pass an absolute path).
+
+Install it from the [Mimir repository](https://github.com/Perseus-Computing-LLC/mimir) (build from source, or grab a release). Verify:
+
+```bash
+mimir --version
+```
+
+The tools spawn `mimir serve --db <db_path>` for you — you do **not** start it manually.
+
+## Install
+
+```bash
+pip install crewai-mimir
+```
+
+(or, from source: `pip install -e ".[test]"`)
+
+## Quickstart
+
+```python
+from crewai import Agent, Crew, Task
+from crewai_mimir import build_mimir_tools
+
+# One shared mimir process backs both tools.
+memory_tools = build_mimir_tools(db_path="~/.mimir/data/crew.db")
+
+researcher = Agent(
+    role="Research Analyst",
+    goal="Answer questions, remembering durable facts for next time.",
+    backstory="You persist key findings to long-term memory and check it before answering.",
+    tools=memory_tools,
+    verbose=True,
+)
+
+remember_task = Task(
+    description="Remember that the project deadline is 2026-08-15. Store it under key 'project-deadline'.",
+    expected_output="Confirmation the deadline was stored.",
+    agent=researcher,
+)
+
+recall_task = Task(
+    description="What is the project deadline? Check your long-term memory.",
+    expected_output="The project deadline date.",
+    agent=researcher,
+)
+
+crew = Crew(agents=[researcher], tasks=[remember_task, recall_task])
+result = crew.kickoff()
+print(result)
+```
+
+### Using the tool classes directly
+
+```python
+from crewai_mimir import MimirRememberTool, MimirRecallTool, MimirClient
+
+client = MimirClient(db_path="~/.mimir/data/crew.db")          # one shared process
+remember = MimirRememberTool(client=client)
+recall = MimirRecallTool(client=client)
+
+agent = Agent(..., tools=[remember, recall])
+```
+
+If you omit `client`, each tool lazily starts its own `mimir serve` on first use
+(configurable via `db_path` and `mimir_binary`).
+
+### Encryption at rest
+
+```python
+tools = build_mimir_tools(
+    db_path="~/.mimir/data/crew.db",
+    encryption_key="~/.mimir/key.b64",   # base64-encoded 32-byte AES-256-GCM key
+)
+```
+
+## Tool reference
+
+| Tool | Required args | Optional args |
+|------|---------------|---------------|
+| `mimir_remember` | `content`, `key` | `category` (default `insight`), `tags`, `importance` (0.0–1.0) |
+| `mimir_recall` | `query` | `limit` (default 5), `category` |
+
+Both return a JSON string. `mimir_recall` returns `{"query": ..., "results": [...]}`.
+
+## How it works
+
+`MimirClient` spawns `mimir serve --db <path>`, performs the MCP `initialize`
+handshake, and issues id-correlated JSON-RPC requests with a per-call timeout
+over stdin/stdout. The client core is adapted from the proven
+[`adk-mimir-memory`](https://github.com/Perseus-Computing-LLC/adk-mimir-memory)
+package.
+
+## Development
+
+```bash
+pip install -e ".[test]"
+pytest -q
+```
+
+Unit tests mock the `mimir` subprocess, so they run with no binary installed.
+`tests/test_smoke_real_binary.py` runs an end-to-end round-trip against a real
+`mimir` binary when one is found on `PATH` (otherwise it is skipped).
+
+## License
+
+MIT © 2026 Perseus Computing LLC. Mimir is MIT-licensed by Perseus Computing LLC.

crewai_mimir-0.1.0/README.md

@@ -0,0 +1,122 @@
+# crewai-mimir
+
+**Long-term, local-first, encrypted memory for [CrewAI](https://crewai.com) agents — as explicit, agent-callable tools.**
+
+`crewai-mimir` wraps [Mimir](https://github.com/Perseus-Computing-LLC/mimir) (an open-source, MIT-licensed persistent memory engine with 40+ MCP tools, FTS5 + dense hybrid search, and optional AES-256-GCM encryption) as standard CrewAI `BaseTool`s. Your agents get two first-class actions they can deliberately call:
+
+- **`mimir_remember`** — persist a fact, decision, insight, or note that survives across runs.
+- **`mimir_recall`** — search what was stored earlier.
+
+### Why tools (and not CrewAI's built-in memory)?
+
+CrewAI ships *implicit* memory (auto-captured short/long-term memory) and a generic MCP adapter. `crewai-mimir` is deliberately different: it exposes **explicit, controllable memory** the agent chooses to invoke, with a typed `args_schema` so the LLM sees exactly what each call needs. Use it when you want the agent to reason about *what* to remember and *when* to recall — backed by a durable, encryptable store you own on disk.
+
+## Prerequisite: the `mimir` binary
+
+The tools talk to a local `mimir` process over JSON-RPC (MCP stdio). You need the `mimir` binary on your `PATH` (or pass an absolute path).
+
+Install it from the [Mimir repository](https://github.com/Perseus-Computing-LLC/mimir) (build from source, or grab a release). Verify:
+
+```bash
+mimir --version
+```
+
+The tools spawn `mimir serve --db <db_path>` for you — you do **not** start it manually.
+
+## Install
+
+```bash
+pip install crewai-mimir
+```
+
+(or, from source: `pip install -e ".[test]"`)
+
+## Quickstart
+
+```python
+from crewai import Agent, Crew, Task
+from crewai_mimir import build_mimir_tools
+
+# One shared mimir process backs both tools.
+memory_tools = build_mimir_tools(db_path="~/.mimir/data/crew.db")
+
+researcher = Agent(
+    role="Research Analyst",
+    goal="Answer questions, remembering durable facts for next time.",
+    backstory="You persist key findings to long-term memory and check it before answering.",
+    tools=memory_tools,
+    verbose=True,
+)
+
+remember_task = Task(
+    description="Remember that the project deadline is 2026-08-15. Store it under key 'project-deadline'.",
+    expected_output="Confirmation the deadline was stored.",
+    agent=researcher,
+)
+
+recall_task = Task(
+    description="What is the project deadline? Check your long-term memory.",
+    expected_output="The project deadline date.",
+    agent=researcher,
+)
+
+crew = Crew(agents=[researcher], tasks=[remember_task, recall_task])
+result = crew.kickoff()
+print(result)
+```
+
+### Using the tool classes directly
+
+```python
+from crewai_mimir import MimirRememberTool, MimirRecallTool, MimirClient
+
+client = MimirClient(db_path="~/.mimir/data/crew.db")          # one shared process
+remember = MimirRememberTool(client=client)
+recall = MimirRecallTool(client=client)
+
+agent = Agent(..., tools=[remember, recall])
+```
+
+If you omit `client`, each tool lazily starts its own `mimir serve` on first use
+(configurable via `db_path` and `mimir_binary`).
+
+### Encryption at rest
+
+```python
+tools = build_mimir_tools(
+    db_path="~/.mimir/data/crew.db",
+    encryption_key="~/.mimir/key.b64",   # base64-encoded 32-byte AES-256-GCM key
+)
+```
+
+## Tool reference
+
+| Tool | Required args | Optional args |
+|------|---------------|---------------|
+| `mimir_remember` | `content`, `key` | `category` (default `insight`), `tags`, `importance` (0.0–1.0) |
+| `mimir_recall` | `query` | `limit` (default 5), `category` |
+
+Both return a JSON string. `mimir_recall` returns `{"query": ..., "results": [...]}`.
+
+## How it works
+
+`MimirClient` spawns `mimir serve --db <path>`, performs the MCP `initialize`
+handshake, and issues id-correlated JSON-RPC requests with a per-call timeout
+over stdin/stdout. The client core is adapted from the proven
+[`adk-mimir-memory`](https://github.com/Perseus-Computing-LLC/adk-mimir-memory)
+package.
+
+## Development
+
+```bash
+pip install -e ".[test]"
+pytest -q
+```
+
+Unit tests mock the `mimir` subprocess, so they run with no binary installed.
+`tests/test_smoke_real_binary.py` runs an end-to-end round-trip against a real
+`mimir` binary when one is found on `PATH` (otherwise it is skipped).
+
+## License
+
+MIT © 2026 Perseus Computing LLC. Mimir is MIT-licensed by Perseus Computing LLC.

crewai_mimir-0.1.0/crewai_mimir/__init__.py

@@ -0,0 +1,35 @@
+"""crewai-mimir: Mimir long-term memory as CrewAI tools.
+
+Exposes explicit, agent-callable CrewAI tools that store and retrieve durable
+memories in Mimir (github.com/Perseus-Computing-LLC/mimir), a local-first,
+encrypted, persistent memory engine.
+
+Example::
+
+    from crewai import Agent
+    from crewai_mimir import build_mimir_tools
+
+    agent = Agent(role="Researcher", goal="...", backstory="...",
+                  tools=build_mimir_tools())
+"""
+
+from ._client import MimirClient
+from .tools import (
+    MimirRecallInput,
+    MimirRecallTool,
+    MimirRememberInput,
+    MimirRememberTool,
+    build_mimir_tools,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "MimirClient",
+    "MimirRememberTool",
+    "MimirRecallTool",
+    "MimirRememberInput",
+    "MimirRecallInput",
+    "build_mimir_tools",
+    "__version__",
+]

crewai_mimir-0.1.0/crewai_mimir/_client.py

@@ -0,0 +1,252 @@
+"""Minimal Mimir MCP stdio client.
+
+Mimir (github.com/Perseus-Computing-LLC/mimir) is an open-source (MIT)
+local-first, encrypted, persistent memory engine exposing 40+ tools over the
+Model Context Protocol.  This module talks to the ``mimir`` binary via JSON-RPC
+2.0 over stdin/stdout (the MCP stdio transport).
+
+The client core (spawn subprocess, background stdout reader, id-correlated RPC
+with timeout, MCP initialize handshake) is adapted from the proven
+``Perseus-Computing-LLC/adk-mimir-memory`` package.
+
+Requirements:
+    A ``mimir`` binary must be on ``$PATH`` or passed explicitly.  Build from
+    source or install from https://github.com/Perseus-Computing-LLC/mimir.
+"""
+
+from __future__ import annotations
+
+import atexit
+import json
+import os
+import queue
+import shutil
+import subprocess
+import threading
+import time
+
+__all__ = ["MimirClient"]
+
+
+class MimirClient:
+    """Thread-safe JSON-RPC client for a ``mimir serve`` stdio subprocess.
+
+    The client spawns ``mimir serve --db <db_path>`` and performs the MCP
+    initialize handshake on construction.  Call :meth:`call_tool` to invoke any
+    Mimir MCP tool by name.
+
+    Attributes:
+        db_path: Filesystem path to the Mimir SQLite database.
+    """
+
+    def __init__(
+        self,
+        db_path: str = "~/.mimir/data/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 SQLite database.  Created if absent.
+            mimir_binary: Name or absolute path of the ``mimir`` executable.
+            timeout_s: Per-RPC response timeout, guarding against a hung server.
+            encryption_key: Optional path to an AES-256-GCM key file; enables
+                encryption at rest.
+
+        Raises:
+            RuntimeError: If the ``mimir`` binary cannot be found.
+        """
+        self.db_path = os.path.expanduser(db_path)
+        self._timeout_s = timeout_s
+
+        if os.path.isabs(mimir_binary):
+            self._mimir_binary = mimir_binary
+        else:
+            resolved = shutil.which(mimir_binary)
+            if resolved is None:
+                raise RuntimeError(
+                    f"mimir binary not found on $PATH (looked for '{mimir_binary}'). "
+                    "Install Mimir from https://github.com/Perseus-Computing-LLC/mimir "
+                    "or pass the absolute path via mimir_binary=."
+                )
+            self._mimir_binary = resolved
+
+        os.makedirs(os.path.dirname(self.db_path) or ".", exist_ok=True)
+
+        cmd = [self._mimir_binary, "serve", "--db", self.db_path]
+        if encryption_key:
+            cmd += ["--encryption-key", os.path.expanduser(encryption_key)]
+
+        # 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).
+        self._proc = subprocess.Popen(
+            cmd,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            text=True,
+        )
+        self._lock = threading.Lock()
+        self._request_id = 0
+
+        # Background reader: pump stdout lines into a queue so _rpc can wait with
+        # a timeout and correlate responses by id rather than block forever.
+        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.
+        self._rpc(
+            "initialize",
+            {
+                "protocolVersion": "2024-11-05",
+                "capabilities": {},
+                "clientInfo": {"name": "crewai-mimir", "version": "0.1.0"},
+            },
+        )
+        self._notify("notifications/initialized", {})
+
+        atexit.register(self.close)
+
+    # -- lifecycle ----------------------------------------------------------
+
+    def close(self) -> None:
+        """Terminates the Mimir subprocess (idempotent)."""
+        proc = getattr(self, "_proc", None)
+        if proc is None:
+            return
+        try:
+            proc.terminate()
+            proc.wait(timeout=5)
+        except Exception:
+            try:
+                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 its ``result`` dict.
+
+        Holds the lock for the whole request/response exchange so pairs never
+        interleave, and honors ``timeout_s`` so a hung server cannot block the
+        caller forever.
+
+        Raises:
+            RuntimeError: 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 RuntimeError(
+                    f"Mimir subprocess communication failed: {e}. "
+                    "The mimir process may have crashed."
+                ) from e
+
+            deadline = time.monotonic() + self._timeout_s
+            while True:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    raise RuntimeError(
+                        f"Mimir RPC '{method}' timed out after {self._timeout_s}s."
+                    )
+                try:
+                    raw = self._recv.get(timeout=remaining)
+                except queue.Empty:
+                    raise RuntimeError(
+                        f"Mimir RPC '{method}' timed out after {self._timeout_s}s."
+                    )
+                if raw is None:
+                    raise RuntimeError(
+                        "Mimir subprocess closed its output (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 RuntimeError(
+                        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`` or
+                ``mimir_recall``.
+            arguments: The tool arguments.
+
+        Returns:
+            The tool's ``structuredContent`` if present, otherwise the parsed
+            text content, otherwise ``{}``.
+        """
+        result = self._rpc("tools/call", {"name": name, "arguments": arguments})
+        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):
+                # Surface raw text when it is not JSON.
+                try:
+                    return {"text": content[0].get("text", "")}
+                except (IndexError, KeyError, AttributeError):
+                    pass
+        return {}

crewai_mimir-0.1.0/crewai_mimir/tools.py

@@ -0,0 +1,210 @@
+"""CrewAI tools that wrap the Mimir memory engine.
+
+These are explicit, agent-callable tools (subclasses of ``crewai.tools.BaseTool``)
+that let a CrewAI agent deliberately store and retrieve durable memories in
+Mimir.  Unlike CrewAI's built-in (implicit) memory or a generic MCP adapter,
+these surface ``remember`` and ``recall`` as first-class actions the agent
+chooses to invoke, with a typed ``args_schema`` so the LLM sees exactly what
+each call needs.
+
+Tools:
+    MimirRememberTool — store a fact/decision/note in Mimir.
+    MimirRecallTool   — search Mimir for previously stored memories.
+
+Both tools share a single :class:`~crewai_mimir._client.MimirClient` so one
+``mimir serve`` subprocess backs the whole crew.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Optional, Type
+
+from crewai.tools import BaseTool
+from pydantic import BaseModel, Field
+
+from ._client import MimirClient
+
+__all__ = [
+    "MimirRememberInput",
+    "MimirRecallInput",
+    "MimirRememberTool",
+    "MimirRecallTool",
+    "build_mimir_tools",
+]
+
+
+# ── args schemas ────────────────────────────────────────────────────────────
+
+
+class MimirRememberInput(BaseModel):
+    """Input schema for :class:`MimirRememberTool`."""
+
+    content: str = Field(
+        ...,
+        description="The fact, decision, insight, or note to remember. Stored "
+        "verbatim and made searchable.",
+    )
+    key: str = Field(
+        ...,
+        description="A short unique identifier for this memory within its "
+        "category, e.g. 'use-postgres-16'. Re-using a key updates that memory.",
+    )
+    category: str = Field(
+        default="insight",
+        description="Memory category: 'decision', 'architecture', 'convention', "
+        "'insight', or a custom label.",
+    )
+    tags: Optional[list[str]] = Field(
+        default=None,
+        description="Optional tags for cross-referencing this memory.",
+    )
+    importance: float = Field(
+        default=0.5,
+        ge=0.0,
+        le=1.0,
+        description="Initial importance 0.0-1.0; sets the starting decay score.",
+    )
+
+
+class MimirRecallInput(BaseModel):
+    """Input schema for :class:`MimirRecallTool`."""
+
+    query: str = Field(
+        ...,
+        description="Search query. Keywords are OR'd together for broad recall.",
+    )
+    limit: int = Field(
+        default=5,
+        ge=1,
+        le=1000,
+        description="Maximum number of memories to return.",
+    )
+    category: Optional[str] = Field(
+        default=None,
+        description="Optionally restrict the search to one category.",
+    )
+
+
+# ── tools ───────────────────────────────────────────────────────────────────
+
+
+class MimirRememberTool(BaseTool):
+    """Store a durable memory in Mimir.
+
+    Pass a shared :class:`MimirClient` (recommended, so all tools reuse one
+    ``mimir serve`` process), or let the tool lazily start its own using
+    ``db_path`` / ``mimir_binary``.
+    """
+
+    name: str = "mimir_remember"
+    description: str = (
+        "Persist a fact, decision, insight, or note to long-term memory (Mimir) "
+        "so it survives across sessions. Provide the content and a short unique "
+        "key. Use this whenever you learn something worth remembering later."
+    )
+    args_schema: Type[BaseModel] = MimirRememberInput
+
+    # Non-schema configuration (excluded from the LLM-facing args_schema).
+    client: Optional[MimirClient] = None
+    db_path: str = "~/.mimir/data/mimir.db"
+    mimir_binary: str = "mimir"
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    def _get_client(self) -> MimirClient:
+        if self.client is None:
+            self.client = MimirClient(
+                db_path=self.db_path, mimir_binary=self.mimir_binary
+            )
+        return self.client
+
+    def _run(
+        self,
+        content: str,
+        key: str,
+        category: str = "insight",
+        tags: Optional[list[str]] = None,
+        importance: float = 0.5,
+    ) -> str:
+        client = self._get_client()
+        result = client.call_tool(
+            "mimir_remember",
+            {
+                "category": category,
+                "key": key,
+                "body_json": json.dumps({"content": content}),
+                "tags": tags or [],
+                "importance": importance,
+            },
+        )
+        return json.dumps(
+            {"status": "remembered", "category": category, "key": key, "mimir": result}
+        )
+
+
+class MimirRecallTool(BaseTool):
+    """Search Mimir for previously stored memories.
+
+    Pass a shared :class:`MimirClient` (recommended), or let the tool lazily
+    start its own using ``db_path`` / ``mimir_binary``.
+    """
+
+    name: str = "mimir_recall"
+    description: str = (
+        "Search long-term memory (Mimir) for facts, decisions, or notes stored "
+        "earlier. Returns the best-matching memories. Use this before answering "
+        "to check what you already know."
+    )
+    args_schema: Type[BaseModel] = MimirRecallInput
+
+    client: Optional[MimirClient] = None
+    db_path: str = "~/.mimir/data/mimir.db"
+    mimir_binary: str = "mimir"
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    def _get_client(self) -> MimirClient:
+        if self.client is None:
+            self.client = MimirClient(
+                db_path=self.db_path, mimir_binary=self.mimir_binary
+            )
+        return self.client
+
+    def _run(
+        self,
+        query: str,
+        limit: int = 5,
+        category: Optional[str] = None,
+    ) -> str:
+        client = self._get_client()
+        arguments: dict = {"query": query, "limit": limit}
+        if category:
+            arguments["category"] = category
+        result = client.call_tool("mimir_recall", arguments)
+        items = result.get("items", result) if isinstance(result, dict) else result
+        return json.dumps({"query": query, "results": items})
+
+
+def build_mimir_tools(
+    db_path: str = "~/.mimir/data/mimir.db",
+    mimir_binary: str = "mimir",
+    encryption_key: Optional[str] = None,
+) -> list[BaseTool]:
+    """Convenience: build remember+recall tools sharing one Mimir process.
+
+    Args:
+        db_path: Path to the Mimir SQLite database.
+        mimir_binary: Name or absolute path of the ``mimir`` executable.
+        encryption_key: Optional path to an AES-256-GCM key file.
+
+    Returns:
+        ``[MimirRememberTool, MimirRecallTool]`` backed by a single client.
+    """
+    client = MimirClient(
+        db_path=db_path, mimir_binary=mimir_binary, encryption_key=encryption_key
+    )
+    return [
+        MimirRememberTool(client=client),
+        MimirRecallTool(client=client),
+    ]

crewai_mimir-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "crewai-mimir"
+version = "0.1.0"
+authors = [
+    { name = "Perseus Computing LLC", email = "hermes@perseus.observer" },
+]
+description = "Mimir long-term memory as CrewAI tools — local-first, encrypted, persistent memory the agent can explicitly call."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+keywords = ["crewai", "mimir", "memory", "agents", "mcp", "tools", "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 = [
+    "crewai>=0.80.0",
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=7.0"]
+
+[project.urls]
+Homepage = "https://github.com/Perseus-Computing-LLC/crewai-mimir"
+Repository = "https://github.com/Perseus-Computing-LLC/crewai-mimir"
+"Bug Tracker" = "https://github.com/Perseus-Computing-LLC/crewai-mimir/issues"
+Mimir = "https://github.com/Perseus-Computing-LLC/mimir"
+
+[tool.hatch.build.targets.wheel]
+packages = ["crewai_mimir"]

crewai_mimir-0.1.0/tests/test_smoke_real_binary.py

@@ -0,0 +1,67 @@
+"""Optional smoke test against a REAL ``mimir`` binary.
+
+Skipped automatically when no ``mimir`` binary is on $PATH. When present, it
+starts a real ``mimir serve`` subprocess against a temp DB and round-trips a
+remember -> recall through the actual MCP stdio transport.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+
+import pytest
+
+from crewai_mimir import MimirClient, MimirRecallTool, MimirRememberTool
+
+
+def _find_mimir() -> str | None:
+    """Locate a runnable mimir binary.
+
+    Prefers $MIMIR_BINARY, then PATH. On Windows the released binary may lack a
+    ``.exe`` extension, so shutil.which() misses it; also probe ~/bin/mimir.
+    """
+    env = os.environ.get("MIMIR_BINARY")
+    if env and os.path.exists(env):
+        return env
+    found = shutil.which("mimir")
+    if found:
+        return found
+    candidate = os.path.expanduser("~/bin/mimir")
+    if os.path.exists(candidate):
+        return candidate
+    candidate_exe = os.path.expanduser("~/bin/mimir.exe")
+    if os.path.exists(candidate_exe):
+        return candidate_exe
+    return None
+
+
+_MIMIR = _find_mimir()
+
+pytestmark = pytest.mark.skipif(
+    _MIMIR is None,
+    reason="real mimir binary not found (set MIMIR_BINARY or put mimir on PATH)",
+)
+
+
+def test_real_remember_recall(tmp_path):
+    db = tmp_path / "mimir.db"
+    client = MimirClient(db_path=str(db), mimir_binary=_MIMIR)
+    try:
+        remember = MimirRememberTool(client=client)
+        recall = MimirRecallTool(client=client)
+
+        remember._run(
+            content="The capital of crewai-mimir testing is verification.",
+            key="smoke-fact",
+            category="insight",
+            tags=["smoke"],
+        )
+        out = json.loads(recall._run(query="verification capital", limit=5))
+        assert any(
+            "verification" in str(r.get("content", "")).lower()
+            for r in out["results"]
+        ), f"expected memory not recalled: {out}"
+    finally:
+        client.close()

crewai_mimir-0.1.0/tests/test_tools.py

@@ -0,0 +1,255 @@
+"""Tests for crewai-mimir tools against a fake Mimir MCP stdio server.
+
+No real ``mimir`` binary is required: ``subprocess.Popen`` is monkeypatched to
+return an in-process fake that speaks JSON-RPC 2.0 over fake stdin/stdout pipes,
+so these exercise the real RPC, handshake, and tool ``_run`` code paths.
+"""
+
+from __future__ import annotations
+
+import json
+import queue
+
+import pytest
+from pydantic import ValidationError
+
+import crewai_mimir._client as client_mod
+from crewai_mimir import (
+    MimirClient,
+    MimirRecallInput,
+    MimirRecallTool,
+    MimirRememberInput,
+    MimirRememberTool,
+    build_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."""
+
+    def __init__(self, cmd=None, **kwargs):
+        self.cmd = cmd
+        self.store = {}  # (category, key) -> body dict
+        self.stdout = _FakeStdout()
+        self.stdin = _FakeStdin(self._handle)
+        self._alive = True
+
+    # -- Popen surface used by MimirClient --
+    def terminate(self):
+        self._alive = False
+        self.stdout.close()
+
+    def wait(self, timeout=None):
+        return 0
+
+    def kill(self):
+        self._alive = False
+
+    # -- request dispatch --
+    def _reply(self, req_id, result):
+        self.stdout.put(json.dumps({"jsonrpc": "2.0", "id": req_id, "result": result}))
+
+    def _handle(self, line):
+        req = json.loads(line)
+        method = req.get("method")
+        req_id = req.get("id")
+        if req_id is None:
+            return  # notification
+        if method == "initialize":
+            self._reply(req_id, {"protocolVersion": "2024-11-05"})
+        elif method == "tools/call":
+            params = req.get("params", {})
+            name = params.get("name")
+            args = params.get("arguments", {})
+            self._reply(req_id, self._call_tool(name, args))
+        else:
+            self._reply(req_id, {})
+
+    def _call_tool(self, name, args):
+        if name == "mimir_remember":
+            key = (args.get("category"), args.get("key"))
+            body = json.loads(args.get("body_json", "{}"))
+            self.store[key] = {**args, "body": body}
+            return {"structuredContent": {"stored": True, "key": args.get("key")}}
+        if name == "mimir_recall":
+            query = (args.get("query") or "").lower()
+            cat = args.get("category")
+            limit = args.get("limit", 10)
+            items = []
+            for (category, key), entry in self.store.items():
+                if cat and category != cat:
+                    continue
+                content = str(entry["body"].get("content", "")).lower()
+                # OR semantics: any query token present in content.
+                if any(tok and tok in content for tok in query.split()):
+                    items.append(
+                        {"key": key, "category": category, **entry["body"]}
+                    )
+            return {"structuredContent": {"items": items[:limit]}}
+        return {"structuredContent": {}}
+
+
+@pytest.fixture
+def fake_popen(monkeypatch):
+    """Patch subprocess.Popen + shutil.which so MimirClient uses FakeMimir."""
+    created = {}
+
+    def _fake_popen(cmd, **kwargs):
+        fm = FakeMimir(cmd=cmd, **kwargs)
+        created["proc"] = fm
+        return fm
+
+    monkeypatch.setattr(client_mod.subprocess, "Popen", _fake_popen)
+    monkeypatch.setattr(client_mod.shutil, "which", lambda b: "/fake/mimir")
+    return created
+
+
+# ── args_schema validation (no client needed) ────────────────────────────────
+
+
+def test_remember_input_requires_content_and_key():
+    with pytest.raises(ValidationError):
+        MimirRememberInput(key="k")  # missing content
+    with pytest.raises(ValidationError):
+        MimirRememberInput(content="c")  # missing key
+    ok = MimirRememberInput(content="c", key="k")
+    assert ok.category == "insight"
+    assert ok.importance == 0.5
+
+
+def test_remember_input_importance_bounds():
+    with pytest.raises(ValidationError):
+        MimirRememberInput(content="c", key="k", importance=1.5)
+    with pytest.raises(ValidationError):
+        MimirRememberInput(content="c", key="k", importance=-0.1)
+
+
+def test_recall_input_requires_query_and_limit_bounds():
+    with pytest.raises(ValidationError):
+        MimirRecallInput()  # missing query
+    with pytest.raises(ValidationError):
+        MimirRecallInput(query="q", limit=0)  # below ge=1
+    ok = MimirRecallInput(query="q")
+    assert ok.limit == 5
+
+
+def test_tool_metadata():
+    t = MimirRememberTool.model_construct()
+    assert t.name == "mimir_remember"
+    assert t.args_schema is MimirRememberInput
+    r = MimirRecallTool.model_construct()
+    assert r.name == "mimir_recall"
+    assert r.args_schema is MimirRecallInput
+
+
+# ── _run round-trips against the fake server ──────────────────────────────────
+
+
+def test_remember_then_recall(fake_popen):
+    client = MimirClient(db_path="./_t/mimir.db")
+    remember = MimirRememberTool(client=client)
+    recall = MimirRecallTool(client=client)
+
+    out = remember._run(
+        content="Use PostgreSQL 16 for the main datastore.",
+        key="use-postgres-16",
+        category="decision",
+        tags=["db"],
+    )
+    parsed = json.loads(out)
+    assert parsed["status"] == "remembered"
+    assert parsed["key"] == "use-postgres-16"
+
+    out = recall._run(query="postgresql datastore", limit=5)
+    parsed = json.loads(out)
+    assert parsed["query"] == "postgresql datastore"
+    assert len(parsed["results"]) == 1
+    assert parsed["results"][0]["content"].startswith("Use PostgreSQL 16")
+    client.close()
+
+
+def test_recall_category_filter(fake_popen):
+    client = MimirClient(db_path="./_t/mimir.db")
+    remember = MimirRememberTool(client=client)
+    recall = MimirRecallTool(client=client)
+
+    remember._run(content="alpha fact", key="a", category="insight")
+    remember._run(content="alpha decision", key="b", category="decision")
+
+    out = json.loads(recall._run(query="alpha", category="decision"))
+    assert len(out["results"]) == 1
+    assert out["results"][0]["content"] == "alpha decision"
+    client.close()
+
+
+def test_run_through_crewai_tool_run_wrapper(fake_popen):
+    """BaseTool.run(**kwargs) validates kwargs via args_schema then dispatches _run.
+
+    Note: in crewai 1.15.x, run() forwards keyword arguments to _run; passing a
+    single positional dict is NOT unpacked, so agents/tooling call with kwargs.
+    """
+    client = MimirClient(db_path="./_t/mimir.db")
+    remember = MimirRememberTool(client=client)
+    result = remember.run(
+        content="wrapped via run()", key="w1", category="insight"
+    )
+    assert json.loads(result)["status"] == "remembered"
+    out = json.loads(MimirRecallTool(client=client).run(query="wrapped"))
+    assert any("wrapped" in r["content"] for r in out["results"])
+    client.close()
+
+
+def test_build_mimir_tools_shares_client(fake_popen):
+    tools = build_mimir_tools(db_path="./_t/mimir.db")
+    assert len(tools) == 2
+    names = {t.name for t in tools}
+    assert names == {"mimir_remember", "mimir_recall"}
+    assert tools[0].client is tools[1].client
+    tools[0].client.close()
+
+
+def test_missing_binary_raises(monkeypatch):
+    monkeypatch.setattr(client_mod.shutil, "which", lambda b: None)
+    with pytest.raises(RuntimeError, match="mimir binary not found"):
+        MimirClient(db_path="./_t/mimir.db", mimir_binary="mimir")