Skip to main content

ememdev: Python client for emem.dev

ememdev is the Python client for the emem.dev Earth memory protocol. Use it when a Python program or agent must read signed Earth-observation facts and keep the receipts for citation. Reads need no key.

pip install ememdev
python -c 'from ememdev import Client; print(Client().locate("Mount Fuji")["cell64"])'

The second line prints the cell64 address of Mount Fuji (defi.zb592.nUkO.zEzE on 7 November 2026). For the protocol itself, read docs/quickstart.md and docs/agents.md.

What the client does

The Client class wraps the public REST surface. Each method sends one request and returns the parsed JSON without changes. That JSON includes the Ed25519-signed receipt and the content-addressed CIDs, so you can cite a fact and verify it offline. The module docstring of ememdev.client maps each endpoint to its method. The full REST surface is the list in /openapi.json. This README gives no count, because a count goes out of date.

The client does not wrap endpoints that do not return JSON over HTTP/1.1. Examples are /v1/stream (SSE), the scene PNG and RGB images, and /v1/attest_cbor. Call them with httpx directly. The module docstring lists all of them.

Install

pip install ememdev

The PyPI distribution and the import package have the same name, ememdev. The shorter name emem on PyPI belongs to a different project. To install from a checkout of this repository:

pip install -e sdks/emem-py

The client needs Python 3.9 or later. Its only runtime dependency is httpx. To sign memory writes or verify receipts offline, add the signing extra. It installs blake3 and cryptography:

pip install "ememdev[signing]"

Read a fact

from ememdev import Client

with Client() as em:
    cell = em.locate("Mount Fuji")["cell64"]
    facts = em.recall(cell, bands=["copdem30m.elevation_mean"])
    print(facts["facts"][0]["value"])

On 7 November 2026 this printed 3539.042236328125 (metres). If no fact is in memory for the cell, recall fetches the source first. That first read can take tens of seconds; the client timeout is 180 seconds.

Use the async client

import asyncio
from ememdev import AsyncClient

async def main() -> None:
    async with AsyncClient() as em:
        out = await em.ask("How tall is Mount Everest?")
        print(out["answer"])

asyncio.run(main())

AsyncClient has the same methods as Client.

Configure the client

Environment variable Default Effect
EMEM_BASE_URL https://emem.dev Responder root. Set it to use a self-hosted node.
EMEM_TIMEOUT_SECS 180 HTTP timeout in seconds. It matches the gateway timeout.

You can also give base_url= and timeout= to the constructor.

Write a signed note

Reads are anonymous. A write into the agent memory namespace must carry an Ed25519 attester block. The MCP client cannot make that signature for you. ememdev[signing] makes it from a persistent identity, so one command writes a signed note.

The key owns your namespace at /memories/by_attester/<pubkey8>/..., so the client uses the same identity in every session. It looks for the key in this order:

  1. EMEM_AGENT_KEY: a 64-character hex seed or the path of a key file.
  2. ~/.emem/agent_ed25519.pem. Set EMEM_HOME to use a different directory.
  3. If there is no key, the client makes one at that path with mode 0600.

From the command line, for an agent that already uses emem over MCP:

ememdev whoami          # your pubkey and namespace_root

# write only the attester block to stdout; no network call:
ememdev sign  --verb create --path /memories/by_attester/<you>/note.md --stdin < note.md

# sign a create and POST it to /mcp in one step (this is a write to emem.dev):
ememdev write --path /memories/by_attester/<you>/note.md --body-file note.md

In Python:

from ememdev import load_or_create_signer

signer = load_or_create_signer()             # persistent identity
path = f"{signer.namespace_root}/note.md"
body = b"a durable, signed, citeable note"
attester = signer.attester_block("create", path, body)
# POST {path, file_text, kind, attester} to /mcp emem_memory_create.

Each block uses the v2 preimage, which binds base: the file_cid that is at the path now. A create with no base signs absent, for a new path. To overwrite a note, pass base=<its file_cid> (ememdev write --base). The other verbs change a note that exists, so they need base.

