memtrust-cli 0.3.0__tar.gz

memtrust_cli-0.3.0/.github/CODEOWNERS

@@ -0,0 +1,3 @@
+# CI/CD workflows are the highest-leverage place for a supply-chain compromise to
+# hide, so changes here always require review.
+/.github/workflows/ @RudrenduPaul

memtrust_cli-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,67 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Lint (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+      - run: pip install ruff
+      - run: ruff check .
+      - run: ruff format --check .
+
+  typecheck:
+    name: Type check (mypy --strict)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev,mem0-direct]"
+      - run: mypy --strict src/memtrust
+
+  test:
+    name: Test (pytest + coverage)
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev,mem0-direct]"
+      # All tests run fully offline -- no vendor or judge API keys are
+      # configured here, and none are required. This is what proves the
+      # "never crash on missing credentials" contract on every push.
+      # The mem0-direct group is installed so test_mem0_direct_adapter.py's
+      # real-package tests (see its module docstring) actually run here,
+      # instead of skipping -- they still make no live network call, they
+      # just import and exercise the real mem0ai/boto3/redis/valkey/
+      # google-genai/fastembed classes with the vendor SDK boundary mocked.
+      - run: pytest --cov=memtrust --cov-report=term-missing --cov-fail-under=80
+
+  security:
+    name: Security (pip-audit)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev,mem0-direct]"
+      - run: pip-audit

memtrust_cli-0.3.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,22 @@
+name: Publish PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.x"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+        with:
+          packages-dir: dist

memtrust_cli-0.3.0/.gitignore

