localmem-memory 0.1.0__tar.gz

localmem_memory-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   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.

localmem_memory-0.1.0/NOTICE

@@ -0,0 +1,5 @@
+localmem Memory API SDK
+Copyright 2026 Vijay Yadav, doing business as localmem.org.
+
+Licensed under the Apache License, Version 2.0 (LICENSE). "localmem" is a
+name of localmem.org; the licence grants no right to use it (section 6).

localmem_memory-0.1.0/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: localmem-memory
+Version: 0.1.0
+Summary: The localmem Memory API: memory of each of your customers, with the source and date of every fact. `localmem-memory login` pairs a terminal with a project.
+License: Apache-2.0
+Project-URL: Homepage, https://localmem.org/docs/memory-api/sdks
+Classifier: License :: OSI Approved :: Apache Software License
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Dynamic: license-file
+
+# localmem-memory
+
+The localmem Memory API from Python: memory of each of your customers, with
+the source and date of every fact. Standard library only. Server-side only.
+
+```sh
+pip install localmem-memory
+localmem-memory login     # pair this terminal: approve the code in the browser
+```
+
+```python
+from localmem_memory import Memory
+
+lm = Memory()  # reads LOCALMEM_PROJECT, LOCALMEM_KEY_ID, LOCALMEM_KEY_SECRET
+tenant = lm.customers.create("cust-42")["tenant"]
+lm.documents.send(tenant, "Ada Byron joined Acme on 3 March.")
+print(lm.recall(tenant, "Ada Byron")["facts"])
+```
+
+Docs: https://localmem.org/docs/memory-api/sdks · Support: support@localmem.org

localmem_memory-0.1.0/README.md

@@ -0,0 +1,20 @@
+# localmem-memory
+
+The localmem Memory API from Python: memory of each of your customers, with
+the source and date of every fact. Standard library only. Server-side only.
+
+```sh
+pip install localmem-memory
+localmem-memory login     # pair this terminal: approve the code in the browser
+```
+
+```python
+from localmem_memory import Memory
+
+lm = Memory()  # reads LOCALMEM_PROJECT, LOCALMEM_KEY_ID, LOCALMEM_KEY_SECRET
+tenant = lm.customers.create("cust-42")["tenant"]
+lm.documents.send(tenant, "Ada Byron joined Acme on 3 March.")
+print(lm.recall(tenant, "Ada Byron")["facts"])
+```
+
+Docs: https://localmem.org/docs/memory-api/sdks · Support: support@localmem.org

localmem_memory-0.1.0/localmem_memory/__init__.py

@@ -0,0 +1,6 @@
+"""localmem-memory: the localmem Memory API from Python (specs/037 R55)."""
+
+from .client import DEFAULT_API, LocalmemError, Memory, sign
+
+__all__ = ["DEFAULT_API", "LocalmemError", "Memory", "sign"]
+__version__ = "0.1.0"

localmem_memory-0.1.0/localmem_memory/cli.py

