memtru 0.1.0__tar.gz

memtru-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.memtru/
+.scratch/
+node_modules/
+.next/
+apps/web/data/
+apps/web/test-results/
+apps/web/playwright-report/
+*.tsbuildinfo
+.env
+.env*.local
+.memoryproof/

memtru-0.1.0/LICENSE

@@ -0,0 +1,53 @@
+Memtru CLI License
+
+Copyright (c) 2026 the Memtru copyright holder. All rights reserved.
+
+The Memtru command-line tool and Python package (the "Software") are
+proprietary. They are not open source.
+
+1. Permitted use. Subject to these terms, you may install and run the Software,
+   free of charge, to test memory systems that you own or are authorized to
+   test, including in your continuous-integration pipelines, and you may use the
+   reports it produces for any purpose.
+
+2. Restrictions. You may not, and may not allow others to:
+   a. copy, modify, translate or create derivative works of the Software,
+      except copies needed to install and run it as permitted above;
+   b. distribute, sublicense, sell, rent, lend or otherwise make the Software
+      available to third parties, including as part of another product or a
+      hosted service;
+   c. reverse engineer, decompile or disassemble the Software, except to the
+      extent applicable law expressly permits it despite this restriction;
+   d. use the Software, or knowledge gained from its code, to build a competing
+      product or service;
+   e. remove or alter any notice of ownership in the Software.
+   Writing your own adapter that loads into the Software through its documented
+   interfaces is not a derivative work of the Software.
+
+3. Testing responsibility. Run the Software only against systems you are
+   authorized to test. You are responsible for its effects on those systems.
+
+4. Memtru services. Use of the hosted Memtru service (for example uploading
+   reports to memtru.com) is governed by its terms at https://memtru.com/terms.
+
+5. Ownership and feedback. The copyright holder keeps all rights not expressly
+   granted here. Feedback you provide may be used without obligation to you.
+
+6. Termination. This license ends automatically if you breach it. On
+   termination you must stop using the Software and delete all copies.
+
+7. No warranty. 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. TEST
+   RESULTS DESCRIBE THE SCENARIOS THAT RAN AND ARE NOT A GUARANTEE OF SECURITY.
+
+8. Limitation of liability. TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT
+   SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+   LIABILITY ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR ITS USE.
+
+9. Other agreements. A separate written agreement signed by the copyright
+   holder takes precedence over these terms.
+
+Third-party components used by the Software remain under their own licenses.
+
+Questions: contact@memtru.com