For str_replace and insert, sign the whole file after the edit. For rename, use signer.rename_attester_block(old, new), which signs both paths. The ememdev.signing docstring gives the body rule for each verb. The server refuses a write into the namespace of a different key with a 403. The sign and write commands refuse it locally before they send anything.

Cite and verify a receipt

Every response from a read primitive (for example recall) has a receipt block. Some responses, such as locate, have none. A receipt contains these fields:

  • responder_pubkey_b32: the Ed25519 public key, base32 without padding, lowercase.
  • signature_b32: the Ed25519 signature over the BLAKE3 preimage digest.
  • preimage_version: the rule that made the signature. Read it; do not assume it.
  • merkle_proof: the inclusion proof for fact_cids[0], if the log recorded one.
  • fact_cids[]: the BLAKE3 CIDs of all facts in the response.

To cite an answer, quote receipt.fact_cids[0] and the responder pubkey. Anyone can verify the signature offline. With the signing extra installed, ememdev.verify does the check in your process:

from ememdev import Client
from ememdev.verify import verify_receipt_offline

with Client() as em:
    cell = em.locate("Mount Fuji")["cell64"]
    resp = em.recall(cell, bands=["copdem30m.elevation_mean"])
    v = verify_receipt_offline(resp["receipt"])
    print(v.ok, v.state, v.signer_b32)

On 7 November 2026 this printed True verified 777er3yi... with preimage_version 2. The function checks the signature against the key in the receipt. Compare v.signer_b32 with the key you trust, for example federation.node.responder_pubkey_b32 in https://emem.dev/.well-known/emem.json. On 7 November 2026 the two keys were the same. The function does not raise and does not use the network. If no check ran, v.ok is False and v.state gives the cause. Without the extra, the state is crypto_unavailable. If the local encoders disagree with the Rust test vectors, the state is self_test_failed. Client.verify_receipt() is different: it asks the responder to do the check.

Keep and forward the receipt whole. ememdev returns it without changes; store it and pass it on the same way. From preimage_version: 2, the signature also covers the inclusion proof. Thus a party between you and the reader cannot remove the proof without detection.

The cost is that a changed receipt fails. Remove merkle_proof, rename a field or summarise the envelope, and the check gives signature_valid: false. That result looks the same as a forgery, although nobody changed the data. If the responder can prove that someone reshaped the receipt, POST /v1/verify_receipt gives reason: receipt_reshaped_after_signing instead of signature_invalid. It never accepts the changed receipt.

License

Apache-2.0, the same license as the protocol.

Metadata

Release files for ememdev 2.4.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ememdev 2.4.6
File Size Uploaded Provenance Actions
ememdev-2.4.6.tar.gz 30.7 kB With provenance Details for ememdev-2.4.6.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ememdev 2.4.6
File Interpreter ABI Platform Actions
ememdev-2.4.6-py3-none-any.whl Python 3 none any Details for ememdev-2.4.6-py3-none-any.whl

Total release size: 63.3 kB

Release files / ememdev-2.4.6.tar.gz

Download URL ememdev-2.4.6.tar.gz
Size 30.7 kB
Tags Source
SHA-256 checksum
How to use checksums
2f9edfec8cfaacc5b3eaa480843c8e187426c89ba8f06e9b1f8ecb2f758124be
BLAKE2b-256 checksum
How to use checksums
901536e0e318ac1aac8f93bde77fe6b4678b57aefbda1ffbcba801dad23d4e2b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Release files / ememdev-2.4.6-py3-none-any.whl

Download URL ememdev-2.4.6-py3-none-any.whl
Size 32.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0756ece962ca690d6e96cef1ce6f45b6d79e4a7af1217e099086dc1fa25eaff3
BLAKE2b-256 checksum
How to use checksums
03f81794b15df34a568afc0007320ab837199e2894821558c01e5167e2003e5e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Security for ememdev 2.4.6

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for ememdev-2.4.6.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page