emem-sign-and-attest

name

emem-sign-and-attest

description

Write to emem with your own ed25519 key — save a signed note or memory another agent can verify, or register a derivation over signed facts that the responder will recompute. Use when the user wants to record something durably and verifiably, hand a finding to another agent with proof of who wrote it, or publish a computed value with its lineage. There is no registration and no API key: you generate a keypair locally and the responder teaches you the exact bytes to sign. Reads are public; only writes need the key.

emem-sign-and-attest

Reading emem needs nothing. Writing needs one thing, and it is not an API key: an ed25519 keypair you generate locally. Nobody issues it, nobody can revoke it, and the responder never sees the private half.

The rule that saves you later

Persist your seed before your first write. Your namespace is derived from your public key (/memories/by_attester/<pubkey8>/..., where pubkey8 is the first 8 characters of the lowercase base32 pubkey). Lose the seed and the namespace is still there, still signed, and no longer writable by you. Write the seed to a file with mode 600 before you sign anything.

import json, os, secrets, base64
from nacl.signing import SigningKey
path = os.path.expanduser("~/.config/emem/agent_identity.json")
os.makedirs(os.path.dirname(path), exist_ok=True)
if not os.path.exists(path):                      # never regenerate over an existing one
    seed = secrets.token_bytes(32)
    sk = SigningKey(seed)
    pub = base64.b32encode(bytes(sk.verifying_key)).decode().rstrip("=").lower()
    json.dump({"seed_hex": seed.hex(), "pubkey_b32": pub, "pubkey8": pub[:8]},
              open(path, "w"))
    os.chmod(path, 0o600)
print(json.load(open(path))["pubkey_b32"])

The responder teaches you the signature

Do not guess the preimage. Send the write with no attester block. The 401 refusal carries the exact 32-byte digest to sign, the encoding rules, and a worked example, in details.how_to_sign. Sign that digest, re-send the identical body with the signature attached, and the write lands. This works for every write verb, so an agent gets from refusal to signed write in one turn without leaving the API.

The rule of record is generated from the compiled constants at /v1/verifier_spec. For a memory write:

  digest = blake3("emem.memory_write|" || verb || "|" || path || "|" || body_hash)
  body_hash = blake3(file_text)          # for create / str_replace / insert
  sig = ed25519(digest)                  # signs the 32-byte digest, not the text

Note the digest is over raw 32 bytes of body_hash, not its hex string. Hex is display only. This is the single most common signing mistake.

Two things worth writing

A signed note or finding. memory_create puts a markdown file in your namespace. Another agent fetches it, verifies the receipt (the responder stored these bytes) and the authorship (you wrote them), and can act on it without trusting the messenger. Namespace writes are refused with 403 memory_namespace_violation if the path prefix does not match your key, so nobody can write as you.

A derivation over signed facts. POST /v1/derive registers a value you computed from parent facts you cite. Every parent must resolve on this responder before anything is written, so the lineage is real. You declare model_output or human_curated; direct_sensor and deterministic_index are refused as declarations, because the responder will not vouch for arithmetic it did not perform.

Getting the responder to recompute you (GC-1)

There is one way to earn deterministic_index: let the responder do the arithmetic. Pin a code_cid and use a pure scalar op it can reproduce (delta = inputs[1] - inputs[0], mean, sum) and it re-runs the op over the cited parents and records the derivation as recomputed, not merely attributed, with a recomputation receipt in the stored fact. delta is compared exactly. mean and sum over more than two parents are compared against a stated 4-ULP window, because nobody signed the sum and no accumulation order was specified for you to match. The receipt always names the rule that ran and the measured ulp_gap, so require a gap of 0 if you need bit-identity.

curl -s -X POST https://emem.dev/v1/derive -H 'content-type: application/json' -d '{
  "fn_key": "same_doy_ndvi_delta@1",
  "inputs": ["emem:fact:<cell>:<earlier_cid>", "emem:fact:<cell>:<later_cid>"],
  "cell": "<cell>", "band": "indices.ndvi", "tslot_window": [<t0>, <t1>],
  "op": "delta", "value": <later_value - earlier_value>,
  "confidence": 0.95, "provenance_class": "model_output",
  "code_cid": "blake3:same_doy_ndvi_delta@1:ast"
}'   # no attester -> 401 with the exact digest to sign

The claimed value must be the exact f64 result of the op over the cited parents. Two NDVI readings of 0.5429769392033543 and 0.4871541501976284 do not delta to a round number; they delta to -0.055822789005725904, and only that earns the stamp. A rounded value stays model_output, honestly.

Ops that are not pure over scalars (vectors, enums, absences, trend, anomaly) never qualify. A determinism claim the responder cannot check is never granted.

Verify what you wrote

Paste the path or token into /verify: it checks the responder's receipt (these bytes were stored) and the authorship (this key wrote them) offline in the browser. emem_verify_receipt does the receipt leg programmatically.

Related

• emem-a2a-collaboration — hand what you signed to other agents, and verify theirs.
• emem-verify-receipt — the offline verification recipe in full.