remember 0.1__tar.gz → 0.3.0__tar.gz

remember-0.3.0/.gitignore

@@ -0,0 +1,78 @@
+.loopy_loop/sessions/
+.loopy_loop/traces/
+.loopy_loop/trace_finalization_outbox/
+.loopy_loop/repository.json
+.loopy_loop/state.json
+.loopy_loop/state.json.lock
+.loopy_loop/state.json.archive_*.json
+
+# Disposable external research checkouts (never vendored)
+.research/
+
+# Python environments and generated caches
+.venv/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+
+# IDE state
+.idea/
+
+# Cloudflare edge local secrets (never commit tokens)
+ops/cloudflare_edge/config.local.toml
+infra/benchmark-host/config.local.toml
+infra/disposable-dp-host/config.local.toml
+
+# Frontend install/build artifacts (source lives in fe/)
+fe/node_modules/
+fe/.next/
+fe/out/
+fe/*.tsbuildinfo
+fe/.pages-deploy.digest
+fe/.agent-browser-shots/
+fe/.pen-exports/
+fe/playwright-report/
+fe/test-results/
+.e2e-runtime/
+
+# Observability host — secret-bearing / generated deploy artifacts (never commit)
+infra/obs/.env
+infra/obs/purge/purge.env
+infra/obs/purge/projects.env
+infra/obs/vmauth.rendered.yaml
+infra/obs/Caddyfile.rendered
+infra/obs/certs/
+
+# Generic secret / rendered shapes (F2 hygiene)
+*.pem
+.env
+*.env
+!*.env.example
+!infra/obs/.env.example
+# Reviewed non-secret image/address inventory; credentials are separate files.
+!infra/storage-cell/runtime.env
+*.rendered.yaml
+Caddyfile.rendered
+**/umcobs0.conf
+
+
+fe/storybook-static/
+infra/benchmark-host/config.beam.local.toml
+
+# fe_admin (D34)
+fe_admin/node_modules/
+fe_admin/out/
+fe_admin/.next/
+fe_admin/.agent-browser-shots/
+fe_admin/storybook-static/
+.dual-review/
+
+# Built client distributions (published via the release workflow, never committed).
+client/dist/
+client/.venv/
+
+# RememberFS local native build products (source and lockfiles remain tracked).
+rememberfs/target/
+experiments/rememberfs/rust-spike/target/
+experiments/rememberfs/go-spike/rememberfs-go-spike

