attested-memory 0.1.0__py3-none-any.whl

attested_memory/__init__.py

@@ -0,0 +1,9 @@
+"""Python client for Attested Memory — verifiable memory for AI agents."""
+
+__version__ = "0.1.0"
+
+from .actor import Actor  # noqa: E402
+from .client import AttestedMemoryError, Client, IntegrityError, check_integrity, content_hash  # noqa: E402
+
+__all__ = ["Actor", "AttestedMemoryError", "Client", "IntegrityError", "check_integrity", "content_hash",
+           "__version__"]

attested_memory/actor.py

@@ -0,0 +1,96 @@
+"""The signed actor identity every protected Attested Memory call carries.
+
+Wire format (the same in the Memory Market, the SaaS gateway and the product shells):
+
+* ``X-Actor-ID``         ``did:actor:`` + hex SHA-256 of the raw Ed25519 public key (74 chars)
+* ``X-Actor-Public-Key`` the raw 32-byte public key, base64url
+* ``X-Actor-Timestamp``  unix seconds; the server accepts five minutes of skew
+* ``X-Actor-Nonce``      16-64 url-safe characters, good for exactly one request
+* ``X-Actor-Signature``  Ed25519 over ``<actor id>\\n<timestamp>\\n<nonce>``, base64url
+
+A captured header set therefore replays nowhere: it is bound to one nonce and expires.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import os
+import secrets
+import time
+from pathlib import Path
+
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+
+def _b64url(raw: bytes) -> str:
+    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii")
+
+
+def _from_b64url(text: str) -> bytes:
+    return base64.urlsafe_b64decode(text + "=" * (-len(text) % 4))
+
+
+class Actor:
+    """An Ed25519 identity. The private key never leaves this object or its key file."""
+
+    def __init__(self, private_key: Ed25519PrivateKey) -> None:
+        self._key = private_key
+        self._public = private_key.public_key().public_bytes(
+            serialization.Encoding.Raw, serialization.PublicFormat.Raw
+        )
+
+    @classmethod
+    def generate(cls) -> "Actor":
+        return cls(Ed25519PrivateKey.generate())
+
+    @classmethod
+    def from_seed(cls, seed_b64url: str) -> "Actor":
+        seed = _from_b64url(seed_b64url)
+        if len(seed) != 32:
+            raise ValueError("an actor seed is 32 bytes")
+        return cls(Ed25519PrivateKey.from_private_bytes(seed))
+
+    @classmethod
+    def load(cls, path: str | os.PathLike[str]) -> "Actor":
+        data = json.loads(Path(path).read_text(encoding="utf-8"))
+        actor = cls.from_seed(data["seed"])
+        if data.get("actor_id") and data["actor_id"] != actor.actor_id:
+            raise ValueError(f"{path}: actor_id does not match the stored key")
+        return actor
+
+    def save(self, path: str | os.PathLike[str]) -> Path:
+        """Write the key file with mode 0600; refuses to overwrite an existing one."""
+        target = Path(path)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        seed = self._key.private_bytes(
+            serialization.Encoding.Raw, serialization.PrivateFormat.Raw, serialization.NoEncryption()
+        )
+        body = json.dumps({"actor_id": self.actor_id, "seed": _b64url(seed)}, indent=2) + "\n"
+        fd = os.open(target, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+        with os.fdopen(fd, "w", encoding="utf-8") as stream:
+            stream.write(body)
+        return target
+
+    @property
+    def public_key(self) -> str:
+        return _b64url(self._public)
+
+    @property
+    def actor_id(self) -> str:
+        return "did:actor:" + hashlib.sha256(self._public).hexdigest()
+
+    def proof_headers(self, *, now: float | None = None, nonce: str | None = None) -> dict[str, str]:
+        """Fresh headers for ONE request (a new nonce each call)."""
+        timestamp = str(int(time.time() if now is None else now))
+        nonce = nonce or secrets.token_urlsafe(24)
+        message = f"{self.actor_id}\n{timestamp}\n{nonce}".encode()
+        return {
+            "X-Actor-ID": self.actor_id,
+            "X-Actor-Public-Key": self.public_key,
+            "X-Actor-Timestamp": timestamp,
+            "X-Actor-Nonce": nonce,
+            "X-Actor-Signature": _b64url(self._key.sign(message)),
+        }

attested_memory/cli.py

@@ -0,0 +1,152 @@
+"""attested-memory — command line for the Attested Memory API.
+
+    attested-memory init                     # create your actor key (~/.config/attested-memory)
+    attested-memory trial                    # claim the 7-day personal key for that actor
+    attested-memory write "Title" "Text"     # or: --file notes.md
+    attested-memory search "supplier"
+    attested-memory read mem_…
+
+Environment: ATTESTED_MEMORY_HOME (config dir), ATTESTED_MEMORY_URL (default
+https://attestedmemory.net), ATTESTED_MEMORY_API_KEY (instead of the stored trial key).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+from . import __version__
+from .actor import Actor
+from .client import DEFAULT_BASE_URL, AttestedMemoryError, Client
+
+
+def _home() -> Path:
+    return Path(os.environ.get("ATTESTED_MEMORY_HOME") or Path.home() / ".config" / "attested-memory")
+
+
+def _actor_path() -> Path:
+    return _home() / "actor.json"
+
+
+def _key_path() -> Path:
+    return _home() / "key.json"
+
+
+def _load_actor() -> Actor:
+    path = _actor_path()
+    if not path.exists():
+        raise SystemExit(f"no actor key at {path} — run: attested-memory init")
+    return Actor.load(path)
+
+
+def _write_private(path: Path, payload: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w", encoding="utf-8") as stream:
+        json.dump(payload, stream, indent=2)
+        stream.write("\n")
+
+
+def _client(args: argparse.Namespace, *, need_key: bool = True) -> Client:
+    api_key = os.environ.get("ATTESTED_MEMORY_API_KEY")
+    if not api_key and _key_path().exists():
+        api_key = json.loads(_key_path().read_text(encoding="utf-8")).get("api_key")
+    if need_key and not api_key:
+        raise SystemExit("no API key — run: attested-memory trial (or set ATTESTED_MEMORY_API_KEY)")
+    return Client(_load_actor(), api_key, base_url=args.url)
+
+
+def _print(value: Any) -> None:
+    print(json.dumps(value, indent=2, ensure_ascii=False))
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    path = _actor_path()
+    if path.exists():
+        print(f"actor already exists: {Actor.load(path).actor_id}  ({path})")
+        return 0
+    actor = Actor.generate()
+    actor.save(path)
+    print(f"created {actor.actor_id}\nkey file: {path} (mode 0600 — keep it; it is your identity)")
+    return 0
+
+
+def cmd_whoami(args: argparse.Namespace) -> int:
+    actor = _load_actor()
+    print(actor.actor_id)
+    if _key_path().exists():
+        stored = json.loads(_key_path().read_text(encoding="utf-8"))
+        print(f"key: {stored.get('product')} {stored.get('plan')} until {stored.get('expires_at')}")
+    return 0
+
+
+def cmd_trial(args: argparse.Namespace) -> int:
+    client = _client(args, need_key=False)
+    result = client.start_trial(args.product)
+    _write_private(_key_path(), {k: result.get(k) for k in ("api_key", "product", "plan", "expires_at", "key_id")})
+    print(f"{result.get('plan')} until {result.get('expires_at')} — key saved to {_key_path()}")
+    return 0
+
+
+def cmd_write(args: argparse.Namespace) -> int:
+    content = Path(args.file).read_text(encoding="utf-8") if args.file else args.content
+    if not content:
+        raise SystemExit("give the text as an argument or with --file")
+    _print(_client(args).write(args.title, content, tags=args.tag or (), visibility=args.visibility,
+                               source_refs=args.source or ()))
+    return 0
+
+
+def cmd_read(args: argparse.Namespace) -> int:
+    _print(_client(args).read(args.memory_id))
+    return 0
+
+
+def cmd_search(args: argparse.Namespace) -> int:
+    _print(_client(args).search(args.query, args.limit))
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="attested-memory", description="Verifiable memory for AI agents.")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    parser.add_argument("--url", default=os.environ.get("ATTESTED_MEMORY_URL", DEFAULT_BASE_URL))
+    sub = parser.add_subparsers(dest="command", required=True)
+    sub.add_parser("init", help="create your actor key").set_defaults(func=cmd_init)
+    sub.add_parser("whoami", help="show your actor id and key").set_defaults(func=cmd_whoami)
+    trial = sub.add_parser("trial", help="claim the free trial key for your actor")
+    trial.add_argument("--product", default="personal", choices=["personal", "team", "expert-market"])
+    trial.set_defaults(func=cmd_trial)
+    write = sub.add_parser("write", help="store a memory")
+    write.add_argument("title")
+    write.add_argument("content", nargs="?")
+    write.add_argument("--file")
+    write.add_argument("--tag", action="append")
+    write.add_argument("--source", action="append", help="a source reference (URL, doc id)")
+    write.add_argument("--visibility", default="private", choices=["private", "shared", "public", "paid"])
+    write.set_defaults(func=cmd_write)
+    read = sub.add_parser("read", help="read a memory (content checked against its hash)")
+    read.add_argument("memory_id")
+    read.set_defaults(func=cmd_read)
+    search = sub.add_parser("search", help="search memories you can see")
+    search.add_argument("query", nargs="?", default="")
+    search.add_argument("--limit", type=int, default=30)
+    search.set_defaults(func=cmd_search)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return args.func(args)
+    except AttestedMemoryError as error:
+        print(f"attested-memory: {error}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

attested_memory/client.py

@@ -0,0 +1,119 @@
+"""HTTP client for the public Attested Memory API (Personal Memory product).
+
+    actor = Actor.generate()
+    client = Client(actor)
+    client.start_trial()                      # 7-day personal key, bound to this actor
+    unit = client.write("Supplier terms", "Net 30, EUR, signed 2026-09-01", tags=["finance"])
+    client.read(unit["id"])                   # content checked against its content_hash
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Iterable
+
+from . import __version__
+from .actor import Actor
+
+DEFAULT_BASE_URL = "https://attestedmemory.net"
+
+
+class AttestedMemoryError(Exception):
+    """The service refused or failed a request; ``status`` is the HTTP code (0 = network)."""
+
+    def __init__(self, status: int, detail: str) -> None:
+        super().__init__(f"HTTP {status}: {detail}" if status else detail)
+        self.status = status
+        self.detail = detail
+
+
+class IntegrityError(AttestedMemoryError):
+    """A memory's content does not hash to the content_hash the service reported."""
+
+
+def content_hash(content: str) -> str:
+    """The Memory Market's hash of a memory's text: ``sha256:`` + hex."""
+    return "sha256:" + hashlib.sha256(content.encode("utf-8")).hexdigest()
+
+
+def check_integrity(unit: dict[str, Any]) -> dict[str, Any]:
+    """Raise IntegrityError unless ``unit['content']`` hashes to ``unit['content_hash']``.
+
+    This is checked here, on the client, not taken from the service. The truth and
+    provenance states in the same object are what the hub reports.
+    """
+    if "content" in unit and unit.get("content_hash") != content_hash(unit["content"]):
+        raise IntegrityError(0, f"memory {unit.get('id')}: content does not match its content_hash")
+    return unit
+
+
+class Client:
+    def __init__(self, actor: Actor, api_key: str | None = None, *,
+                 base_url: str = DEFAULT_BASE_URL, timeout: float = 20.0) -> None:
+        self.actor = actor
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    # --- account -------------------------------------------------------------------------
+    def start_trial(self, product: str = "personal") -> dict[str, Any]:
+        """Claim the free trial key for this actor (one per actor and product) and keep it."""
+        result = self._request("POST", "/api/v1/trials", {"product": product}, need_key=False)
+        self.api_key = result.get("api_key") or self.api_key
+        return result
+
+    def key_status(self, product: str = "personal") -> dict[str, Any]:
+        return self._request("GET", "/api/v1/keys/me?" + urllib.parse.urlencode({"product": product}))
+
+    # --- memory --------------------------------------------------------------------------
+    def write(self, title: str, content: str, *, tags: Iterable[str] = (), visibility: str = "private",
+              source_refs: Iterable[str] = (), parent_memory_ids: Iterable[str] = (),
+              price_usdc: str | None = None) -> dict[str, Any]:
+        body = {"title": title, "content": content, "tags": list(tags), "visibility": visibility,
+                "source_refs": list(source_refs), "parent_memory_ids": list(parent_memory_ids),
+                "price_usdc": price_usdc}
+        return check_integrity(self._request("POST", "/memory/api/memories", body))
+
+    def read(self, memory_id: str) -> dict[str, Any]:
+        path = "/memory/api/memories/" + urllib.parse.quote(memory_id, safe="")
+        return check_integrity(self._request("GET", path))
+
+    def search(self, query: str = "", limit: int = 30) -> dict[str, Any]:
+        params = urllib.parse.urlencode({"q": query, "limit": max(1, min(int(limit), 100))})
+        return self._request("GET", "/memory/api/search?" + params)
+
+    # --- transport -----------------------------------------------------------------------
+    def _request(self, method: str, path: str, body: dict[str, Any] | None = None, *,
+                 need_key: bool = True) -> Any:
+        headers = {"Accept": "application/json", "User-Agent": f"attested-memory-python/{__version__}",
+                   **self.actor.proof_headers()}
+        if need_key:
+            if not self.api_key:
+                raise AttestedMemoryError(0, "no API key: call start_trial() or pass api_key")
+            headers["X-SaaS-Key"] = self.api_key
+        data = None
+        if body is not None:
+            data = json.dumps(body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        request = urllib.request.Request(self.base_url + path, data=data, method=method, headers=headers)
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                raw = response.read()
+        except urllib.error.HTTPError as error:
+            raise AttestedMemoryError(error.code, _detail(error.read())) from None
+        except (urllib.error.URLError, TimeoutError, OSError) as error:
+            raise AttestedMemoryError(0, f"cannot reach {self.base_url}: {error}") from None
+        return json.loads(raw) if raw else {}
+
+
+def _detail(raw: bytes) -> str:
+    try:
+        payload = json.loads(raw)
+    except ValueError:
+        return raw.decode("utf-8", "replace")[:300]
+    detail = payload.get("detail") if isinstance(payload, dict) else None
+    return str(detail if detail is not None else payload)[:300]

attested_memory-0.1.0.dist-info/METADATA

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: attested-memory
+Version: 0.1.0
+Summary: Client and CLI for Attested Memory: write, search and read verifiable AI-agent memory under a signed Ed25519 actor identity.
+Project-URL: Homepage, https://attestedmemory.net/
+Project-URL: Source, https://github.com/alexar76/attested-memory
+Author: AIMarket
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agent-memory,ai-agents,ed25519,memory-poisoning,provenance,verifiable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.9
+Requires-Dist: cryptography>=41
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# attested-memory
+
+Python client and CLI for [Attested Memory](https://attestedmemory.net/) — verifiable memory
+for AI agents. Every call is signed by your own Ed25519 **actor** key; the private key never
+leaves your machine. A memory you read is checked here, on the client, against the
+`content_hash` the hub recorded, so a changed text is refused instead of trusted.
+
+```bash
+pip install attested-memory
+attested-memory init                      # your actor key → ~/.config/attested-memory/actor.json (0600)
+attested-memory trial                     # 7-day personal key, bound to that actor
+attested-memory write "Supplier terms" "Net 30, EUR, signed 2026-09-01" --tag finance --source contract-17
+attested-memory search supplier
+attested-memory read mem_…
+```
+
+```python
+from attested_memory import Actor, Client
+
+actor = Actor.generate()              # or Actor.load("actor.json")
+client = Client(actor)
+client.start_trial()                  # or Client(actor, api_key="ask_…")
+unit = client.write("Supplier terms", "Net 30", tags=["finance"])
+client.read(unit["id"])               # raises IntegrityError if the text does not match its hash
+```
+
+What is checked where:
+
+| | where |
+|---|---|
+| your identity (`did:actor:` + SHA-256 of your public key) and a one-time signed proof per request | client signs, server verifies |
+| the text of a memory matches its `content_hash` | **this client** |
+| `truth` (supported / contested / rejected) and `provenance` (attested receipt) | reported by the hub |
+
+The proof is a signature over `<actor id>\n<unix seconds>\n<nonce>`: good for five minutes and
+one request, so a captured header set replays nowhere.
+
+Environment for the CLI: `ATTESTED_MEMORY_HOME`, `ATTESTED_MEMORY_URL`, `ATTESTED_MEMORY_API_KEY`.
+
+Apache-2.0. Source: [alexar76/attested-memory](https://github.com/alexar76/attested-memory) (`clients/python`).

attested_memory-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+attested_memory/__init__.py,sha256=lyzStnftEkJJ84sRPPEe53cl2C6izfyiALK3mZuswds,382
+attested_memory/actor.py,sha256=hkiQkzdHOrJV0_IIa-ZaklGcw9NTqHlQ8UzxfxxR3Ns,3708
+attested_memory/cli.py,sha256=NUgSHKlG47_eaanSB7MG_2Qo1u6rpejSze5xuWrVaAA,5787
+attested_memory/client.py,sha256=-xEDXmdBg5qaGNl1O419D6ZleEOTsq-fVrJjEQd97uo,5453
+attested_memory-0.1.0.dist-info/METADATA,sha256=BIXlGNDhJPooRvg-xvGXBbSriNYPa4UOnkInFXPcr7U,2698
+attested_memory-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+attested_memory-0.1.0.dist-info/entry_points.txt,sha256=1csrTCjvea6Byg2l9bXdqkO-yv5Z3b8MSrObVgAPXkI,61
+attested_memory-0.1.0.dist-info/licenses/LICENSE,sha256=FkIqCjBmfAAgdAOWCOggpfp-BEHHObGox599lEvM-l8,647
+attested_memory-0.1.0.dist-info/RECORD,,

attested_memory-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

attested_memory-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+attested-memory = attested_memory.cli:main

attested_memory-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,17 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+Copyright 2026 Attested Memory Hub contributors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.