mgp-gateway 0.1.1

Reference gateway for the Memory Governance Protocol

Reference Implementation

The runnable Python reference gateway for MGP. It maps the full protocol surface to pluggable adapters while validating every request and response against published JSON Schemas.

Key features:

• package metadata in the repository root pyproject.toml
• a CLI entrypoint through mgp-gateway
• configurable adapter, audit, auth, and tenant-binding settings
• operational endpoints for health, readiness, and version inspection

Requirements

• Python 3.11+
• dependencies from requirements.txt or pyproject.toml

Install

Repository Development Path

make install

Gateway Package Path

python3 -m pip install .

That install exposes the mgp-gateway command. Run it from the repository root so setuptools can pick up gateway/, audit/, policy/ (under reference/) and the sibling adapters/, schemas/, openapi/ trees referenced by the build configuration.

If you want the LanceDB adapter available in the installed gateway, install the optional extra:

python3 -m pip install ".[lancedb]"

Run

Source Path

make serve

Or manually:

cd reference
python3 -m gateway.app

Installed CLI Path

mgp-gateway --host 127.0.0.1 --port 8080

File Adapter With Persistent Storage

mgp-gateway \
  --adapter file \
  --file-storage-dir ./data \
  --audit-log ./audit.jsonl

PostgreSQL Adapter

mgp-gateway \
  --adapter postgres \
  --postgres-dsn postgresql://postgres:postgres@127.0.0.1:5432/mgp

LanceDB Adapter

mgp-gateway \
  --adapter lancedb \
  --lancedb-dir /tmp/mgp-lancedb \
  --lancedb-table memories

You also need an embedding configuration, for example:

export MGP_LANCEDB_EMBEDDING_PROVIDER=openrouter
export MGP_LANCEDB_EMBEDDING_MODEL=openai/text-embedding-3-small
export MGP_LANCEDB_EMBEDDING_API_KEY=...
export MGP_LANCEDB_EMBEDDING_BASE_URL=https://openrouter.ai/api/v1

Repository smoke test helper:

./.venv/bin/python scripts/smoke_lancedb_gateway.py

If you want to validate the source-path gateway instead of an installed mgp-gateway command:

./.venv/bin/python scripts/smoke_lancedb_gateway.py \
  --gateway-cmd "../.venv/bin/python -m gateway.__main__" \
  --gateway-cwd reference

Docker Path

docker compose up --build

See examples/deploy/reference-gateway/.env.example for a container-oriented environment file.

Configuration Surface

Important environment variables:

• MGP_ADAPTER
• MGP_AUDIT_LOG
• MGP_FILE_STORAGE_DIR
• MGP_GRAPH_DB_PATH
• MGP_POSTGRES_DSN
• MGP_LANCEDB_DIR
• MGP_LANCEDB_TABLE
• MGP_LANCEDB_ENABLE_HYBRID
• MGP_LANCEDB_EMBEDDING_PROVIDER
• MGP_LANCEDB_EMBEDDING_MODEL
• MGP_LANCEDB_EMBEDDING_API_KEY
• MGP_LANCEDB_EMBEDDING_BASE_URL
• MGP_LANCEDB_EMBEDDING_DIM
• MGP_GATEWAY_AUTH_MODE
• MGP_GATEWAY_API_KEY
• MGP_GATEWAY_BEARER_TOKEN
• MGP_GATEWAY_TENANT_HEADER
• MGP_GATEWAY_REQUIRE_TENANT_HEADER

Authentication modes:

• off
• api_key
• bearer

The auth and tenant-binding middleware is intentionally minimal, but it provides an official place to plug deployment-specific enforcement into the reference gateway.

What Is Included

• FastAPI gateway covering the current reference HTTP surface
• operational endpoints at /healthz, /readyz, and /version
• in-memory, file, graph, postgres, lancedb, and service-backed adapter routing
• minimal policy hook
• JSON Lines audit sink

The gateway validates operation-specific request and response payloads against the published schemas.

Current protocol endpoints:

• POST /mgp/initialize
• POST /mgp/write
• POST /mgp/search
• POST /mgp/get
• POST /mgp/update
• POST /mgp/expire
• POST /mgp/revoke
• POST /mgp/delete
• POST /mgp/purge
• POST /mgp/write/batch
• POST /mgp/export
• POST /mgp/import
• POST /mgp/sync
• POST /mgp/tasks/get
• POST /mgp/tasks/cancel
• GET /mgp/capabilities
• POST /mgp/audit/query