remember-0.3.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.5
+Name: remember
+Version: 0.3.0
+Summary: Official Python client for the remember.dev managed memory service.
+Project-URL: Homepage, https://remember.dev
+Project-URL: Documentation, https://remember.dev/docs
+Project-URL: Source, https://github.com/writeitai/ultimate-memory-cloud
+Author-email: "WriteIt.ai s.r.o." <info@writeit.ai>
+License: Apache-2.0
+Keywords: agents,memory,remember.dev,rememberstack
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: rememberstack>=0.8.1
+Description-Content-Type: text/markdown
+
+# remember
+
+Official Python SDK for the [remember.dev](https://remember.dev) managed memory service.
+
+This distribution provides:
+- **`remember.Client`** (D65): The primary ergonomic client for memory operations. Connects directly to your dedicated tenant deployment ingress with a single deployment API token (`umc_dp_…`).
+- **`remember.CloudClient`** (D53): The control-plane client for checking deployment readiness, credit balances, and spend gates using a control-plane token (`umc_cp_…`).
+- **`remember-status`**: CLI tool for quick control-plane status checks.
+
+## Install
+
+```console
+pip install remember
+```
+
+This automatically installs `rememberstack` (which provides the `remember` CLI tool on `PATH`).
+
+## Quickstart: Memory Operations (`Client`)
+
+Mint an **API Token** (`umc_dp_…`) from your dashboard at **Settings → API Tokens**, then initialize `Client`:
+
+```python
+import remember
+
+# Client accepts a bare secret (umc_dp_...) or a full Bearer string,
+# and converts string file paths automatically:
+with remember.Client(
+    api_key="umc_dp_…",
+    base_url="https://<deployment-id>.dp.remember.dev",
+) as memory:
+    landed = memory.ingest("notes/project.md")
+    print("Ingested version:", landed.version_id)
+
+    # Search claims or chunks
+    claims = memory.search_claims(query="architecture decisions")
+```
+
+### Environment Variables
+
+For zero-config agent setups, set `REMEMBER_API_KEY` and `REMEMBER_API_URL`:
+
+```console
+export REMEMBER_API_URL="https://<deployment-id>.dp.remember.dev"
+export REMEMBER_API_KEY="umc_dp_…"
+```
+
+```python
+import remember
+
+with remember.Client.from_env() as memory:
+    landed = memory.ingest("notes/project.md")
+```
+
+`Client` also automatically falls back to `REMEMBERSTACK_API_AUTHORIZATION` and `REMEMBERSTACK_API_URL` for seamless compatibility.
+
+## Quickstart: Status & Balances (`CloudClient`)
+
+To check billing balance and deployment readiness in CI or monitoring bots, use `CloudClient` with an organisation-scoped control-plane token (`umc_cp_…`).
+
+Control tokens are read-only, expiring status credentials (D53/D65). Because they are an API-only operational surface, mint one via the control-plane endpoint while authenticated with an owner session:
+- **Endpoint**: `POST /app/api/v1/orgs/{org_id}/control-tokens` (or `POST /v1/orgs/{org_id}/control-tokens` against the direct control-plane URL).
+- **Body**: `{"label": "ci-monitor", "expires_in_days": 90}` (accepts `label` and optional `expires_in_days` up to 90).
+
+```console
+export REMEMBER_CLOUD_TOKEN='umc_cp_…'
+export REMEMBER_CLOUD_ORG='your-organisation-id'
+```
+
+```python
+from remember import CloudClient
+
+with CloudClient.from_env() as cloud:
+    if cloud.is_ready():
+        print("Balance:", cloud.billing_status().balance)
+```
+
+You can also run the status CLI:
+
+```console
+$ remember-status
+deployment  active     bb81063d-6b7b-41d0-a1df-dc57d4f1fe87
+endpoint    live       bb81063d-6b7b-41d0-a1df-dc57d4f1fe87.dp.remember.dev
+billing     active     balance 42.10
+spend       allow
+```

remember-0.3.0/README.md

@@ -0,0 +1,85 @@
+# remember
+
+Official Python SDK for the [remember.dev](https://remember.dev) managed memory service.
+
+This distribution provides:
+- **`remember.Client`** (D65): The primary ergonomic client for memory operations. Connects directly to your dedicated tenant deployment ingress with a single deployment API token (`umc_dp_…`).
+- **`remember.CloudClient`** (D53): The control-plane client for checking deployment readiness, credit balances, and spend gates using a control-plane token (`umc_cp_…`).
+- **`remember-status`**: CLI tool for quick control-plane status checks.
+
+## Install
+
+```console
+pip install remember
+```
+
+This automatically installs `rememberstack` (which provides the `remember` CLI tool on `PATH`).
+
+## Quickstart: Memory Operations (`Client`)
+
+Mint an **API Token** (`umc_dp_…`) from your dashboard at **Settings → API Tokens**, then initialize `Client`:
+
+```python
+import remember
+
+# Client accepts a bare secret (umc_dp_...) or a full Bearer string,
+# and converts string file paths automatically:
+with remember.Client(
+    api_key="umc_dp_…",
+    base_url="https://<deployment-id>.dp.remember.dev",
+) as memory:
+    landed = memory.ingest("notes/project.md")
+    print("Ingested version:", landed.version_id)
+
+    # Search claims or chunks
+    claims = memory.search_claims(query="architecture decisions")
+```
+
+### Environment Variables
+
+For zero-config agent setups, set `REMEMBER_API_KEY` and `REMEMBER_API_URL`:
+
+```console
+export REMEMBER_API_URL="https://<deployment-id>.dp.remember.dev"
+export REMEMBER_API_KEY="umc_dp_…"
+```
+
+```python
+import remember
+
+with remember.Client.from_env() as memory:
+    landed = memory.ingest("notes/project.md")
+```
+
+`Client` also automatically falls back to `REMEMBERSTACK_API_AUTHORIZATION` and `REMEMBERSTACK_API_URL` for seamless compatibility.
+
+## Quickstart: Status & Balances (`CloudClient`)
+
+To check billing balance and deployment readiness in CI or monitoring bots, use `CloudClient` with an organisation-scoped control-plane token (`umc_cp_…`).
+
+Control tokens are read-only, expiring status credentials (D53/D65). Because they are an API-only operational surface, mint one via the control-plane endpoint while authenticated with an owner session:
+- **Endpoint**: `POST /app/api/v1/orgs/{org_id}/control-tokens` (or `POST /v1/orgs/{org_id}/control-tokens` against the direct control-plane URL).
+- **Body**: `{"label": "ci-monitor", "expires_in_days": 90}` (accepts `label` and optional `expires_in_days` up to 90).
+
+```console
+export REMEMBER_CLOUD_TOKEN='umc_cp_…'
+export REMEMBER_CLOUD_ORG='your-organisation-id'
+```
+
+```python
+from remember import CloudClient
+
+with CloudClient.from_env() as cloud:
+    if cloud.is_ready():
+        print("Balance:", cloud.billing_status().balance)
+```
+
+You can also run the status CLI:
+
+```console
+$ remember-status
+deployment  active     bb81063d-6b7b-41d0-a1df-dc57d4f1fe87
+endpoint    live       bb81063d-6b7b-41d0-a1df-dc57d4f1fe87.dp.remember.dev
+billing     active     balance 42.10
+spend       allow
+```

remember-0.3.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "remember"
+version = "0.3.0"
+description = "Official Python client for the remember.dev managed memory service."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "Apache-2.0" }
+authors = [{ name = "WriteIt.ai s.r.o.", email = "info@writeit.ai" }]
+keywords = ["remember.dev", "rememberstack", "memory", "agents"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+# D43 rule 1 & D65: the cloud distribution depends on rememberstack for the core
+# memory client and engine wire models. This package exposes the ergonomic Client
+# facade for data-plane memory operations and CloudClient for control-plane queries.
+dependencies = [
+    "httpx>=0.27",
+    "rememberstack>=0.8.1",
+]
+
+[project.urls]
+Homepage = "https://remember.dev"
+Documentation = "https://remember.dev/docs"
+Source = "https://github.com/writeitai/ultimate-memory-cloud"
+
+# D43 rule 3: this project declares NO console script named `remember`. That
+# entry point belongs to `rememberstack` alone, and colliding on it would be a
+# PATH conflict between two installed distributions.
+[project.scripts]
+remember-status = "remember.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/remember"]
+
+# The client's tests are their own suite: the repository's root pytest run is
+# scoped to ``src/tests`` and never collects them. Declaring the section here
+# also makes ``client`` pytest's rootdir, so a run does not inherit the service's
+# asyncio settings.
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[dependency-groups]
+dev = ["pytest>=8.3", "respx>=0.21", "mypy>=1.14", "ruff>=0.9"]

remember-0.3.0/src/remember/__init__.py

@@ -0,0 +1,77 @@
+"""Python client library for the remember.dev managed memory service (D65).
+
+PyPI project **`remember`**, import name **`remember`**.
+
+What this package provides
+--------------------------
+
+1. **`Client`** (D65):
+   The primary developer memory client. Accepts a single deployment API token
+   (``umc_dp_…``) or bare secret, connects directly to tenant deployment ingress,
+   and provides ergonomic access to all memory operations (ingest, search,
+   pipeline readiness, and assured operations).
+
+       import remember
+
+       with remember.Client(
+           api_key="umc_dp_…",
+           base_url="https://<deployment-id>.dp.remember.dev",
+       ) as memory:
+           landed = memory.ingest("guide.pdf")
+
+   Or zero-config from environment variables (``REMEMBER_API_KEY`` and ``REMEMBER_API_URL``):
+
+       memory = remember.Client.from_env()
+
+2. **`CloudClient`** (D53):
+   The control-plane client. Uses an organisation-scoped control-plane token
+   (``umc_cp_…``) to inspect deployment readiness, credit balance, and spend gates.
+
+       from remember import CloudClient
+
+       with CloudClient.from_env() as cloud:
+           status = cloud.billing_status()
+           print(status.state, status.balance)
+
+3. **Core Re-exports**:
+   Typed models and errors (:class:`Envelope`, :class:`ContextBundleV1`,
+   :class:`IngestedVersion`, :class:`ReadinessRequirements`, :class:`MemoryApiError`)
+   are re-exported directly from ``remember`` for convenient typing.
+"""
+
+from rememberstack.client import MemoryApiError
+from rememberstack.client import ReadinessRequirements
+from rememberstack.model import ContextBundleV1
+from rememberstack.model import Envelope
+from rememberstack.model import IngestedVersion
+
+from remember.client import Client
+from remember.client import CloudClient
+from remember.errors import CloudError
+from remember.errors import NotPermitted
+from remember.errors import RateLimited
+from remember.errors import Unauthenticated
+from remember.models import BillingStatus
+from remember.models import Deployment
+from remember.models import LedgerEntry
+from remember.models import SpendGate
+
+__all__ = [
+    "BillingStatus",
+    "Client",
+    "CloudClient",
+    "CloudError",
+    "ContextBundleV1",
+    "Deployment",
+    "Envelope",
+    "IngestedVersion",
+    "LedgerEntry",
+    "MemoryApiError",
+    "NotPermitted",
+    "RateLimited",
+    "ReadinessRequirements",
+    "SpendGate",
+    "Unauthenticated",
+]
+
+__version__ = "0.3.0"

remember-0.3.0/src/remember/cli.py

@@ -0,0 +1,113 @@
+"""``remember-status`` — one command that answers the operator's question.
+
+Named for what it does, and deliberately **not** ``remember``: that console
+script belongs to ``rememberstack`` alone (D43 rule 3), and two installed
+distributions competing for one name on ``PATH`` is a conflict no user should
+have to debug.
+
+    $ remember-status
+    deployment  active     bb81063d-…dc57d4f1fe87
+    endpoint    live       bb81063d-….dp.remember.dev
+    billing     active     balance 42.10
+    spend       allow
+
+Exit status is meaningful, so a shell can branch: ``0`` ready, ``1`` not ready,
+``2`` could not ask.
+"""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Sequence
+import sys
+
+from remember.client import CloudClient
+from remember.errors import CloudError
+from remember.errors import RateLimited
+from remember.errors import Unauthenticated
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Print one organisation's status; return an exit code a script can use."""
+    parser = argparse.ArgumentParser(
+        prog="remember-status",
+        description=(
+            "Report a remember.dev organisation's deployment, billing, and "
+            "spend state. Reads REMEMBER_CLOUD_TOKEN and REMEMBER_CLOUD_ORG."
+        ),
+    )
+    parser.add_argument("--org", default=None, help="organisation id")
+    parser.add_argument("--url", default=None, help="control-plane base URL")
+    parser.add_argument(
+        "--quiet", action="store_true", help="print nothing; use the exit status only"
+    )
+    args = parser.parse_args(argv)
+
+    try:
+        overrides = {}
+        if args.org:
+            overrides["org_id"] = args.org
+        if args.url:
+            overrides["base_url"] = args.url
+        with CloudClient.from_env(**overrides) as cloud:
+            return _report(cloud=cloud, quiet=bool(args.quiet))
+    except ValueError as error:
+        # Missing configuration: tell the user what to set, not a stack trace.
+        print(f"remember-status: {error}", file=sys.stderr)
+        return 2
+    except Unauthenticated as error:
+        print(
+            f"remember-status: credential rejected ({error}). "
+            "Mint a fresh control-plane token with "
+            "POST /v1/orgs/<org>/control-tokens while signed in.",
+            file=sys.stderr,
+        )
+        return 2
+    except RateLimited as error:
+        wait = f" retry in {error.retry_after:.0f}s" if error.retry_after else ""
+        print(f"remember-status: rate limited{wait}", file=sys.stderr)
+        return 2
+    except CloudError as error:
+        print(f"remember-status: {error}", file=sys.stderr)
+        return 2
+
+
+def _report(*, cloud: CloudClient, quiet: bool) -> int:
+    """Print the four facts worth knowing, and decide the exit code."""
+    deployment = cloud.deployment()
+    billing = cloud.billing_status()
+    gate = None
+    if deployment is not None:
+        gate = cloud.spend_gate(deployment_id=deployment.id)
+
+    if not quiet:
+        if deployment is None:
+            _line("deployment", "none", "no deployment provisioned yet")
+        else:
+            _line("deployment", deployment.state, deployment.id)
+            _line(
+                "endpoint",
+                "live" if deployment.hostname_live else "not serving",
+                deployment.hostname or "unknown",
+            )
+        balance = f"balance {billing.balance}" if billing.balance else ""
+        _line("billing", billing.state, balance)
+        if gate is not None:
+            _line("spend", gate.decision, gate.reason_code or "")
+
+    # Every fact printed above counts toward the exit code. A script that
+    # branches on `remember-status` is asking "can work run right now", and a
+    # zero exit while the spend gate says `park` would send it straight into a
+    # refusal. `is_ready` already covers endpoint liveness as well as state.
+    ready = (
+        deployment is not None
+        and deployment.is_ready
+        and billing.can_spend
+        and (gate is None or gate.allows_work)
+    )
+    return 0 if ready else 1
+
+
+def _line(label: str, state: str, detail: str = "") -> None:
+    """One aligned row, so several runs stack readably in a terminal."""
+    print(f"{label:<11} {state:<10} {detail}".rstrip())