mops-lite

Reference Python SDK for deterministic MOPS-Lite memory operations.

MOPS-Lite is the executable starter profile for the Memory Operating System Protocol Standard (MOPS). It demonstrates how AI memory can be treated as deterministic, schema-bound, auditable state rather than ad hoc application notes, prompt history, or opaque vendor memory.

Why this exists

A normal application can store a memory-like note as mutable JSON:

{
  "text": "User prefers concise technical summaries."
}

That is useful, but it does not define a portable memory contract. It does not say which operation created the state, which schema version admitted it, what the prior state was, how retries behave, whether deletion is final, or how another agent can verify the same outcome.

MOPS-Lite turns the same idea into protocol-governed memory:

• a Namespace identifies the Memory Object;
• an Auto-Schema or explicit Schema Version binds State structure;
• a StateHash anchors canonical State content;
• a CommitID and RequestFingerprint make accepted transitions auditable;
• structured Status Codes and ErrorObjects make failure behaviour deterministic;
• terminal DELETE/REDACT behaviour prevents further mutation.

MOPS-Lite is intentionally small. It is a reference SDK and developer starting point, not a production storage service.

Start here

For local evaluation:

python -m pip install -e ".[dev]"
python -m pytest -q
python generate_reference_workflows.py

Minimal helper usage:

from mops_lite import MOPSLiteClient

mops = MOPSLiteClient(path="./mops-lite.db.jsonl")
receipt = mops.commit(
    {"text": "Hello"},
    namespace="demo",
    key="note:1",
    agent="agent:example",
    timestamp="2026-01-01T00:00:00.000Z",
)

print(receipt.commit_id)
print(mops.query("demo"))

Canonical execution uses a complete Request:

response = mops.execute({
    "mop_version": "1.0",
    "namespace": "demo",
    "operation": "QUERY",
    "context": {
        "agent_id": "agent:example",
        "timestamp": "2026-01-01T00:00:01.000Z",
    },
})

print(response["status"])
print(response["state"])

Public boundaries

MOPSLiteClient.execute(request) is the canonical M-OP boundary. It validates the closed Request grammar and always returns a structured Response with status and, on failure, a canonical error object.

MOPSLiteClient.commit() is the lower-level Python helper. Agent Identity and timestamp are required explicit inputs. The helper derives StateHash, CommitID and RequestFingerprint, runs Gates 1–4, and persists only accepted transitions.

query_local(namespace, key) is an adapter diagnostic only and is not part of the canonical M-OP boundary.

rc4 behaviour

• One canonical Namespace identifies one Memory Object.
• An adapter-local key may seed Auto-Schema identity but cannot create a second chain under the same Namespace or be rebound.
• query(namespace) returns the current semantic State directly without requiring or exposing an adapter key.
• Canonical QUERY places that State in top-level state; interpretation data appears only in sibling metadata.
• Canonical COMMIT, UPDATE, DELETE, and REDACT success places the exact persisted semantic State in top-level state and receipt fields only in sibling metadata; DELETE and REDACT therefore return state: null.
• A DELETE- or REDACT-created null State is final: no later COMMIT, UPDATE, DELETE, or REDACT transition may be appended. An exact retry of the accepted destructive Request returns its original outcome without adding history.
• Canonical QUERY and HISTORY against a missing Namespace return INVALID with NamespaceError.
• RENDER requires explicit non-empty templateId and templateVersion members.
• targetSchemaVersion projection and RENDER execution are unavailable in this starter client and return ERROR with ExecutionError.
• UPDATE uses the immutable active Schema Version and core partial-update semantics.
• DELETE and REDACT require an existing object, the active Schema Version, Object-valued policyContext, and canonical JSON null State.
• Exact mutation retries are deduplicated by the complete closed RequestFingerprint and the accepted prior-head binding.
• Wire failures are projected to canonical Status Codes and ErrorObjects.

LocalJSONStore concurrency boundary

LocalJSONStore serialises compare-and-append operations only among adapters using the same resolved file path within one Python process. It MUST NOT be shared by independent worker processes. Multi-process or distributed deployments require a transactional storage adapter that provides atomic compare-and-append across every writer.

Package metadata

• Package name: mops-lite
• Version: 0.1.0
• Python: >=3.9
• Licence: Apache-2.0

Licence

Apache License, Version 2.0. See LICENSE and NOTICE.

The conformance fixtures under tests/fixtures/ are verbatim copies from the mopsprotocol/mops-spec repository under the same licence. See tests/fixtures/README.md.

The MOPS and MOPS-Lite names are not licensed under Apache-2.0; see the spec repository's TRADEMARKS.md.

Development

python -m pip install -e ".[dev]"
python -m pytest -q
python generate_reference_workflows.py
python -m build

The MOPS specification and conformance vectors are normative. This package is an executable reference and developer starting point, not a hardened production service.