cURL Examples

Write

curl -X POST http://127.0.0.1:8080/mgp/write \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "req_write_1",
    "policy_context": {
      "actor_agent": "nanobot/main",
      "acting_for_subject": {"kind": "user", "id": "user_123"},
      "requested_action": "write",
      "tenant_id": "tenant_1"
    },
    "payload": {
      "memory": {
        "memory_id": "mem_1",
        "subject": {"kind": "user", "id": "user_123"},
        "scope": "user",
        "type": "preference",
        "content": {
          "statement": "User prefers dark mode.",
          "preference": "dark mode",
          "preference_key": "theme",
          "preference_value": "dark"
        },
        "source": {"kind": "human", "ref": "chat:1"},
        "sensitivity": "internal",
        "ttl_seconds": 3600,
        "created_at": "2026-03-17T12:00:00Z",
        "backend_ref": {"tenant_id": "tenant_1"},
        "extensions": {}
      }
    }
  }'

Search

curl -X POST http://127.0.0.1:8080/mgp/search \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "req_search_1",
    "policy_context": {
      "actor_agent": "nanobot/main",
      "acting_for_subject": {"kind": "user", "id": "user_123"},
      "requested_action": "search",
      "tenant_id": "tenant_1"
    },
    "payload": {
      "query": "dark",
      "limit": 10
    }
  }'

Get

curl -X POST http://127.0.0.1:8080/mgp/get \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "req_get_1",
    "policy_context": {
      "actor_agent": "nanobot/main",
      "acting_for_subject": {"kind": "user", "id": "user_123"},
      "requested_action": "read",
      "tenant_id": "tenant_1"
    },
    "payload": {
      "memory_id": "mem_1"
    }
  }'

Update

curl -X POST http://127.0.0.1:8080/mgp/update \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "req_update_1",
    "policy_context": {
      "actor_agent": "nanobot/main",
      "acting_for_subject": {"kind": "user", "id": "user_123"},
      "requested_action": "update",
      "tenant_id": "tenant_1"
    },
    "payload": {
      "memory_id": "mem_1",
      "patch": {
        "content": {
          "statement": "User prefers light mode.",
          "preference": "light mode",
          "preference_value": "light"
        },
        "updated_at": "2026-03-17T12:05:00Z"
      }
    }
  }'

Expire

curl -X POST http://127.0.0.1:8080/mgp/expire \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "req_expire_1",
    "policy_context": {
      "actor_agent": "nanobot/main",
      "acting_for_subject": {"kind": "user", "id": "user_123"},
      "requested_action": "expire",
      "tenant_id": "tenant_1"
    },
    "payload": {
      "memory_id": "mem_1",
      "expired_at": "2026-03-17T13:00:00Z",
      "reason": "manual_expire"
    }
  }'

Revoke

curl -X POST http://127.0.0.1:8080/mgp/revoke \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "req_revoke_1",
    "policy_context": {
      "actor_agent": "nanobot/main",
      "acting_for_subject": {"kind": "user", "id": "user_123"},
      "requested_action": "revoke",
      "tenant_id": "tenant_1"
    },
    "payload": {
      "memory_id": "mem_1",
      "revoked_at": "2026-03-17T13:05:00Z",
      "reason": "user_removed"
    }
  }'

Capabilities

curl http://127.0.0.1:8080/mgp/capabilities

Audit Query

curl -X POST http://127.0.0.1:8080/mgp/audit/query \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "req_audit_1",
    "policy_context": {
      "actor_agent": "nanobot/main",
      "acting_for_subject": {"kind": "user", "id": "user_123"},
      "requested_action": "read",
      "tenant_id": "tenant_1"
    },
    "payload": {
      "action": "write",
      "limit": 20
    }
  }'

Notes

• The in-memory adapter is the simplest path for local testing.
• The file adapter stores each memory object as a JSON file.
• Audit events are appended as JSON Lines and can be inspected directly.
• initialize, async tasking, and interop endpoints are implemented as optional protocol layers on top of the core governed-memory contract.