@@ -0,0 +1,155 @@
+"""``localmem-memory login`` (specs/037 R53): pairs this terminal with a
+project, as ``npx @localmem/memory login`` does. It asks for a pairing,
+prints the code, opens the approval page, and polls with its device secret
+until the key is handed to it once; then writes the three variables into
+.env (or --env-file) and keeps that file out of git. The secret is never
+printed.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import socket
+import subprocess
+import sys
+import time
+import urllib.error
+import urllib.request
+import webbrowser
+from typing import Callable, Dict, Tuple
+
+from .client import DEFAULT_API
+
+
+def post(url: str, body: dict) -> Tuple[int, dict]:
+    req = urllib.request.Request(
+        url, data=json.dumps(body).encode(), method="POST", headers={"content-type": "application/json"}
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=30) as r:
+            status, raw = r.status, r.read()
+    except urllib.error.HTTPError as e:
+        status, raw = e.code, e.read()
+    try:
+        return status, json.loads(raw) if raw else {}
+    except ValueError:
+        return status, {"message": raw[:200].decode(errors="replace")}
+
+
+def _read(path: str) -> str:
+    if not os.path.exists(path):
+        return ""
+    with open(path, encoding="utf8") as f:
+        return f.read()
+
+
+def with_vars(text: str, values: Dict[str, str]) -> str:
+    """``text`` with each of ``values`` set: an existing line replaced, a new one appended."""
+    lines = text.rstrip("\n").split("\n") if text else []
+    for k, v in values.items():
+        pattern = re.compile(rf"^\s*(export\s+)?{re.escape(k)}\s*=")
+        at = next((i for i, l in enumerate(lines) if pattern.match(l)), None)
+        if at is None:
+            lines.append(f"{k}={v}")
+        else:
+            lines[at] = f"{k}={v}"
+    return "\n".join(lines) + "\n"
+
+
+def keep_out_of_git(path: str) -> str:
+    """Nothing when git already ignores ``path``, else its name added to the .gitignore beside it."""
+    folder, name = os.path.split(os.path.abspath(path))
+    try:
+        checked = subprocess.run(["git", "check-ignore", "-q", name], cwd=folder, capture_output=True).returncode
+    except OSError:
+        checked = 128
+    if checked == 0:
+        return f"{name} is already ignored by git."
+    ignore = os.path.join(folder, ".gitignore")
+    have = _read(ignore)
+    if checked != 1 and any(l.strip() in (name, f"/{name}") for l in have.split("\n")):
+        return f"{name} is already in .gitignore."
+    with open(ignore, "a", encoding="utf8") as f:
+        f.write(("\n" if have and not have.endswith("\n") else "") + name + "\n")
+    return f"Added {name} to .gitignore, so the secret is never committed."
+
+
+def login(
+    api: str,
+    env_file: str,
+    device: str,
+    browser: bool,
+    log: Callable[[str], None] = print,
+    send: Callable[[str, dict], Tuple[int, dict]] = post,
+    sleep: Callable[[float], None] = time.sleep,
+    open_url: Callable[[str], object] = webbrowser.open,
+) -> int:
+    status, opened = send(f"{api}/v1/pair", {"device": device})
+    if status != 201:
+        log(f"Could not start pairing: {opened.get('message') or f'localmem answered {status}'}")
+        return 1
+    until = time.monotonic() + float(opened.get("expires_in", 600))
+    log(f"Your code: {opened['code']}")
+    log(f"Approve it at {opened['url']}")
+    if browser:
+        try:
+            open_url(opened["url"])
+        except Exception:
+            pass  # The link is printed; opening it is a courtesy.
+    log("Waiting for approval…")
+    while True:
+        sleep(float(opened.get("interval", 3)))
+        if time.monotonic() > until:
+            log("The code expired before it was approved. Run `localmem-memory login` again.")
+            return 1
+        try:
+            status, said = send(f"{api}/v1/pair/{opened['pairing']}/token", {"device_secret": opened["device_secret"]})
+        except OSError:
+            continue
+        if status == 202 or status == 429 or status >= 500:
+            continue
+        if status != 200:
+            log(said.get("message") or "This pairing has ended. Run `localmem-memory login` again.")
+            return 1
+        values = {
+            "LOCALMEM_PROJECT": said["project"],
+            "LOCALMEM_KEY_ID": said["key_id"],
+            "LOCALMEM_KEY_SECRET": said["secret"],
+        }
+        if api != DEFAULT_API:
+            values["LOCALMEM_API_URL"] = api
+        existed = os.path.exists(env_file)
+        text = _read(env_file)
+        with open(env_file, "w", encoding="utf8") as f:
+            f.write(with_vars(text, values))
+        if not existed:
+            os.chmod(env_file, 0o600)
+        log(f"Paired with project {said['project']}: a test key, {said['key_id']}.")
+        log(f"Wrote {', '.join(values)} to {env_file}. The secret is not shown here.")
+        log(keep_out_of_git(env_file))
+        return 0
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(
+        prog="localmem-memory",
+        description="Pairs this terminal with a localmem project: approve the code it prints in the browser, and a test key is written to your .env file.",
+    )
+    sub = p.add_subparsers(dest="command")
+    l = sub.add_parser("login", help="pair this terminal with a project")
+    l.add_argument("--env-file", default=".env")
+    l.add_argument("--device", default=(socket.gethostname() or "a terminal")[:60])
+    l.add_argument("--api", default=os.environ.get("LOCALMEM_API_URL", DEFAULT_API))
+    l.add_argument("--no-browser", action="store_true")
+    a = p.parse_args(argv)
+    if a.command != "login":
+        p.print_help()
+        return 0 if a.command is None else 2
+    return login(a.api.rstrip("/"), a.env_file, a.device, not a.no_browser)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

localmem_memory-0.1.0/localmem_memory/client.py

@@ -0,0 +1,251 @@
+"""The localmem Memory API from Python (specs/037 R55).
+
+Reads LOCALMEM_PROJECT, LOCALMEM_KEY_ID and LOCALMEM_KEY_SECRET (written by
+``localmem-memory login``), signs every request as the gateway checks it
+(033 R2), sends an Idempotency-Key with every document and retries it on a
+timeout or a 5xx, honours Retry-After, and raises LocalmemError with the
+gateway's ``{ error, message }``. Standard library only. Server-side only:
+the secret must never reach a browser.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import os
+import random
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from typing import Any, Callable, Dict, Optional
+
+DEFAULT_API = "https://api.localmem.org"
+# The longest Retry-After waited for; past it the error is raised at once.
+MAX_WAIT_SECONDS = 60
+
+Json = Dict[str, Any]
+
+
+class LocalmemError(Exception):
+    """An answer that is not a success: the gateway's code and its words."""
+
+    def __init__(self, status: int, body: Json, request_id: Optional[str], retry_after: Optional[int]):
+        self.status = status
+        self.error = body.get("error") if isinstance(body.get("error"), str) else f"http_{status}"
+        self.message = body.get("message") if isinstance(body.get("message"), str) else f"localmem answered {status}"
+        self.request_id = request_id
+        self.retry_after = retry_after
+        self.body = body
+        super().__init__(self.message)
+
+
+def sign(secret: str, timestamp: str, method: str, path: str, body: bytes) -> str:
+    """The hex HMAC-SHA256 the gateway checks: ``timestamp.METHOD.path.body``, the path without its query."""
+    bare = path.split("?", 1)[0]
+    signed = f"{timestamp}.{method}.{bare}.".encode() + body
+    return hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
+
+
+def _env(name: str) -> Optional[str]:
+    v = os.environ.get(name, "").strip()
+    return v or None
+
+
+def _backoff(attempt: int) -> float:
+    """0.5 s, 1 s, 2 s ... with jitter, at most 8 s."""
+    return min(8.0, 0.5 * 2**attempt) * (0.5 + random.random() / 2)
+
+
+class Transport:
+    """One HTTP exchange: (status, headers, body bytes). Raises OSError on no answer."""
+
+    def __call__(self, method: str, url: str, headers: Dict[str, str], body: Optional[bytes], timeout: float):
+        req = urllib.request.Request(url, data=body, method=method, headers=headers)
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as r:
+                return r.status, dict(r.headers), r.read()
+        except urllib.error.HTTPError as e:
+            return e.code, dict(e.headers or {}), e.read()
+
+
+class _Customers:
+    def __init__(self, m: "Memory"):
+        self._m = m
+
+    def create(self, external_ref: str, phi: Optional[bool] = None) -> Json:
+        """Made once per ``external_ref``: the same one again answers the same customer."""
+        body: Json = {"external_ref": external_ref}
+        if phi is not None:
+            body["phi"] = phi
+        return self._m._call("POST", "/v1/partner/tenants", body=body)
+
+    def list(self) -> Json:
+        return self._m._call("GET", "/v1/partner/tenants")
+
+    def get(self, tenant: str) -> Json:
+        return self._m._call("GET", f"/v1/partner/tenants/{urllib.parse.quote(tenant, safe='')}")
+
+    def delete(self, tenant: str) -> Json:
+        """Access stops at once; see the data contract for what follows."""
+        return self._m._call("DELETE", f"/v1/partner/tenants/{urllib.parse.quote(tenant, safe='')}")
+
+
+class _Documents:
+    def __init__(self, m: "Memory"):
+        self._m = m
+
+    def send(self, tenant: str, text: str, *, idempotency_key: Optional[str] = None, **fields: Any) -> Json:
+        """Sends a document (``title``, ``as_of``, ``tags``, ``external_ref`` as keywords),
+        with an Idempotency-Key so a retry never reads it twice. Answers the written
+        facts, or ``{ status, follow }`` when it is read in the background: pass its
+        ``document_id`` to :meth:`wait`."""
+        return self._m._call(
+            "POST",
+            "/v1/memory/documents",
+            body={"text": text, **fields},
+            tenant=tenant,
+            headers={"Idempotency-Key": idempotency_key or str(uuid.uuid4())},
+            repeatable=True,
+        )
+
+    def get(self, tenant: str, document_id: str) -> Json:
+        return self._m._call(
+            "GET", f"/v1/memory/documents/{urllib.parse.quote(document_id, safe='')}", tenant=tenant
+        )
+
+    def wait(self, tenant: str, document_id: str, timeout: float = 600, every: float = 5) -> Json:
+        """Polls a background document until it is written or failed."""
+        until = time.monotonic() + timeout
+        while True:
+            d = self.get(tenant, document_id)
+            if d.get("status") in ("written", "failed") or time.monotonic() > until:
+                return d
+            self._m._sleep(every)
+
+
+class Memory:
+    """A project's key, signing each request."""
+
+    def __init__(
+        self,
+        project: Optional[str] = None,
+        key_id: Optional[str] = None,
+        secret: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 120,
+        max_retries: int = 3,
+        transport: Optional[Callable[..., Any]] = None,
+        sleep: Callable[[float], None] = time.sleep,
+    ):
+        project = project or _env("LOCALMEM_PROJECT")
+        key_id = key_id or _env("LOCALMEM_KEY_ID")
+        secret = secret or _env("LOCALMEM_KEY_SECRET")
+        missing = [n for n, v in (("LOCALMEM_PROJECT", project), ("LOCALMEM_KEY_ID", key_id), ("LOCALMEM_KEY_SECRET", secret)) if not v]
+        if missing:
+            raise ValueError(f"Set {', '.join(missing)}: run `localmem-memory login`, or pass them to Memory().")
+        self.project, self.key_id, self._secret = project, key_id, secret
+        self.base_url = (base_url or _env("LOCALMEM_API_URL") or DEFAULT_API).rstrip("/")
+        self._timeout, self._max_retries = timeout, max_retries
+        self._transport = transport or Transport()
+        self._sleep = sleep
+        self.customers = _Customers(self)
+        self.documents = _Documents(self)
+
+    def facts(self, tenant: str, **body: Any) -> Json:
+        """Facts you extracted yourself: nothing goes to a model."""
+        return self._memory("facts", tenant, body)
+
+    def write(self, tenant: str, content: str, **body: Any) -> Json:
+        return self._memory("write", tenant, {"content": content, **body})
+
+    def search(self, tenant: str, query: str, **body: Any) -> Json:
+        return self._memory("search", tenant, {"query": query, **body})
+
+    def recall(self, tenant: str, entity: str, **body: Any) -> Json:
+        """What is known about ``entity``, now or at ``at_time``."""
+        return self._memory("recall", tenant, {"entity": entity, **body})
+
+    def get(self, tenant: str, event_id: str) -> Json:
+        return self._memory("get", tenant, {"event_id": event_id})
+
+    def profile(self, tenant: str, **body: Any) -> Json:
+        return self._memory("profile", tenant, body)
+
+    def forget(self, tenant: str, target_id: str) -> Json:
+        """Hides it from answers from now on; it does not destroy it."""
+        return self._memory("forget", tenant, {"target_id": target_id})
+
+    def usage(self, from_: Optional[str] = None, to: Optional[str] = None) -> Json:
+        """One entry per customer and day, both dates included (YYYY-MM-DD)."""
+        q = urllib.parse.urlencode({k: v for k, v in (("from", from_), ("to", to)) if v})
+        return self._call("GET", f"/v1/partner/usage{'?' + q if q else ''}")
+
+    def _memory(self, route: str, tenant: str, body: Json) -> Json:
+        return self._call("POST", f"/v1/memory/{route}", body=body, tenant=tenant)
+
+    def _call(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Json] = None,
+        tenant: Optional[str] = None,
+        headers: Optional[Dict[str, str]] = None,
+        repeatable: Optional[bool] = None,
+    ) -> Json:
+        raw = b"" if body is None else json.dumps(body, separators=(",", ":")).encode()
+        repeatable = method == "GET" if repeatable is None else repeatable
+        attempt = 0
+        while True:
+            ts = str(int(time.time()))
+            h = {
+                "x-partner-id": self.project,
+                "x-localmem-key": self.key_id,
+                "x-localmem-timestamp": ts,
+                "x-localmem-signature": sign(self._secret, ts, method, path, raw),
+                "user-agent": "localmem-memory-python",
+            }
+            if raw:
+                h["content-type"] = "application/json"
+            if tenant:
+                h["x-tenant-id"] = tenant
+            h.update(headers or {})
+            try:
+                status, got, data = self._transport(method, self.base_url + path, h, raw if body is not None else None, self._timeout)
+            except OSError:
+                # No answer: sent again only when that cannot do it twice.
+                if repeatable and attempt < self._max_retries:
+                    self._sleep(_backoff(attempt))
+                    attempt += 1
+                    continue
+                raise
+            try:
+                answer = json.loads(data) if data else {}
+            except ValueError:
+                answer = {"error": "not_json", "message": data[:200].decode(errors="replace")}
+            if 200 <= status < 300:
+                return answer
+            lower = {k.lower(): v for k, v in got.items()}
+            after = lower.get("retry-after")
+            retry_after = int(after) if after and after.isdigit() else None
+            err = LocalmemError(status, answer, lower.get("x-request-id"), retry_after)
+            if attempt < self._max_retries:
+                # A 429, and a 503 server_busy, were refused before any work,
+                # so any request may go again when the wait is short; a monthly
+                # limit's wait is days, so raised. Any other 503 (a timeout)
+                # may have done the work: only a repeatable request goes again.
+                not_done = status == 429 or (status == 503 and answer.get("error") == "server_busy")
+                if (not_done or (status == 503 and repeatable)) and (retry_after or 1) <= MAX_WAIT_SECONDS:
+                    self._sleep(retry_after if retry_after is not None else _backoff(attempt))
+                    attempt += 1
+                    continue
+                # A document whose first send is still being read: its answer
+                # comes to the same Idempotency-Key shortly.
+                in_use = status == 409 and answer.get("error") == "idempotency_key_in_use"
+                if (status >= 500 or in_use) and repeatable:
+                    self._sleep(_backoff(attempt))
+                    attempt += 1
+                    continue
+            raise err

