@mnemom/mnemom 0.17.20 → 0.17.22

package/plugins/mnemom/skills/about-mnemom/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: about-mnemom
+description: Explains Mnemom, the Trust Rating, the gateway and the /mnemom commands in a session launched by `mnemom agent`. Use when the person asks what Mnemom is, what "governed" means here, why the band or the ◆ sign shows, how the Trust Rating is scored or verified, or how to route Claude Code through the Mnemom gateway.
+---
+
+# Mnemom for Claude Code
+
+Mnemom is **the trust plane for the agentic internet**: live, cryptographic trust signals for AI
+agents and the sites they act on. Everything Mnemom publishes is signed and independently
+verifiable against its public keys. Site: https://www.mnemom.ai · Docs: https://docs.mnemom.ai ·
+What kind of company it is, for agents: https://www.mnemom.ai/for-agents
+
+## What "governed" means in this session
+
+`mnemom agent <session>` launches stock Claude Code with its model traffic routed through the
+Mnemom gateway:
+
+- `ANTHROPIC_BASE_URL` points at the gateway's Anthropic door (`<gateway>/anthropic`); the
+  Mnemom API key and the governed identity (agent, conversation, goal mode) travel in request
+  headers. Under Remote Control a local proxy does the same for the server process.
+- The gateway records every model call as an **integrity checkpoint** on an append-only hash
+  chain, applies the agent's **protection posture** (the policy its owner set), and feeds the
+  agent's public **Trust Rating**.
+- Nothing about the model or the tools changes: this is governance around the session, not a
+  different Claude.
+
+This plugin is the visible part: the band above the prompt, the status pane, the ◆ sign on the
+spinner and the turn line, Mnemom trailers in commit attribution, a governance section in the
+system prompt, and a guard that denies Bash commands which would point `ANTHROPIC_BASE_URL`,
+`ANTHROPIC_AUTH_TOKEN` or `ANTHROPIC_CUSTOM_HEADERS` away from the gateway.
+
+A session that was NOT launched by `mnemom agent` shows an amber "not governed" band. Nothing is
+recorded for it. Tell the person to launch with `mnemom agent` (install: `npm i -g @mnemom/mnemom`,
+then `mnemom login`).
+
+## The /mnemom commands
+
+| Command                           | What it does                                                                                                                                                                                           |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `/mnemom` or `/mnemom status`     | agent, conversation, cell, gateway, shape, goal (mode, statement, requirements, paths, guardrails, verdict), Trust Rating, turn count                                                                  |
+| `/mnemom goal`                    | the goal in full: statement, every requirement, path fences, guardrail ceilings + usage, the gateway's latest verdict; sealed shows `mnemom agent show`, implicit `mnemom agent goal show\|pin\|reset` |
+| `/mnemom doctor`                  | GETs `<gateway>/health` and the Trust Rating endpoint; reports both                                                                                                                                    |
+| `/mnemom verify`                  | GETs `/v1/reputation/<agent>/verify`: the hash-chain + Merkle-root attestation                                                                                                                         |
+| `/mnemom panel` / `/mnemom close` | opens or closes the Mnemom status pane (the band's `▸ status` mark opens it too)                                                                                                                       |
+| `/mnemom hide` / `/mnemom show`   | hides or shows the band for this session                                                                                                                                                               |
+| `/mnemom help`                    | the list above                                                                                                                                                                                         |
+
+Plugin options (in `/config` or `pluginConfigs["mnemom"]` in settings): `showBand`,
+`requireGovernance` (refuse all tool calls while ungoverned), `guardReroute`, `commitTrailer`,
+`spinnerMark`.
+
+## The Trust Rating
+
+Public, no auth: `GET https://api.mnemom.ai/v1/reputation/{agent_id}`.
+
+- **score** 0–1000, **grade** AAA · AA · A · BBB · BB · B · CCC · CC · C · D, or **NR** (not
+  rated) until the agent has enough checkpoints (the band shows `NR (building n/50)`).
+- **tier** describes the evidence volume; **integrity_ratio** is the public, signed proof of
+  chain integrity. Integrity- and alignment-internal detail stays owner-private.
+- Public page: `https://www.mnemom.ai/agents/{agent_id}/reputation`; badge: `.../badge.svg`.
+
+Two DISTINCT verification paths; do not conflate them:
+
+- `/v1/reputation/{agent_id}/verify` (what `/mnemom verify` calls): a **chain-integrity
+  attestation**: Merkle root + `hash_chain_valid`, plus a pointer to a signed integrity
+  certificate. Not an in-band signature check.
+- Website scorecards (`scan_trust` on the Mnemom MCP server) are verified **in-band** with Ed25519
+  against `https://api.mnemom.ai/.well-known/jwks.json`.
+
+## The Mnemom MCP server
+
+This plugin connects `https://api.mnemom.ai/mcp` (HTTP). Zero-auth tools: `get_started`,
+`get_reputation`, `verify_reputation`, `search_reputation_directory`, `scan_trust`, `verify_scan`.
+With a Mnemom credential (Bearer JWT or `X-Mnemom-Api-Key`) it also manages the person's own
+agents: alignment cards, protection postures, governance signals, webhooks, API keys. The docs
+server at `https://docs.mnemom.ai/mcp` answers questions from the published docs.
+
+## When the person asks…
+
+- **"Why is there a ◆ on the spinner?"** The session is governed; every model call is being
+  checkpointed through the Mnemom gateway. `/mnemom status` shows by whom.
+- **"Can I turn the gateway off for one command?"** Not inside this session: the plugin denies
+  it, by design. Use another terminal, or `mnemom agent --no-plugin` for a session without the
+  guard (the routing itself still comes from the launcher).
+- **"Is my score good?"** Grades A and up are strong; NR means not enough history yet, not a
+  bad score. Point them at the public page for the breakdown.
+- **"Who sees what?"** The public rating and its chain attestation are public. Alignment and
+  integrity internals are visible only to the agent's owner.

package/plugins/mnemom/types/index.d.ts

@@ -0,0 +1,142 @@
+/**
+ * The state contract of the `mnemom` mod: every value it keeps in
+ * `$.state`, declared under its plugin name. `claude plugin validate` holds the
+ * module's `$.state` keys to this file.
+ */
+
+/** How the session came to be: the non-secret launch facts `mnemom agent` exports. */
+export type MnemomLaunch = {
+  /** Gateway origin the session's model traffic goes through (`https://gateway.mnemom.ai`). */
+  gatewayHost: string;
+  /** Mnemom API origin for the public Trust Rating lookups (`https://api.mnemom.ai`). */
+  apiUrl: string;
+  /** The governed identity (`x-mnemom-agent`). */
+  agent: string;
+  /** The conversation id (`x-mnemom-conversation-id`). */
+  conversationId: string;
+  /** The cell note the launcher printed (`us-2/prod`, `custom (https://…)`). */
+  cell: string;
+  /** `terminal`, `remote-control` or `server`. */
+  shape: string;
+  /** `sealed` (a `--goal` contract), `implicit` (the gateway infers the goal) or `off`. */
+  goalMode: "sealed" | "implicit" | "off";
+  /** The sealed contract's display hash (sha256[0:16]), empty when none. */
+  contractSha: string;
+  /** The sealed contract as the launcher sealed it; null unless `goalMode` is `sealed`. */
+  contract: MnemomContract | null;
+  /**
+   * The guardrail ceilings the launch asked for: the sealed contract's, or the implicit mode's
+   * `--max-turns/--budget/--stall`. All null when none was given.
+   */
+  ceilings: MnemomCeilings;
+  /**
+   * The argv that runs the launching `mnemom` again (`[node, …, script]`); the live goal state is
+   * read through `mnemom agent show --json`. Empty when the launcher did not say.
+   */
+  launcherExec: string[];
+  /** The launcher's session name (`mnemom agent <session>`). */
+  session: string;
+  /** The `mnemom` CLI version that launched the session. */
+  launcherVersion: string;
+};
+
+/** What a `--goal` launch sealed: the person's own words, as sent in `x-mnemom-contract`. */
+export type MnemomContract = {
+  goalId: string | null;
+  statement: string;
+  requirements: string[];
+  allowedPaths: string[];
+  forbiddenPaths: string[];
+};
+
+/** Guardrail ceilings; null = that guardrail is not set. */
+export type MnemomCeilings = {
+  maxTurns: number | null;
+  budgetUsd: number | null;
+  stallTurns: number | null;
+};
+
+/** The goal judge's latest word on the conversation. */
+export type MnemomVerdict = {
+  /** `aligned` | `drifting` | `violation` (the gateway's own words). */
+  verdict: string;
+  turn: number | null;
+  reason: string | null;
+  /** ISO time the verdict was stored, when known. */
+  at: string | null;
+};
+
+/**
+ * The live goal state as the gateway holds it, read through `mnemom agent show --json` (and, in
+ * implicit mode, `mnemom agent goal show --json`). Sealed: the gateway's hash and verdict, the
+ * guardrail usage. Implicit: the inferred goal (statement, requirements, fences), its revision and
+ * pin, the verdict, the guardrail usage.
+ */
+export type MnemomGoal =
+  | { state: "loading" }
+  | { state: "unavailable"; reason: string; fetchedAt: number }
+  | {
+      state: "live";
+      fetchedAt: number;
+      /** `sealed` | `implicit`, as the gateway reports it. */
+      mode: "sealed" | "implicit";
+      /** The gateway's contract hash (sealed) or the intent's contract_hash (implicit). */
+      hash: string | null;
+      /** Implicit: the inferred goal's revision; null when sealed. */
+      revision: number | null;
+      /** Implicit: whether the person pinned the goal (`mnemom agent goal pin`). */
+      pinned: boolean | null;
+      /** Implicit: how many revisions wait for the next turn boundary. */
+      pendingCount: number | null;
+      /** The goal as the gateway holds it (implicit: inferred; sealed: echoed). */
+      statement: string | null;
+      requirements: string[];
+      allowedPaths: string[];
+      forbiddenPaths: string[];
+      /** The ceilings the gateway enforces (its view, over the launch's). */
+      ceilings: MnemomCeilings;
+      /** Guardrail usage so far; null until the gateway has seen a turn. */
+      usage: {
+        turns: number;
+        spendUsd: number;
+        stallRun: number;
+        /** Which guardrails fired: `turns`, `budget`, `stall`. */
+        fired: string[];
+      } | null;
+      verdict: MnemomVerdict | null;
+      /** The gateway's turn counter for the conversation. */
+      turn: number | null;
+    };
+
+/** The agent's public Trust Rating as last fetched from the Mnemom API. */
+export type MnemomReputation =
+  | { state: "loading" }
+  | {
+      state: "rated";
+      grade: string;
+      score: number;
+      tier: string | null;
+      checkpointCount: number | null;
+      fetchedAt: number;
+    }
+  | { state: "unrated"; checkpointCount: number | null; fetchedAt: number }
+  | { state: "error"; reason: string; fetchedAt: number };
+
+declare module "claude-code" {
+  interface PluginState {
+    mnemom: {
+      /** The launch facts, or null when the session was not launched by `mnemom agent`. */
+      launch: MnemomLaunch | null;
+      /** The Trust Rating, or null before the first lookup. */
+      reputation: MnemomReputation | null;
+      /** Whether the person hid the band for this session. */
+      isHidden: boolean;
+      /** Turns completed in this session. */
+      turns: number;
+      /** The intro animation's frame while it plays on the band; -1 once it is over. */
+      introFrame: number;
+      /** The live goal state, or null when the session is not governed. */
+      goal: MnemomGoal | null;
+    };
+  }
+}