memtru-0.1.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.5
+Name: memtru
+Version: 0.1.0
+Summary: Reproducible reliability and isolation tests for AI agent memory systems.
+Project-URL: Homepage, https://memtru.com
+Project-URL: Documentation, https://memtru.com/docs
+Project-URL: Demo, https://memtru.com/demo
+Author-email: Memtru <contact@memtru.com>
+License: Memtru CLI License
+        
+        Copyright (c) 2026 the Memtru copyright holder. All rights reserved.
+        
+        The Memtru command-line tool and Python package (the "Software") are
+        proprietary. They are not open source.
+        
+        1. Permitted use. Subject to these terms, you may install and run the Software,
+           free of charge, to test memory systems that you own or are authorized to
+           test, including in your continuous-integration pipelines, and you may use the
+           reports it produces for any purpose.
+        
+        2. Restrictions. You may not, and may not allow others to:
+           a. copy, modify, translate or create derivative works of the Software,
+              except copies needed to install and run it as permitted above;
+           b. distribute, sublicense, sell, rent, lend or otherwise make the Software
+              available to third parties, including as part of another product or a
+              hosted service;
+           c. reverse engineer, decompile or disassemble the Software, except to the
+              extent applicable law expressly permits it despite this restriction;
+           d. use the Software, or knowledge gained from its code, to build a competing
+              product or service;
+           e. remove or alter any notice of ownership in the Software.
+           Writing your own adapter that loads into the Software through its documented
+           interfaces is not a derivative work of the Software.
+        
+        3. Testing responsibility. Run the Software only against systems you are
+           authorized to test. You are responsible for its effects on those systems.
+        
+        4. Memtru services. Use of the hosted Memtru service (for example uploading
+           reports to memtru.com) is governed by its terms at https://memtru.com/terms.
+        
+        5. Ownership and feedback. The copyright holder keeps all rights not expressly
+           granted here. Feedback you provide may be used without obligation to you.
+        
+        6. Termination. This license ends automatically if you breach it. On
+           termination you must stop using the Software and delete all copies.
+        
+        7. No warranty. 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. TEST
+           RESULTS DESCRIBE THE SCENARIOS THAT RAN AND ARE NOT A GUARANTEE OF SECURITY.
+        
+        8. Limitation of liability. TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT
+           SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+           LIABILITY ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR ITS USE.
+        
+        9. Other agreements. A separate written agreement signed by the copyright
+           holder takes precedence over these terms.
+        
+        Third-party components used by the Software remain under their own licenses.
+        
+        Questions: contact@memtru.com
+License-File: LICENSE
+Keywords: ai agents,deletion,langgraph,llm,mem0,memory,privacy,testing
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: jinja2>=3.1
+Requires-Dist: pydantic<3,>=2.9
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Requires-Dist: typer<1,>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: types-pyyaml>=6; extra == 'dev'
+Provides-Extra: langgraph
+Requires-Dist: langgraph==1.2.16; extra == 'langgraph'
+Provides-Extra: mem0
+Requires-Dist: mem0ai==2.2.1; extra == 'mem0'
+Description-Content-Type: text/markdown
+
+# Memtru
+
+Reproducible tests for the memory systems behind AI agents. Memtru writes synthetic markers into your memory store and checks the boundaries that matter: one user's memory never reaches another user or tenant, deleted memory stays deleted, updates replace stale facts, and sessions stay separate.
+
+Every finding comes with the evidence to reproduce it. Tests run locally or in CI; nothing is uploaded unless you run `memtru upload`.
+
+```bash
+pip install memtru
+memtru demo              # a deliberately broken store, then a fixed one
+memtru demo --afterlife  # a deleted memory that comes back after a later event
+```
+
+## Test your own system
+
+```bash
+memtru init              # writes memtru.yaml
+memtru doctor            # checks the configuration and adapter
+memtru test              # runs the scenarios, writes JSON and HTML reports
+```
+
+Adapters: the built-in reference store (`in_memory`), any service implementing the Memtru REST contract (`http`), your own Python class (`custom`), and Mem0 OSS (`pip install "memtru[mem0]"`).
+
+## Scenarios
+
+| Id | What it checks |
+|---|---|
+| MT-ISO-001 | Cross-user isolation |
+| MT-TEN-002 | Cross-tenant isolation |
+| MT-DEL-003 | Deleted memory stops being retrievable |
+| MT-STALE-004 | Updated facts replace stale ones |
+| MT-SES-005 | Session isolation |
+| MT-INT-006 | Updates change only the intended record |
+| MT-POISON-007 | Controlled memory poisoning (agent mode) |
+| MT-AF-001 | Afterlife: a late write brings deleted memory back |
+| MT-AF-002 | Afterlife: a new session rebuilds deleted memory from history |
+
+Every scenario reports PASS, FAIL, INCONCLUSIVE, ERROR or SKIPPED. A result is never PASS without a positive control showing the authorized path works.
+
+Exit codes make it CI-ready: `0` pass, `1` a scenario failed, `3` execution error, `4` inconclusive when `--fail-on-inconclusive` is set.
+
+## Links
+
+- Documentation: https://memtru.com/docs
+- Interactive demo: https://memtru.com/demo
+- Dashboard for uploaded runs: https://memtru.com
+- Security reports: security@memtru.com · Contact: contact@memtru.com
+
+## License
+
+Proprietary. Free to install and use for testing systems you own or are authorized to test; see the LICENSE file for the terms. Test results describe the scenarios that ran and are not a guarantee of security.

memtru-0.1.0/README.md