localmem_memory-0.1.0/localmem_memory.egg-info/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: localmem-memory
+Version: 0.1.0
+Summary: The localmem Memory API: memory of each of your customers, with the source and date of every fact. `localmem-memory login` pairs a terminal with a project.
+License: Apache-2.0
+Project-URL: Homepage, https://localmem.org/docs/memory-api/sdks
+Classifier: License :: OSI Approved :: Apache Software License
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Dynamic: license-file
+
+# localmem-memory
+
+The localmem Memory API from Python: memory of each of your customers, with
+the source and date of every fact. Standard library only. Server-side only.
+
+```sh
+pip install localmem-memory
+localmem-memory login     # pair this terminal: approve the code in the browser
+```
+
+```python
+from localmem_memory import Memory
+
+lm = Memory()  # reads LOCALMEM_PROJECT, LOCALMEM_KEY_ID, LOCALMEM_KEY_SECRET
+tenant = lm.customers.create("cust-42")["tenant"]
+lm.documents.send(tenant, "Ada Byron joined Acme on 3 March.")
+print(lm.recall(tenant, "Ada Byron")["facts"])
+```
+
+Docs: https://localmem.org/docs/memory-api/sdks · Support: support@localmem.org

localmem_memory-0.1.0/localmem_memory.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+NOTICE
+README.md
+pyproject.toml
+localmem_memory/__init__.py
+localmem_memory/cli.py
+localmem_memory/client.py
+localmem_memory.egg-info/PKG-INFO
+localmem_memory.egg-info/SOURCES.txt
+localmem_memory.egg-info/dependency_links.txt
+localmem_memory.egg-info/entry_points.txt
+localmem_memory.egg-info/top_level.txt
+tests/test_sdk.py

