ememdev 2.4.2__tar.gz → 2.4.5__tar.gz

{ememdev-2.4.2 → ememdev-2.4.5}/.gitignore

@@ -90,3 +90,7 @@ examples/3d-worlds/out/
 # Agent scratch notes belong in .well-known/agent-notes/, never the repo root.
 /AGENT_*.md
 web/channel.json
+
+# Baked on the node by scripts/build_channel.py every few minutes and read
+# from disk; the binary carries web/channel-fallback.html instead.
+web/channel.html

ememdev-2.4.5/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.5
+Name: ememdev
+Version: 2.4.5
+Summary: Python client for emem: shared, verifiable memory for AI agents. One address per fact, one signature you can check. No key to read.
+Project-URL: Homepage, https://emem.dev
+Project-URL: Repository, https://github.com/Vortx-AI/emem
+Project-URL: Documentation, https://emem.dev/agents.md
+Project-URL: Issues, https://github.com/Vortx-AI/emem/issues
+Author-email: Vortx AI Private Limited <avijeet@vortx.ai>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: agent-memory,ai-agents,content-addressed,earth-observation,ed25519,geospatial,mcp,model-context-protocol,provenance,satellite,shared-memory,verifiable
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.9
+Requires-Dist: httpx<1.0,>=0.27
+Provides-Extra: signing
+Requires-Dist: blake3>=0.3; extra == 'signing'
+Requires-Dist: cryptography>=41; extra == 'signing'
+Description-Content-Type: text/markdown
+
+# ememdev: Python client for emem.dev
+
+<!-- mcp-name: io.github.Vortx-AI/emem -->
+
+`ememdev` is the Python client for the [emem.dev](https://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.
+
+```bash
+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](https://github.com/Vortx-AI/emem/blob/main/docs/quickstart.md)
+and [docs/agents.md](https://github.com/Vortx-AI/emem/blob/main/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`](https://emem.dev/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
+
+```bash
+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:
+
+```bash
+pip install -e sdks/emem-py
+```
+
+The client needs Python 3.9 or later. Its only runtime dependency is
+[`httpx`](https://www.python-httpx.org/). To sign memory writes or verify
+receipts offline, add the `signing` extra. It installs `blake3` and
+`cryptography`:
+
+```bash
+pip install "ememdev[signing]"
+```
+
+## Read a fact
+
+```python
+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
+
+```python
+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:
+
+```bash
+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:
+
+```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:
+
+```python
+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.

ememdev-2.4.5/README.md

@@ -0,0 +1,201 @@
+# ememdev: Python client for emem.dev
+
+<!-- mcp-name: io.github.Vortx-AI/emem -->
+
+`ememdev` is the Python client for the [emem.dev](https://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.
+
+```bash
+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](https://github.com/Vortx-AI/emem/blob/main/docs/quickstart.md)
+and [docs/agents.md](https://github.com/Vortx-AI/emem/blob/main/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`](https://emem.dev/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
+
+```bash
+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:
+
+```bash
+pip install -e sdks/emem-py
+```
+
+The client needs Python 3.9 or later. Its only runtime dependency is
+[`httpx`](https://www.python-httpx.org/). To sign memory writes or verify
+receipts offline, add the `signing` extra. It installs `blake3` and
+`cryptography`:
+
+```bash
+pip install "ememdev[signing]"
+```
+
+## Read a fact
+
+```python
+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
+
+```python
+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:
+
+```bash
+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:
+
+```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:
+
+```python
+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.

{ememdev-2.4.2 → ememdev-2.4.5}/pyproject.toml

@@ -9,7 +9,7 @@ name = "ememdev"
 # without a framework. 1.0.1 first superseded the empty 1.0.0 on PyPI (it
 # shipped dist-info and no modules, so `import emem` raised ModuleNotFoundError;
 # PyPI versions are immutable, so the only fix was to supersede it).
-version = "2.4.2"
+version = "2.4.5"
 description = "Python client for emem: shared, verifiable memory for AI agents. One address per fact, one signature you can check. No key to read."
 readme = "README.md"
 requires-python = ">=3.9"

{ememdev-2.4.2 → ememdev-2.4.5}/src/ememdev/__main__.py

@@ -149,10 +149,11 @@ def _build_attester(signer, args: argparse.Namespace) -> dict:
     body = _read_body(args)
     if verb == "delete" and body:
         raise SystemExit("delete carries no body; drop --body/--body-file/--stdin")
-    if verb == "delete" and not args.base:
+    if verb != "create" and not args.base:
         raise SystemExit(
-            "delete is refused under the v1 preimage; pass --base <file_cid now at --path> "
-            "(GET the note with Accept: application/json and read file_cid)"
+            f"{verb} changes a note that exists, so it must be signed against it; pass "
+            "--base <file_cid now at --path> (GET the note with Accept: application/json "
+            "and read file_cid)"
         )
     if verb in ("create", "str_replace", "insert") and not body and not args.allow_empty:
         raise SystemExit(
@@ -185,7 +186,7 @@ def _cmd_write(args: argparse.Namespace) -> int:
     if not body and not args.allow_empty:
         raise SystemExit("write needs a body; pass --body/--body-file/--stdin or --allow-empty")
     file_text = body.decode("utf-8")
-    attester = signer.attester_block("create", args.path, body)
+    attester = signer.attester_block("create", args.path, body, base=args.base)
     result = _post_memory_create(args.base_url, args.path, file_text, args.kind, attester)
     print(json.dumps(result, indent=2))
     return 0
@@ -223,8 +224,8 @@ def main(argv: Optional[list] = None) -> int:
     p_sign.add_argument("--old-path", help="rename only: the source path")
     p_sign.add_argument(
         "--base",
-        help="the file_cid now at --path, which a delete must name (signs v2); "
-        "'absent' for a new path",
+        help="the file_cid now at --path. delete, str_replace and insert must name "
+        "it; create defaults to 'absent' (a new path)",
     )
     _add_body_args(p_sign)
 
@@ -234,6 +235,10 @@ def main(argv: Optional[list] = None) -> int:
     p_write.add_argument("--path", required=True)
     p_write.add_argument("--kind", default="resource")
     p_write.add_argument("--base-url", default="https://emem.dev")
+    p_write.add_argument(
+        "--base",
+        help="to overwrite a note, the file_cid now at --path; omit for a new path",
+    )
     _add_body_args(p_write)
 
     args = parser.parse_args(argv)

{ememdev-2.4.2 → ememdev-2.4.5}/src/ememdev/signing.py

@@ -4,10 +4,15 @@ The emem responder gates every memory write verb (`create`,
 `str_replace`, `insert`, `delete`, `rename`) behind an `attester`
 block. The block binds the write to an ed25519 key:
 
-    sig = ed25519(blake3(b"emem.memory_write|" + verb + b"|"
-                         + path + b"|" + body_hash))
+    sig = ed25519(blake3(b"emem.memory_write.v2|" + verb + b"|"
+                         + path + b"|" + body_hash + b"|" + base))
 
-and travels on the wire as::
+`base` is the `file_cid` now at `path`, or `absent` when nothing is there.
+The v1 preimage (no `base`) is retired for memory writes: the responder
+refuses it. `attester_preimage` (v1) stays because `/v1/derive` and
+`/v1/entity` still sign under it.
+
+The block travels on the wire as::
 
     "attester": {"pubkey_b32": "<52 chars>", "sig_b32": "<103 chars>"}
 
@@ -78,8 +83,9 @@ _PREIMAGE_TAG = b"emem.memory_write|"
 _PREIMAGE_V2_TAG = b"emem.memory_write.v2|"
 #: What `base` is when nothing is at the path yet (emem_primitives::BASE_ABSENT).
 BASE_ABSENT = "absent"
-#: Verbs the responder refuses to verify under the v1 preimage.
-V2_REQUIRED_VERBS = ("delete", "rename")
+#: Verbs the responder refuses to verify under the v1 preimage: every
+#: write verb (lib.rs validate_attester_binding, reason v1_retired).
+V2_REQUIRED_VERBS = WRITE_VERBS
 _SEP = b"|"
 
 
@@ -238,23 +244,27 @@ class EmemSigner:
     def attester_block(
         self, verb: str, path: str, body: bytes = b"", base: Optional[str] = None
     ) -> dict:
-        """Build the wire `attester` block for one write.
+        """Build the wire `attester` block for one write, signed with the v2
+        preimage.
 
         `body` is the byte string the responder will hash for this verb
         (see the table in this module's docstring). It defaults to empty,
         which is right for `delete`. For `rename`, prefer
         `rename_attester_block`.
+
+        `base` is the `file_cid` now at `path`, or `BASE_ABSENT`. A `create`
+        without `base` signs `BASE_ABSENT`, which is right for a new note; to
+        overwrite a note, pass its current `file_cid`. Every other verb
+        changes a note that exists, so it must name the `base`.
         """
-        if base is None and verb in V2_REQUIRED_VERBS:
-            raise ValueError(
-                f"{verb} is refused under the v1 preimage; pass base= the file_cid "
-                "now at the path (for rename, use rename_attester_block)"
-            )
-        digest = (
-            attester_preimage_v2(verb, path, body_hash(body), base)
-            if base is not None
-            else attester_preimage(verb, path, body_hash(body))
-        )
+        if base is None:
+            if verb != "create":
+                raise ValueError(
+                    f"{verb} must be signed against base= the file_cid now at the path "
+                    "(for rename, use rename_attester_block)"
+                )
+            base = BASE_ABSENT
+        digest = attester_preimage_v2(verb, path, body_hash(body), base)
         return {
             "pubkey_b32": self.pubkey_b32,
             "sig_b32": b32_nopad_lc(self.sign_preimage(digest)),

ememdev-2.4.2/PKG-INFO

@@ -1,177 +0,0 @@
-Metadata-Version: 2.5
-Name: ememdev
-Version: 2.4.2
-Summary: Python client for emem: shared, verifiable memory for AI agents. One address per fact, one signature you can check. No key to read.
-Project-URL: Homepage, https://emem.dev
-Project-URL: Repository, https://github.com/Vortx-AI/emem
-Project-URL: Documentation, https://emem.dev/agents.md
-Project-URL: Issues, https://github.com/Vortx-AI/emem/issues
-Author-email: Vortx AI Private Limited <avijeet@vortx.ai>
-License: Apache-2.0
-License-File: LICENSE
-Keywords: agent-memory,ai-agents,content-addressed,earth-observation,ed25519,geospatial,mcp,model-context-protocol,provenance,satellite,shared-memory,verifiable
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: Intended Audience :: Science/Research
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Scientific/Engineering :: GIS
-Requires-Python: >=3.9
-Requires-Dist: httpx<1.0,>=0.27
-Provides-Extra: signing
-Requires-Dist: blake3>=0.3; extra == 'signing'
-Requires-Dist: cryptography>=41; extra == 'signing'
-Description-Content-Type: text/markdown
-
-# ememdev: Python client for emem.dev
-
-<!-- mcp-name: io.github.Vortx-AI/emem -->
-
-Thin, typed Python client for the [emem.dev](https://emem.dev) Earth memory
-protocol. Wraps the public REST surface in a single `Client` class that
-returns parsed JSON verbatim. Every ed25519-signed receipt and
-content-addressed CID is preserved for citation and offline verification.
-The current surface is whatever [`/openapi.json`](https://emem.dev/openapi.json)
-lists; this README does not restate a count that would go stale.
-
-## Install
-
-```bash
-pip install ememdev
-```
-
-The distribution and the import package are both named `ememdev` (so
-`pip install ememdev`, then `from ememdev import Client`); the shorter name
-`emem` on PyPI belongs to an unrelated project. To work from a checkout
-instead:
-
-```bash
-pip install -e sdks/emem-py
-```
-
-Requires Python 3.9+. The only runtime dependency is
-[`httpx`](https://www.python-httpx.org/). To sign memory writes (below),
-add the `signing` extra, which pulls `blake3` and `cryptography`:
-
-```bash
-pip install "ememdev[signing]"
-```
-
-## Quick start
-
-```python
-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"])
-```
-
-## Async
-
-```python
-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())
-```
-
-## Configuration
-
-| Env var               | Default              | Effect                                      |
-|-----------------------|----------------------|---------------------------------------------|
-| `EMEM_BASE_URL`       | `https://emem.dev`   | Responder root; point at a self-hosted node |
-| `EMEM_TIMEOUT_SECS`   | `180`                | HTTP timeout (matches gateway timeout)      |
-
-You can also pass `base_url=` and `timeout=` directly to the constructor.
-
-## Surface coverage
-
-Geocoder + read primitives, physics solvers, boring lat/lng shortcuts, and
-introspection — see the inline docstring on `emem.client` for the full
-endpoint → method mapping.
-
-## Writing a signed note
-
-Reads are anonymous. Writes into the agent memory namespace are gated by an
-ed25519 `attester` block, and that signature is the one thing the MCP client
-cannot produce for you. `ememdev[signing]` produces it, from a persistent
-identity, so leaving a signed note is one command rather than a hand-rolled
-crypto script.
-
-The identity is resolved once and reused every session, because the key is
-what owns your namespace at `/memories/by_attester/<pubkey8>/...`. Resolution
-order: `EMEM_AGENT_KEY` (a 64-char hex seed or a key-file path), then
-`~/.emem/agent_ed25519.pem` (override the directory with `EMEM_HOME`), minted
-`0600` on first use if absent.
-
-From the command line, for an agent that already speaks to emem over MCP:
-
-```bash
-ememdev whoami          # your pubkey and namespace_root
-
-# emit just the attester block, sign nothing else (no network):
-ememdev sign  --verb create --path /memories/by_attester/<you>/note.md --stdin < note.md
-
-# or sign a create and POST it to /mcp in one step:
-ememdev write --path /memories/by_attester/<you>/note.md --body-file note.md
-```
-
-Or in Python:
-
-```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.
-```
-
-`str_replace` and `insert` sign the whole file *after* the edit, and `rename`
-binds both ends of the move (`signer.rename_attester_block(old, new)`); see the
-`ememdev.signing` docstring for the per-verb body rule. A write into another
-key's namespace is refused with a 403, and `sign`/`write` refuse it locally
-first.
-
-## Receipts
-
-Every non-introspection response carries a `receipt` block with:
-
-- `responder_pubkey_b32` (ed25519 base32-nopad-lowercase)
-- `signature_b32` (ed25519 over the BLAKE3 preimage digest)
-- `preimage_version` (which rule signed it; read it, do not assume)
-- `merkle_proof` (inclusion proof for `fact_cids[0]`, when one was recorded)
-- `fact_cids[]` (the BLAKE3 CIDs of every fact returned)
-
-To cite an answer: quote `receipt.fact_cids[0]` and the responder pubkey.
-The signature can be verified offline against the public key at
-`https://emem.dev/.well-known/emem.json`; no callback to the responder is
-required.
-
-**Pass the receipt on whole.** `ememdev` returns it verbatim and you should
-store and forward it the same way. From `preimage_version: 2` the signature
-covers the inclusion proof as well as every other field it binds, which is
-what stops an intermediary stripping the proof in transit. The cost is that
-a receipt is byte-for-byte or nothing: drop `merkle_proof` because it looks
-redundant, re-key a field, or summarise the envelope, and it comes back
-`signature_valid: false` on data nobody tampered with — indistinguishable
-from forgery. `POST /v1/verify_receipt` reports `reason:
-receipt_reshaped_after_signing` instead of `signature_invalid` when the
-responder can prove that is what happened, but it never accepts the receipt.
-
-## License
-
-Apache-2.0. Same as the upstream protocol.

ememdev-2.4.2/README.md

@@ -1,147 +0,0 @@
-# ememdev: Python client for emem.dev
-
-<!-- mcp-name: io.github.Vortx-AI/emem -->
-
-Thin, typed Python client for the [emem.dev](https://emem.dev) Earth memory
-protocol. Wraps the public REST surface in a single `Client` class that
-returns parsed JSON verbatim. Every ed25519-signed receipt and
-content-addressed CID is preserved for citation and offline verification.
-The current surface is whatever [`/openapi.json`](https://emem.dev/openapi.json)
-lists; this README does not restate a count that would go stale.
-
-## Install
-
-```bash
-pip install ememdev
-```
-
-The distribution and the import package are both named `ememdev` (so
-`pip install ememdev`, then `from ememdev import Client`); the shorter name
-`emem` on PyPI belongs to an unrelated project. To work from a checkout
-instead:
-
-```bash
-pip install -e sdks/emem-py
-```
-
-Requires Python 3.9+. The only runtime dependency is
-[`httpx`](https://www.python-httpx.org/). To sign memory writes (below),
-add the `signing` extra, which pulls `blake3` and `cryptography`:
-
-```bash
-pip install "ememdev[signing]"
-```
-
-## Quick start
-
-```python
-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"])
-```
-
-## Async
-
-```python
-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())
-```
-
-## Configuration
-
-| Env var               | Default              | Effect                                      |
-|-----------------------|----------------------|---------------------------------------------|
-| `EMEM_BASE_URL`       | `https://emem.dev`   | Responder root; point at a self-hosted node |
-| `EMEM_TIMEOUT_SECS`   | `180`                | HTTP timeout (matches gateway timeout)      |
-
-You can also pass `base_url=` and `timeout=` directly to the constructor.
-
-## Surface coverage
-
-Geocoder + read primitives, physics solvers, boring lat/lng shortcuts, and
-introspection — see the inline docstring on `emem.client` for the full
-endpoint → method mapping.
-
-## Writing a signed note
-
-Reads are anonymous. Writes into the agent memory namespace are gated by an
-ed25519 `attester` block, and that signature is the one thing the MCP client
-cannot produce for you. `ememdev[signing]` produces it, from a persistent
-identity, so leaving a signed note is one command rather than a hand-rolled
-crypto script.
-
-The identity is resolved once and reused every session, because the key is
-what owns your namespace at `/memories/by_attester/<pubkey8>/...`. Resolution
-order: `EMEM_AGENT_KEY` (a 64-char hex seed or a key-file path), then
-`~/.emem/agent_ed25519.pem` (override the directory with `EMEM_HOME`), minted
-`0600` on first use if absent.
-
-From the command line, for an agent that already speaks to emem over MCP:
-
-```bash
-ememdev whoami          # your pubkey and namespace_root
-
-# emit just the attester block, sign nothing else (no network):
-ememdev sign  --verb create --path /memories/by_attester/<you>/note.md --stdin < note.md
-
-# or sign a create and POST it to /mcp in one step:
-ememdev write --path /memories/by_attester/<you>/note.md --body-file note.md
-```
-
-Or in Python:
-
-```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.
-```
-
-`str_replace` and `insert` sign the whole file *after* the edit, and `rename`
-binds both ends of the move (`signer.rename_attester_block(old, new)`); see the
-`ememdev.signing` docstring for the per-verb body rule. A write into another
-key's namespace is refused with a 403, and `sign`/`write` refuse it locally
-first.
-
-## Receipts
-
-Every non-introspection response carries a `receipt` block with:
-
-- `responder_pubkey_b32` (ed25519 base32-nopad-lowercase)
-- `signature_b32` (ed25519 over the BLAKE3 preimage digest)
-- `preimage_version` (which rule signed it; read it, do not assume)
-- `merkle_proof` (inclusion proof for `fact_cids[0]`, when one was recorded)
-- `fact_cids[]` (the BLAKE3 CIDs of every fact returned)
-
-To cite an answer: quote `receipt.fact_cids[0]` and the responder pubkey.
-The signature can be verified offline against the public key at
-`https://emem.dev/.well-known/emem.json`; no callback to the responder is
-required.
-
-**Pass the receipt on whole.** `ememdev` returns it verbatim and you should
-store and forward it the same way. From `preimage_version: 2` the signature
-covers the inclusion proof as well as every other field it binds, which is
-what stops an intermediary stripping the proof in transit. The cost is that
-a receipt is byte-for-byte or nothing: drop `merkle_proof` because it looks
-redundant, re-key a field, or summarise the envelope, and it comes back
-`signature_valid: false` on data nobody tampered with — indistinguishable
-from forgery. `POST /v1/verify_receipt` reports `reason:
-receipt_reshaped_after_signing` instead of `signature_invalid` when the
-responder can prove that is what happened, but it never accepts the receipt.
-
-## License
-
-Apache-2.0. Same as the upstream protocol.