@@ -0,0 +1,50 @@
+# Memtru
+
+Reproducible tests for the memory systems behind AI agents. Memtru writes synthetic markers into your memory store and checks the boundaries that matter: one user's memory never reaches another user or tenant, deleted memory stays deleted, updates replace stale facts, and sessions stay separate.
+
+Every finding comes with the evidence to reproduce it. Tests run locally or in CI; nothing is uploaded unless you run `memtru upload`.
+
+```bash
+pip install memtru
+memtru demo              # a deliberately broken store, then a fixed one
+memtru demo --afterlife  # a deleted memory that comes back after a later event
+```
+
+## Test your own system
+
+```bash
+memtru init              # writes memtru.yaml
+memtru doctor            # checks the configuration and adapter
+memtru test              # runs the scenarios, writes JSON and HTML reports
+```
+
+Adapters: the built-in reference store (`in_memory`), any service implementing the Memtru REST contract (`http`), your own Python class (`custom`), and Mem0 OSS (`pip install "memtru[mem0]"`).
+
+## Scenarios
+
+| Id | What it checks |
+|---|---|
+| MT-ISO-001 | Cross-user isolation |
+| MT-TEN-002 | Cross-tenant isolation |
+| MT-DEL-003 | Deleted memory stops being retrievable |
+| MT-STALE-004 | Updated facts replace stale ones |
+| MT-SES-005 | Session isolation |
+| MT-INT-006 | Updates change only the intended record |
+| MT-POISON-007 | Controlled memory poisoning (agent mode) |
+| MT-AF-001 | Afterlife: a late write brings deleted memory back |
+| MT-AF-002 | Afterlife: a new session rebuilds deleted memory from history |
+
+Every scenario reports PASS, FAIL, INCONCLUSIVE, ERROR or SKIPPED. A result is never PASS without a positive control showing the authorized path works.
+
+Exit codes make it CI-ready: `0` pass, `1` a scenario failed, `3` execution error, `4` inconclusive when `--fail-on-inconclusive` is set.
+
+## Links
+
+- Documentation: https://memtru.com/docs
+- Interactive demo: https://memtru.com/demo
+- Dashboard for uploaded runs: https://memtru.com
+- Security reports: security@memtru.com · Contact: contact@memtru.com
+
+## License
+
+Proprietary. Free to install and use for testing systems you own or are authorized to test; see the LICENSE file for the terms. Test results describe the scenarios that ran and are not a guarantee of security.

memtru-0.1.0/pyproject.toml