localmem_memory-0.1.0/localmem_memory.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

localmem_memory-0.1.0/localmem_memory.egg-info/entry_points.txt

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

localmem_memory-0.1.0/localmem_memory.egg-info/top_level.txt

@@ -0,0 +1 @@
+localmem_memory

localmem_memory-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "localmem-memory"
+version = "0.1.0"
+description = "The localmem Memory API: memory of each of your customers, with the source and date of every fact. `localmem-memory login` pairs a terminal with a project."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+classifiers = ["License :: OSI Approved :: Apache Software License"]
+dependencies = []
+
+[project.urls]
+Homepage = "https://localmem.org/docs/memory-api/sdks"
+
+[project.scripts]
+localmem-memory = "localmem_memory.cli:main"
+
+[tool.setuptools]
+packages = ["localmem_memory"]

localmem_memory-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

localmem_memory-0.1.0/tests/test_sdk.py

@@ -0,0 +1,144 @@
+"""specs/037 R53, R55: the Python SDK and its login, against a fake gateway."""
+
+import hashlib
+import hmac
+import json
+import os
+import tempfile
+import unittest
+
+from localmem_memory import LocalmemError, Memory, sign
+from localmem_memory.cli import login, with_vars
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+VECTOR = json.load(open(os.path.join(HERE, "..", "..", "signing-vector.json")))
+
+
+class Fake:
+    """Answers from ``answers`` in turn, recording each request."""
+
+    def __init__(self, answers):
+        self.answers, self.seen = list(answers), []
+
+    def __call__(self, method, url, headers, body, timeout):
+        self.seen.append({"method": method, "url": url, "headers": dict(headers), "body": body})
+        a = self.answers.pop(0)
+        if isinstance(a, Exception):
+            raise a
+        status, payload, headers = (a + ({},))[:3]
+        return status, headers, json.dumps(payload).encode()
+
+
+def memory(fake, **kw):
+    return Memory(project="p-1a2b3c4d", key_id="key_abc", secret="s3cret", base_url="https://api.test/",
+                  transport=fake, sleep=kw.pop("sleep", lambda s: None), **kw)
+
+
+class Sdk(unittest.TestCase):
+    def test_signs_the_shared_vector_exactly_as_the_gateway_checks_it(self):
+        v = VECTOR
+        self.assertEqual(sign(v["secret"], v["timestamp"], v["method"], v["path"], v["body"].encode()), v["signature"])
+
+    def test_says_which_variables_are_missing(self):
+        saved = dict(os.environ)
+        for k in ("LOCALMEM_PROJECT", "LOCALMEM_KEY_ID", "LOCALMEM_KEY_SECRET"):
+            os.environ.pop(k, None)
+        try:
+            with self.assertRaisesRegex(ValueError, "LOCALMEM_PROJECT, LOCALMEM_KEY_ID, LOCALMEM_KEY_SECRET.*login"):
+                Memory()
+        finally:
+            os.environ.update(saved)
+
+    def test_each_request_is_signed_for_its_method_path_and_exact_body(self):
+        f = Fake([(201, {"tenant": "t1"}), (200, {"facts": []})])
+        lm = memory(f)
+        lm.recall(lm.customers.create("cust-42")["tenant"], "Ada", at_time="2026-11-05T12:00:00Z")
+        made, recalled = f.seen
+        h = made["headers"]
+        want = hmac.new(b"s3cret", f"{h['x-localmem-timestamp']}.POST./v1/partner/tenants.".encode() + made["body"], hashlib.sha256).hexdigest()
+        self.assertEqual(made["url"], "https://api.test/v1/partner/tenants")
+        self.assertEqual((h["x-partner-id"], h["x-localmem-key"], h["x-localmem-signature"]), ("p-1a2b3c4d", "key_abc", want))
+        self.assertEqual(recalled["headers"]["x-tenant-id"], "t1")
+        self.assertEqual(json.loads(recalled["body"]), {"entity": "Ada", "at_time": "2026-11-05T12:00:00Z"})
+
+    def test_a_document_is_retried_with_the_same_idempotency_key(self):
+        f = Fake([OSError("reset"), (502, {"error": "extraction_failed"}), (200, {"status": "written", "facts_written": 3})])
+        self.assertEqual(memory(f).documents.send("t1", "Ada moved to Leeds.")["facts_written"], 3)
+        keys = {s["headers"]["Idempotency-Key"] for s in f.seen}
+        self.assertEqual((len(f.seen), len(keys)), (3, 1))
+
+    def test_a_write_is_not_sent_twice_after_a_5xx_but_waits_out_a_short_429(self):
+        f = Fake([(502, {"error": "internal", "message": "boom"})])
+        with self.assertRaises(LocalmemError) as e:
+            memory(f).write("t1", "x")
+        self.assertEqual((e.exception.status, len(f.seen)), (502, 1))
+        waits = []
+        f = Fake([(429, {"error": "rate_limited"}, {"Retry-After": "2"}), (200, {"event_id": "e1"})])
+        self.assertEqual(memory(f, sleep=waits.append).write("t1", "x")["event_id"], "e1")
+        self.assertEqual(waits, [2])
+
+    def test_server_busy_goes_again_a_timeout_does_not_and_a_document_waits_out_a_key_in_use(self):
+        f = Fake([(503, {"error": "server_busy"}), (200, {"event_id": "e1"})])
+        self.assertEqual(memory(f).write("t1", "x")["event_id"], "e1")
+        f = Fake([(503, {"error": "timeout"})])
+        with self.assertRaises(LocalmemError):
+            memory(f).write("t1", "x")
+        self.assertEqual(len(f.seen), 1)
+        f = Fake([(409, {"error": "idempotency_key_in_use"}), (200, {"status": "written"})])
+        self.assertEqual(memory(f).documents.send("t1", "x")["status"], "written")
+
+    def test_a_monthly_limit_is_raised_at_once_with_the_gateways_words(self):
+        body = {"error": "monthly_limit", "message": "This project's account has read 500 of 500 documents this month.", "resets_at": "2026-12-01T00:00:00Z"}
+        f = Fake([(429, body, {"Retry-After": "2160000", "X-Request-Id": "r1"})])
+        with self.assertRaises(LocalmemError) as e:
+            memory(f).documents.send("t1", "x")
+        err = e.exception
+        self.assertEqual((err.error, err.message, err.retry_after, err.request_id), ("monthly_limit", body["message"], 2160000, "r1"))
+        self.assertEqual((err.body["resets_at"], len(f.seen)), (body["resets_at"], 1))
+
+    def test_usage_sends_its_range_as_a_query_the_signature_leaves_out(self):
+        f = Fake([(200, {"usage": []})])
+        memory(f).usage("2026-11-01", "2026-11-05")
+        s = f.seen[0]
+        self.assertEqual(s["url"], "https://api.test/v1/partner/usage?from=2026-11-01&to=2026-11-05")
+        self.assertEqual(s["headers"]["x-localmem-signature"], sign("s3cret", s["headers"]["x-localmem-timestamp"], "GET", "/v1/partner/usage", b""))
+
+
+class Login(unittest.TestCase):
+    def test_pairs_writes_the_three_variables_and_keeps_the_file_out_of_git(self):
+        d = tempfile.mkdtemp()
+        env = os.path.join(d, ".env")
+        open(env, "w").write("OTHER=1\nLOCALMEM_KEY_ID=old\n")
+        answers = [
+            (201, {"pairing": "pair_1", "device_secret": "ds", "code": "WDJB-MJHT", "url": "https://app.test/pair?code=WDJB-MJHT", "expires_in": 600, "interval": 3}),
+            (202, {"status": "pending"}),
+            (200, {"project": "p-1a2b3c4d", "key_id": "key_new", "secret": "lm_test_SECRET", "mode": "test"}),
+        ]
+        sent, lines, opened = [], [], []
+
+        def send(url, body):
+            sent.append((url, body))
+            return answers.pop(0)
+
+        code = login("https://api.localmem.org", env, "ci", True, log=lines.append, send=send, sleep=lambda s: None, open_url=opened.append)
+        self.assertEqual(code, 0)
+        self.assertEqual(sent[0], ("https://api.localmem.org/v1/pair", {"device": "ci"}))
+        self.assertEqual(sent[1][1], {"device_secret": "ds"})
+        self.assertEqual(opened, ["https://app.test/pair?code=WDJB-MJHT"])
+        self.assertEqual(open(env).read(), "OTHER=1\nLOCALMEM_KEY_ID=key_new\nLOCALMEM_PROJECT=p-1a2b3c4d\nLOCALMEM_KEY_SECRET=lm_test_SECRET\n")
+        self.assertIn(".env\n", open(os.path.join(d, ".gitignore")).read())
+        self.assertNotIn("lm_test_SECRET", "\n".join(lines))
+
+    def test_says_so_when_the_pairing_ends(self):
+        answers = [(201, {"pairing": "p", "device_secret": "d", "code": "C", "url": "u"}), (410, {"message": "This pairing has ended."})]
+        lines = []
+        env = os.path.join(tempfile.mkdtemp(), ".env")
+        self.assertEqual(login("https://x", env, "ci", False, log=lines.append, send=lambda u, b: answers.pop(0), sleep=lambda s: None), 1)
+        self.assertEqual(lines[-1], "This pairing has ended.")
+
+    def test_with_vars_replaces_an_exported_line(self):
+        self.assertEqual(with_vars("export LOCALMEM_PROJECT=old", {"LOCALMEM_PROJECT": "p", "B": "2"}), "LOCALMEM_PROJECT=p\nB=2\n")
+
+
+if __name__ == "__main__":
+    unittest.main()