SHShomeiGOVERNED MEMORY
Sign inGet API key
DOCS

Start with the local service, add memory, recall with source quotes, and verify governed-action receipts with a pinned public key.

Shomei Governed Memory — Developer Docs

Shomei Governed Memory is a memory layer for AI agents (Mem0-shaped API) whose differentiator is provable governance: every deletion, restriction, and subject-access operation emits a content-free, ed25519-signed receipt that anyone can verify offline, with a pinned signer key. Deletion is cryptographic erasure (destroy the per-row key) under your own key custody (BYOK), not graded decay.

Pages

Page What it covers
Quickstart Cold start: run the service, add/search/delete, verify a deletion receipt offline.
Python SDK reference The mochi_memory SDK — Memory (in-process) and RemoteMemory (HTTP client) verbs + signatures.
HTTP API reference The governed-memory service endpoints (/v1/...), request/response + receipt fields.
Entity Memory Graph demo seeding Populate real byte-grounded demo/test edge rows without model calls; ingest-lane and stub-vs-Bedrock parity boundary.
MCP integration The governed MCP server for Claude Desktop / Cursor / IDEs / agent frameworks.
Governance & verifiable receipts Deletion (Art.17), restriction (Art.18), access/export (Art.15), and the standalone offline verifier — the proof boundary.
Deployment & key custody Self-host / customer-VPC: per-row DEK envelope encryption, BYOK/KMS, env vars.

The shape of the system

The package is imported as mochi_memory. It exposes two client surfaces, plus a service, an MCP server, and a standalone verifier:

  • mochi_memory.Memory — the in-process engine. Construct it with Memory.from_profile(...) or Memory.from_env(). This is the full governance surface.
  • mochi_memory.RemoteMemory — a thin HTTP client for the service. Same data verbs, talking to a running deployment over /v1/....
  • The service (service/app.py) — a stdlib HTTP server. Default bind 127.0.0.1:8088 (SHOMEI_BIND_HOST / SHOMEI_PORT); https only when both SHOMEI_TLS_CERT and SHOMEI_TLS_KEY are set.
  • The MCP server (shomei_memory_mcp) — exposes 10 governed tools for Claude Desktop / Cursor / agent frameworks. It imports no engine code.
  • The offline verifier (shomei_memory_verify) — a tiny, one-dependency package (cryptography) that authenticates a signed receipt against a pinned public key, with zero engine dependencies. This is the part anyone can run.

Two surfaces, one note worth knowing up front

The two client surfaces now cover the same governance verbs; what remains different is the clock and the control plane:

  • Memory (in-process SDK) is the full engine facade, including a now= clock override on most verbs (in-process only).
  • RemoteMemory (HTTP client) wraps the data verbs — add, search, context, get, get_all, update, delete, verify, history, hold, release, forget, export, the lineage reads, the inference-evidence verbs, plus signer_key() and the static verify_receipt() — and the Art.18 verbs restrict() / release_restriction() (POST / DELETE /v1/memories/{id}/restrict; both admin-scoped). It also carries an admin/ops sub-client, RemoteMemory(...).admin, for the /v1/admin/* control plane (key issue/rotate/revoke, projects, invites, retention policy, plan, quota, health, metrics, and the destructive erase_tenant(confirm=<tenant-id>), which refuses client-side unless confirm matches the tenant bound to the API key). See the SDK reference.

Governance verbs and their articles

The governance operations map to the GDPR articles they implement:

  • Erasure (Art.17) — forget(user_id=...) for a whole subject, delete(memory_id) for one record. Both are cryptographic erasure: the per-row key is destroyed. Memories under legal hold are not erased immediately; they are restricted now and carry a durable obligation that auto-fires on hold release.
  • Restriction (Art.18) — restrict() / release_restriction() (on both Memory and RemoteMemory), backed by the POST / DELETE /v1/memories/{id}/restrict routes. Restricted data is held out of use, not deleted.
  • Access / export (Art.15) — export(user_id=...). The export bundle discloses the subject's live governed memories, already-erased evidence, the inference set, and — newly — the subject's derived-artifact set: content-free opaque artifact:<hex> ids, each carrying a recallable flag. The export's live_count includes those derived artifacts, and the derived ids are bound into the signed witness. (Derived-artifact lineage is on by default wherever a receipt signer is present, which is everywhere the hosted service and the SDK from_profile path run.)

A signed receipt is content-free: it proves the operator authored and did not tamper with the stated governance action. It does not assert anything about copies or backups that may live outside the system.

Honest scope (today)

Receipts are operator-verifiable today (Tier 2): a third party confirms the signature against a pinned key, proving the operator did not forge or tamper with the receipt. Independent hardware attestation of the runtime (TEE / Tier 3) is roadmap, not shipped. Say "verifiable receipts" and scope that claim to pinned-key receipt verification.

Key custody is the proof boundary. Deletion is cryptographic erasure of a per-row key, so the guarantee is only as strong as who holds the keys. Run with BYOK/KMS (SHOMEI_KEK_PROVIDER=aws-kms) in production; the file / inmemory providers are dev-only and the service refuses to start on them unless you explicitly opt in with SHOMEI_ALLOW_DEV_CUSTODY=1.

At rest, each tenant's payload and embedding cells are sealed with per-row DEK envelope encryption, not SQLCipher page-encryption — each tenant gets its own workspace KEK, and erasing a record destroys its row key.