@@ -0,0 +1,28 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.env
+.env.*
+!.env.example
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.log
+.DS_Store
+results/*/
+!results/.gitkeep
+node_modules/
+.idea/
+.vscode/
+.claude/
+uv.lock
+memtrust-report-*.json

memtrust_cli-0.3.0/.pre-commit-config.yaml

@@ -0,0 +1,17 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.14.1
+    hooks:
+      - id: mypy
+        args: [--strict, src/memtrust]
+        pass_filenames: false
+        additional_dependencies:
+          - httpx>=0.27.0
+          - click>=8.1.7

memtrust_cli-0.3.0/CHANGELOG.md

@@ -0,0 +1,196 @@
+# Changelog
+
+All notable changes to this project are documented here. Format loosely follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [0.3.0] - 2026-07-17
+
+### Changed
+
+- `MemPalaceAdapter` (`adapters/mempalace_adapter.py`) rewritten against the real,
+  live-verified `mempalace.mcp_server` API. Every previous version called a fictional
+  `mempalace.Palace` class that does not exist in the real installed package (confirmed:
+  `hasattr(mempalace, 'Palace')` is `False`) -- `store()`/`query()`/`update()` never
+  worked against the real vendor package in this project's history. `delete()`, which
+  previously always raised (no primitive existed), now genuinely works via
+  `tool_delete_drawer`. New additive `kg_add()`/`kg_invalidate()`/`kg_query()` methods
+  wrap the real KG API, including a new `TemporalBoundarySignal` (`CLEAN`/
+  `DOUBLE_COUNT`/`NOT_APPLICABLE`) detecting the exact boundary-instant double-counting
+  shape MemPalace/mempalace#1913/PR#1914 fixed. `RankingSignal` classification
+  re-pointed from fictional `importance`/`emotional_weight`/`weight` fields to the real
+  `similarity`/`authored_at` fields `tool_search` actually returns.
+- `--locomo-dataset-path` CLI flag added to `memtrust run` -- `run_locomo()` already
+  accepted a `dataset_path` parameter and `docs/methodology.md` already documented it,
+  but the CLI never exposed a way to actually pass one in. `load_dataset()` now raises
+  actionable errors (missing file / invalid JSON / missing `conversations` key) naming
+  the download URL and expected schema, instead of a bare `FileNotFoundError`/
+  `KeyError`/`JSONDecodeError`.
+
+### Fixed
+
+- `cryptography` dependency ceiling raised from `<47.0` to `<49.0` (floor raised to
+  `>=48.0.1`) -- the prior ceiling actively prevented installing the fix for
+  GHSA-537c-gmf6-5ccf (vulnerable OpenSSL bundled in the `cryptography` wheel, HIGH,
+  CVSS 7.5), found via `pip-audit` during a routine security sweep.
+
+## [0.2.0] - 2026-07-17
+
+### Added
+
+- `ZepGraphitiSelfHostedAdapter` (`adapters/zep_graphiti_selfhosted_adapter.py`) -- a second,
+  separately-configured Zep/Graphiti adapter (`GRAPHITI_NEO4J_URI` or `GRAPHITI_FALKORDB_URL`)
+  that instantiates `graphiti_core.Graphiti` directly in-process, reaching internal
+  graphiti-core bugs (getzep/graphiti#1302, #836, #1013, #1001) the existing Zep-Cloud REST
+  adapter can never see. Adds `MemoryRecord.attributes` so structured per-record properties
+  survive the adapter boundary, and `ConflictSignal.EDGE_INTEGRITY_VIOLATION` for edge records
+  with a missing `source_node_uuid`/`target_node_uuid`.
+- `Mem0DirectAdapter` (`adapters/mem0_direct_adapter.py`) -- a direct, in-process `mem0.Memory`
+  handle via `Memory.from_config()`, reaching mem0's construction-time `graph_store`/`embedder`/
+  `vector_store` config surface that the REST-only `Mem0Adapter`/`Mem0SelfHostedAdapter` cannot.
+  Built and tested against the real installed `mem0ai==2.0.12` package: confirms mem0ai/mem0
+  #5671, #4362, #4711, and #2304 are fixed in that release, and that #3558 (Kuzu) cannot be
+  reproduced because the installed package has no `graph_store` field or kuzu dependency at all.
+  Adds `CorruptionSignal` (`CONFIG_REJECTED`/`VECTOR_ZEROED`/`CLEAN`/`NOT_APPLICABLE`) and an
+  optional `mem0-direct` dependency group. Opt-in only, registered as `mem0_direct` in
+  `ADAPTER_REGISTRY`, not in `cli.ALL_BACKENDS`.
+  - `custom_instructions` passthrough constructor argument, threading a caller-supplied
+    fact-extraction prompt into `MemoryConfig` (mem0ai/mem0#4573's junk-retention finding;
+    `custom_instructions` is the real top-level key after mem0 renamed it away from
+    `custom_fact_extraction_prompt` in mem0ai/mem0#4740).
+  - Qdrant support (`vector_store_provider="qdrant"`) and a `query(threshold=...)` parameter
+    forwarded to `Memory.search()`, giving mem0ai/mem0#4297 (embedding-dimension mismatch,
+    confirmed still reachable in the installed package) and #4453 (search-threshold inversion,
+    confirmed fixed) a real construction-time surface to reach.
+  - Elasticsearch vector-store support (host/api_key/embedding-dims threading) plus a new
+    `filter_injection` eval and `FilterInjectionSignal` taxonomy (`FILTER_REJECTED`/
+    `FILTER_ACCEPTED_SAFELY`/`INJECTION_SUCCEEDED`/`NOT_APPLICABLE`), built on
+    `probe_raw_filter()`/`RawFilterProbeResult` (`adapters/base.py`), which submits an
+    adversarial filter dict directly to a backend's filter-building layer. Confirms the
+    installed `mem0ai==2.0.12` already carries the `_validate_filter()` fix from
+    mem0ai/mem0#5980.
+- Ed25519-signed receipts for `memtrust run` output (`src/memtrust/receipt.py`): canonical JSON
+  encoding, Ed25519 sign/verify, PEM keypair I/O, and three new CLI commands (`memtrust keygen`,
+  `memtrust run --sign <keyfile>`, `memtrust verify <receipt.json>`). Signing is opt-in and off
+  by default; unsigned `memtrust run` output is unchanged.
+- Crash-recovery eval (`evals/crash_recovery.py`, `crash_stress` capability flags in
+  `adapters/base.py`) modeling volcengine/OpenViking#2644's silent index-rebuild skip on
+  restart, with `CrashRecoverySignal` (`RECOVERED`/`INDEX_LOST_DATA_SURVIVED`/`DATA_LOST`/
+  `NOT_APPLICABLE`). Built at the harness level against a fake adapter; no adapter in this repo
+  has real process-lifecycle control over a live backend.
+- Embedding-drift/consistency eval (`evals/embedding_drift.py`) for volcengine/OpenViking#1523's
+  in-place vector overwrite during an embedder migration, with `EmbeddingDriftSignal`
+  (`EMBEDDING_DRIFT`/`CLEAN`/`NOT_APPLICABLE`).
+- Extraction-quality-at-scale eval (`evals/extraction_quality.py`) modeled on a real 32-day mem0
+  audit (mem0ai/mem0#4573, jamebobob: 97.8% of 10,134 stored entries were junk) plus a
+  documented feedback-loop case (one hallucinated memory re-extracted into 808 duplicate
+  stores). Adds `ExtractionQualitySignal` (`RETAINED_JUNK`/`REJECTED_JUNK`/`RETAINED_VALID`/
+  `LOST_VALID`/`FEEDBACK_LOOP_DUPLICATE`/`NO_UNEXPECTED_GROWTH`/`NOT_APPLICABLE`).
+- Scale/volume stress-testing eval (`evals/scale_stress.py`, `evals/scale_fixtures.py`,
+  `scale_stress`) for volcengine/OpenViking#2850 (BM25 search going silently empty at volume)
+  and getzep/graphiti#1275 (O(n) entity-resolution growth silently dropping old episodes), with
+  a deterministic large-scale synthetic corpus generator and a `--scale-stress-n-records` CLI
+  flag.
+- Migration-rollback-safety eval (`evals/migration_rollback.py`) verifying the concept behind
+  MemPalace's real rename-aside swap fix (mempalace/mempalace#1028, PR#935) for an unguarded
+  `shutil.rmtree()`-then-`shutil.move()` migration swap that could permanently lose data on a
+  partial failure. Adds `MigrationRollbackSignal` (`RESTORED`/`DATA_LOST`/`NOT_APPLICABLE`); no
+  real adapter sets the new capability flag since none has filesystem control over a live
+  `migrate()` call.
+- New crash-classification signals in `adapters/base.py`'s `CrashSignal`: `UNPACK_ERROR` and
+  `TYPE_COMPARISON_ERROR` for graphiti-core's `store()` exceptions (getzep/graphiti#836's
+  tuple-unpack `ValueError`, #920's tz-naive/tz-aware `TypeError`), and
+  `QUERY_SANITIZATION_ERROR` for FalkorDB RediSearch syntax errors in `query()`
+  (getzep/graphiti#1222, superseded by #1475; #1183, merged).
+- MemPalace degraded-retrieval signal: `RetrievalWarning` and `QueryResult.degraded_retrieval`
+  (`adapters/base.py`), surfacing MemPalace's real merged `search_memories()` fix
+  (mempalace/mempalace#1005) that degrades vector-query failures into a response carrying
+  warnings and partial results instead of raising -- a failure mode
+  `ConflictSignal.EMPTY_OR_LOST` could not see.
+- MemPalace `authored_at` ranking tie-breaker: `_RANKING_METADATA_KEYS` and query-result parsing
+  now recognize `authored_at` (top-level or nested under `metadata`) as a ranking-driving field,
+  matching MemPalace's real merged PR#1890/#1889.
+- Retrieval-graded vs. generated-answer accuracy disclosure in `docs/methodology.md`: memtrust's
+  LongMemEval/LoCoMo accuracy metric grades raw retrieved-record content directly, with no
+  answer-generation step, so it is not the same measurement as the official leaderboards'
+  generate-then-judge QA-accuracy scores (closes mempalace/mempalace#367).
+
+### Fixed
+
+- MemPalace adapter docstring no longer conflates "no API key required" with "no network
+  required" -- `mempalace mine .` can still fail offline because chromadb's default embedder
+  downloads its ONNX model on first use (mempalace/mempalace#524). LongMemEval now flags cases
+  where `top_k` already covers the whole corpus (`top_k_exceeds_corpus`), so a small haystack
+  can no longer read as artificially high recall.
+- Report table width corrected for 12-column output as new evals were added.
+- OpenViking adapter's `BackendAPIError` now reads the real HTTP response body
+  (`exc.response.text`) instead of only `httpx`'s status line, across `store`/`query`/`update`/
+  `delete`/`list_resource_paths`/`trigger_resync` -- volcengine/OpenViking#1227's server-side
+  Pydantic validation detail was previously swallowed down to a useless status-line-only
+  message.
+
+## [0.1.2] - 2026-07-16
+
+### Added
+
+- `npm/` -- an unpublished npm-distributable CLI wrapper (`npx memtrust ...`) for CI and agent
+  runners that have Node.js but not necessarily a Python toolchain. Six per-platform optional
+  packages (`@memtrust/darwin-arm64`, `darwin-x64`, `linux-arm64`, `linux-x64`, `win32-arm64`,
+  `win32-x64`) each bundle a genuine, SHA-256-verified copy of Astral's `uv` binary
+  (github.com/astral-sh/uv, dual-licensed MIT OR Apache-2.0), fetched from uv's own GitHub
+  release 0.11.28 at npm package-publish time via a `prepack` script, never at end-user install
+  time. The `memtrust` bin shim runs `uv tool run --from memtrust memtrust <args>`, which
+  bootstraps a Python interpreter and installs `memtrust` from PyPI on first use. Not yet
+  published to npm -- gated on a separate publish step. See the README's "npx (agent-native)"
+  section and `npm/` for the wrapper source and third-party attribution.
+
+### Added
+
+- `StoreResult.extraction_signal` (`ExtractionSignal`, `adapters/base.py`) -- flags when a `store()`
+  call completes without raising but the response carried no usable memory id, the exact
+  mem0ai/mem0#5178 "store() succeeded but silently extracted zero facts" shape. `Mem0Adapter`,
+  `Mem0SelfHostedAdapter`, and `Mem0DirectAdapter` all now set `FACTS_EXTRACTED`/`EMPTY_EXTRACTION`
+  instead of silently returning a normal-looking `StoreResult` with `memory_id=""`. See
+  docs/methodology.md's "ExtractionSignal and mem0ai/mem0#5178" section.
+
+### Fixed
+
+- PyPI `project.urls` now link each author to their GitHub profile instead of leaving the `Author` field email-less with no way to reach either maintainer
+
+## [0.1.0] - 2026-07-11
+
+Initial release.
+
+### Added
+
+- Shared `MemoryBackendAdapter` interface (`store()`/`query()`/`update()`) in
+  `src/memtrust/adapters/base.py`, plus `ConflictSignal` classification used by the
+  contradiction-detection eval.
+- Four backend adapters: MemPalace, Mem0, Zep/Graphiti, OpenViking. Each reads its configuration
+  from a single environment variable and raises `BackendNotConfiguredError` (never crashes) when
+  it's missing. Confidence level per adapter documented in `docs/methodology.md`.
+- Three eval runners: LongMemEval-style long-horizon recall, LoCoMo-style multi-session recall,
+  and memtrust's original multi-hop contradiction-detection eval (flagged / silently-overwrote /
+  served-stale / not-applicable).
+- LLM-judge scoring pipeline (`scoring/llm_judge.py`), model-configurable via environment
+  variables, with a no-crash `NOT_RUN` fallback when no judge API key is configured.
+- Cost tracker (`scoring/cost_tracker.py`) with a dated, approximate per-model pricing table.
+- `memtrust run` and `memtrust report` CLI commands.
+- Static leaderboard site (`leaderboard/index.html` + `leaderboard/data.json`) with a documented
+  schema, shipped as an example rather than fabricated live results.
+- Full test suite: 57 tests, 95% overall coverage, 100% on `adapters/base.py`,
+  `evals/contradiction.py`, `evals/longmemeval.py`, and `scoring/`. All tests run fully offline.
+- CI workflow: lint (ruff), type-check (mypy --strict), test (pytest + coverage across Python
+  3.11-3.13), security (pip-audit).
+- `docs/methodology.md`, `CONTRIBUTING.md`, `SECURITY.md`.
+
+### Known limitations (v0.1)
+
+- Adapters for MemPalace and OpenViking are built against best-effort interpretations of
+  documented product concepts, not a confirmed API reference -- see the confidence table in
+  `docs/methodology.md`. They should be verified against a live instance before their output is
+  treated as authoritative.
+- LongMemEval and LoCoMo eval runners ship against small, explicitly synthetic sample fixtures
+  matching each benchmark's real published schema, not the full public datasets.
+- No live benchmark numbers are published in the README -- running the harness against real
+  backends requires vendor API keys not available at the time of this release. See the README's
+  "Benchmarks" section for exactly what was and wasn't measured.

memtrust_cli-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,117 @@
+# Contributing
+
+The easiest and most useful way to contribute is adding a new backend adapter. This document
+covers that path in detail, plus the general workflow for everything else.
+
+## Adding a new backend adapter
+
+Every adapter implements `memtrust.adapters.base.MemoryBackendAdapter`, defined in
+`src/memtrust/adapters/base.py`. Read that file first; it is short and it is the actual contract,
+not a summary of one.
+
+### The interface
+
+```python
+class MemoryBackendAdapter(ABC):
+    name: str
+    env_var: str
+    supports_update: bool = True
+
+    def store(self, session_id: str, content: str, metadata: dict[str, str] | None = None) -> StoreResult: ...
+    def query(self, session_id: str, query: str, top_k: int = 5) -> QueryResult: ...
+    def update(self, session_id: str, memory_id: str, content: str) -> UpdateResult: ...
+```
+
+### Step by step
+
+1. **Pick your `env_var`.** Every adapter reads exactly one environment variable in `__init__` and
+   raises `BackendNotConfiguredError(self.name, self.env_var)` immediately if it's missing --
+   never on the first method call. This is what lets `memtrust run` report SKIPPED instead of
+   crashing when a backend isn't configured. If your backend genuinely needs no secret (like
+   MemPalace, which is local-first), gate on whatever configuration value it does need instead --
+   see `mempalace_adapter.py` for the pattern and `docs/methodology.md` for why.
+
+2. **Implement `store()`, `query()`, `update()`** against the vendor's real API. Wrap every
+   network/vendor failure in `BackendAPIError(self.name, detail)` -- never let a raw
+   `httpx.HTTPError` or vendor SDK exception escape the adapter. `query()` must return a
+   `ConflictSignal` (see below).
+
+3. **Report `ConflictSignal` honestly.** This is what the contradiction-detection eval reads.
+   - `FLAGGED` if your backend's response makes a contradiction visible (returns both old and new
+     values, an explicit conflict marker, an invalidation timestamp, etc.)
+   - `NOT_APPLICABLE` if you cannot determine this from the response -- do **not** guess `FLAGGED`
+     or `SILENT_OVERWRITE` to make a number look better. The contradiction eval independently
+     cross-checks your reported signal against the actual retrieved content (see
+     `evals/contradiction.py::classify_case`), so an inflated self-report gets caught and
+     downgraded, not rewarded.
+   - If your backend has no update/contradiction-relevant primitive at all, set
+     `supports_update = False` on the class. The eval then records `NOT_APPLICABLE` for every case
+     without calling your adapter, and that gap is shown explicitly in results tables -- it is
+     never silently dropped.
+
+4. **Document your confidence level.** At the top of your adapter file, write a docstring stating
+   what you verified against real vendor documentation and what you built as best-effort. Add a
+   row to the confidence table in `docs/methodology.md`. If you are not confident about an exact
+   endpoint path or method signature, say so in the code comment at the point of use, the same way
+   `mempalace_adapter.py` and `openviking_adapter.py` do. A wrong guess that's labeled is useful; a
+   wrong guess presented as confirmed is a bug that will mislead every leaderboard reader.
+
+5. **Register it.** Add your adapter class to `ADAPTER_REGISTRY` in
+   `src/memtrust/adapters/__init__.py`, keyed by the name users will pass to `--backends`.
+
+6. **Write tests.** Every adapter test mocks the HTTP layer (`pytest-httpx`) or injects a fake
+   object matching your adapter's expected vendor interface -- see `tests/test_adapters.py` for
+   the pattern used by all four existing adapters. No test may make a real network call. Cover at
+   minimum: `BackendNotConfiguredError` when the env var is missing, a successful `store`/`query`/
+   `update` round trip against a mocked response, and a `BackendAPIError` on a failed HTTP call.
+
+7. **Run the full check before opening a PR:**
+   ```bash
+   ruff check . && ruff format --check .
+   mypy --strict src/memtrust
+   pytest --cov=memtrust --cov-report=term-missing --cov-fail-under=80
+   pip-audit
+   ```
+
+### What a PR adding an adapter should include
+
+- The adapter file, following the pattern above.
+- Its registration in `ADAPTER_REGISTRY`.
+- Tests in `tests/test_adapters.py`.
+- A confidence-level entry in `docs/methodology.md`'s adapter table.
+- A one-line addition to the README's backend coverage table.
+
+## Adding or extending an eval
+
+The three eval families live in `src/memtrust/evals/`. Each is a plain function taking a
+configured `MemoryBackendAdapter` (and an `LLMJudge` for the two that need semantic grading) and
+returning a dataclass of results -- there is no plugin system to learn, just a function signature
+to match. See `evals/contradiction.py` for the simplest example (no LLM judge needed) and
+`evals/longmemeval.py` for the LLM-judged pattern.
+
+To extend the contradiction-detection eval's case set, add entries to
+`tests/fixtures/contradiction_cases.json`. Read `docs/methodology.md`'s note on how the
+`contradicting_fact` field should be phrased before adding a case -- a correction that restates
+the old value inside its own text can produce a misleading classification (this happened once
+during the initial build and is documented there in detail).
+
+To run the harness against the real, full LongMemEval or LoCoMo datasets instead of the bundled
+synthetic samples, see the "to run against the real dataset" note under each eval in
+`docs/methodology.md` -- both loaders accept a `dataset_path` argument already; only a format
+conversion (or a second loader function) is needed.
+
+## General workflow
+
+1. Fork, branch, make your change.
+2. Run the full check list above locally before pushing.
+3. Keep PRs scoped to one adapter, one eval change, or one clearly-described fix -- easier to
+   review, easier to bisect if something regresses.
+4. Every claim in a PR description about a score or benchmark number must be reproducible from a
+   command someone else can run. "I ran X and got Y" needs the X.
+
+## Code of conduct
+
+Be direct, be specific, assume good faith. Disagreement about a methodology choice is welcome and
+expected -- open an issue with the specific flaw, not a vague complaint. This project exists
+because vague, unverifiable claims about agent-memory backends are the problem it's trying to fix;
+holding contributions to the same standard is the point.

memtrust_cli-0.3.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.