@saihm/mcp-server-pro

Production thin-client for SAIHM non-custodial memory.

SaihmProClient seals every cell on the client with @saihm/client-pro, then POSTs the resulting ciphertext to the blind SAIHM /mcp endpoint. The endpoint stores, anchors, shares, and meters over ciphertext — it never holds your keys and cannot read your memory. Your master secret, key-encryption key, and plaintext never leave this process.

• Seal before send — remember encrypts client-side; recall decrypts client-side.
• Post-quantum — ML-DSA-65 identity/signing, ML-KEM-768 authenticated sharing (via @saihm/client-pro).
• Same transport as the standards client — POST {method, params} + Authorization: Bearer <JWT>; the endpoint binds your tenant from the JWT. HTTPS-only (loopback http permitted for local dev).
• Crypto-shred erasure — forget destroys the endpoint-side wrapped DEK, rendering the cell undecryptable (GDPR Art. 17).

Key loss is unrecoverable by design. If you lose your master secret you lose your KEK, and no one — including SAIHM — can open your cells. Back it up securely.

See it run

• Live cross-model demos — offline, ~1 min each, no account: https://citw2.github.io/saihm-demos/. Ground a memory you own in Claude, GPT, DeepSeek, Qwen, Kimi, or GLM, then prove you can erase it. demo-claude-code runs a stdio MCP server exactly like this one for Claude Code and Cursor.
• Token benchmark — recalling a bounded set of memory cells instead of re-sending the transcript cut input tokens by 62.8%–85.9% (up to ~86%) across a realistic multi-session task; open, offline, reproducible: https://github.com/citw2/saihm-token-benchmark.

Tool reference

Tool	Title	Behavior
saihm_remember	Remember	seals + writes a memory cell (client-side)
saihm_recall	Recall	read-only; opens your cells — or a cell shared to you — client-side
saihm_forget	Forget (GDPR erasure)	destructive — irreversible erasure
saihm_status	Status	read-only
saihm_share	Share	end-to-end-authenticated grant
saihm_revoke_share	Revoke share	withdraws a grant
saihm_governance_propose	Propose (governance)	opens a proposal
saihm_governance_vote	Vote (governance)	casts a vote

Each tool carries MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) and a human-readable title, so MCP hosts can gate confirmations and agents can select the right tool at reasoning time.

Install

npm install @saihm/mcp-server-pro

Run as an MCP server

The package ships a stdio MCP server. Point your MCP host (Claude Desktop, Claude Code, …) at it — paste this once:

{
  "mcpServers": {
    "saihm": {
      "command": "npx",
      "args": ["-y", "@saihm/mcp-server-pro"],
      "env": {
        "SAIHM_ENDPOINT_URL": "https://saihm.coti.global/mcp",
        "SAIHM_MASTER_SECRET_HEX": "<your 64+ hex master secret>",
        "SAIHM_TIER": "PRO",
        "SAIHM_PAYMENT_METHOD": "stripe",
      },
    },
  },
}

With no SAIHM_AUTH_HEADER, the server self-onboards: it mints and auto-refreshes its own short-lived access token from your master secret, so there is no token to paste or re-paste. Eight tools are exposed (saihm_remember, saihm_recall, saihm_forget, saihm_status, saihm_share, saihm_revoke_share, saihm_governance_propose, saihm_governance_vote).

Zero-config free start — prompt your agent to "Join SAIHM"

The easiest start needs no master secret and no card. Self-join is on by default, so this is the whole configuration:

{
  "mcpServers": {
    "saihm": {
      "command": "npx",
      "args": ["-y", "@saihm/mcp-server-pro"],
      "env": {
        "SAIHM_ENDPOINT_URL": "https://saihm.coti.global/mcp",
      },
    },
  },
}

Then, in your agent session, just say:

Join SAIHM.

The agent calls the saihm_join tool, which generates your identity on this device (a 32-byte master secret written mode-600 to ~/.saihm/free-identity.key) and hands back a one-time device sign-in — open the link, enter the short code, approve. That step confirms you're a unique person; SAIHM never sees or stores the token. When it returns, your free, non-custodial memory is live and the other tools work. The key persists on this device, so your next session resumes with your memory intact.

saihm_join is a one-time onboarding affordance, not a ninth protocol tool. It is registered by default; set SAIHM_SELF_JOIN=0 to suppress it and expose only the canonical eight. Because your master secret is generated locally and never leaves the process, back up ~/.saihm/free-identity.key — if you lose it, no one (including SAIHM) can open your cells.

