Trust primitives for AI agent memory. A portable wire spec, two reference servers, and a 17-case conformance suite for the audit and policy layer that AI memory systems are missing today.

Why this exists

Today's AI memory libraries (mem0, Letta, graphiti, txtai, ...) are excellent at storing memories. They were not designed to prove what they did with those memories - what was deleted, when, by whom, under what policy. As AI agents move into regulated environments (GDPR Art. 17 erasure, SOC 2 Type 2 audits, HIPAA, the EU AI Act) that gap becomes load-bearing.

MOSAIC defines four trust primitives every memory substrate should expose, and ships them as an open HTTP wire spec:

1. Cryptographic deletion receipts - every forget returns a signed, chain-linked receipt that an external auditor can verify without trusting the substrate.
2. Default-DENY policy DSL - a small contract language with glob subjects, priority resolution, and DENY-wins-tie semantics.
3. Bi-temporal validity - every fact carries valid_at, invalid_at, and expired_at so historical state can be queried.
4. Tamper-evident audit chain - Merkle-linked deletion log, per-tenant, replayable.

The spec is intentionally minimal. It does not compete with the storage / retrieval / extraction layers of the upstream libraries - it sits above them.

What's in this repo

mosaic/
├── agentic/                   Python reference substrate + HTTP server
│   ├── memory/store.py        SQLite + bi-temporal columns
│   ├── memory/tenants.py      per-tenant store factory
│   ├── mosaic_forgetting.py   HMAC-Merkle deletion receipt chain
│   ├── mosaic_contracts.py    default-DENY policy engine
│   └── memory_api.py          Python reference HTTP server
│
├── mosaic-ts/                 TypeScript reference HTTP server
│
├── conformance/               the spec + the runner
│   ├── profiles/              `mosaic-memory-v1` (11 required + 6 optional)
│   ├── cases/                 17 JSON-driven case files
│   ├── runner/                stateless HTTP runner
│   └── render_leaderboard.py  auto-renders the matrix
│
├── adapters/                  HTTP wrappers around real upstream packages
│   ├── mem0_real.py           wraps mem0ai
│   ├── txtai_real.py          wraps txtai
│   ├── letta_real.py          proxies to live Letta server
│   └── graphiti_real.py       Cypher direct against live Neo4j
│
├── integrations/acpx-flow-memory/   npm package - 4 acpx flow primitives
├── tests/                            7 pytest files
├── demo/index.html                   static browser demo
└── LEADERBOARD.md / CHANGELOG.md / WHAT_REAL_NUMBERS_MEAN.md

Conformance results

Both reference servers score full marks on the mosaic-memory-v1 profile. Real upstream packages are scored against the same suite, with no shimming - each adapter is a thin HTTP wrapper that calls the actual library or service.

The 6 cases none of the upstream substrates currently pass are the trust primitives: signed receipts, chain verification, default-DENY, DENY-wins-tie, case + whitespace normalisation. These are the behaviours an enterprise procurement / compliance review typically asks for.

graphiti is the strongest non-MOSAIC substrate - its bi-temporal edge model already covers the time-axis, leaving only the trust layer above it. graphiti + MOSAIC compose naturally.

See LEADERBOARD.md and WHAT_REAL_NUMBERS_MEAN.md for per-case breakdowns and reproduction notes.

Quick start

Run the reference server (Python)

pip install -e .
python -m agentic.memory_api --port 5151

Run the reference server (TypeScript / Node, no build needed)

node mosaic-ts/server.js --port 5119

Score a substrate against the conformance suite

python -m conformance.runner \
    --include-optional \
    --url http://127.0.0.1:5151 \
    --report results/python-ref.json

Render the leaderboard from a directory of reports

python -m conformance.render_leaderboard \
    --reports-dir results --out LEADERBOARD_AUTO.md

Scoring real upstream substrates

# Infra
docker run -d --name neo4j -p 7687:7687 -p 7474:7474 \
    -e NEO4J_AUTH=neo4j/mosaic-test-password neo4j:5
docker run -d --name letta -p 8283:8283 letta/letta:latest

# Python deps
pip install -e ".[adapters]"

# Adapters (each on its own port)
python -m adapters.mem0_real     --port 8811 &
python -m adapters.txtai_real    --port 8812 &
python -m adapters.letta_real    --port 8813 &
python -m adapters.graphiti_real --port 8814 &

# Run conformance against each
for p in 8811 8812 8813 8814; do
  python -m conformance.runner --include-optional \
    --url http://127.0.0.1:$p \
    --report results/leaderboard-port$p.json
done

Tests

pip install -e ".[dev]"
pytest tests/ -v

Covers the substrate primitives, the bi-temporal store, contract fuzzing, cross-language signature parity (Python ⇔ TypeScript byte equality), differential conformance, the chain-concurrency stress test, and the acpx integration.

Roadmap

• More upstream substrates wrapped (zep, cognee, langmem, MIRIX).
• A reference Go and Rust implementation of the wire spec.
• Hosted leaderboard service so substrates can self-submit results.
• An optional v2 profile expanding contract grammar (RBAC roles, rate-limited DENY) and adding pluggable signature schemes.

Contributing

PRs welcome. Particularly interested in:

• Adapters wrapping additional upstream memory libraries.
• New conformance cases that surface real behavioural divergence.
• Bug-finding via cross-implementation runs (this is how the v0.4.1 Python /v0/forget table-name bug was caught).

Open an issue to discuss before large changes.

License

MIT. See LICENSE.

Contact

Open an issue, or reach the author via @upcomingsimplecoder.