Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mnemom.ai/llms.txt

Use this file to discover all available pages before exploring further.

Mnemom’s two cards — alignment and protection — are first-class API resources. Every card, at every scope, has the same URL shape: 
/v1/<resource>/<scope>/<scope_id>[/<verb>]
where <resource> is one of alignment or protection, <scope> is one of platform, org, team, agent, and <scope_id> is a stable identifier (the literal string default for platform scope). This page is the customer-facing orientation to the canonical URL surface, the four scopes, and the migration from the earlier scope-specific paths.

​
Resources × Scope × Verb

Mnemom uses the Resources × Scope × Verb idiom — the same one Stripe uses for its Resource nouns, Kubernetes uses for spec/status, AWS IAM uses for Policy/Effective, and Linear uses for Settings. There are two resources, four scopes, and a small fixed set of verbs. 
GET    /v1/alignment/agent/smolt-512448e7                  # this layer's spec
PUT    /v1/alignment/agent/smolt-512448e7                  # full replace
DELETE /v1/alignment/org/polis-mnemom-v1                   # clear this layer
POST   /v1/alignment/org/polis-mnemom-v1/preview-compose   # dry-run composer
The same shape works for protection: 
GET  /v1/protection/team/team-finance
PUT  /v1/protection/platform/default
POST /v1/protection/agent/smolt-512448e7/preview-compose
A single mental model covers the entire surface. Authoring tools, CI Actions, and SDKs build one routing table and address every scope through it.

​
The four scopes

Cards compose across scopes in this order — every later layer can tighten what earlier layers declared, never loosen.
Scopescope_idWhat it declaresWho edits it
platformdefault (singleton)Mnemom’s universal defaults — the catalog floor that ships with every customer.Mnemom platform team.
orgThe org slug, e.g. polis-mnemom-v1Org-wide values, modes, and trusted sources — applied to every agent in the org.Org owner / admin.
teamThe team slugTeam-wide overlays — finance teams tighten financial primitives, growth teams loosen creative constraints, and so on.Team admin (falls through to org admin).
agentThe agent IDPer-agent specialization — a single agent’s value emphasis, capabilities, and protection thresholds.Agent owner (falls through to team / org admin).
Composition runs platform → org → team → agent. The composed result is the agent’s effective card, surfaced (in Wave 2 of cards-as-primitive) at /v1/<resource>/<scope>/<scope_id>/effective.

​
Naming retirement — card leaves the API surface

Before this canonicalization, the same concept lived under four different nouns: alignment-card, alignment-template, platform-card/alignment, and bare card. That was unteachable. The reshape:
LayerOldNew
API resourcealignment-card, alignment-template, platform-card/alignmentalignment
API resourceprotection-card, protection-template, platform-card/protectionprotection
Source file (devs author)“card YAML”manifest (Kubernetes / Helm / Vercel idiom)
Composed view”canonical card”effective sub-resource
Internal storage tablesunchangedunchanged
The word card survives in conversation and in the docs you’re reading — it’s a useful piece of shorthand. It just doesn’t appear in URLs any more. The API spec uses alignment and protection as the resource nouns.

​
Legacy URL migration

Every legacy URL returns HTTP 308 Permanent Redirect (RFC 7538) to its canonical equivalent. RFC 7538 §3 guarantees that compliant clients preserve the original method and body across the redirect — so a PUT against a legacy URL becomes a PUT against the canonical URL with the same body, automatically. Every 308 carries three migration headers:
  • Location: the canonical URL (with the original query string preserved).
  • Deprecation: true (RFC 8594) — flags the resource as deprecated for intermediaries and observability tooling.
  • Sunset: Fri, 15 Jan 2027 00:00:00 GMT — the date after which the legacy URL stops redirecting and returns 410 Gone. Roughly aligned with Mnemom Phase 5 GA.
  • Link: <https://docs.mnemom.ai/concepts/cards-as-resources>; rel="deprecation"; type="text/html" (RFC 5988) — points you here.

​
Migration table