Start free

The simplest way: just ask your agent to "Join SAIHM." Self-join is on by default, so the saihm_join tool is already there — it generates your key on this machine, starts the sign-in, and activates the free trial for you. No master secret to invent, no env vars, no website visit.

To do it yourself from a shell instead, generate a master secret first — it never leaves your machine, and it is the only key to your memory:

openssl rand -hex 32 > saihm-master.key && chmod 600 saihm-master.key

Then activate. Prove you're a unique person once via a GitHub device sign-in; your memory is then bound to your own key for life:

SAIHM_ENDPOINT_URL=https://saihm.coti.global/mcp \
SAIHM_MASTER_SECRET_FILE=./saihm-master.key \
SAIHM_TIER=FREE \
  npx -y @saihm/mcp-server-pro free-join

Open the printed link, enter the short code, approve. SAIHM never sees or stores the GitHub token — the sign-in stays in your browser and the token is server-ephemeral. When it returns, start the server normally (drop free-join) and it self-onboards free.

The free trial is for testing on real infrastructure: a fixed, one-time allowance of writes, reads, and shares that never resets or refills. No card, and nothing to cancel — it is not an auto-renewing subscription. The client shows your remaining balance and warns you as you approach it, so nothing fails by surprise.

Upgrade any time — same key, same memories:

SAIHM_ENDPOINT_URL=https://saihm.coti.global/mcp \
SAIHM_MASTER_SECRET_HEX=<your 64+ hex master secret> \
SAIHM_TIER=FREE \
  npx -y @saihm/mcp-server-pro upgrade PRO

This prints a monthly checkout link bound to your identity; billing attaches to the same key, so every memory you already have persists. Pay, switch your config to the paid tier, and start the server normally.

Self-serve join

To subscribe an identity from the command line instead of the website, run the one-off join command with the same env:

SAIHM_ENDPOINT_URL=https://saihm.coti.global/mcp \
SAIHM_MASTER_SECRET_HEX=<your 64+ hex master secret> \
SAIHM_TIER=PRO SAIHM_PAYMENT_METHOD=stripe \
  npx -y @saihm/mcp-server-pro join

It prints a Stripe checkout link bound to your identity. Pay in a browser, then start the server normally (drop join) — it connects automatically. Keep SAIHM_MASTER_SECRET_HEX safe: it is the only key to your memory and cannot be recovered.

Use as a library

import { SaihmProClient } from '@saihm/mcp-server-pro';

// Boot from env: SAIHM_ENDPOINT_URL, SAIHM_MASTER_SECRET_HEX
//   self-onboard (recommended): + SAIHM_PAYMENT_METHOD + SAIHM_TIER (omit SAIHM_AUTH_HEADER)
//   static token (advanced):    + SAIHM_AUTH_HEADER="Bearer <JWT>"
//   (optional: SAIHM_SEQ_STATE_PATH)
const saihm = SaihmProClient.bootFromEnv();

// Store — encrypted before it leaves the process.
const { cellId } = await saihm.remember('remember this');

// Recall — decrypted after it returns.
const cell = await saihm.recallOne(cellId);
console.log(cell?.plaintext); // 'remember this'

// Recall everything (client-side keyword filter; the endpoint has no plaintext to filter on).
const matches = await saihm.recall('this');

// Update an existing cell (a fresh monotonic sequence is issued automatically).
await saihm.remember('new contents', { cellId });

// Forget — crypto-shred.
await saihm.forget(cellId);

// Share a cell with another agent, end-to-end authenticated. Pin the grantee's agentIdHash
// out-of-band; the library rejects directory key-substitution.
await saihm.share({
  cellId,
  recipientRecord, // the grantee's published identity record (hex)
  recipientPinnedAgentIdHashHex, // pinned out-of-band
});
await saihm.revokeShare(cellId, recipientPinnedAgentIdHashHex);

// Read a cell another agent shared TO you (the recipient side of `share`). Pin the
// sharer's agentIdHash out-of-band; the library verifies the sharer's signature and
// returns null when there is no live grant (e.g. revoked, or the sharer crypto-shredded it).
const shared = await saihm.recallShared({
  sharerPinnedAgentIdHashHex, // the sharer's agentIdHash, pinned out-of-band
  sharerRecord, // the sharer's published identity record (hex)
  cellId,
});
console.log(shared?.plaintext);