@@ -0,0 +1,94 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "memtru"
+version = "0.1.0"
+description = "Reproducible reliability and isolation tests for AI agent memory systems."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { file = "LICENSE" }
+authors = [{ name = "Memtru", email = "contact@memtru.com" }]
+keywords = ["ai agents", "memory", "testing", "privacy", "deletion", "llm", "mem0", "langgraph"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: Other/Proprietary License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Testing",
+  "Topic :: Security",
+]
+dependencies = [
+  "typer>=0.12,<1",
+  "rich>=13.7",
+  "pydantic>=2.9,<3",
+  "pyyaml>=6.0",
+  "jinja2>=3.1",
+  "httpx>=0.27,<1",
+]
+
+[project.optional-dependencies]
+mem0 = ["mem0ai==2.2.1"]
+# Afterlife integration example (examples/afterlife-langgraph); pinned on purpose.
+langgraph = ["langgraph==1.2.16"]
+dev = [
+  "pytest>=8.3",
+  "pytest-cov>=5",
+  "ruff>=0.6",
+  "mypy>=1.11",
+  "types-PyYAML>=6",
+]
+
+[project.urls]
+Homepage = "https://memtru.com"
+Documentation = "https://memtru.com/docs"
+Demo = "https://memtru.com/demo"
+
+[project.scripts]
+memtru = "memtru.cli.app:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/memtru"]
+
+# The source distribution ships the package only: no tests, fixtures or examples.
+[tool.hatch.build.targets.sdist]
+include = ["src/memtru", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+pythonpath = ["."]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "S", "RUF", "SIM", "PT"]
+ignore = [
+  "S101",   # assert is the idiom in pytest and for type narrowing
+  "E501",   # line length is enforced by `ruff format`; long strings are allowed
+  "RUF001", # status glyphs (en dash, check marks) are intentional
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S105", "S106", "S108", "S310", "PT018"]
+"src/memtru/cli/app.py" = ["PT028"]  # `test` is a CLI command, not a pytest test
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+packages = ["memtru"]
+mypy_path = "src"
+plugins = ["pydantic.mypy"]
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false

memtru-0.1.0/src/memtru/__init__.py

@@ -0,0 +1,7 @@
+"""Memtru: reproducible reliability and isolation tests for AI agent memory."""
+
+__version__ = "0.1.0"
+
+REPORT_SCHEMA_VERSION = "1.0"
+
+__all__ = ["REPORT_SCHEMA_VERSION", "__version__"]

memtru-0.1.0/src/memtru/adapters/__init__.py

@@ -0,0 +1,105 @@
+"""Adapter registry: builds the adapter described by the configuration."""
+
+from __future__ import annotations
+
+import importlib
+import os
+import sys
+from dataclasses import dataclass
+
+from memtru.adapters.base import AgentAdapter, MemoryAdapter
+from memtru.adapters.in_memory import InMemoryAdapter
+from memtru.core.config import (
+    Config,
+    CustomAdapterConfig,
+    HttpAdapterConfig,
+    InMemoryAdapterConfig,
+    Mem0AdapterConfig,
+)
+from memtru.errors import ConfigError
+
+__all__ = ["AgentAdapter", "MemoryAdapter", "build_adapter", "describe_builtin_adapters"]
+
+
+@dataclass(frozen=True)
+class AdapterInfo:
+    type: str
+    summary: str
+    verification: str
+
+
+BUILTIN_ADAPTERS = [
+    AdapterInfo(
+        "in_memory",
+        "Built-in reference store with tenant, user and session scoping. Supports fault injection.",
+        "Verified by the Memtru test suite.",
+    ),
+    AdapterInfo(
+        "http",
+        "Any service implementing the Memtru REST contract (docs/adapters.md).",
+        "Verified against the reference server in examples/provider-integration.",
+    ),
+    AdapterInfo(
+        "mem0",
+        "Mem0 OSS 2.2.1; explicit SDK factory, synthetic search-filter testing.",
+        "SDK contract tests and local Qdrant integration; hosted verification is separate.",
+    ),
+    AdapterInfo(
+        "custom",
+        "Your own Python class implementing memtru.adapters.base.MemoryAdapter.",
+        "Verified by you: Memtru only loads it.",
+    ),
+]
+
+
+def describe_builtin_adapters() -> list[AdapterInfo]:
+    return list(BUILTIN_ADAPTERS)
+
+
+def _load_custom(config: CustomAdapterConfig) -> MemoryAdapter:
+    module_name, _, attr = config.entrypoint.partition(":")
+    # Like pytest, resolve user modules relative to the directory the CLI runs in.
+    if os.getcwd() not in sys.path:
+        sys.path.insert(0, os.getcwd())
+    try:
+        module = importlib.import_module(module_name)
+    except ImportError as err:
+        raise ConfigError(
+            f"Cannot import adapter module {module_name!r}: {err}",
+            hint="Make sure the module is importable from the current directory or PYTHONPATH.",
+        ) from None
+    factory = getattr(module, attr, None)
+    if factory is None:
+        raise ConfigError(f"{module_name!r} has no attribute {attr!r}.")
+    adapter = factory(**config.options)
+    if not isinstance(adapter, MemoryAdapter):
+        raise ConfigError(f"{config.entrypoint} did not produce a MemoryAdapter instance.")
+    return adapter
+
+
+def build_adapter(config: Config) -> MemoryAdapter:
+    adapter_config = config.adapter
+    if isinstance(adapter_config, InMemoryAdapterConfig):
+        return InMemoryAdapter(adapter_config.faults, adapter_config.index_delay_ms)
+    if isinstance(adapter_config, HttpAdapterConfig):
+        from memtru.adapters.http import HttpAdapter
+
+        return HttpAdapter(adapter_config, environment=config.execution.environment)
+    if isinstance(adapter_config, CustomAdapterConfig):
+        return _load_custom(adapter_config)
+    if isinstance(adapter_config, Mem0AdapterConfig):
+        from memtru.adapters.mem0 import Mem0Adapter
+
+        # The optional SDK otherwise enables its own telemetry at import time.
+        os.environ["MEM0_TELEMETRY"] = "false"
+        module_name, _, attr = adapter_config.factory.partition(":")
+        if os.getcwd() not in sys.path:
+            sys.path.insert(0, os.getcwd())
+        try:
+            factory = getattr(importlib.import_module(module_name), attr)
+        except (ImportError, AttributeError):
+            raise ConfigError(
+                "Cannot load Mem0 factory. Check adapter.factory and install memtru[mem0]."
+            ) from None
+        return Mem0Adapter(factory())
+    raise ConfigError(f"Unknown adapter type {adapter_config!r}")  # pragma: no cover

memtru-0.1.0/src/memtru/adapters/base.py

@@ -0,0 +1,80 @@
+"""The adapter contract every memory provider integration implements.
+
+Adapters translate Memtru operations into calls on a real memory system.
+They must scope every operation to the given :class:`MemoryContext`; the
+scenarios then verify whether that scoping actually holds.
+
+Optional operations raise :class:`UnsupportedCapabilityError` by default.
+Declare what is supported in :meth:`MemoryAdapter.capabilities` so scenarios
+can be skipped, never silently passed, when a prerequisite is missing.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import ClassVar
+
+from memtru.core.models import Capability, MemoryContext, MemoryRecord, MemoryScope
+from memtru.errors import UnsupportedCapabilityError
+
+
+class MemoryAdapter(ABC):
+    name: ClassVar[str]
+    version: ClassVar[str] = "1.0"
+
+    @abstractmethod
+    def capabilities(self) -> frozenset[Capability]:
+        """Capabilities this adapter supports *and* boundaries it claims to enforce."""
+
+    def setup(self, namespace: str) -> None:  # noqa: B027 - optional hook
+        """Prepare an isolated test namespace. Called once per run."""
+
+    def teardown(self, namespace: str) -> None:  # noqa: B027 - optional hook
+        """Release the namespace created by :meth:`setup`. Must not touch other data."""
+
+    @abstractmethod
+    def add(
+        self,
+        ctx: MemoryContext,
+        content: str,
+        *,
+        metadata: dict[str, str] | None = None,
+        scope: MemoryScope = "user",
+    ) -> MemoryRecord: ...
+
+    @abstractmethod
+    def search(self, ctx: MemoryContext, query: str, *, limit: int = 10) -> list[MemoryRecord]: ...
+
+    def get(self, ctx: MemoryContext, memory_id: str) -> MemoryRecord | None:
+        raise UnsupportedCapabilityError(f"{self.name} does not support read by id")
+
+    def update(
+        self,
+        ctx: MemoryContext,
+        memory_id: str,
+        content: str,
+        *,
+        metadata: dict[str, str] | None = None,
+    ) -> MemoryRecord:
+        raise UnsupportedCapabilityError(f"{self.name} does not support updates")
+
+    def delete(self, ctx: MemoryContext, memory_id: str) -> None:
+        raise UnsupportedCapabilityError(f"{self.name} does not support deletion")
+
+    def describe(self) -> dict[str, str]:
+        """Safe, non-secret metadata included in reports."""
+        return {}
+
+    def close(self) -> None:  # noqa: B027 - optional hook
+        """Release connections."""
+
+
+class AgentAdapter(MemoryAdapter):
+    """An adapter that can also run the agent on top of the memory store.
+
+    Required for agent-mode scenarios (MT-POISON-007). ``respond`` must run the
+    real agent with the memory visible to ``ctx`` and return its final output.
+    """
+
+    @abstractmethod
+    def respond(self, ctx: MemoryContext, prompt: str) -> str: ...