flux7-memory 0.5.0__tar.gz

flux7_memory-0.5.0/.gitignore

@@ -0,0 +1,34 @@
+# Build / OS
+*.exe
+*.dll
+*.so
+*.dylib
+/mem7
+.DS_Store
+
+# IDE & local context
+.claude
+CLAUDE.md
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Internal / strategic docs (not for public repo)
+docs/internal/
+
+# Go
+vendor/
+
+# Environment
+.env
+.env.*
+
+# Debug / test artifacts
+*.debug
+*.test
+
+# Internal bench harness (not for public repo)
+/bench/
+__pycache__/
+dist/

flux7_memory-0.5.0/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.4
+Name: flux7-memory
+Version: 0.5.0
+Summary: Python SDK for mem7 — governed memory substrate for AI agents
+Project-URL: Homepage, https://github.com/KTCrisis/flux7-memory
+Project-URL: Repository, https://github.com/KTCrisis/flux7-memory
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Requires-Dist: requests>=2.28
+Description-Content-Type: text/markdown
+
+# flux7-memory
+
+Python client for [mem7](https://github.com/KTCrisis/flux7-memory) — governed memory substrate for AI agents.
+
+```bash
+pip install flux7-memory
+```
+
+```python
+from mem7 import Mem7
+
+m = Mem7("http://localhost:9070", token="my-token")
+m.store("deploy.decision", "approved by ops lead", tags=["decision"], agent="supervisor")
+results = m.search("deployment approval", limit=5)
+```

flux7_memory-0.5.0/README.md

@@ -0,0 +1,15 @@
+# flux7-memory
+
+Python client for [mem7](https://github.com/KTCrisis/flux7-memory) — governed memory substrate for AI agents.
+
+```bash
+pip install flux7-memory
+```
+
+```python
+from mem7 import Mem7
+
+m = Mem7("http://localhost:9070", token="my-token")
+m.store("deploy.decision", "approved by ops lead", tags=["decision"], agent="supervisor")
+results = m.search("deployment approval", limit=5)
+```

flux7_memory-0.5.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "flux7-memory"
+version = "0.5.0"
+description = "Python SDK for mem7 — governed memory substrate for AI agents"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+dependencies = ["requests>=2.28"]
+
+[project.urls]
+Homepage = "https://github.com/KTCrisis/flux7-memory"
+Repository = "https://github.com/KTCrisis/flux7-memory"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mem7"]

flux7_memory-0.5.0/src/mem7/__init__.py

@@ -0,0 +1,4 @@
+from mem7.client import Mem7, Memory
+
+__all__ = ["Mem7", "Memory"]
+__version__ = "0.5.0"

flux7_memory-0.5.0/src/mem7/client.py

@@ -0,0 +1,226 @@
+"""mem7 Python SDK — governed memory substrate for AI agents.
+
+Usage::
+
+    from mem7 import Mem7
+
+    m = Mem7("http://localhost:9070", token="my-token")
+    m.store("user.prefs", "prefers dark mode", tags=["user"])
+    results = m.search("dark mode", limit=5)
+    memories = m.context("dark mode", limit=5)  # structured JSON
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+import requests
+
+
+@dataclass
+class Memory:
+    key: str
+    value: str
+    tags: list[str] = field(default_factory=list)
+    agent: str = ""
+    updated: str = ""
+
+
+class Mem7Error(Exception):
+    pass
+
+
+class Mem7:
+    def __init__(self, url: str, token: str = "", timeout: int = 30) -> None:
+        self._url = url.rstrip("/")
+        self._token = token
+        self._timeout = timeout
+        self._session = requests.Session()
+        if token:
+            self._session.headers["Authorization"] = f"Bearer {token}"
+        self._session.headers["Content-Type"] = "application/json"
+        self._req_id = 0
+
+    def _call(self, tool: str, arguments: dict[str, Any]) -> Any:
+        self._req_id += 1
+        payload = {
+            "jsonrpc": "2.0",
+            "id": self._req_id,
+            "method": "tools/call",
+            "params": {"name": tool, "arguments": arguments},
+        }
+        resp = self._session.post(
+            f"{self._url}/rpc", json=payload, timeout=self._timeout
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        if "error" in data and data["error"]:
+            raise Mem7Error(data["error"].get("message", str(data["error"])))
+        result = data.get("result", {})
+        if result.get("isError"):
+            text = result.get("content", [{}])[0].get("text", "unknown error")
+            raise Mem7Error(text)
+        content = result.get("content", [])
+        if content:
+            return content[0].get("text", "")
+        return ""
+
+    # ── Core tools ───────────────────────────────────────────────
+
+    def store(
+        self,
+        key: str,
+        value: str,
+        *,
+        tags: list[str] | None = None,
+        agent: str = "",
+        ttl: int = 0,
+    ) -> str:
+        args: dict[str, Any] = {"key": key, "value": value}
+        if tags:
+            args["tags"] = tags
+        if agent:
+            args["agent"] = agent
+        if ttl > 0:
+            args["ttl"] = ttl
+        return self._call("memory_store", args)
+
+    def recall(
+        self,
+        *,
+        key: str = "",
+        tags: list[str] | None = None,
+        agent: str = "",
+        limit: int = 10,
+    ) -> str:
+        args: dict[str, Any] = {"limit": limit}
+        if key:
+            args["key"] = key
+        if tags:
+            args["tags"] = tags
+        if agent:
+            args["agent"] = agent
+        return self._call("memory_recall", args)
+
+    def search(
+        self,
+        query: str,
+        *,
+        mode: str = "natural",
+        tags: list[str] | None = None,
+        agent: str = "",
+        limit: int = 10,
+        include_neighbors: bool = False,
+        neighbor_radius: int = 1,
+        since: str = "",
+        until: str = "",
+    ) -> str:
+        args: dict[str, Any] = {"query": query, "mode": mode, "limit": limit}
+        if tags:
+            args["tags"] = tags
+        if agent:
+            args["agent"] = agent
+        if include_neighbors:
+            args["include_neighbors"] = True
+            args["neighbor_radius"] = neighbor_radius
+        if since:
+            args["since"] = since
+        if until:
+            args["until"] = until
+        return self._call("memory_search", args)
+
+    def context(
+        self,
+        query: str,
+        *,
+        mode: str = "natural",
+        tags: list[str] | None = None,
+        agent: str = "",
+        limit: int = 10,
+        include_neighbors: bool = False,
+        neighbor_radius: int = 1,
+        since: str = "",
+        until: str = "",
+    ) -> list[Memory]:
+        args: dict[str, Any] = {"query": query, "mode": mode, "limit": limit}
+        if tags:
+            args["tags"] = tags
+        if agent:
+            args["agent"] = agent
+        if include_neighbors:
+            args["include_neighbors"] = True
+            args["neighbor_radius"] = neighbor_radius
+        if since:
+            args["since"] = since
+        if until:
+            args["until"] = until
+        raw = self._call("memory_context", args)
+        items = json.loads(raw) if raw else []
+        return [
+            Memory(
+                key=it.get("key", ""),
+                value=it.get("value", ""),
+                tags=it.get("tags") or [],
+                agent=it.get("agent", ""),
+                updated=it.get("updated", ""),
+            )
+            for it in items
+        ]
+
+    def get(self, path: str, *, from_line: int = 0, to_line: int = 0) -> str:
+        args: dict[str, Any] = {"path": path}
+        if from_line > 0:
+            args["from_line"] = from_line
+        if to_line > 0:
+            args["to_line"] = to_line
+        return self._call("memory_get", args)
+
+    def list(
+        self, *, tags: list[str] | None = None, agent: str = ""
+    ) -> str:
+        args: dict[str, Any] = {}
+        if tags:
+            args["tags"] = tags
+        if agent:
+            args["agent"] = agent
+        return self._call("memory_list", args)
+
+    def forget(self, *, key: str = "", tags: list[str] | None = None) -> str:
+        args: dict[str, Any] = {}
+        if key:
+            args["key"] = key
+        if tags:
+            args["tags"] = tags
+        return self._call("memory_forget", args)
+
+    # ── Convenience ──────────────────────────────────────────────
+
+    def health(self) -> bool:
+        try:
+            resp = self._session.get(
+                f"{self._url}/healthz", timeout=self._timeout
+            )
+            return resp.status_code == 200
+        except requests.RequestException:
+            return False
+
+    def context_block(
+        self,
+        query: str,
+        *,
+        limit: int = 10,
+        **kwargs: Any,
+    ) -> str:
+        """Search and return a formatted text block ready for LLM prompt injection."""
+        memories = self.context(query, limit=limit, **kwargs)
+        if not memories:
+            return ""
+        parts = []
+        for m in memories:
+            header = f"[{m.key}]" if m.key else ""
+            if header:
+                parts.append(f"{header}\n{m.value}")
+            else:
+                parts.append(m.value)
+        return "\n\n".join(parts)

flux7_memory-0.5.0/tests/test_client.py

@@ -0,0 +1,281 @@
+"""Tests for the mem7 Python SDK client."""
+from __future__ import annotations
+
+import json
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from mem7 import Mem7, Memory
+from mem7.client import Mem7Error
+
+
+def _rpc_ok(text: str = "") -> dict:
+    return {
+        "jsonrpc": "2.0",
+        "id": 1,
+        "result": {
+            "content": [{"type": "text", "text": text}],
+        },
+    }
+
+
+def _rpc_tool_error(msg: str) -> dict:
+    return {
+        "jsonrpc": "2.0",
+        "id": 1,
+        "result": {
+            "isError": True,
+            "content": [{"type": "text", "text": msg}],
+        },
+    }
+
+
+def _rpc_error(code: int, msg: str) -> dict:
+    return {
+        "jsonrpc": "2.0",
+        "id": 1,
+        "error": {"code": code, "message": msg},
+    }
+
+
+@pytest.fixture
+def client():
+    return Mem7("http://localhost:9070", token="test-token")
+
+
+class TestInit:
+    def test_url_trailing_slash_stripped(self):
+        m = Mem7("http://localhost:9070/")
+        assert m._url == "http://localhost:9070"
+
+    def test_auth_header_set(self):
+        m = Mem7("http://localhost:9070", token="abc")
+        assert m._session.headers["Authorization"] == "Bearer abc"
+
+    def test_no_auth_header_without_token(self):
+        m = Mem7("http://localhost:9070")
+        assert "Authorization" not in m._session.headers
+
+    def test_content_type_set(self):
+        m = Mem7("http://localhost:9070")
+        assert m._session.headers["Content-Type"] == "application/json"
+
+
+class TestCall:
+    def test_successful_call(self, client):
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = _rpc_ok("done")
+        mock_resp.raise_for_status = MagicMock()
+        with patch.object(client._session, "post", return_value=mock_resp) as mock_post:
+            result = client._call("memory_store", {"key": "k", "value": "v"})
+        assert result == "done"
+        call_args = mock_post.call_args
+        assert call_args[0][0] == "http://localhost:9070/rpc"
+        payload = call_args[1]["json"]
+        assert payload["method"] == "tools/call"
+        assert payload["params"]["name"] == "memory_store"
+
+    def test_rpc_error_raises(self, client):
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = _rpc_error(-32601, "method not found")
+        mock_resp.raise_for_status = MagicMock()
+        with patch.object(client._session, "post", return_value=mock_resp):
+            with pytest.raises(Mem7Error, match="method not found"):
+                client._call("bad_method", {})
+
+    def test_tool_error_raises(self, client):
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = _rpc_tool_error("unknown tool: nope")
+        mock_resp.raise_for_status = MagicMock()
+        with patch.object(client._session, "post", return_value=mock_resp):
+            with pytest.raises(Mem7Error, match="unknown tool"):
+                client._call("nope", {})
+
+    def test_empty_result(self, client):
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = {"jsonrpc": "2.0", "id": 1, "result": {}}
+        mock_resp.raise_for_status = MagicMock()
+        with patch.object(client._session, "post", return_value=mock_resp):
+            assert client._call("something", {}) == ""
+
+    def test_request_id_increments(self, client):
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = _rpc_ok("")
+        mock_resp.raise_for_status = MagicMock()
+        with patch.object(client._session, "post", return_value=mock_resp) as mock_post:
+            client._call("a", {})
+            client._call("b", {})
+        ids = [c[1]["json"]["id"] for c in mock_post.call_args_list]
+        assert ids == [1, 2]
+
+
+class TestStore:
+    def test_minimal(self, client):
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = _rpc_ok("created")
+        mock_resp.raise_for_status = MagicMock()
+        with patch.object(client._session, "post", return_value=mock_resp) as mock_post:
+            result = client.store("k", "v")
+        args = mock_post.call_args[1]["json"]["params"]["arguments"]
+        assert args == {"key": "k", "value": "v"}
+        assert result == "created"
+
+    def test_all_params(self, client):
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = _rpc_ok("created")
+        mock_resp.raise_for_status = MagicMock()
+        with patch.object(client._session, "post", return_value=mock_resp) as mock_post:
+            client.store("k", "v", tags=["a"], agent="bot", ttl=3600)
+        args = mock_post.call_args[1]["json"]["params"]["arguments"]
+        assert args == {"key": "k", "value": "v", "tags": ["a"], "agent": "bot", "ttl": 3600}
+
+
+class TestSearch:
+    def test_minimal(self, client):
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = _rpc_ok("results")
+        mock_resp.raise_for_status = MagicMock()
+        with patch.object(client._session, "post", return_value=mock_resp) as mock_post:
+            client.search("dark mode")
+        args = mock_post.call_args[1]["json"]["params"]["arguments"]
+        assert args["query"] == "dark mode"
+        assert args["mode"] == "natural"
+        assert args["limit"] == 10
+
+    def test_with_neighbors(self, client):
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = _rpc_ok("results")
+        mock_resp.raise_for_status = MagicMock()
+        with patch.object(client._session, "post", return_value=mock_resp) as mock_post:
+            client.search("q", include_neighbors=True, neighbor_radius=3)
+        args = mock_post.call_args[1]["json"]["params"]["arguments"]
+        assert args["include_neighbors"] is True
+        assert args["neighbor_radius"] == 3
+
+    def test_with_time_range(self, client):
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = _rpc_ok("results")
+        mock_resp.raise_for_status = MagicMock()
+        with patch.object(client._session, "post", return_value=mock_resp) as mock_post:
+            client.search("q", since="2026-01-01", until="2026-05-01")
+        args = mock_post.call_args[1]["json"]["params"]["arguments"]
+        assert args["since"] == "2026-01-01"
+        assert args["until"] == "2026-05-01"
+
+
+class TestContext:
+    def test_returns_memory_objects(self, client):
+        items = [
+            {"key": "user.prefs", "value": "dark mode", "tags": ["user"], "agent": "bot", "updated": "2026-05-07T18:00:00Z"},
+            {"key": "user.role", "value": "engineer", "tags": [], "agent": "", "updated": "2026-05-07T17:00:00Z"},
+        ]
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = _rpc_ok(json.dumps(items))
+        mock_resp.raise_for_status = MagicMock()
+        with patch.object(client._session, "post", return_value=mock_resp):
+            memories = client.context("prefs")
+        assert len(memories) == 2
+        assert isinstance(memories[0], Memory)
+        assert memories[0].key == "user.prefs"
+        assert memories[0].value == "dark mode"
+        assert memories[0].tags == ["user"]
+        assert memories[0].agent == "bot"
+        assert memories[0].updated == "2026-05-07T18:00:00Z"
+        assert memories[1].tags == []
+
+    def test_empty_result(self, client):
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = _rpc_ok("")
+        mock_resp.raise_for_status = MagicMock()
+        with patch.object(client._session, "post", return_value=mock_resp):
+            memories = client.context("nothing")
+        assert memories == []
+
+    def test_calls_memory_context_tool(self, client):
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = _rpc_ok("[]")
+        mock_resp.raise_for_status = MagicMock()
+        with patch.object(client._session, "post", return_value=mock_resp) as mock_post:
+            client.context("q")
+        assert mock_post.call_args[1]["json"]["params"]["name"] == "memory_context"
+
+
+class TestContextBlock:
+    def test_formats_memories(self, client):
+        items = [
+            {"key": "a.b", "value": "hello world", "tags": [], "agent": "", "updated": ""},
+            {"key": "c.d", "value": "foo bar", "tags": [], "agent": "", "updated": ""},
+        ]
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = _rpc_ok(json.dumps(items))
+        mock_resp.raise_for_status = MagicMock()
+        with patch.object(client._session, "post", return_value=mock_resp):
+            block = client.context_block("q")
+        assert "[a.b]" in block
+        assert "hello world" in block
+        assert "[c.d]" in block
+
+    def test_empty_returns_empty_string(self, client):
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = _rpc_ok("")
+        mock_resp.raise_for_status = MagicMock()
+        with patch.object(client._session, "post", return_value=mock_resp):
+            assert client.context_block("nothing") == ""
+
+
+class TestOtherTools:
+    def test_recall(self, client):
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = _rpc_ok("recalled")
+        mock_resp.raise_for_status = MagicMock()
+        with patch.object(client._session, "post", return_value=mock_resp) as mock_post:
+            client.recall(key="k", tags=["t"], agent="a", limit=5)
+        args = mock_post.call_args[1]["json"]["params"]["arguments"]
+        assert args == {"key": "k", "tags": ["t"], "agent": "a", "limit": 5}
+
+    def test_get(self, client):
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = _rpc_ok("content")
+        mock_resp.raise_for_status = MagicMock()
+        with patch.object(client._session, "post", return_value=mock_resp) as mock_post:
+            client.get("user.prefs", from_line=1, to_line=10)
+        args = mock_post.call_args[1]["json"]["params"]["arguments"]
+        assert args == {"path": "user.prefs", "from_line": 1, "to_line": 10}
+
+    def test_list(self, client):
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = _rpc_ok("2 memories")
+        mock_resp.raise_for_status = MagicMock()
+        with patch.object(client._session, "post", return_value=mock_resp) as mock_post:
+            client.list(tags=["user"])
+        args = mock_post.call_args[1]["json"]["params"]["arguments"]
+        assert args == {"tags": ["user"]}
+
+    def test_forget(self, client):
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = _rpc_ok("removed")
+        mock_resp.raise_for_status = MagicMock()
+        with patch.object(client._session, "post", return_value=mock_resp) as mock_post:
+            client.forget(key="k")
+        args = mock_post.call_args[1]["json"]["params"]["arguments"]
+        assert args == {"key": "k"}
+
+
+class TestHealth:
+    def test_healthy(self, client):
+        mock_resp = MagicMock()
+        mock_resp.status_code = 200
+        with patch.object(client._session, "get", return_value=mock_resp):
+            assert client.health() is True
+
+    def test_unhealthy(self, client):
+        mock_resp = MagicMock()
+        mock_resp.status_code = 500
+        with patch.object(client._session, "get", return_value=mock_resp):
+            assert client.health() is False
+
+    def test_connection_error(self, client):
+        import requests
+        with patch.object(client._session, "get", side_effect=requests.ConnectionError):
+            assert client.health() is False