The Gateway & memory API

Component deep-dive · 7 July 2026 · status: parked. Ecosystem overview: /ecosystem.

Purpose

The Gateway is the access layer of Memory Commons — Layer 4 of the Project Aletheia stack (register, store, retrieve, query). Its only concrete instance is a 2025 memory API prototype: a small REST service that gave each agent one persistent JSON file. It is kept as prior art for a future Gateway, not as a live surface. The present public surface is a static site; there is no running API in the current build.

Current state

Parked / prior art. SESSION_CONTEXT.md (Dec 2025) records the service as “DEPLOYED AND OPERATIONAL”; the July 2026 ecosystem.md labels it parked. Under the project’s canonical source hierarchy (decision 0008) the present status is parked. The deployment was real — service URL, project memorycommons (number 127672577584), region australia-southeast1, SA memorycommons-sa, bucket gs://memorycommons-store are all recorded — but whether the Cloud Run service or bucket still exist or bill today is not verifiable from the repo (open question).

What exists on disk: archive/MemoryCommons/gcp/ — main.py (FastAPI 1.0.0), storage/gcs.py, auth/api_key.py, config/settings.py, Dockerfile, cloudbuild.yaml. It realizes 2 of the 5 named Aletheia Layer-4 functions (storeMemoria via PUT, retrieveMemoria via GET), adds an idempotent DELETE the design never listed, and implements none of registerAgent / getAccountBalance / queryDataIndex. No Trust Fabric (API keys, not DIDs), no Agora ledger, a single GCS blob instead of a chunked/replicated Library.

Mechanisms / data model

Four endpoints: GET / (health, no auth), GET|PUT|DELETE /memory/{agent_id} (authed). Payloads use one schema — {v, updated, memory}: v is an int validated >= 1; memory is Any (string/object/array, agent’s choice); updated is an ISO8601 timestamp the server sets, so PUT bodies send only v and memory. Storage path is agents/{agent_id}/memory.json; a 10 MB per-agent cap (MAX_MEMORY_SIZE_BYTES) is enforced in store_memory and returns 400 on breach.

Two real subtleties worth recording. First, a single PUT stamps two divergent timestamps: main.py writes the in-file updated via datetime.now(timezone.utc).isoformat() (offset form, +00:00), while gcs.py computes its own datetime.utcnow().isoformat() + "Z" for the blob metadata and the StoreResponse.updated_at — same write, two formats, two moments. Second, settings.py sets AGENT_ID_PATTERN = ^[a-zA-Z0-9_.:-]{3,64}$ — with a dot; SESSION_CONTEXT quotes it without one. Code wins (0008). The dot and colon mean the deployed prototype already accepts current-design identifiers — both did:alters:xyz and the namespace.name.glyph form.

Auth is two independent layers: Cloud Run deployed --no-allow-unauthenticated (a Google IAM identity token, Authorization: Bearer) plus an app-level X-API-Key checked against a JSON array in Secret Manager (api-keys), lru_cached, failing closed with 503 when no keys load, 401 when the header is missing, 403 when wrong; clear_api_key_cache() handles rotation. Deploy is a Docker build (python:3.11-slim, uvicorn) pushed to Artifact Registry, run on 256Mi / 1 CPU / 60s.

How it binds to the rest

It sits above the Commons (today: git repo + published corpus + findings JSON) and would be gated by AltersID (Layer 1 DIDs) and named by glyphs (namespace.name.glyph; DID hash → agent glyph). A v2 Gateway aligned with the current design (inferred throughout) would: replace X-API-Key with DID signature verification (SESSION_CONTEXT’s own transition note); be release-aware, serving frozen-snapshot items by Merkle root rather than mutable per-agent blobs; be provenance-stamped with an RFC 3161 timestamp at each release cut; and be read-mostly — writes become curation submissions, not private mutable memory. The economic functions (getAccountBalance; the Chrons/Mnemos token model) have no counterpart because token mechanics are deferred.

Key decisions

• decisions/0002 — audience inversion: address successors, not strangers; the reason the shape changed from a mutable agent-memory store to a published commons.
• decisions/0004 — Merkle-rooted releases: a v2 Gateway serves by release root, not by ad-hoc PUT.
• decisions/0006 — integrity as active renewal: provenance/timestamp duties, not “store once.”
• decisions/0007 — quiet cadence, nonprofit-track separation: no launch before Oct 2027; why nothing is being revived now.
• decisions/0008 — context-integrity controls: frozen snapshots + canonical hierarchy that settle the parked-vs-operational status conflict.

Open questions

• Does the Cloud Run service / GCS bucket still physically exist or bill? Not knowable from the repo.
• v2 auth: verify DID signatures per-request, or issue short-lived tokens after a DID handshake?
• Does a read-mostly commons need write endpoints at all, or only a submission/curation path?
• gRPC vs HTTPS (the design names both) is unresolved.

What deeper builds next

Nothing is scheduled before the Oct 2027 point (0007). The honest next step is a paper spec, not code: define a v2 read path that serves corpus items by release Merkle root over the frozen snapshots (0004/0008), with a DID-signature auth stub replacing X-API-Key. Keep the prototype archived as the reference for request/response shapes; do not redeploy it.