bilinc 2.3.7__tar.gz → 2.3.8__tar.gz

{bilinc-2.3.7/src/bilinc.egg-info → bilinc-2.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bilinc
-Version: 2.3.7
+Version: 2.3.8
 Summary: Cloud-only memory SDK and MCP adapter for autonomous agents
 Author: Bilinc Team
 License-Expression: BUSL-1.1
@@ -21,7 +21,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: certifi>=2024.2.2
-Requires-Dist: mcp<2.0,>=1.0.0
+Requires-Dist: mcp<2.0,>=1.10.0
 Provides-Extra: dev
 Requires-Dist: build<2.0,>=1.2; extra == "dev"
 Requires-Dist: pytest<9.0,>=7.0; extra == "dev"
@@ -56,7 +56,7 @@ Dynamic: license-file
 
 Retrieval answers *"what is similar to this?"*. Long-running agents also need to answer *"who wrote this state, was it verified, did it contradict what we already knew, and can we undo it?"* — that is the layer Bilinc provides.
 
-Bilinc 2.3.7 on PyPI is the public cloud-only package: a thin Python SDK, CLI, and MCP adapter for Bilinc Cloud. It does not ship the local StatePlane, storage backends, eval, observability, integrations, or server runtime internals.
+Bilinc 2.3.8 on PyPI is the public cloud-only package: a thin Python SDK, CLI, and MCP adapter for Bilinc Cloud. It does not ship the local StatePlane, storage backends, eval, observability, integrations, or server runtime internals.
 
 > **Frozen regression receipt** — LongMemEval-s cleaned retrieval fixture, 500 questions: **Hit@5 98.0%**, **NDCG@5 0.913**, no LLM reranker, no paid API. This is an isolated retrieval guardrail, not a current hosted SLA, end-to-end agent score, or competitor ranking — see [Benchmark receipt](#benchmark-receipt) for the full scope and qualification.
 
@@ -157,7 +157,7 @@ Cloud status check.
 To reproduce this release exactly:
 
 ```bash
-pip install -U bilinc==2.3.7
+pip install -U bilinc==2.3.8
 ```
 
 If you prefer a browser guide, open https://bilinc.space/install and follow the
@@ -191,7 +191,7 @@ bilinc mcp install                          # plain mcpServers JSON for any othe
 `command` is the interpreter that has Bilinc installed, and the adapter reads the key saved by `bilinc login`, so
 the config carries no key. On a machine without a saved key, add `"env": { "BILINC_API_KEY": "bil_live_..." }`.
 
-Eight tools — the core memory lifecycle, and nothing else:
+Eleven tools: the eight-step memory lifecycle plus three review tools.
 
 | Tool | What it does |
 | --- | --- |
@@ -203,8 +203,11 @@ Eight tools — the core memory lifecycle, and nothing else:
 | `snapshot` | Checkpoint a project before risky work, or list existing checkpoints. |
 | `diff` | Compare a checkpoint against another checkpoint or current state. Values are redacted by default. |
 | `rollback` | **Destructive in execute mode.** Restore a checkpoint through a free preview plus an explicitly confirmed execute. |
+| `list_memories` | Browse what is stored, ordered by key, with prefix, type and updated-time filters. Read-only and free. |
+| `history` | Show one memory's recorded changes, newest first, with the value before and after. Read-only and free. |
+| `confirm` | Record that a memory is still accurate without resending its value. Costs one write. |
 
-Operator and debug tooling — health probes, benchmarks, export/import, workspace replay — stays
+Operator and debug tooling — health probes, benchmarks, bulk import, workspace replay — stays
 local-only, as do the epistemic read tools for claims, contradictions, and graph queries. The hosted
 adapter does not bundle local runtime internals.
 
@@ -243,6 +246,24 @@ client.status()   # what can this key do?
 client.health()   # is the service reachable?
 ```
 
+### Review what Bilinc remembers
+
+Listing, history and export are reads and are not billed. Confirming costs one write.
+
+```python
+page = client.list_memories(prefix="agent.", limit=50)       # one page, ordered by key
+for entry in client.iter_memories(memory_type="semantic"):   # every page
+    print(entry["key"], entry["updatedAt"])
+
+client.history("agent.goal")   # newest changes first (20 by default, up to 100); "truncated" marks older ones
+client.confirm("agent.goal", expected_version=page["entries"][0]["entryVersion"])  # still true
+
+backup = client.export()       # every stored memory with its full value, as one dict
+```
+
+Forgetting a memory removes its value from history as well: earlier values of a forgotten
+memory are not returned.
+
 For server, CI, and hosted agent runtimes, store the key as `BILINC_API_KEY`.
 
 ## CLI
@@ -260,6 +281,16 @@ bilinc forget --key agent.goal --reason "superseded by the planner service"
 bilinc doctor
 ```
 
+Review what is stored:
+
+```bash
+bilinc list --prefix agent.          # table of keys, types, update times, value previews
+bilinc list --all --json             # every page as JSON
+bilinc history agent.goal            # recorded changes, newest first
+bilinc confirm agent.goal            # still accurate; the value is unchanged
+bilinc export -o bilinc-export.json  # full values; the file is readable only by you
+```
+
 Rollback is two stages. Execute takes the token from the preview and never prompts interactively,
 so it stays safe inside automation:
 

{bilinc-2.3.7 → bilinc-2.3.8}/README.md

@@ -14,7 +14,7 @@
 
 Retrieval answers *"what is similar to this?"*. Long-running agents also need to answer *"who wrote this state, was it verified, did it contradict what we already knew, and can we undo it?"* — that is the layer Bilinc provides.
 
-Bilinc 2.3.7 on PyPI is the public cloud-only package: a thin Python SDK, CLI, and MCP adapter for Bilinc Cloud. It does not ship the local StatePlane, storage backends, eval, observability, integrations, or server runtime internals.
+Bilinc 2.3.8 on PyPI is the public cloud-only package: a thin Python SDK, CLI, and MCP adapter for Bilinc Cloud. It does not ship the local StatePlane, storage backends, eval, observability, integrations, or server runtime internals.
 
 > **Frozen regression receipt** — LongMemEval-s cleaned retrieval fixture, 500 questions: **Hit@5 98.0%**, **NDCG@5 0.913**, no LLM reranker, no paid API. This is an isolated retrieval guardrail, not a current hosted SLA, end-to-end agent score, or competitor ranking — see [Benchmark receipt](#benchmark-receipt) for the full scope and qualification.
 
@@ -115,7 +115,7 @@ Cloud status check.
 To reproduce this release exactly:
 
 ```bash
-pip install -U bilinc==2.3.7
+pip install -U bilinc==2.3.8
 ```
 
 If you prefer a browser guide, open https://bilinc.space/install and follow the
@@ -149,7 +149,7 @@ bilinc mcp install                          # plain mcpServers JSON for any othe
 `command` is the interpreter that has Bilinc installed, and the adapter reads the key saved by `bilinc login`, so
 the config carries no key. On a machine without a saved key, add `"env": { "BILINC_API_KEY": "bil_live_..." }`.
 
-Eight tools — the core memory lifecycle, and nothing else:
+Eleven tools: the eight-step memory lifecycle plus three review tools.
 
 | Tool | What it does |
 | --- | --- |
@@ -161,8 +161,11 @@ Eight tools — the core memory lifecycle, and nothing else:
 | `snapshot` | Checkpoint a project before risky work, or list existing checkpoints. |
 | `diff` | Compare a checkpoint against another checkpoint or current state. Values are redacted by default. |
 | `rollback` | **Destructive in execute mode.** Restore a checkpoint through a free preview plus an explicitly confirmed execute. |
+| `list_memories` | Browse what is stored, ordered by key, with prefix, type and updated-time filters. Read-only and free. |
+| `history` | Show one memory's recorded changes, newest first, with the value before and after. Read-only and free. |
+| `confirm` | Record that a memory is still accurate without resending its value. Costs one write. |
 
-Operator and debug tooling — health probes, benchmarks, export/import, workspace replay — stays
+Operator and debug tooling — health probes, benchmarks, bulk import, workspace replay — stays
 local-only, as do the epistemic read tools for claims, contradictions, and graph queries. The hosted
 adapter does not bundle local runtime internals.
 
@@ -201,6 +204,24 @@ client.status()   # what can this key do?
 client.health()   # is the service reachable?
 ```
 
+### Review what Bilinc remembers
+
+Listing, history and export are reads and are not billed. Confirming costs one write.
+
+```python
+page = client.list_memories(prefix="agent.", limit=50)       # one page, ordered by key
+for entry in client.iter_memories(memory_type="semantic"):   # every page
+    print(entry["key"], entry["updatedAt"])
+
+client.history("agent.goal")   # newest changes first (20 by default, up to 100); "truncated" marks older ones
+client.confirm("agent.goal", expected_version=page["entries"][0]["entryVersion"])  # still true
+
+backup = client.export()       # every stored memory with its full value, as one dict
+```
+
+Forgetting a memory removes its value from history as well: earlier values of a forgotten
+memory are not returned.
+
 For server, CI, and hosted agent runtimes, store the key as `BILINC_API_KEY`.
 
 ## CLI
@@ -218,6 +239,16 @@ bilinc forget --key agent.goal --reason "superseded by the planner service"
 bilinc doctor
 ```
 
+Review what is stored:
+
+```bash
+bilinc list --prefix agent.          # table of keys, types, update times, value previews
+bilinc list --all --json             # every page as JSON
+bilinc history agent.goal            # recorded changes, newest first
+bilinc confirm agent.goal            # still accurate; the value is unchanged
+bilinc export -o bilinc-export.json  # full values; the file is readable only by you
+```
+
 Rollback is two stages. Execute takes the token from the preview and never prompts interactively,
 so it stays safe inside automation:
 

{bilinc-2.3.7 → bilinc-2.3.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "bilinc"
-version = "2.3.7"
+version = "2.3.8"
 description = "Cloud-only memory SDK and MCP adapter for autonomous agents"
 readme = "README.md"
 license = "BUSL-1.1"
@@ -33,7 +33,7 @@ classifiers = [
 
 dependencies = [
     "certifi>=2024.2.2",
-    "mcp>=1.0.0,<2.0",
+    "mcp>=1.10.0,<2.0",
 ]
 
 [project.urls]

{bilinc-2.3.7 → bilinc-2.3.8}/src/bilinc/__init__.py

@@ -1,4 +1,4 @@
-"""Bilinc 2.3.7: cloud-only SDK for agent memory."""
+"""Bilinc 2.3.8: cloud-only SDK for agent memory."""
 
 from bilinc.client import (
     ACTIVATION_SIGNUP_URL,
@@ -25,7 +25,7 @@ from bilinc.client import (
     CloudClient,
 )
 
-__version__ = "2.3.7"
+__version__ = "2.3.8"
 version = __version__
 
 __all__ = [

{bilinc-2.3.7 → bilinc-2.3.8}/src/bilinc/cli/main.py

@@ -4,13 +4,16 @@
 from __future__ import annotations
 
 import argparse
+import contextlib
 import json
 import os
 import shlex
 import subprocess
 import sys
+import tempfile
 import time
 import webbrowser
+from datetime import datetime
 from typing import Any
 
 from bilinc import __version__
@@ -18,9 +21,12 @@ from bilinc.client import (
     ACTIVATION_SIGNUP_URL,
     BilincApiKeyRequired,
     BilincCloudError,
+    BilincValidationError,
     CloudClient,
     INSTALL_URL,
+    MEMORY_TYPES,
     SIGNUP_URL,
+    VALUE_MODES,
     config_path,
     load_config_api_key,
     save_config_api_key,
@@ -39,6 +45,125 @@ def _print(payload: dict[str, Any]) -> None:
     print(json.dumps(payload, indent=2, ensure_ascii=False))
 
 
+def _short_time(value: Any) -> str:
+    """Render an ISO-8601 timestamp as `YYYY-MM-DD HH:MM:SS` UTC for tables."""
+    if not isinstance(value, str) or not value:
+        return "-"
+    try:
+        moment = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return value
+    return moment.strftime("%Y-%m-%d %H:%M:%S")
+
+
+def _short_value(value: Any, width: int = 60) -> str:
+    text = value if isinstance(value, str) else json.dumps(value, ensure_ascii=False)
+    text = " ".join(text.split())
+    return text if len(text) <= width else text[: width - 1] + "…"
+
+
+def _print_history(payload: dict[str, Any]) -> None:
+    key = payload.get("key", "")
+    entries = payload.get("entries") or []
+    if not entries:
+        print(f"No recorded changes for {key}.")
+        return
+    forgotten = any(entry.get("op") == "forget" for entry in entries[:1])
+    state = "" if payload.get("exists", True) else (", forgotten" if forgotten else ", not currently stored")
+    print(f"{key}  ({len(entries)} shown, newest first{state})")
+    for entry in entries:
+        op = str(entry.get("op", "?"))
+        line = f"  {_short_time(entry.get('at'))}  {op:<8}"
+        if entry.get("valuesRedacted"):
+            line += "  (value not shown: the memory was forgotten)"
+        elif "before" in entry and "after" in entry and op != "confirm":
+            line += f"  {_short_value(entry['before'], 30)} -> {_short_value(entry['after'], 30)}"
+        elif "after" in entry:
+            line += f"  {_short_value(entry['after'])}"
+        if entry.get("reason"):
+            line += f"  reason: {_short_value(entry['reason'], 40)}"
+        if entry.get("source"):
+            line += f"  source: {entry['source']}"
+        print(line)
+    if payload.get("truncated"):
+        print("  … older changes not shown; raise --limit to see more.")
+
+
+def _continuation_command(next_cursor: str, filters: dict[str, Any] | None) -> str:
+    """The `bilinc list` command for the next page, with the same filters.
+
+    A cursor only marks a position; the filters must be repeated or the next
+    page would cover a different set of memories.
+    """
+
+    parts = ["bilinc list"]
+    flags = {
+        "prefix": "--prefix",
+        "memory_type": "--type",
+        "updated_after": "--updated-after",
+        "updated_before": "--updated-before",
+        "limit": "--limit",
+    }
+    for name, flag in flags.items():
+        value = (filters or {}).get(name)
+        if value is not None and value != "":
+            parts.append(f"{flag} {shlex.quote(str(value))}")
+    values = (filters or {}).get("values")
+    if values and values != "preview":
+        parts.append(f"--values {shlex.quote(str(values))}")
+    parts.append(f"--cursor {shlex.quote(next_cursor)}")
+    return " ".join(parts)
+
+
+def _print_memories(
+    entries: list[dict[str, Any]],
+    *,
+    total: Any,
+    next_cursor: Any,
+    filters: dict[str, Any] | None = None,
+) -> None:
+    if not entries:
+        print("No memories match.")
+        return
+    key_width = min(max(len(str(entry.get("key", ""))) for entry in entries), 40)
+    print(f"{'KEY':<{key_width}}  {'TYPE':<10}  {'UPDATED (UTC)':<19}  VALUE")
+    for entry in entries:
+        key = _short_value(str(entry.get("key", "")), key_width)
+        value = _short_value(entry["value"]) if "value" in entry else ""
+        print(
+            f"{key:<{key_width}}  {str(entry.get('memoryType', '-')):<10}  "
+            f"{_short_time(entry.get('updatedAt')):<19}  {value}"
+        )
+    summary = f"{len(entries)} shown"
+    if isinstance(total, int):
+        summary += f" of {total}"
+    print(summary)
+    if isinstance(next_cursor, str) and next_cursor:
+        print(f"More: {_continuation_command(next_cursor, filters)}  (or --all)")
+
+
+def _write_private_json(path: str, payload: dict[str, Any]) -> None:
+    """Write an export owner-only: it holds the full memory contents.
+
+    The content goes to a new temporary file (created 0600) beside the
+    target, which then atomically replaces it. An existing file at ``path``
+    keeps its old contents until the write has fully succeeded, and the
+    result never inherits a wider mode from the file it replaces. This avoids
+    ``os.fchmod``, which Windows lacks before Python 3.13.
+    """
+    directory = os.path.dirname(os.path.abspath(path))
+    fd, temporary = tempfile.mkstemp(prefix=".bilinc-export-", suffix=".json", dir=directory)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(json.dumps(payload, indent=2, ensure_ascii=False))
+            handle.write("\n")
+        os.replace(temporary, path)
+    except BaseException:
+        with contextlib.suppress(FileNotFoundError):
+            os.unlink(temporary)
+        raise
+
+
 def _client(args: argparse.Namespace) -> CloudClient:
     return CloudClient(api_key=args.api_key, base_url=args.base_url, timeout=args.timeout)
 
@@ -165,6 +290,33 @@ def build_parser() -> argparse.ArgumentParser:
     forget.add_argument("--reason", required=True, help="Required audit reason for the deletion")
     forget.add_argument("--expected-version", help="Fail if the memory changed since this version")
 
+    confirm = sub.add_parser("confirm", help="Record that an existing memory is still accurate")
+    confirm.add_argument("key", help="Memory key")
+    confirm.add_argument("--expected-version", help="Fail if the memory changed since this version")
+    confirm.add_argument("--reason", help="Optional note recorded in the memory's history")
+
+    history = sub.add_parser("history", help="Show one memory's recorded changes, newest first")
+    history.add_argument("key", help="Memory key")
+    history.add_argument("--limit", type=int, default=20)
+    history.add_argument("--values", choices=VALUE_MODES, default="full", help="How much of each value to show")
+    history.add_argument("--json", action="store_true", help="Print the raw JSON response")
+
+    list_cmd = sub.add_parser("list", help="List stored memories, ordered by key")
+    list_cmd.add_argument("--prefix", help="Only keys starting with this text")
+    list_cmd.add_argument("--type", choices=MEMORY_TYPES, help="Only this memory type")
+    list_cmd.add_argument("--updated-after", help="Only memories updated after this ISO-8601 time")
+    list_cmd.add_argument("--updated-before", help="Only memories updated before this ISO-8601 time")
+    list_cmd.add_argument("--limit", type=int, default=50, help="Page size (1-100)")
+    list_cmd.add_argument("--cursor", help="Continue from a previous page")
+    list_cmd.add_argument("--all", action="store_true", help="Follow every page")
+    list_cmd.add_argument("--values", choices=VALUE_MODES, default="preview", help="How much of each value to show")
+    list_cmd.add_argument("--json", action="store_true", help="Print the raw JSON response")
+
+    export = sub.add_parser("export", help="Export every stored memory with its full value as JSON")
+    export.add_argument("-o", "--output", help="Write to this file (owner-only) instead of stdout")
+    export.add_argument("--prefix", help="Only keys starting with this text")
+    export.add_argument("--type", choices=MEMORY_TYPES, help="Only this memory type")
+
     snapshot = sub.add_parser("snapshot", help="Create or list project checkpoints")
     snapshot.add_argument("action", choices=["create", "list"], nargs="?", default="create")
     snapshot.add_argument("--label", help="Human-readable label for a new checkpoint")
@@ -340,6 +492,63 @@ def main(argv: list[str] | None = None) -> int:
                     expected_version=args.expected_version,
                 )
             )
+        elif args.command == "confirm":
+            _print(
+                client.confirm(
+                    args.key,
+                    expected_version=args.expected_version,
+                    reason=args.reason,
+                )
+            )
+        elif args.command == "history":
+            try:
+                result = client.history(args.key, limit=args.limit, values=args.values)
+            except BilincValidationError as exc:
+                if (exc.details or {}).get("reason") != "response_too_large":
+                    raise
+                raise BilincValidationError(
+                    "This history is too large to return at once. "
+                    "Try --limit 1, or --values preview.",
+                    code=exc.code,
+                    status=exc.status,
+                    details=exc.details,
+                ) from exc
+            if args.json:
+                _print(result)
+            else:
+                _print_history(result)
+        elif args.command == "list":
+            filters = {
+                "prefix": args.prefix,
+                "memory_type": args.type,
+                "updated_after": args.updated_after,
+                "updated_before": args.updated_before,
+                "values": args.values,
+            }
+            if args.all:
+                entries = list(client.iter_memories(page_size=args.limit, cursor=args.cursor, **filters))
+                if args.json:
+                    _print({"entries": entries, "count": len(entries)})
+                else:
+                    _print_memories(entries, total=len(entries), next_cursor=None)
+            else:
+                result = client.list_memories(cursor=args.cursor, limit=args.limit, **filters)
+                if args.json:
+                    _print(result)
+                else:
+                    _print_memories(
+                        result.get("entries") or [],
+                        total=result.get("total"),
+                        next_cursor=result.get("nextCursor"),
+                        filters={**filters, "limit": args.limit},
+                    )
+        elif args.command == "export":
+            exported = client.export(prefix=args.prefix, memory_type=args.type)
+            if args.output:
+                _write_private_json(args.output, exported)
+                print(f"Exported {exported['count']} memories to {args.output}", file=sys.stderr)
+            else:
+                _print(exported)
         elif args.command == "snapshot":
             if args.action == "list":
                 _print(client.list_snapshots(limit=args.limit))

{bilinc-2.3.7 → bilinc-2.3.8}/src/bilinc/client.py

@@ -1,6 +1,6 @@
 """Bilinc Cloud client.
 
-Bilinc 2.3.7 is cloud-only: the PyPI package is a thin SDK and MCP adapter for
+Bilinc 2.3.8 is cloud-only: the PyPI package is a thin SDK and MCP adapter for
 https://bilinc.space. Local self-hosted StatePlane internals are no longer
 shipped in the public package.
 """
@@ -15,10 +15,11 @@ import urllib.error
 import urllib.parse
 import urllib.request
 from dataclasses import dataclass
+from datetime import datetime, timezone
 from pathlib import Path
-from typing import Any, Callable
+from typing import Any, Callable, Iterator
 
-__version__ = "2.3.7"
+__version__ = "2.3.8"
 DEFAULT_BASE_URL = "https://bilinc.space"
 SIGNUP_URL = "https://bilinc.space/signup"
 ACTIVATION_CAMPAIGN = "activation_2_3_4"
@@ -46,6 +47,7 @@ CANONICAL_ERROR_CODES: dict[str, int] = {
     "payment_required": 402,
     "invalid_request": 400,
     "memory_not_found": 404,
+    "memory_exists": 409,
     "snapshot_not_found": 404,
     "version_conflict": 409,
     "idempotency_conflict": 409,
@@ -53,9 +55,13 @@ CANONICAL_ERROR_CODES: dict[str, int] = {
     "rollback_confirmation_expired": 410,
     "rate_limited": 429,
     "cloud_runtime_unavailable": 503,
+    "capability_unavailable": 503,
 }
 
 RETRYABLE_ERROR_CODES = frozenset({"rate_limited", "cloud_runtime_unavailable", "connection_failed"})
+#: Answered with 503, but retrying cannot help: the running service lacks the
+#: feature until it is upgraded.
+NON_RETRYABLE_ERROR_CODES = frozenset({"capability_unavailable"})
 
 
 class BilincError(RuntimeError):
@@ -153,7 +159,9 @@ def error_for_response(status: int, payload: Any) -> BilincCloudError:
     message = body.get("message") if isinstance(body.get("message"), str) else None
     request_id = body.get("requestId") if isinstance(body.get("requestId"), str) else None
     retryable = body.get("retryable")
-    if not isinstance(retryable, bool):
+    if code in NON_RETRYABLE_ERROR_CODES:
+        retryable = False
+    elif not isinstance(retryable, bool):
         retryable = status in (429, 503) or status >= 500 or code in RETRYABLE_ERROR_CODES
 
     error_class = _STATUS_ERRORS.get(status, BilincCloudError)
@@ -181,6 +189,12 @@ MAX_REASON_LENGTH = 512
 MAX_RECALL_LIMIT = 100
 MAX_SNAPSHOT_LIST_LIMIT = 100
 MAX_DIFF_LIMIT = 500
+MAX_HISTORY_LIMIT = 100
+MAX_LIST_LIMIT = 100
+
+#: How much of each stored value history and list return: the whole value, a
+#: short single-string preview, or nothing (keys and metadata only).
+VALUE_MODES = ("full", "preview", "none")
 
 #: Bounded retries for read-only calls. Mutations are never retried
 #: automatically: billing idempotency alone does not prove that a retried write
@@ -279,6 +293,15 @@ def _optional_text(value: Any, field: str) -> str | None:
     return value.strip()
 
 
+def _optional_raw_text(value: Any, field: str) -> str | None:
+    """Like :func:`_optional_text`, but keeps the value exactly as given."""
+    if value is None:
+        return None
+    if not isinstance(value, str) or value == "":
+        raise _invalid(field, "must be a non-empty string when provided")
+    return value
+
+
 def _optional_query_timestamp(value: Any) -> str | None:
     """Validate the bounded public representation of a point-in-time query.
 
@@ -296,6 +319,24 @@ def _optional_query_timestamp(value: Any) -> str | None:
     return parsed
 
 
+def _optional_timestamp(value: Any, field: str) -> str | None:
+    """Accept a datetime or an ISO-8601 string; send ISO-8601.
+
+    A naive datetime is read as UTC, so the same call means the same instant
+    on every machine.
+    """
+
+    if value is None:
+        return None
+    if isinstance(value, datetime):
+        moment = value if value.tzinfo else value.replace(tzinfo=timezone.utc)
+        return moment.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
+    parsed = _optional_text(value, field)
+    if parsed is not None and len(parsed) > MAX_QUERY_TIMESTAMP_LENGTH:
+        raise _invalid(field, f"must be at most {MAX_QUERY_TIMESTAMP_LENGTH} characters")
+    return parsed
+
+
 def _optional_bool(value: Any, field: str) -> bool | None:
     if value is None:
         return None
@@ -443,6 +484,11 @@ def _default_transport(
         ) from exc
 
 
+def _is_response_too_large(error: BilincCloudError) -> bool:
+    details = getattr(error, "details", None)
+    return isinstance(details, dict) and details.get("reason") == "response_too_large"
+
+
 @dataclass(slots=True)
 class CloudClient:
     """Minimal Bilinc Cloud SDK client."""
@@ -598,6 +644,153 @@ class CloudClient:
             idempotency_key=_optional_text(idempotency_key, "idempotency_key"),
         )
 
+    def confirm(
+        self,
+        key: str,
+        *,
+        expected_version: str | None = None,
+        reason: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any]:
+        """Record that an existing memory is still accurate.
+
+        The value stays exactly as stored; only its last-updated time moves to
+        now, and history records the step as a confirmation rather than an
+        edit. Costs one write operation. Pass ``expected_version`` to get
+        ``version_conflict`` if the memory changed since you read it.
+        """
+
+        payload: dict[str, Any] = {"key": _require_key(key)}
+        _put_optional(payload, "expectedVersion", _optional_text(expected_version, "expected_version"))
+        _put_optional(payload, "reason", _optional_text(reason, "reason"))
+
+        return self._post(
+            "/api/cloud/memory/confirm",
+            payload,
+            idempotency_key=_optional_text(idempotency_key, "idempotency_key"),
+        )
+
+    def history(self, key: str, *, limit: int = 20, values: str = "full") -> dict[str, Any]:
+        """Return one memory's recorded changes, newest first.
+
+        Read-only and not billed. Each entry carries the operation, when it
+        happened, the recorded reason and source, and (unless ``values`` is
+        ``"none"``) the value before and after. Values recorded before the
+        memory was forgotten are never returned.
+        """
+
+        return self._read(
+            "/api/cloud/memory/history",
+            {
+                "key": _require_key(key),
+                "limit": _require_limit(limit, "limit", MAX_HISTORY_LIMIT),
+                "values": _require_choice(values, "values", VALUE_MODES),
+            },
+        )
+
+    def list_memories(
+        self,
+        *,
+        prefix: str | None = None,
+        memory_type: str | None = None,
+        updated_after: datetime | str | None = None,
+        updated_before: datetime | str | None = None,
+        cursor: str | None = None,
+        limit: int = 50,
+        values: str = "preview",
+    ) -> dict[str, Any]:
+        """Return one page of stored memories, ordered by key.
+
+        Read-only and not billed. ``total`` counts every memory matching the
+        filters; pass ``nextCursor`` back as ``cursor`` for the next page, or
+        use :meth:`iter_memories` to walk every page.
+        """
+
+        payload: dict[str, Any] = {
+            "limit": _require_limit(limit, "limit", MAX_LIST_LIMIT),
+            "values": _require_choice(values, "values", VALUE_MODES),
+        }
+        # Not stripped: a trailing space is part of the prefix ("note " is not "note").
+        _put_optional(payload, "prefix", _optional_raw_text(prefix, "prefix"))
+        if memory_type is not None:
+            payload["memoryType"] = _require_memory_type(memory_type)
+        _put_optional(payload, "updatedAfter", _optional_timestamp(updated_after, "updated_after"))
+        _put_optional(payload, "updatedBefore", _optional_timestamp(updated_before, "updated_before"))
+        _put_optional(payload, "cursor", _optional_text(cursor, "cursor"))
+
+        return self._read("/api/cloud/memory/list", payload)
+
+    def iter_memories(
+        self,
+        *,
+        prefix: str | None = None,
+        memory_type: str | None = None,
+        updated_after: datetime | str | None = None,
+        updated_before: datetime | str | None = None,
+        page_size: int = MAX_LIST_LIMIT,
+        values: str = "preview",
+        cursor: str | None = None,
+    ) -> Iterator[dict[str, Any]]:
+        """Yield every stored memory matching the filters, page by page.
+
+        Starts after ``cursor`` when one is given. With ``values="full"`` a
+        page too large for one response is fetched again in smaller pages,
+        and the walk steps back up one size after each page that fits; Bilinc
+        Cloud always returns a single entry whole, so it never fails on size.
+        """
+
+        sizes = sorted({page_size, min(page_size, 10), 1}, reverse=True)
+        size_index = 0
+        seen: set[str] = set()
+        while True:
+            try:
+                page = self.list_memories(
+                    prefix=prefix,
+                    memory_type=memory_type,
+                    updated_after=updated_after,
+                    updated_before=updated_before,
+                    cursor=cursor,
+                    limit=sizes[size_index],
+                    values=values,
+                )
+            except BilincValidationError as exc:
+                if not _is_response_too_large(exc) or size_index == len(sizes) - 1:
+                    raise
+                size_index += 1
+                continue
+            # Step back up after a page that fit, so one large value does not
+            # leave the rest of the walk at one entry per request.
+            size_index = max(0, size_index - 1)
+            entries = page.get("entries")
+            yield from entries if isinstance(entries, list) else []
+            next_cursor = page.get("nextCursor")
+            if not isinstance(next_cursor, str) or not next_cursor:
+                return
+            if next_cursor in seen:
+                raise BilincCloudError(
+                    "Bilinc Cloud returned a repeated list cursor",
+                    code="invalid_response",
+                )
+            seen.add(next_cursor)
+            cursor = next_cursor
+
+    def export(
+        self,
+        *,
+        prefix: str | None = None,
+        memory_type: str | None = None,
+    ) -> dict[str, Any]:
+        """Return every stored memory with its full value, as one JSON-ready dict.
+
+        Pages through :meth:`iter_memories`; reads are not billed. Every
+        exported memory carries its full value. History is not included; use
+        :meth:`history` per key for that.
+        """
+
+        exported_at = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+        entries = list(self.iter_memories(prefix=prefix, memory_type=memory_type, values="full"))
+        return {"exported_at": exported_at, "count": len(entries), "entries": entries}
+
     def snapshot(
         self,
         action: str = "create",
@@ -834,6 +1027,8 @@ __all__ = [
     "INSTALL_URL",
     "load_config_api_key",
     "MAX_DIFF_LIMIT",
+    "MAX_HISTORY_LIMIT",
+    "MAX_LIST_LIMIT",
     "MAX_RECALL_LIMIT",
     "MAX_SNAPSHOT_LIST_LIMIT",
     "MEMORY_TYPES",
@@ -842,4 +1037,5 @@ __all__ = [
     "REVISION_STRATEGIES",
     "save_config_api_key",
     "SIGNUP_URL",
+    "VALUE_MODES",
 ]

{bilinc-2.3.7 → bilinc-2.3.8}/src/bilinc/cloud_mcp.py

@@ -9,7 +9,9 @@ Requires BILINC_API_KEY at call time, not at import time.
 This adapter exposes the eight core memory-lifecycle capabilities of hosted
 Bilinc — write, recall, deliberately revise, deliberately forget, checkpoint,
 inspect a change, restore a known-good state, and inspect runtime status —
-without bundling local StatePlane or storage internals.
+plus three review tools (list what is stored, show one memory's history, and
+confirm a memory is still accurate), without bundling local StatePlane or
+storage internals.
 
 Operator/debug tooling (health, benchmark, export/import, workspace replay) and
 the epistemic read tools (verify, claims, contradictions, graph queries) stay
@@ -33,6 +35,9 @@ CLOUD_MCP_TOOLS = (
     "snapshot",
     "diff",
     "rollback",
+    "list_memories",
+    "history",
+    "confirm",
 )
 
 
@@ -50,6 +55,8 @@ def build_server():
     except Exception as exc:  # pragma: no cover - depends on optional MCP runtime import path
         raise RuntimeError("Bilinc Cloud MCP adapter requires mcp>=1.0.0") from exc
 
+    from mcp.types import ToolAnnotations
+
     mcp = FastMCP("bilinc")
 
     @mcp.tool()
@@ -265,6 +272,98 @@ def build_server():
             )
         raise ValueError("mode must be either preview or execute")
 
+    @mcp.tool(
+        title="List stored memories",
+        annotations=ToolAnnotations(
+            readOnlyHint=True,
+            destructiveHint=False,
+            idempotentHint=True,
+            openWorldHint=False,
+        ),
+    )
+    def list_memories(
+        prefix: str | None = None,
+        memory_type: str | None = None,
+        updated_after: str | None = None,
+        updated_before: str | None = None,
+        cursor: str | None = None,
+        limit: int = 50,
+        values: str = "preview",
+    ) -> dict[str, Any]:
+        """List the memories stored in this Bilinc Cloud project, ordered by key.
+
+        Read-only and free. Filters: key `prefix`, `memory_type`, and ISO-8601
+        `updated_after` / `updated_before`. Returns up to `limit` entries
+        (1-100) with key, type, importance, source, created and updated times,
+        entry version, and a value whose size follows `values` ("preview" by
+        default, "full", or "none"). `total` counts all matches; `nextCursor`
+        is the `cursor` for the next page and is null on the last page.
+        """
+
+        return create_client().list_memories(
+            prefix=prefix,
+            memory_type=memory_type,
+            updated_after=updated_after,
+            updated_before=updated_before,
+            cursor=cursor,
+            limit=limit,
+            values=values,
+        )
+
+    @mcp.tool(
+        title="Show a memory's history",
+        annotations=ToolAnnotations(
+            readOnlyHint=True,
+            destructiveHint=False,
+            idempotentHint=True,
+            openWorldHint=False,
+        ),
+    )
+    def history(key: str, limit: int = 20, values: str = "full") -> dict[str, Any]:
+        """Show the recorded changes to one memory key, newest first.
+
+        Read-only and free. Each entry has the operation (create, update,
+        confirm, forget or delete), its time, the recorded reason and source,
+        and the value before and after unless `values` is "none". A change
+        made by a rollback keeps its create, update or delete operation and
+        also carries `rollbackSnapshotId`.
+        Values recorded before a memory was forgotten are not returned.
+        `exists` is false when the key is not currently stored.
+        """
+
+        return create_client().history(key, limit=limit, values=values)
+
+    @mcp.tool(
+        title="Confirm a memory is still accurate",
+        annotations=ToolAnnotations(
+            readOnlyHint=False,
+            destructiveHint=False,
+            # Each call adds a history entry, so a repeat is not a no-op.
+            idempotentHint=False,
+            openWorldHint=False,
+        ),
+    )
+    def confirm(
+        key: str,
+        expected_version: str | None = None,
+        reason: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any]:
+        """Record that an existing memory is still accurate.
+
+        The stored value is not changed; the memory's updated time moves to now
+        and its history gains a confirm entry. Costs one write operation.
+        Fails with `memory_not_found` when the key does not exist, and with
+        `version_conflict` when `expected_version` no longer matches.
+        """
+
+        return create_client().confirm(
+            key,
+            expected_version=expected_version,
+            reason=reason,
+            idempotency_key=idempotency_key,
+        )
+
     return mcp
 
 

{bilinc-2.3.7 → bilinc-2.3.8/src/bilinc.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bilinc
-Version: 2.3.7
+Version: 2.3.8
 Summary: Cloud-only memory SDK and MCP adapter for autonomous agents
 Author: Bilinc Team
 License-Expression: BUSL-1.1
@@ -21,7 +21,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: certifi>=2024.2.2
-Requires-Dist: mcp<2.0,>=1.0.0
+Requires-Dist: mcp<2.0,>=1.10.0
 Provides-Extra: dev
 Requires-Dist: build<2.0,>=1.2; extra == "dev"
 Requires-Dist: pytest<9.0,>=7.0; extra == "dev"
@@ -56,7 +56,7 @@ Dynamic: license-file
 
 Retrieval answers *"what is similar to this?"*. Long-running agents also need to answer *"who wrote this state, was it verified, did it contradict what we already knew, and can we undo it?"* — that is the layer Bilinc provides.
 
-Bilinc 2.3.7 on PyPI is the public cloud-only package: a thin Python SDK, CLI, and MCP adapter for Bilinc Cloud. It does not ship the local StatePlane, storage backends, eval, observability, integrations, or server runtime internals.
+Bilinc 2.3.8 on PyPI is the public cloud-only package: a thin Python SDK, CLI, and MCP adapter for Bilinc Cloud. It does not ship the local StatePlane, storage backends, eval, observability, integrations, or server runtime internals.
 
 > **Frozen regression receipt** — LongMemEval-s cleaned retrieval fixture, 500 questions: **Hit@5 98.0%**, **NDCG@5 0.913**, no LLM reranker, no paid API. This is an isolated retrieval guardrail, not a current hosted SLA, end-to-end agent score, or competitor ranking — see [Benchmark receipt](#benchmark-receipt) for the full scope and qualification.
 
@@ -157,7 +157,7 @@ Cloud status check.
 To reproduce this release exactly:
 
 ```bash
-pip install -U bilinc==2.3.7
+pip install -U bilinc==2.3.8
 ```
 
 If you prefer a browser guide, open https://bilinc.space/install and follow the
@@ -191,7 +191,7 @@ bilinc mcp install                          # plain mcpServers JSON for any othe
 `command` is the interpreter that has Bilinc installed, and the adapter reads the key saved by `bilinc login`, so
 the config carries no key. On a machine without a saved key, add `"env": { "BILINC_API_KEY": "bil_live_..." }`.
 
-Eight tools — the core memory lifecycle, and nothing else:
+Eleven tools: the eight-step memory lifecycle plus three review tools.
 
 | Tool | What it does |
 | --- | --- |
@@ -203,8 +203,11 @@ Eight tools — the core memory lifecycle, and nothing else:
 | `snapshot` | Checkpoint a project before risky work, or list existing checkpoints. |
 | `diff` | Compare a checkpoint against another checkpoint or current state. Values are redacted by default. |
 | `rollback` | **Destructive in execute mode.** Restore a checkpoint through a free preview plus an explicitly confirmed execute. |
+| `list_memories` | Browse what is stored, ordered by key, with prefix, type and updated-time filters. Read-only and free. |
+| `history` | Show one memory's recorded changes, newest first, with the value before and after. Read-only and free. |
+| `confirm` | Record that a memory is still accurate without resending its value. Costs one write. |
 
-Operator and debug tooling — health probes, benchmarks, export/import, workspace replay — stays
+Operator and debug tooling — health probes, benchmarks, bulk import, workspace replay — stays
 local-only, as do the epistemic read tools for claims, contradictions, and graph queries. The hosted
 adapter does not bundle local runtime internals.
 
@@ -243,6 +246,24 @@ client.status()   # what can this key do?
 client.health()   # is the service reachable?
 ```
 
+### Review what Bilinc remembers
+
+Listing, history and export are reads and are not billed. Confirming costs one write.
+
+```python
+page = client.list_memories(prefix="agent.", limit=50)       # one page, ordered by key
+for entry in client.iter_memories(memory_type="semantic"):   # every page
+    print(entry["key"], entry["updatedAt"])
+
+client.history("agent.goal")   # newest changes first (20 by default, up to 100); "truncated" marks older ones
+client.confirm("agent.goal", expected_version=page["entries"][0]["entryVersion"])  # still true
+
+backup = client.export()       # every stored memory with its full value, as one dict
+```
+
+Forgetting a memory removes its value from history as well: earlier values of a forgotten
+memory are not returned.
+
 For server, CI, and hosted agent runtimes, store the key as `BILINC_API_KEY`.
 
 ## CLI
@@ -260,6 +281,16 @@ bilinc forget --key agent.goal --reason "superseded by the planner service"
 bilinc doctor
 ```
 
+Review what is stored:
+
+```bash
+bilinc list --prefix agent.          # table of keys, types, update times, value previews
+bilinc list --all --json             # every page as JSON
+bilinc history agent.goal            # recorded changes, newest first
+bilinc confirm agent.goal            # still accurate; the value is unchanged
+bilinc export -o bilinc-export.json  # full values; the file is readable only by you
+```
+
 Rollback is two stages. Execute takes the token from the preview and never prompts interactively,
 so it stays safe inside automation:
 

{bilinc-2.3.7 → bilinc-2.3.8}/src/bilinc.egg-info/requires.txt

@@ -1,5 +1,5 @@
 certifi>=2024.2.2
-mcp<2.0,>=1.0.0
+mcp<2.0,>=1.10.0
 
 [dev]
 build<2.0,>=1.2

{bilinc-2.3.7 → bilinc-2.3.8}/tests/test_cloud_only_package.py

@@ -12,8 +12,8 @@ import pytest
 def test_public_api_is_cloud_only():
     import bilinc
 
-    assert bilinc.__version__ == "2.3.7"
-    assert bilinc.version == "2.3.7"
+    assert bilinc.__version__ == "2.3.8"
+    assert bilinc.version == "2.3.8"
     assert "utm_campaign=activation_2_3_4" in bilinc.ACTIVATION_SIGNUP_URL
     assert hasattr(bilinc, "Bilinc")
     assert hasattr(bilinc, "CloudClient")
@@ -32,7 +32,7 @@ def test_declared_wheel_packages_stay_cloud_only():
         pyproject = tomllib.load(handle)
 
     assert pyproject["tool"]["setuptools"]["packages"] == ["bilinc", "bilinc.cli"]
-    assert set(pyproject["project"]["dependencies"]) == {"certifi>=2024.2.2", "mcp>=1.0.0,<2.0"}
+    assert set(pyproject["project"]["dependencies"]) == {"certifi>=2024.2.2", "mcp>=1.10.0,<2.0"}
 
 
 class RecordingTransport:
@@ -110,9 +110,9 @@ def test_cloud_client_commit_posts_to_hosted_api():
             "headers": {
                 "Authorization": "Bearer bil_live_example",
                 "Content-Type": "application/json",
-                "User-Agent": "bilinc-python/2.3.7",
+                "User-Agent": "bilinc-python/2.3.8",
                 "X-Bilinc-Client": "python-sdk",
-                "X-Bilinc-Client-Version": "2.3.7",
+                "X-Bilinc-Client-Version": "2.3.8",
             },
             "body": json.dumps(
                 {
@@ -188,7 +188,7 @@ def test_cloud_client_status_reads_the_authenticated_status_endpoint():
             "url": "https://bilinc.space/api/cloud/status",
             "headers": {
                 "Authorization": "Bearer bil_live_example",
-                "User-Agent": "bilinc-python/2.3.7",
+                "User-Agent": "bilinc-python/2.3.8",
             },
             "body": None,
             "timeout": 30.0,