memmachine-client 0.3.7__tar.gz → 0.3.9__tar.gz

{memmachine_client-0.3.7 → memmachine_client-0.3.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memmachine-client
-Version: 0.3.7
+Version: 0.3.9
 Summary: MemMachine REST Client - A lightweight Python client library for MemMachine memory system
 Author-email: MemMachine <noreply@memmachine.ai>
 License-Expression: Apache-2.0
@@ -39,11 +39,15 @@ A Python client library for the MemMachine memory system.
 ## Installation
 
 ```bash
-# Install from source (for development)
-pip install -e .
+pip install memmachine-client
+```
+
+### Development installation
+
+If you are working on the package locally inside the MemMachine monorepo, install it from source instead:
 
-# Or install dependencies
-pip install requests urllib3
+```bash
+pip install -e packages/client
 ```
 
 ## Quick Start
@@ -130,14 +134,14 @@ memory = client.memory(
 memory.add("I like pizza", metadata={"type": "preference", "category": "food"})
 memory.add("I work as a software engineer", metadata={"type": "fact", "category": "work"})
 
-# Search memories
+# Search memories — Memory.search() returns a SearchResult Pydantic model
 results = memory.search("What do I like to eat?")
-print(f"Episodic memory: {results.get('episodic_memory', [])}")
-print(f"Profile memory: {results.get('profile_memory', [])}")
+print(f"Episodic memory: {results.content.episodic_memory}")
+print(f"Semantic memory: {results.content.semantic_memory}")
 
-# Search with filters
-work_results = memory.search("Tell me about work", filter_dict={"category": "work"})
-print(f"Work results: {work_results}")
+# Search with filters (user metadata fields require the `m.` / `metadata.` prefix)
+work_results = memory.search("Tell me about work", filter_dict={"m.category": "work"})
+print(f"Work results: {work_results.model_dump()}")
 ```
 
 ### Multiple Users

{memmachine_client-0.3.7 → memmachine_client-0.3.9}/README.md

@@ -13,11 +13,15 @@ A Python client library for the MemMachine memory system.
 ## Installation
 
 ```bash
-# Install from source (for development)
-pip install -e .
+pip install memmachine-client
+```
+
+### Development installation
+
+If you are working on the package locally inside the MemMachine monorepo, install it from source instead:
 
-# Or install dependencies
-pip install requests urllib3
+```bash
+pip install -e packages/client
 ```
 
 ## Quick Start
@@ -104,14 +108,14 @@ memory = client.memory(
 memory.add("I like pizza", metadata={"type": "preference", "category": "food"})
 memory.add("I work as a software engineer", metadata={"type": "fact", "category": "work"})
 
-# Search memories
+# Search memories — Memory.search() returns a SearchResult Pydantic model
 results = memory.search("What do I like to eat?")
-print(f"Episodic memory: {results.get('episodic_memory', [])}")
-print(f"Profile memory: {results.get('profile_memory', [])}")
+print(f"Episodic memory: {results.content.episodic_memory}")
+print(f"Semantic memory: {results.content.semantic_memory}")
 
-# Search with filters
-work_results = memory.search("Tell me about work", filter_dict={"category": "work"})
-print(f"Work results: {work_results}")
+# Search with filters (user metadata fields require the `m.` / `metadata.` prefix)
+work_results = memory.search("Tell me about work", filter_dict={"m.category": "work"})
+print(f"Work results: {work_results.model_dump()}")
 ```
 
 ### Multiple Users

memmachine_client-0.3.9/client_tests/test_cli.py

@@ -0,0 +1,228 @@
+"""Tests for the MemMachine command line client."""
+
+import sys
+from pathlib import Path
+from unittest.mock import Mock, patch
+
+import pytest
+from pydantic import BaseModel
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+from memmachine_client import cli
+
+
+class CliResult(BaseModel):
+    """Small Pydantic test result."""
+
+    uid: str
+
+
+def test_pyproject_installs_command_name():
+    """Editable installs should expose the documented mem-cli command."""
+    pyproject = tomllib.loads(
+        (Path(__file__).resolve().parents[1] / "pyproject.toml").read_text()
+    )
+
+    assert pyproject["project"]["scripts"]["mem-cli"] == ("memmachine_client.cli:main")
+
+
+def test_build_client_uses_args_over_environment(monkeypatch):
+    """Command arguments should override environment variables."""
+    monkeypatch.setenv("MEMORY_BACKEND_URL", "http://env:8080")
+    monkeypatch.setenv("MEMMACHINE_API_KEY", "env-key")
+    monkeypatch.setenv("MEMMACHINE_TIMEOUT", "10")
+    monkeypatch.setenv("MEMMACHINE_MAX_RETRIES", "2")
+
+    args = cli.build_parser().parse_args(
+        [
+            "--base-url",
+            "http://arg:8080",
+            "--api-key",
+            "arg-key",
+            "--timeout",
+            "20",
+            "--max-retries",
+            "4",
+            "health",
+        ]
+    )
+
+    client = cli.build_client(args)
+
+    assert client.base_url == "http://arg:8080"
+    assert client.api_key == "arg-key"
+    assert client.timeout == 20
+    assert client.max_retries == 4
+
+
+def test_build_client_requires_base_url(monkeypatch):
+    """The CLI should fail clearly when base_url is unavailable."""
+    monkeypatch.delenv("MEMORY_BACKEND_URL", raising=False)
+
+    args = cli.build_parser().parse_args(["health"])
+
+    with pytest.raises(SystemExit) as exc:
+        cli.build_client(args)
+
+    assert exc.value.code == 2
+
+
+def test_parser_help_uses_installed_command_name(capsys):
+    """Help output should match the documented console script."""
+    with pytest.raises(SystemExit) as exc:
+        cli.build_parser().parse_args(["--help"])
+
+    assert exc.value.code == 0
+    assert capsys.readouterr().out.startswith("usage: mem-cli ")
+
+
+def test_custom_errors_use_parser_program_name(monkeypatch, capsys):
+    """Custom errors should use the same program name as argparse."""
+    monkeypatch.delenv("MEMORY_BACKEND_URL", raising=False)
+
+    args = cli.build_parser().parse_args(["health"])
+
+    with pytest.raises(SystemExit) as exc:
+        cli.build_client(args)
+
+    assert exc.value.code == 2
+    assert capsys.readouterr().err == (
+        "mem-cli: error: --base-url or MEMORY_BACKEND_URL is required\n"
+    )
+
+
+def test_health_command_prints_json(capsys):
+    """The health command should call the underlying client."""
+    client = Mock()
+    client.health_check.return_value = {"status": "healthy"}
+
+    result = cli.run_command(client, cli.build_parser().parse_args(["health"]))
+
+    assert result == 0
+    client.health_check.assert_called_once_with(timeout=None)
+    assert capsys.readouterr().out == '{\n  "status": "healthy"\n}\n'
+
+
+def test_memory_add_uses_env_project_context(monkeypatch, capsys):
+    """Memory commands should accept project context from the environment."""
+    monkeypatch.setenv("MEMMACHINE_ORG_ID", "env-org")
+    monkeypatch.setenv("MEMMACHINE_PROJECT_ID", "env-project")
+    client = Mock()
+    project = Mock()
+    memory = Mock()
+    memory.add.return_value = [CliResult(uid="mem-1")]
+    project.memory.return_value = memory
+    client.get_project.return_value = project
+
+    args = cli.build_parser().parse_args(
+        ["memory", "add", "hello", "--metadata", "user_id=user-1"]
+    )
+
+    exit_code = cli.run_command(client, args)
+
+    assert exit_code == 0
+    client.get_project.assert_called_once_with(
+        org_id="env-org",
+        project_id="env-project",
+        timeout=None,
+    )
+    project.memory.assert_called_once_with(metadata={"user_id": "user-1"})
+    memory.add.assert_called_once_with(
+        "hello",
+        role="",
+        producer=None,
+        produced_for=None,
+        metadata=None,
+        timeout=None,
+    )
+    assert capsys.readouterr().out == '[\n  {\n    "uid": "mem-1"\n  }\n]\n'
+
+
+@pytest.mark.parametrize(
+    ("argv", "memory_method"),
+    [
+        (["memory", "search", "hello"], "search"),
+        (["memory", "list"], "list"),
+        (["memory", "delete-episodic", "--id", "episode-1"], "delete_episodic"),
+        (["memory", "delete-semantic", "--id", "semantic-1"], "delete_semantic"),
+    ],
+)
+def test_memory_subcommands_use_env_project_context(
+    argv, memory_method, monkeypatch, capsys
+):
+    """Memory subcommands should resolve project context through the shared helper."""
+    monkeypatch.setenv("MEMMACHINE_ORG_ID", "env-org")
+    monkeypatch.setenv("MEMMACHINE_PROJECT_ID", "env-project")
+    client = Mock()
+    project = Mock()
+    memory = Mock()
+    getattr(memory, memory_method).return_value = (
+        True if memory_method.startswith("delete_") else []
+    )
+    project.memory.return_value = memory
+    client.get_project.return_value = project
+
+    args = cli.build_parser().parse_args(argv)
+
+    assert cli.run_command(client, args) == 0
+    client.get_project.assert_called_once_with(
+        org_id="env-org",
+        project_id="env-project",
+        timeout=None,
+    )
+    project.memory.assert_called_once_with(metadata={})
+    assert capsys.readouterr().out
+
+
+def test_projects_create_uses_env_project_context(monkeypatch, capsys):
+    """Project create should accept project context from the environment."""
+    monkeypatch.setenv("MEMMACHINE_ORG_ID", "env-org")
+    monkeypatch.setenv("MEMMACHINE_PROJECT_ID", "env-project")
+    client = Mock()
+    project = Mock(
+        org_id="env-org",
+        project_id="env-project",
+        description="",
+        config={},
+    )
+    client.create_project.return_value = project
+
+    args = cli.build_parser().parse_args(["projects", "create"])
+
+    exit_code = cli.run_command(client, args)
+
+    assert exit_code == 0
+    client.create_project.assert_called_once_with(
+        org_id="env-org",
+        project_id="env-project",
+        description="",
+        embedder="",
+        reranker="",
+        timeout=None,
+    )
+    assert capsys.readouterr().out == (
+        "{\n"
+        '  "config": {},\n'
+        '  "description": "",\n'
+        '  "org_id": "env-org",\n'
+        '  "project_id": "env-project"\n'
+        "}\n"
+    )
+
+
+@patch("memmachine_client.cli.MemMachineClient")
+def test_main_closes_client(mock_client_class, monkeypatch):
+    """The top-level entry point should close the client after command execution."""
+    monkeypatch.setenv("MEMORY_BACKEND_URL", "http://localhost:8080")
+    client = Mock()
+    client.health_check.return_value = {"status": "healthy"}
+    mock_client_class.return_value = client
+
+    exit_code = cli.main(["health"])
+
+    assert exit_code == 0
+    client.close.assert_called_once_with()

{memmachine_client-0.3.7 → memmachine_client-0.3.9}/client_tests/test_client.py

@@ -206,6 +206,97 @@ class TestMemMachineClient:
                 project_id="test_project",
             )
 
+    def test_create_project_event_backend_fields_reach_wire(self):
+        """Event-backend fields must reach the wire — without this the SDK
+        has no supported path to event-backed projects."""
+        client = MemMachineClient(base_url="http://localhost:8080")
+        mock_response = Mock()
+        mock_response.status_code = 200
+        mock_response.raise_for_status = Mock()
+        mock_response.json.return_value = {
+            "org_id": "test_org",
+            "project_id": "test_project",
+            "description": "",
+            "config": {
+                "backend": "event",
+                "embedder": "default",
+                "reranker": "default",
+                "vector_store": "qdrant_vs",
+                "segment_store": "sqlite_db",
+                "properties_schema": {"customer_tier": "str"},
+            },
+        }
+        with patch.object(
+            client._session, "post", return_value=mock_response
+        ) as mock_post:
+            client.create_project(
+                org_id="test_org",
+                project_id="test_project",
+                backend="event",
+                vector_store="qdrant_vs",
+                segment_store="sqlite_db",
+                properties_schema={"customer_tier": "str"},
+            )
+            cfg = mock_post.call_args[1]["json"]["config"]
+            assert cfg["backend"] == "event"
+            assert cfg["vector_store"] == "qdrant_vs"
+            assert cfg["segment_store"] == "sqlite_db"
+            assert cfg["properties_schema"] == {"customer_tier": "str"}
+
+    def test_get_project_404_raises_http_error(self):
+        """Test missing project preserves HTTPError semantics."""
+        client = MemMachineClient(base_url="http://localhost:8080")
+        mock_response = Mock()
+        mock_response.status_code = 404
+        http_error = requests.HTTPError(response=mock_response)
+        mock_response.raise_for_status.side_effect = http_error
+
+        with (
+            patch.object(client, "request", return_value=mock_response),
+            pytest.raises(requests.HTTPError) as exc_info,
+        ):
+            client.get_project(org_id="test_org", project_id="missing_project")
+
+        assert exc_info.value is http_error
+        assert exc_info.value.response.status_code == 404
+
+    def test_get_or_create_project_creates_after_get_404(self):
+        """Test missing project is created by get_or_create_project."""
+        client = MemMachineClient(base_url="http://localhost:8080")
+        get_response = Mock()
+        get_response.status_code = 404
+        get_response.raise_for_status.side_effect = requests.HTTPError(
+            response=get_response
+        )
+
+        create_response = Mock()
+        create_response.status_code = 200
+        create_response.raise_for_status = Mock()
+        create_response.json.return_value = {
+            "org_id": "test_org",
+            "project_id": "new_project",
+            "description": "Created project",
+            "config": {"embedder": "", "reranker": ""},
+        }
+
+        with (
+            patch.object(client, "request", return_value=get_response) as mock_request,
+            patch.object(
+                client._session, "post", return_value=create_response
+            ) as mock_post,
+        ):
+            project = client.get_or_create_project(
+                org_id="test_org",
+                project_id="new_project",
+                description="Created project",
+            )
+
+        assert project.org_id == "test_org"
+        assert project.project_id == "new_project"
+        assert project.description == "Created project"
+        mock_request.assert_called_once()
+        mock_post.assert_called_once()
+
     @patch("requests.Session.get")
     def test_health_check_success(self, mock_get):
         """Test successful health check."""

{memmachine_client-0.3.7 → memmachine_client-0.3.9}/client_tests/test_config.py

@@ -368,6 +368,30 @@ class TestConfig:
         with pytest.raises(RuntimeError, match="client has been closed"):
             config.update_long_term_memory_config(embedder="x")
 
+    def test_update_long_term_memory_config_event_backend(self, config, mock_client):
+        """Event-backend fields (backend / vector_store / segment_store /
+        properties_schema) must reach the wire — without these the SDK has no
+        supported path to event-backed projects."""
+        mock_client.request.return_value = _mock_response(
+            {"success": True, "message": "Long-term memory configuration updated"}
+        )
+        result = config.update_long_term_memory_config(
+            backend="event",
+            embedder="new-embedder",
+            vector_store="qdrant_vs",
+            segment_store="sqlite_db",
+            properties_schema={"customer_tier": "str"},
+        )
+        assert isinstance(result, UpdateMemoryConfigResponse)
+        body = mock_client.request.call_args[1]["json"]
+        assert body["backend"] == "event"
+        assert body["vector_store"] == "qdrant_vs"
+        assert body["segment_store"] == "sqlite_db"
+        assert body["properties_schema"] == {"customer_tier": "str"}
+        assert body["embedder"] == "new-embedder"
+        # Untouched declarative-only field must NOT leak into the payload.
+        assert "vector_graph_store" not in body
+
     def test_update_short_term_memory_config(self, config, mock_client):
         mock_client.request.return_value = _mock_response(
             {"success": True, "message": "Short-term memory configuration updated"}
@@ -533,9 +557,13 @@ class TestConfig:
             {"success": True, "message": "Episodic memory configuration updated"}
         )
         ltm_spec = UpdateLongTermMemorySpec(
+            backend=None,
             embedder="new-embedder",
             reranker="new-reranker",
             vector_graph_store="new-store",
+            vector_store=None,
+            segment_store=None,
+            properties_schema=None,
         )
         stm_spec = UpdateShortTermMemorySpec(
             llm_model="new-llm",

{memmachine_client-0.3.7 → memmachine_client-0.3.9}/client_tests/test_format.py

@@ -99,6 +99,59 @@ class TestFormatEpisodes:
         result = format_episodes([ep])
         assert json.dumps('She said "hello"') in result
 
+    def test_non_ascii_content_preserved_literally(self):
+        """Non-ASCII characters must appear literally in the LLM context, not
+        as ``\\uXXXX`` escapes — escaping bloats token counts and degrades
+        recall on multilingual content."""
+        ep = EpisodeResponse(
+            uid="1",
+            content="寿司 café 🍕 naïve résumé Привет",
+            producer_id="user_1",
+            producer_role="user",
+            created_at=datetime(2024, 1, 1, 0, 0, tzinfo=timezone.utc),
+        )
+        result = format_episodes([ep])
+        assert "寿司" in result
+        assert "café" in result
+        assert "🍕" in result
+        assert "naïve" in result
+        assert "résumé" in result
+        assert "Привет" in result
+        # Sanity: no escaped CJK / cyrillic / accented sequences.
+        assert "\\u" not in result
+
+    def test_non_ascii_content_lossless_roundtrip(self):
+        """The JSON-encoded portion must round-trip back to the original
+        string so downstream LLM consumers (and any client-side
+        post-processing) still see correct text."""
+        original = '日本語 — "quoted" + emoji 🎉'
+        ep = EpisodeResponse(
+            uid="1",
+            content=original,
+            producer_id="user_1",
+            producer_role="user",
+            created_at=None,
+        )
+        result = format_episodes([ep])
+        json_part = result.removeprefix("user_1: ").rstrip("\n")
+        assert json.loads(json_part) == original
+
+    def test_output_is_utf8_encodable(self):
+        """The LLM-visible string must be safe to send over UTF-8 transports
+        (HTTP body, logging sinks). ``ensure_ascii=False`` produces
+        unescaped surrogates only for malformed inputs; clean Unicode must
+        encode without error."""
+        ep = EpisodeResponse(
+            uid="1",
+            content="Mixed: ASCII + 中文 + 🚀",
+            producer_id="user_1",
+            producer_role="user",
+            created_at=datetime(2024, 1, 1, 0, 0, tzinfo=timezone.utc),
+        )
+        result = format_episodes([ep])
+        encoded = result.encode("utf-8")
+        assert encoded.decode("utf-8") == result
+
 
 class TestFormatSemanticMemories:
     """Tests for format_semantic_memories."""
@@ -146,6 +199,32 @@ class TestFormatSemanticMemories:
             "background": {"role": "engineer"},
         }
 
+    def test_non_ascii_value_preserved_literally(self):
+        feature = SemanticFeature(
+            category="profile",
+            tag="prefs",
+            feature_name="favorite_food",
+            value="寿司 🍣",
+        )
+        result = format_semantic_memories([feature])
+        assert "寿司" in result
+        assert "🍣" in result
+        assert "\\u" not in result
+        # And the JSON is still valid.
+        assert json.loads(result) == {"prefs": {"favorite_food": "寿司 🍣"}}
+
+    def test_non_ascii_tag_and_feature_name_preserved(self):
+        feature = SemanticFeature(
+            category="profile",
+            tag="préférences",
+            feature_name="種類",
+            value="ramen",
+        )
+        result = format_semantic_memories([feature])
+        assert "préférences" in result
+        assert "種類" in result
+        assert json.loads(result) == {"préférences": {"種類": "ramen"}}
+
     def test_metadata_excluded(self):
         feature = SemanticFeature(
             set_id="set_1",

{memmachine_client-0.3.7 → memmachine_client-0.3.9}/client_tests/test_langgraph.py

@@ -2,6 +2,8 @@
 
 from unittest.mock import Mock, patch
 
+from memmachine_common.api import EpisodeType
+
 from memmachine_client.langgraph import (
     MemMachineTools,
     create_add_memory_tool,
@@ -145,9 +147,43 @@ class TestAddMemory:
         assert result["uids"] == ["uid-123"]
         assert result["content"] == "Hello world"
         mock_memory.add.assert_called_once_with(
-            content="Hello world", role="user", metadata={}
+            content="Hello world", role="user", metadata={}, episode_type=None
+        )
+
+    def test_raw_filter_passthrough(self):
+        tools, mock_memory = self._make_tools()
+
+        mock_content = Mock()
+        mock_content.episodic_memory = None
+        mock_content.semantic_memory = []
+
+        mock_search_result = Mock()
+        mock_search_result.content = mock_content
+        mock_memory.search.return_value = mock_search_result
+
+        result = tools.search_memory(query="food", filter='metadata.category = "work"')
+
+        assert result["status"] == "success"
+        mock_memory.search.assert_called_once_with(
+            query="food",
+            limit=20,
+            score_threshold=None,
+            filter_dict=None,
+            filter='metadata.category = "work"',
         )
 
+    def test_episode_type_string_is_normalized(self):
+        tools, mock_memory = self._make_tools()
+        mock_result = Mock()
+        mock_result.uid = "uid-ep"
+        mock_memory.add.return_value = [mock_result]
+
+        result = tools.add_memory(content="Hello world", episode_type="message")
+
+        assert result["status"] == "success"
+        mock_memory.add.assert_called_once()
+        assert mock_memory.add.call_args.kwargs["episode_type"] == EpisodeType.MESSAGE
+
     def test_error_path(self):
         tools, mock_memory = self._make_tools()
         mock_memory.add.side_effect = RuntimeError("boom")
@@ -203,7 +239,7 @@ class TestSearchMemory:
         assert result["results"]["episodic_memory"] == {"episodes": [{"content": "hi"}]}
         assert result["results"]["semantic_memory"] == [{"name": "likes pizza"}]
         mock_memory.search.assert_called_once_with(
-            query="food", limit=20, score_threshold=None, filter_dict=None
+            query="food", limit=20, score_threshold=None, filter_dict=None, filter=None
         )
 
     def test_error_path(self):
@@ -323,7 +359,7 @@ class TestFactoryFunctions:
         mock_memory.add.return_value = [mock_result]
 
         add_fn = create_add_memory_tool(tools)
-        result = add_fn("test content", None, None)
+        result = add_fn("test content", None, None, None)
 
         assert result["status"] == "success"
         assert result["uids"] == ["uid-1"]
@@ -335,7 +371,7 @@ class TestFactoryFunctions:
         mock_memory.add.return_value = [mock_result]
 
         add_fn = create_add_memory_tool(tools)
-        result = add_fn("content", "u1", None)
+        result = add_fn("content", "u1", None, "message")
 
         assert result["status"] == "success"
 
@@ -368,5 +404,5 @@ class TestFactoryFunctions:
         search_fn("hello", None, 10)
 
         mock_memory.search.assert_called_once_with(
-            query="hello", limit=10, score_threshold=None, filter_dict=None
+            query="hello", limit=10, score_threshold=None, filter_dict=None, filter=None
         )