@mnemom/sdk

TypeScript SDK for the Mnemom platform — wraps the locked Phase 4/5 API surface (alignment + protection cards, AI helpers, AAP attestation, transparency log, SSE + webhook subscriptions).

Architecture: ADR-SDK-001 records the v1 design — namespace tree, auth tiers, the single request chokepoint, canonical error envelope, Ed25519/JWKS verification, versioning + publish policy, the verify-sdk conformance contract, and the no-second-tenant stance.

Status: Phase 6 day-1 (0.1.0). Day-2 (agent.protection, agent.tools, agent.observability, agent.attestation, agent.a2a, mnemom.transparency, org.coherence, JWKS, OTEL bridge) lands in PR 4; npm-publish + provenance + 1.0.0 cut in PR 5.

Installation

npm install @mnemom/sdk @mnemom/policy-engine

@mnemom/policy-engine is a peer-dep for shared types (catalog).

Quick start

import { Mnemom } from "@mnemom/sdk";

const mnemom = new Mnemom({ apiKey: process.env.MNEMOM_API_KEY });

// Read the live composed alignment card for an agent.
const effective = await mnemom.agents.get("themis").alignment.get_current();
console.log(effective.card, effective.etag);

// Preview a draft against org + team + platform layers.
const draft = { agent_id: "themis", policy: { thoughtful: true } };
const preview = await mnemom.agents.get("themis").alignment.preview_compose(draft);

// Commit. Auto-generates Idempotency-Key; pass `if_match` for optimistic concurrency.
const result = await mnemom.agents
  .get("themis")
  .alignment.commit(preview, { if_match: effective.etag });

// Catalog discovery (read-only, in-memory TTL cache).
const values = await mnemom.catalog.list_values();

// Release in-memory credentials for ephemeral worker contexts.
mnemom.destroy();

Auth strategies

Pass exactly one of apiKey, oauthToken, or supabaseJwt:

new Mnemom({ apiKey: "mnm_..." });
new Mnemom({ oauthToken: async () => fetchObo() });
new Mnemom({ supabaseJwt: async () => session.access_token });

Alignment ops are owner-scoped. agents.get(id).alignment.* (get_current / preview_compose / commit) require an authenticated owner session — an org-owner user JWT via supabaseJwt (or oauthToken), not a bare agent apiKey. Composing/committing an agent's effective alignment card is a privileged owner operation, not a runtime data-plane call; an agent key alone returns a MnemomError with effectiveStatus 401/403. (The apiKey example above illustrates client construction — use an owner-session strategy for the alignment calls specifically.)

Multi-instance pattern (baseUrl separates staging vs prod; not multi-tenant):

const prod = new Mnemom({ apiKey: process.env.PROD_KEY });
const staging = new Mnemom({
  apiKey: process.env.STAGING_KEY,
  baseUrl: "https://staging.mnemom.ai",
});

Testing surface (no network)

import { createMockClient } from "@mnemom/sdk/testing";

const mock = createMockClient({
  agents: {
    themis: { effective: { agent_id: "themis", v: 1 }, etag: '"sha256:fixture"' },
  },
});

const result = await mock.agents.get("themis").alignment.get_current();

The mock implements the same shape as the real client — swap Mnemom for MockMnemom in customer tests.

What ships in day-1 (this PR)

• Mnemom root client with three auth strategies (apiKey / oauthToken / supabaseJwt)
• mnemom.agents.get(id) → Agent navigation handle
• agent.alignment.{get_current, preview_compose, commit} against the Phase 4 cards endpoints, with ETag + If-Match + Idempotency-Key plumbing
• mnemom.catalog.{list_values, get, get_pass2} with in-memory TTL cache
• Fetch wrapper: exponential-backoff retry with jitter, Retry-After honoring, X-Mnemom-Retry-Hint: do-not-retry bail-out, configurable concurrency cap (default 10), per-request timeout (default 30 s), telemetry hook
• Token-redaction pass on every thrown error message (sk-, sk-ant-, mnm_, Bearer ..., JWT shapes → [redacted])
• mnemom.destroy() swaps the signer for a tombstoned strategy so the in-memory credential is GC-eligible (Security S1)
• @mnemom/sdk/testing subpath: createMockClient(fixtures) for customer unit tests
• Structured error hierarchy: MnemomError ← ValidationError, AuthError, RateLimitError, NetworkError, AttestationError, TransparencyError, CoherenceError
• Care-framing audit, both runtime (per error) + static (regex scan over src/**/*.ts) — no Blocked / Denied / Required / Forbidden / Violation / Must / Prohibited / Not Allowed / Cannot in thrown messages

What lands in subsequent Phase 6 PRs

• Day 2 (PR 4): agent.protection, agent.tools, agent.observability (SSE + webhook), agent.attestation, agent.a2a, mnemom.transparency, org.coherence, JWKS verifier with TOFU pinning, OTEL telemetry bridge.
• Publish (PR 5): release-please + npm provenance + @mnemom/[email protected] cut.

Development

# In-repo dev: build policy-engine first so the file: dep resolves.
(cd ../policy-engine && npm ci && npm run build)
npm ci
npm run build       # tsc → dist/
npm test            # vitest run
npm run typecheck   # tsc --noEmit

License

Apache-2.0