# Mem0-backed local staging integration — 3 November 2026

Trace was connected to a local memory service backed by **unmodified mem0ai 2.2.1 and embedded Qdrant 1.18.0**. This is an actual third-party memory engine, exposed through a small staging gateway; it is not Trace's ReferenceApp or its synthetic demo. The records are still synthetic. This is not a customer deployment or a test of hosted Mem0.

## Reproduce

Create an isolated environment for the optional staging application. Trace itself still has no mandatory third-party runtime dependency:

```text
python -m venv .mem0-venv
.mem0-venv\Scripts\python -m pip install mem0ai==2.2.1
.mem0-venv\Scripts\python scripts/mem0_staging.py --data-dir .mem0-staging
```

On macOS/Linux, use `.mem0-venv/bin/python` in place of the Windows executable path. In a second terminal, from the extracted project:

```text
python scripts/launch.py external-register --target mem0-local-221 --config examples/mem0-local.json
python scripts/launch.py external-plan --target mem0-local-221
python scripts/launch.py external-run --target mem0-local-221 --output reports/mem0-healthy.json
```

Stop the staging gateway with Ctrl+C when finished. It writes a final provenance receipt into its selected data directory. Do not expose this unauthenticated gateway beyond loopback. It accepts only fresh Trace synthetic namespace/ID formats and a bounded JSON body. Persistent Qdrant, Mem0 history and ID mappings live exclusively in the supplied staging directory; no production or existing user memory is connected.

## Actual upstream paths

Ingestion calls `Memory.add(..., infer=False)` and records the upstream-generated memory ID. Retrieval calls `Memory.search`. Inventory compares `Memory.get_all` IDs with fully paginated raw Qdrant scroll results. Deletion enumerates the namespace and calls `Memory.delete` only for metadata carrying the supplied Trace IDs. Mapping metadata supports cleanup when an ingest response is lost. No Mem0 storage, search or deletion implementation is patched.

The test uses a local 64-dimensional lexical embedding HTTP endpoint configured through Mem0's normal OpenAI-compatible embedder. These are deterministic feature hashes, not neural embeddings or a semantic accuracy benchmark. The client uses a non-secret placeholder key and connects only to loopback. LLM inference is disabled, telemetry is disabled before importing Mem0, and a Python audit hook blocks non-loopback connections. The optional BM25 model attempted a download and was blocked; Mem0 fell back without that encoder. No paid API/model account or cloud instance was used.

## Observed results

1. Normal Mem0-backed service: **PASS**, canary retrieved before deletion, absent afterward, unrelated control preserved, full two-second window observed, and active-memory cleanup complete.
2. Gateway started with `--fault skip-delete`: **FAIL**, surviving real Mem0/Qdrant records observed and cleanup correctly marked incomplete. This is deliberate fault injection in our gateway, **not a discovered upstream Mem0 bug**.
3. Saved the failure's contract. Restarted with normal gateway deletion, explicitly removed the fault's historical synthetic residuals, then replayed through a real official-SDK MCP client/server. Replay: **PASS** with cleanup complete. Comparison: **FAIL → PASS**, same target and contract hash.

All 148 installed Mem0 Python modules matched the downloaded PyPI wheel. Wheel SHA-256: `fe91bb91ac8926231993a4aa58df00a60c6c74c709e6a338fe399500776eef4d`. Mem0's memory module SHA-256: `f329ca4a17af1fbefb32ac10d4cc7ae7ddbdb7435a87eb74c30915cff98b8b7c`. The integration evidence JSON and integrity receipt are delivered beside the release archive.

## Exact coverage boundary

- `source_records` means Mem0-visible active memories. `vector_records` means raw Qdrant points. These are two views of the **same backing store**, not independent source and index databases.
- This configuration has no answer cache. `cache_records=0` describes an absent component; it does not establish cache-deletion coverage.
- Mem0 audit history and adapter ID mappings remain. After all three manual runs and cleanup, the audit history had 24 rows, and all 24 contained synthetic canary text. Active-memory PASS is **not erasure from audit history**.
- LLM extraction, graph/entity-memory inference, hosted Mem0, distributed consistency, pagination stress beyond the small test set, historical-chat deletion and physical erasure are outside this assessment.

The optional `tests/test_mem0_staging.py` launches the actual installed release in a separate process and tests both normal behavior and the explicitly injected gateway fault. It skips when Mem0 is not installed; install `mem0ai==2.2.1` in the separate environment to run it. Use that environment's Python with `-m pytest` to include these integration cases.

Upstream references: [Mem0 source](https://github.com/mem0ai/mem0), [exact PyPI release](https://pypi.org/project/mem0ai/2.2.1/). The local wheel and installed module comparisons, not an unpinned main branch, establish the executed source provenance.