// Operator-observable metadata only (no plaintext).
const status = await saihm.status();

The derived saihm.agentIdHash is the sub the endpoint binds your tenant to — when self-onboarding the client proves it via ML-DSA; with a static SAIHM_AUTH_HEADER it must equal the JWT sub. Publish saihm.identityRecord so other agents can share to you.

Configuration

Env	Required	Meaning
SAIHM_ENDPOINT_URL	no	https://…/mcp (or http:// only for 127.0.0.1/localhost). Defaults to https://saihm.coti.global/mcp — set it only to point at a different operator.
SAIHM_AUTH_HEADER	no	Bearer <JWT>, used verbatim. Omit to self-onboard (recommended): the client mints + auto-refreshes its own short-lived JWT from the master secret, so you paste one config once and never re-paste a token.
SAIHM_PAYMENT_METHOD	paid self-onboard	Your entitlement rail (e.g. stripe) for a paid tier. Not used by the FREE tier — activate free with free-join (no card). Ignored when SAIHM_AUTH_HEADER is set.
SAIHM_MASTER_SECRET_HEX	yes*	≥ 64 hex chars (≥ 32 bytes), high-entropy, client-held; never sent. *Provide this or SAIHM_MASTER_SECRET_FILE.
SAIHM_MASTER_SECRET_FILE	yes*	Path to a mode-600 file holding the hex master secret. Preferred for operators: keeps the root seed out of a synced/shared MCP config. Takes precedence over SAIHM_MASTER_SECRET_HEX when both are set.
SAIHM_TIER	self-onboard only	Tier label baked into sealed metadata (FREE, PRO, …). Required when self-onboarding; otherwise optional — resolved via status() if unset.
SAIHM_SEQ_STATE_PATH	no	Persists per-cell sequence high-water marks (mode 600) for cross-restart updates.
SAIHM_SELF_JOIN	no	Controls the saihm_join onboarding tool ("prompt your agent to Join SAIHM"), which self-generates + persists a non-custodial identity and activates the free trial — no master secret needed. On by default; set to 0 to suppress the tool and disable every self-join path.
SAIHM_HOME	no	Base dir for the self-join identity file ($SAIHM_HOME/free-identity.key, mode 600). Defaults to ~/.saihm.

Self-onboarding (paste once): with SAIHM_AUTH_HEADER unset, the client proves control of your identity via the endpoint's ML-DSA challenge/response and mints its own token, refreshing transparently on expiry. Cancelling your subscription stops the next refresh, so access ends naturally.

Errors

Non-2xx responses throw SaihmEndpointError with status and a typed code (e.g. BLIND_BAD_EXPIRY, BLIND_STALE_SEQ, governance_unavailable). Branch on those rather than the message.

Security model

Property	Guarantee
Confidentiality vs the endpoint	The endpoint holds ciphertext + wrapped DEKs + public keys only; no key able to decrypt.
Integrity / authenticity	Every cell is ML-DSA-65-signed over its contents, including the sequence number.
Anti-replay	The signed monotonic sequence is rejected by the endpoint if not strictly increasing.
Tenant isolation	Your agentIdHash (= the JWT sub) namespaces your state; a write whose signed identity differs from the JWT is rejected.
Authenticated sharing	Grantee public keys are pinned out-of-band and verified before any secret is bound to them; on the recipient side, recallShared pins the sharer's key and verifies the cell signature before returning any plaintext.
Erasure	Destroying the endpoint-side wrapped DEK crypto-shreds the cell.

Where sealed cells are stored

This client seals cells and hands the ciphertext to whatever operator endpoint you point SAIHM_ENDPOINT_URL at; that operator chooses and configures the durable storage backend — typically a local IPFS / Kubo node first, then a Filecoin deep-archive provider (e.g. Pinata, Synapse, or Lighthouse). Storage is operator-configured by design: the protocol never locks anyone to a single provider. If you run your own endpoint, provisioning that backend is your responsibility — see your operator deployment guide.

Prefer not to run storage at all? Join SAIHM at https://saihm.coti.global and use the hosted non-custodial operator, which provides durable storage for you. Because this client seals every cell locally, the hosted operator only ever stores ciphertext and never holds your keys — managed storage without giving up custody (a paid hosted service).

License

Apache-2.0 © SAIHM