LegacyCanonical
GET /v1/agents/{id}/alignment-cardGET /v1/alignment/agent/{id}
PUT /v1/agents/{id}/alignment-cardPUT /v1/alignment/agent/{id}
POST /v1/agents/{id}/alignment-card/preview-composePOST /v1/alignment/agent/{id}/preview-compose
GET /v1/agents/{id}/protection-cardGET /v1/protection/agent/{id}
PUT /v1/agents/{id}/protection-cardPUT /v1/protection/agent/{id}
POST /v1/agents/{id}/protection-card/preview-composePOST /v1/protection/agent/{id}/preview-compose
GET /v1/orgs/{id}/alignment-templateGET /v1/alignment/org/{id}
PUT /v1/orgs/{id}/alignment-templatePUT /v1/alignment/org/{id}
DELETE /v1/orgs/{id}/alignment-templateDELETE /v1/alignment/org/{id}
POST /v1/orgs/{id}/alignment-template/preview-composePOST /v1/alignment/org/{id}/preview-compose
GET /v1/orgs/{id}/protection-templateGET /v1/protection/org/{id}
PUT /v1/orgs/{id}/protection-templatePUT /v1/protection/org/{id}
DELETE /v1/orgs/{id}/protection-templateDELETE /v1/protection/org/{id}
POST /v1/orgs/{id}/protection-template/preview-composePOST /v1/protection/org/{id}/preview-compose
GET /v1/teams/{id}/alignment-templateGET /v1/alignment/team/{id}
PUT /v1/teams/{id}/alignment-templatePUT /v1/alignment/team/{id}
DELETE /v1/teams/{id}/alignment-templateDELETE /v1/alignment/team/{id}
POST /v1/teams/{id}/alignment-template/preview-composePOST /v1/alignment/team/{id}/preview-compose
GET /v1/teams/{id}/protection-templateGET /v1/protection/team/{id}
PUT /v1/teams/{id}/protection-templatePUT /v1/protection/team/{id}
DELETE /v1/teams/{id}/protection-templateDELETE /v1/protection/team/{id}
POST /v1/teams/{id}/protection-template/preview-composePOST /v1/protection/team/{id}/preview-compose
GET /v1/admin/platform-card/alignmentGET /v1/alignment/platform/default
PUT /v1/admin/platform-card/alignmentPUT /v1/alignment/platform/default
POST /v1/admin/platform-card/alignment/preview-composePOST /v1/alignment/platform/default/preview-compose
GET /v1/admin/platform-card/protectionGET /v1/protection/platform/default
PUT /v1/admin/platform-card/protectionPUT /v1/protection/platform/default
POST /v1/admin/platform-card/protection/preview-composePOST /v1/protection/platform/default/preview-compose

​
Client compatibility

Modern HTTP clients follow 308 with method and body preservation by default:
  • curl 7.46 and later — preserves method on 308. Pass -L to follow redirects.
  • fetch / node-fetch / undici — preserve method on 308 by default.
  • Python requests 2.7 and later — preserves method on 308.
  • Python httpx — preserves method on 308.
  • Go net/http since 1.8 — preserves method on 308.
  • axios — preserves method on 308.
Older clients (curl ≤ 7.45, Python requests ≤ 2.6) may downgrade POST to GET on 308 — those vintages predate RFC 7538 strict-308 compliance. Upgrade the client or call the canonical URL directly.

​
Worked example

A common Polis-side flow before canonicalization: 
curl -X PUT https://api.mnemom.ai/v1/agents/smolt-512448e7/alignment-card \
  -H "X-Mnemom-Api-Key: $KEY" \
  -H "Content-Type: application/yaml" \
  -d @manifest.yaml
The same call works against the legacy URL today — it returns a 308 to the canonical URL and the client re-issues the PUT. The client doesn’t need to change to keep working. To stop the round-trip, point the call at the canonical URL directly: 
curl -X PUT https://api.mnemom.ai/v1/alignment/agent/smolt-512448e7 \
  -H "X-Mnemom-Api-Key: $KEY" \
  -H "Content-Type: application/yaml" \
  -d @manifest.yaml
That’s the only change — one URL, one method, same body.

​
What this unlocks

This canonicalization is the foundation for the rest of the cards-as-primitive surface:
  • GET /v1/<resource>/<scope>/<scope_id>/effective — the composed view, with per-key provenance back to whichever scope authored each field.
  • GET /v1/agents/{id}/state — the runtime composite: one call returns alignment + protection + capabilities with full tool definitions.
  • Sub-resource verbs — PUT /v1/alignment/<scope>/<scope_id>/<primitive> to set just one primitive (values, conscience, capabilities, etc.) without replacing the whole spec.
  • AI-forward verbs — scaffold, explain, simulate, import — natural-language and probing UX that all bind on the same root namespace.
Each builds on the same Resources × Scope × Verb shape this page describes.

​
See also