saihm-mcp-server-pro

# SAIHM — memory for AI agents

**Portable memory for AI agents.** Your assistant remembers what matters — across
sessions, across models, across vendors. Share a memory with someone else's
agent, take it back, or erase it for good.

[![npm version](https://img.shields.io/npm/v/@saihm/mcp-server-pro.svg)](https://www.npmjs.com/package/@saihm/mcp-server-pro)
[![license](https://img.shields.io/npm/l/@saihm/mcp-server-pro.svg)](./LICENSE)

AI assistants forget everything when the session ends. SAIHM gives yours a memory
that doesn't — one that follows you to a different assistant, a different model,
or a different company's product.

Everything is encrypted on your own machine before it goes anywhere, so nobody
else can read your memories. Not the storage, not SAIHM.

## Start free — one command

```sh
npx -y @saihm/mcp-server-pro free-join
```

That's it. No card, no account to fill in, nothing to invent. It sets up your
identity on this machine and prints a one-time sign-in to confirm you're a real
person. Open the link, enter the short code, approve.

Then point your AI tool at it. This works in Claude Desktop, Claude Code, Cursor,
Cline, and anything else that speaks MCP — add the `"saihm"` entry inside your
existing `mcpServers` section:

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

Restart the connection and say **"Recall my SAIHM memories."** You're running.

Two details in that config are load-bearing:

- **Keep `timeout: 60`.** Some tools allow as little as 1.5 seconds for a server
  to start, which isn't long enough for `npx` to fetch and launch a package. A
  server that misses the deadline is skipped **silently** — the tools simply never
  appear, and nothing in the chat says why.
- **No trailing commas.** These files are strict JSON. A stray comma doesn't just
  break this entry; it invalidates the whole file and every other tool you had
  configured disappears with it.

**Prefer not to touch a terminal?** Add the config above first, then say **"Join
SAIHM"** to your assistant. It does the same setup for you.

## Things to say

You don't call tools by name — you talk to your assistant. Some starters:

> Liberally use SAIHM protocol to maximize token economy.

> Recall my SAIHM memories before you start.

> Remember that I prefer short answers and no preamble.

> Set an invariant to doubly confirm before any SAIHM forget action.

> Share that note with my colleague's agent until 5:00 pm today.

> How much of my SAIHM allowance is left?

> Forget everything I told you about the Henderson account.

| Tool | What it does |
|---|---|
| `saihm_remember` | Encrypts on your machine, then stores it |
| `saihm_recall` | Fetches and decrypts on your machine |
| `saihm_forget` | **Permanently erases.** No undo |
| `saihm_status` | Your usage and settings |
| `saihm_share` | Grants one memory to one agent, optionally with an expiry |
| `saihm_revoke_share` | Withdraws that grant |

Every tool is labelled for your AI tool to read, including which are read-only and
which one destroys data — so hosts that ask "are you sure?" before destructive
actions know when to ask. Two further tools, `saihm_governance_propose` and
`saihm_governance_vote`, are registered for a roadmap feature and are not yet
active.

**"Forget" really means forget.** The key to that specific memory is destroyed, so
the stored copy becomes permanently unreadable — by you, by SAIHM, by anyone
holding a backup of it. This is how SAIHM answers a GDPR Article 17 erasure
request, and it is why there is no undo.

## Your memories follow your key

Your memory belongs to your key, not to a computer — that's what makes it
portable. The key is created on your machine during setup and never sent
anywhere, which is exactly why nobody else can read your memories. **Keep a copy
of the key file somewhere safe.** SAIHM cannot make you another one.

Setup prints the file's location when it runs — that's the line to keep. The same
key carries through if you upgrade to a paid plan: same identity, same memories,
nothing migrated.

**Using a second computer?** Two ways:

- **Same memory, both machines** — put your key file on the second machine, set up
  the config there, and say *"Recall my SAIHM memories."*
- **Work and personal kept apart** — start fresh on the second machine and share
  across instead: *"Share these notes with my work agent until 5:00 pm."* A share
  can be revoked or given an expiry, so the two stay separate.

## See it run

- **Live demos across every major model** — offline, about a minute each, no
  account: <https://citw2.github.io/saihm-demos/>. Store a memory in Claude, GPT,
  DeepSeek, Qwen, Kimi, or GLM, then prove you can erase it.
- **Token benchmark** — recalling a bounded set of memories instead of re-sending
  the whole conversation cut input tokens by **62.8%–85.9%** across a realistic
  multi-session task. Open, offline, reproducible:
  <https://github.com/citw2/saihm-token-benchmark>.

## What it costs

Start free. The free tier is a fixed, one-time allowance of writes, reads, and
shares for trying SAIHM on real infrastructure — it doesn't reset or refill.
**No card, and nothing to cancel.** Your assistant shows what's left and warns you
as it runs low, so nothing fails by surprise.

Paid plans are monthly. Upgrading keeps the same key and every memory you already
have:

```sh
SAIHM_MASTER_SECRET_FILE=$HOME/.saihm/free-identity.key \
SAIHM_TIER=FREE \
  npx -y @saihm/mcp-server-pro upgrade PRO
```

That prints a checkout link tied to your identity. Pay, then add two lines to your
config's `env` block and restart:

```json
"SAIHM_TIER": "PRO",
"SAIHM_PAYMENT_METHOD": "stripe"
```

Both are needed — a paid plan without `SAIHM_PAYMENT_METHOD` refuses to start,
because that setting names which payment rail to check. `stripe` is one option;
`stablecoin` is another, and your assistant can tell you what your operator
accepts.

## If something isn't working

| What you see | Usual cause |
|---|---|
| No SAIHM tools appear, and no error anywhere | `timeout` too low — see the config above |
| Every other tool vanished too | A trailing comma broke the settings file |
| Tools appear but every call fails | `SAIHM_ENDPOINT_URL` unreachable |
| "no identity" | Setup hasn't run on this machine yet |
| A different memory than you expected | This machine has its own key rather than yours |
| `status` mentions `seq-state` | A small local safeguard file couldn't be read or written. Your memories are unaffected — see `SAIHM_SEQ_STATE_PATH` below |
| `forget` worked but mentions a feed | The erasure stands — only the notification line couldn't be written. See `SAIHM_ERASURE_FEED` below |

## How it works

**In plain terms.** Everything is encrypted on your machine before it is sent, and
decrypted on your machine after it comes back. What's stored is unreadable
ciphertext and no key that opens it. To erase something, its key is destroyed —
which is why erasure is immediate and final rather than a promise that a copy was
deleted somewhere.

**For the technically inclined.**

- **Encrypt before send** — `remember` encrypts client-side; `recall` decrypts
  client-side. Your plaintext, master secret, and key-encryption key never leave
  this process.
- **Post-quantum** — ML-DSA-65 for identity and signing, ML-KEM-768 for
  authenticated sharing, via
  [`@saihm/client-pro`](https://www.npmjs.com/package/@saihm/client-pro).
- **Crypto-shred erasure** — `forget` destroys the endpoint-side wrapped
  data-encryption key, rendering the cell undecryptable (GDPR Art. 17).
- **Erasure that travels** — `forget` also appends one line to a per-identity
  feed, so anything that derived from a cell — an index, a mirror, an extracted
  fact — can be told to drop it too. An erasure that stops at this substrate is
  not an erasure. On by default; `SAIHM_ERASURE_FEED=0` turns it off.
- **Standard transport** — `POST {method, params}` with
  `Authorization: Bearer <JWT>`; the endpoint binds your tenant from the JWT.
  HTTPS only, with loopback `http` permitted for local development.
- **Self-onboarding** — with no `SAIHM_AUTH_HEADER` set, the client proves control
  of your identity and mints its own short-lived token, refreshing transparently.
  You paste one config once and never re-paste a token. Cancelling a subscription
  stops the next refresh, so access ends naturally.

### Security model

| Property | Guarantee |
| --- | --- |
| Confidentiality vs the endpoint | The endpoint holds ciphertext, wrapped DEKs, and 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 it does not strictly increase. |
| 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. |
| Erasure cascade | Each `forget` appends one line to `$SAIHM_HOME/tenants/<agentIdHash>/erasures.ndjson`. The line carries the cell id, the identity and the time — never cell content. |

### Where encrypted cells are stored

This client encrypts cells and hands the ciphertext to whichever operator endpoint
`SAIHM_ENDPOINT_URL` points at; **that operator chooses and configures the durable
storage behind it** — typically a local IPFS / Kubo node first, then a Filecoin
deep-archive provider. Storage is operator-configured **by design**: the protocol
neve