The open protocol for governed memory in AI systems.
MGP standardizes how AI runtimes write, recall, govern, and audit persistent memory across heterogeneous backends. Think of it as a unified contract layer — your agent talks to one protocol, and any compliant memory backend just works.
Current protocol version: v0.1.1
MCP standardizes tools and resources. MGP standardizes governed memory. They are peer protocols — complementary, not competing.
flowchart LR
subgraph runtime ["🤖 Agent Runtime"]
sdk[Python SDK]
sidecar[Sidecar Bridge]
end
subgraph gateway ["🔀 MGP Gateway"]
api[API Layer]
policy[Policy Hook]
audit[Audit Sink]
router[Adapter Router]
end
subgraph adapters ["🧩 Adapters"]
mem[In-Memory]
file[File]
graphAdapter[Graph]
pg[PostgreSQL]
ob[OceanBase]
lance[LanceDB]
ext["Mem0 / Zep"]
end
sdk --> api
sidecar --> api
api --> policy
api --> audit
api --> router
router --> mem
router --> file
router --> graphAdapter
router --> pg
router --> ob
router --> lance
router --> ext
| 📐 One Protocol, Any Backend | Write once, connect to in-memory, file, graph, relational, vector, or managed memory services |
| 🔒 Governance Built-In | Every request carries policy context — who acts, for whom, under what constraints |
| 🔄 Full Lifecycle | Write → Search → Get → Update → Expire → Revoke → Delete → Purge — each with distinct semantics |
| 📋 Audit Trail | Every state transition is recorded. Query the audit log through the protocol itself |
| 🧩 Pluggable Adapters | Ship your own adapter or pick from 8 reference implementations |
| 🤝 Peer to MCP | Complements MCP — use MCP for tools, MGP for memory, both in the same runtime |
| ✅ Compliance Suite | Machine-verifiable conformance profiles: Core, Lifecycle, Interop, ExternalService |
| 📄 Schema-Driven | 60+ JSON Schemas + OpenAPI spec — validate everything, guess nothing |
Get a governed memory gateway running in under 2 minutes:
git clone https://github.com/hkuds/MGP.git
cd MGP
make install # creates .venv/ and installs everything
make serve # starts the gateway at http://127.0.0.1:8080Verify it's running:
curl http://127.0.0.1:8080/mgp/capabilitiesWrite your first memory:
curl -X POST http://127.0.0.1:8080/mgp/write \
-H "Content-Type: application/json" \
-d '{
"request_id": "req_001",
"policy_context": {
"actor_agent": "my-agent/v1",
"acting_for_subject": {"kind": "user", "id": "user_alice"},
"requested_action": "write",
"tenant_id": "my_tenant"
},
"payload": {
"memory": {
"memory_id": "mem_001",
"subject": {"kind": "user", "id": "user_alice"},
"scope": "user",
"type": "preference",
"content": {
"statement": "User prefers dark mode.",
"preference_key": "theme",
"preference_value": "dark"
},
"source": {"kind": "human", "ref": "chat:1"},
"sensitivity": "internal",
"created_at": "2026-01-01T00:00:00Z",
"backend_ref": {"tenant_id": "my_tenant"},
"extensions": {}
}
}
}'Search it back:
curl -X POST http://127.0.0.1:8080/mgp/search \
-H "Content-Type: application/json" \
-d '{
"request_id": "req_002",
"policy_context": {
"actor_agent": "my-agent/v1",
"acting_for_subject": {"kind": "user", "id": "user_alice"},
"requested_action": "search",
"tenant_id": "my_tenant"
},
"payload": {
"query": "dark mode",
"limit": 10
}
}'Or use the Python SDK:
from mgp_client import MGPClient, PolicyContextBuilder, SearchQuery
ctx = PolicyContextBuilder(
actor_agent="my-agent/v1",
subject_id="user_alice",
tenant_id="my_tenant",
)
with MGPClient("http://127.0.0.1:8080") as client:
client.write_memory(
ctx.build("write"),
{
"memory_id": "mem_001",
"subject": {"kind": "user", "id": "user_alice"},
"scope": "user",
"type": "preference",
"content": {"statement": "User prefers dark mode."},
"source": {"kind": "human", "ref": "chat:1"},
"created_at": "2026-01-01T00:00:00Z",
"backend_ref": {"tenant_id": "my_tenant"},
"extensions": {},
},
)
results = client.search_memory(
ctx.build("search"),
SearchQuery(query="dark mode", limit=10),
)
for item in results.data.get("results", []):
print(item["consumable_text"])📖 For the complete walkthrough — including update, expire, and audit — see the Getting Started Guide.
MGP/
├── spec/ # 📜 Protocol semantics — the source of truth
├── schemas/ # 📐 60+ JSON Schemas for all protocol objects
├── openapi/ # 🌐 OpenAPI definition (HTTP binding)
├── reference/ # ⚙️ Python reference gateway (FastAPI)
├── adapters/ # 🧩 Backend adapter implementations
├── sdk/python/ # 📦 MGPClient + AsyncMGPClient + helpers
├── compliance/ # ✅ Executable conformance test suite
├── integrations/ # 🔌 Runtime bridges (Nanobot, LangGraph, minimal)
├── examples/ # 💡 Runnable end-to-end demos
└── docs/ # 📖 MkDocs documentation site (EN + ZH)
| Adapter | Backend | Profile | Use Case |
|---|---|---|---|
| In-Memory | Process memory | Reference | Testing & development |
| File | JSON files | Reference | File-native workflows |
| Graph | SQLite | Reference | Relationship semantics |
| PostgreSQL | PostgreSQL | Production | Relational backends |
| OceanBase | OceanBase / oceanbase/seekdb |
Production | MySQL-compatible relational backend |
| LanceDB | LanceDB | Production | Vector / hybrid search |
| Mem0 | Mem0 service | External | Managed memory |
| Zep | Zep service | External | Graph-native memory |
Reference adapters are for protocol verification and learning. For production, use the PostgreSQL / OceanBase / LanceDB baselines or build your own.
| Dimension | MCP | MGP |
|---|---|---|
| Focus | Tools & resource connectivity | Governed persistent memory |
| Protocol surface | Tool invocation, resource discovery | Memory CRUD, policy, audit, lifecycle |
| Data model | Tools, prompts, resources | Memory objects, candidates, recall intents |
| Governance | Not in scope | Policy context, access control, retention |
| Audit | Not in scope | Built-in audit trail & lineage |
| Relationship | Peer protocol | Peer protocol |
One-line heuristic: Use MCP for action, use MGP for memory.
Both can coexist in the same runtime — call a calendar tool via MCP, remember the user's scheduling preferences via MGP.
📖 Deep dive: MGP vs MCP
Choose your path:
| You are... | Start here |
|---|---|
| 🛠️ Runtime developer | Getting Started → Python SDK → Sidecar Integration |
| 🏢 Platform engineer | Reference Implementation → Deployment Guide → Security Baseline |
| 📐 Protocol implementer | Protocol Reference → Schema Reference → Spec Index |
| 🧩 Adapter author | Adapter Guide → Adapters Overview → Compliance Suite |
Core operations:
WriteMemory · SearchMemory · GetMemory · UpdateMemory
ExpireMemory · RevokeMemory · DeleteMemory · PurgeMemory
BatchWrite · AuditQuery
Discovery & lifecycle:
GET /mgp/capabilities · POST /mgp/initialize
Export · Import · Sync · Task polling & cancellation
Operational:
GET /healthz · GET /readyz · GET /version
We welcome contributions! See CONTRIBUTING.md for the development workflow.
make install # set up the dev environment
make lint # contract validation + code quality
make test-all # compliance suite on all reference adapters
make docs-build # verify documentation buildsMGP is released under the MIT License.