--- name: create-engram description: Create an EngramX engram — a personal, user-OWNED memory store plus a tamper-evident action record on the Internet Computer. Use when the user wants to set up their own engram so an AI agent can remember them across sessions and across models. Creation is free and makes the user the owner; the agent connects separately, later, as an append-only operator. --- # Create an EngramX engram An **engram** is a per-user canister on the Internet Computer that holds an agent's memory and a tamper-evident audit record, **owned by the user** — not the AI vendor, and not you (the agent). Creating one is **free** (the platform funds it). This skill CREATES an engram the user owns; it does **not** operate one — reading and appending memory is a separate *operator* step (`@engramx/client`), kept in a different package so operators never gain owner powers. ## When to use The user says something like "create an engram", "set up my EngramX memory", "give me my own memory store", or "I want my own agent memory that I control." If they instead want an agent to *read/write* an engram that already exists, that's the operator flow (`@engramx/client pair`), not this skill. ## Reserve, then activate (important) Creation is two-stage on purpose: - **Reserve** (the default) = a **free** registry record (~$0). Nothing runs yet. - **Activate** (`--activate`) = spawns the live canister (the platform funds the ~1.15T-cycle spawn). This is a deliberate cycle anti-drain: reserving costs nothing, so a speculative "create" never wastes money. **Only pass `--activate` once the user has confirmed they actually want to spin it up now** — i.e. they're going to use it. Reserving is idempotent (one per principal), so a reserve-now, activate-later flow is safe. ## How to run Creation goes through the standalone CLI. You need the EngramX **registry canister id** (ask the user, or read `ENGRAMX_REGISTRY` from the environment). Always pass `--yes` when running as an agent so it doesn't wait on a prompt. 1. **Reserve** (free — do this first): - Reusing the user's icp-cli identity (they keep full custody; EngramX holds nothing): ``` npx @engramx/owner --icp-identity --registry --yes ``` - Otherwise a local Ed25519 owner key is generated at `~/.engramx/owner.key`: ``` npx @engramx/owner --registry --yes ``` ⚠ That seed is the user's **only** key. Tell them to back up `~/.engramx/owner.key`; losing it means permanently losing ownership of the engram. 2. **Activate** once the user confirms they want it running — same flags plus `--activate`: ``` npx @engramx/owner --activate --icp-identity --registry --yes ``` The command prints the live engram's canister id and the owner principal. - **Local dev replica**: add `--local` (host defaults to `http://127.0.0.1:4943`). ## After activating 1. The user **owns** the engram. To let this agent (or any host) read and append its memory, connect as an **operator** — a separate, append-only step: `npx @engramx/client pair --engram `. Owner ≠ operator, by design. 2. Ongoing cycles can be funded with **ckUSDC** via the cashier (optional). ## Which custody, for which engram (the two-tier rule) Match the custody to what will live inside — the tiers are not interchangeable: - **Throwaway / development** (CI, drills, experiments): agent-held keys are fine, but run it against a **local replica or a staging registry**, not the production fleet. Nothing of consequence should live in an engram whose key sits on an agent host. - **Durable — a record or money will live here**: the OWNER creates it with a **recoverable wallet identity** (the web wizard / `--wallet`), on the owner's own device. The owner key and its recovery phrase must never touch the machine the agent runs on — if they do, both tiers collapse to that machine, and "the user owns it" stops being true in any sense an outsider can verify. The agent then connects the ordinary way: the owner mints a one-shot invite (expires in 30 minutes) and ONLY that code is handed to the agent host. Anyone can check which tier an engram lives in: its public `getOwnershipHistory()` shows who has held owner power since creation, and the registry's `getCustodyMode()` shows who controls upgrades. ## Honesty (state these plainly to the user) - The owner key is the **user's own** — EngramX never holds it. A single local key means loss = total, unrecoverable loss; recommend backing it up (or using their icp-cli identity, or the web wizard with a wallet for real recovery). - The record is tamper-**evident**, not immutable: the owner can overwrite their own memory, but every change is a signed entry anyone can check. - Nothing is on a public fleet yet — until the registry is deployed, this creates against a dev replica.