forget-ai 0.2.0__py3-none-any.whl

forget/__init__.py

@@ -0,0 +1,19 @@
+"""forget — memory for your AI. It forgets the junk, keeps what matters.
+
+The engine stores durable facts, retrieves them newest-first, retires stale
+ones non-destructively (supersede), and runs a verification loop so the
+memory keeps proving itself. The secret is the forgetting: an observation
+gate decides what is worth keeping at all.
+"""
+from __future__ import annotations
+
+import os
+
+__version__ = "0.1.0"
+
+# Environment compatibility shim: the engine historically reads MEM1_*
+# variables. FORGET_* is the public spelling; either works — FORGET_* fills
+# in only where the MEM1_* twin is unset.
+for _key, _value in list(os.environ.items()):
+    if _key.startswith("FORGET_"):
+        os.environ.setdefault("MEM1_" + _key[len("FORGET_"):], _value)

forget/cli.py

@@ -0,0 +1,183 @@
+"""forget-server — run and manage the local Forget server.
+
+The beta funnel's silent killer: a user installs, connects, reboots — and
+the server is gone. Hooks are fail-open by design, so memory just quietly
+stops arriving. The fix is a real lifecycle: `forget-server run` for the
+foreground, `forget-server install-service` for a login service (launchd on
+macOS, systemd --user on Linux), `status` to see what's true.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import socket
+import subprocess
+import sys
+from pathlib import Path
+
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 8000
+SERVICE_LABEL = "ai.forget.server"
+
+
+def forget_home() -> Path:
+    return Path(os.environ.get("FORGET_HOME", Path.home() / ".forget"))
+
+
+def db_path() -> Path:
+    return Path(os.environ.get("MEM1_DB_PATH", forget_home() / "forget.sqlite3"))
+
+
+def log_path() -> Path:
+    return forget_home() / "server.log"
+
+
+def launchd_plist(python: str, host: str, port: int) -> str:
+    return f"""<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>{SERVICE_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>{python}</string>
+    <string>-m</string><string>uvicorn</string>
+    <string>forget.server:app</string>
+    <string>--host</string><string>{host}</string>
+    <string>--port</string><string>{port}</string>
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict><key>MEM1_DB_PATH</key><string>{db_path()}</string></dict>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>{log_path()}</string>
+  <key>StandardErrorPath</key><string>{log_path()}</string>
+</dict>
+</plist>
+"""
+
+
+def systemd_unit(python: str, host: str, port: int) -> str:
+    return f"""[Unit]
+Description=Forget local memory server
+
+[Service]
+Environment=MEM1_DB_PATH={db_path()}
+ExecStart={python} -m uvicorn forget.server:app --host {host} --port {port}
+Restart=always
+RestartSec=2
+
+[Install]
+WantedBy=default.target
+"""
+
+
+def _port_open(host: str, port: int) -> bool:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.settimeout(0.6)
+        return sock.connect_ex((host, port)) == 0
+
+
+def _require_uvicorn() -> None:
+    try:
+        import uvicorn  # noqa: F401
+    except ImportError:
+        sys.exit("uvicorn is not installed. Run: pip install 'forget-ai[server]'")
+
+
+def cmd_run(args: argparse.Namespace) -> None:
+    _require_uvicorn()
+    import uvicorn
+
+    forget_home().mkdir(parents=True, exist_ok=True)
+    os.environ.setdefault("MEM1_DB_PATH", str(db_path()))
+    print(f"forget-server: http://{args.host}:{args.port}  (db: {db_path()})")
+    uvicorn.run("forget.server:app", host=args.host, port=args.port)
+
+
+def _launchd_paths() -> tuple[Path, str]:
+    plist = Path.home() / "Library" / "LaunchAgents" / f"{SERVICE_LABEL}.plist"
+    domain = f"gui/{os.getuid()}"
+    return plist, domain
+
+
+def cmd_install_service(args: argparse.Namespace) -> None:
+    _require_uvicorn()
+    forget_home().mkdir(parents=True, exist_ok=True)
+    python = sys.executable
+    if sys.platform == "darwin":
+        plist, domain = _launchd_paths()
+        plist.parent.mkdir(parents=True, exist_ok=True)
+        subprocess.run(["launchctl", "bootout", f"{domain}/{SERVICE_LABEL}"],
+                       capture_output=True)
+        plist.write_text(launchd_plist(python, args.host, args.port))
+        subprocess.run(["launchctl", "bootstrap", domain, str(plist)], check=True)
+        print(f"installed launchd service {SERVICE_LABEL}\n  plist: {plist}\n  logs:  {log_path()}")
+    elif sys.platform.startswith("linux"):
+        unit = Path.home() / ".config" / "systemd" / "user" / "forget-server.service"
+        unit.parent.mkdir(parents=True, exist_ok=True)
+        unit.write_text(systemd_unit(python, args.host, args.port))
+        subprocess.run(["systemctl", "--user", "daemon-reload"], check=True)
+        subprocess.run(["systemctl", "--user", "enable", "--now", "forget-server.service"], check=True)
+        print(f"installed systemd user service forget-server\n  unit: {unit}\n  logs: journalctl --user -u forget-server")
+    else:
+        sys.exit("install-service supports macOS (launchd) and Linux (systemd --user). "
+                 "On other platforms run `forget-server run` in a terminal.")
+
+
+def cmd_uninstall_service(_args: argparse.Namespace) -> None:
+    if sys.platform == "darwin":
+        plist, domain = _launchd_paths()
+        subprocess.run(["launchctl", "bootout", f"{domain}/{SERVICE_LABEL}"],
+                       capture_output=True)
+        if plist.exists():
+            plist.unlink()
+        print(f"removed launchd service {SERVICE_LABEL}")
+    elif sys.platform.startswith("linux"):
+        subprocess.run(["systemctl", "--user", "disable", "--now", "forget-server.service"],
+                       capture_output=True)
+        unit = Path.home() / ".config" / "systemd" / "user" / "forget-server.service"
+        if unit.exists():
+            unit.unlink()
+        subprocess.run(["systemctl", "--user", "daemon-reload"], capture_output=True)
+        print("removed systemd user service forget-server")
+    else:
+        sys.exit("nothing to uninstall on this platform")
+
+
+def cmd_status(args: argparse.Namespace) -> None:
+    listening = _port_open(args.host, args.port)
+    print(f"server: {'listening' if listening else 'not listening'} on {args.host}:{args.port}")
+    print(f"db:     {db_path()}{'' if db_path().exists() else '  (not created yet)'}")
+    if sys.platform == "darwin":
+        plist, _ = _launchd_paths()
+        print(f"service: {'installed' if plist.exists() else 'not installed'} ({plist})")
+    elif sys.platform.startswith("linux"):
+        unit = Path.home() / ".config" / "systemd" / "user" / "forget-server.service"
+        print(f"service: {'installed' if unit.exists() else 'not installed'} ({unit})")
+    if not listening:
+        sys.exit(1)
+
+
+def main(argv: list[str] | None = None) -> None:
+    shared = argparse.ArgumentParser(add_help=False)
+    shared.add_argument("--host", default=DEFAULT_HOST)
+    shared.add_argument("--port", type=int, default=DEFAULT_PORT)
+    parser = argparse.ArgumentParser(prog="forget-server", parents=[shared],
+                                     description="Run and manage the local Forget server.")
+    sub = parser.add_subparsers(dest="command")
+    sub.add_parser("run", help="run the server in the foreground", parents=[shared])
+    sub.add_parser("install-service", help="install a login service (launchd/systemd)", parents=[shared])
+    sub.add_parser("uninstall-service", help="remove the login service", parents=[shared])
+    sub.add_parser("status", help="show server and service state", parents=[shared])
+    args = parser.parse_args(argv)
+    command = args.command or "run"
+    {"run": cmd_run,
+     "install-service": cmd_install_service,
+     "uninstall-service": cmd_uninstall_service,
+     "status": cmd_status}[command](args)
+
+
+if __name__ == "__main__":
+    main()

forget/consolidation.py

@@ -0,0 +1,222 @@
+"""Consolidation worker — the verification loop as a product behavior.
+
+The brand promise is memory that keeps itself fresh, but until now the loop
+(stale-candidates → adjudication → supersede) only ran when an agent or a
+benchmark runner drove it by hand. This worker runs it in the background,
+per project, against entities with recent write activity:
+
+  1. find entities that stored memories since the last cycle (overlap-safe)
+  2. surface same-topic old/new pairs via stale_candidate_pairs (a hint
+     generator — precision tuned for triage, the adjudicator decides)
+  3. adjudicate each pair batch with a small LLM; two supersede registers:
+     state replacement (moved cities, changed stack) and plan completion
+     (a newer memory records that the older todo/intention got done or
+     dropped — the dogfood pain this worker exists to remove)
+  4. supersede the losers (non-destructive; search demotes, rows stay)
+
+Fail-safe posture: no adjudicator (missing API key, bad response) means no
+supersession — the worker never guesses. Everything is capped per cycle so
+a pathological corpus cannot melt the server or the LLM bill.
+
+Gates: project setting `consolidation_enabled` (dogfood-first, like
+temporal_rerank), env kill switch MEM1_CONSOLIDATION=0.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+import httpx
+
+from .db import get_db
+from .providers import get_project_settings
+
+ADJUDICATE_SYSTEM_PROMPT = (
+    "You maintain a long-term memory store. You are given pairs of memories "
+    "about the same subject: an OLDER one and a NEWER one. For each pair, "
+    "decide whether the newer memory makes the older one stale. Mark "
+    "supersede=true in exactly two situations:\n"
+    "1. State replacement: both describe the same fact or state and the newer "
+    "one replaces or invalidates the older one (moved cities, changed stack, "
+    "condition resolved, decision reversed).\n"
+    "2. Plan completion: the older memory is a plan, todo, or intention and "
+    "the newer memory records that it was completed, shipped, or abandoned.\n"
+    "If they cover different topics, or both can be true at once, answer "
+    "false. When unsure, answer false.\n"
+    'Reply with a JSON array only, one object per pair, in the same order: '
+    '[{"pair": <index>, "supersede": true|false}]'
+)
+
+
+def consolidation_env_enabled() -> bool:
+    return (os.getenv("MEM1_CONSOLIDATION") or "1").strip().lower() not in {"0", "false", "no"}
+
+
+def _consolidation_params() -> dict[str, Any]:
+    return {
+        "model": os.getenv("MEM1_CONSOLIDATION_MODEL") or "gpt-4o-mini",
+        "base_url": (os.getenv("MEM1_CONSOLIDATION_BASE_URL") or "https://api.openai.com/v1").rstrip("/"),
+        "api_key": os.getenv("MEM1_CONSOLIDATION_API_KEY") or os.getenv("OPENAI_API_KEY") or "",
+        "max_entities": int(os.getenv("MEM1_CONSOLIDATION_MAX_ENTITIES", "20")),
+        "max_pairs_per_entity": int(os.getenv("MEM1_CONSOLIDATION_MAX_PAIRS", "60")),
+        "max_supersedes_per_cycle": int(os.getenv("MEM1_CONSOLIDATION_MAX_SUPERSEDES", "40")),
+        "activity_window_hours": float(os.getenv("MEM1_CONSOLIDATION_WINDOW_HOURS", "26")),
+        # optional floor override for the pair inbox (embedding-scale dependent:
+        # production bge sits at ~0.80, the deterministic test embedding lower)
+        "min_similarity": os.getenv("MEM1_CONSOLIDATION_MIN_SIMILARITY"),
+        "batch_size": 12,
+    }
+
+
+def _recently_active_entities(window_hours: float, limit: int) -> list[dict[str, str]]:
+    """(project, entity) pairs with new memories inside the window.
+
+    The window deliberately overlaps consecutive cycles: rerunning an entity
+    is idempotent (surfaced pairs whose loser is already superseded drop out
+    of the inbox), so a restart never loses work, only repeats cheap reads.
+    """
+    from datetime import datetime, timedelta, timezone
+
+    cutoff_iso = (datetime.now(timezone.utc) - timedelta(hours=window_hours)).strftime("%Y-%m-%dT%H:%M:%SZ")
+    with get_db() as conn:
+        rows = conn.execute(
+            """
+            SELECT project_id, user_id, agent_id, MAX(created_at) AS latest
+              FROM memories
+             WHERE deleted = 0 AND created_at > ?
+               AND (user_id IS NOT NULL AND user_id != '' OR agent_id IS NOT NULL AND agent_id != '')
+             GROUP BY project_id, user_id, agent_id
+             ORDER BY latest DESC
+            """,
+            (cutoff_iso,),
+        ).fetchall()
+    entities: list[dict[str, str]] = []
+    for row in rows[: max(limit, 0)]:
+        field = "user_id" if row["user_id"] else "agent_id"
+        entities.append({"project_id": row["project_id"], "field": field, "value": row[field]})
+    return entities
+
+
+def _adjudicate_batch(pairs: list[dict[str, Any]], params: dict[str, Any]) -> list[bool]:
+    """One LLM call per batch; any failure refuses the whole batch."""
+    lines = []
+    for index, pair in enumerate(pairs):
+        older, newer = pair.get("older") or {}, pair.get("newer") or {}
+        lines.append(
+            f"PAIR {index}:\n"
+            f"  OLDER ({str(older.get('created_at'))[:10]}): {str(older.get('memory'))[:400]}\n"
+            f"  NEWER ({str(newer.get('created_at'))[:10]}): {str(newer.get('memory'))[:400]}"
+        )
+    body = {
+        "model": params["model"],
+        "messages": [
+            {"role": "system", "content": ADJUDICATE_SYSTEM_PROMPT},
+            {"role": "user", "content": "\n\n".join(lines)},
+        ],
+        "temperature": 0,
+    }
+    try:
+        with httpx.Client(timeout=30) as client:
+            response = client.post(
+                f"{params['base_url']}/chat/completions",
+                headers={"Authorization": f"Bearer {params['api_key']}", "Content-Type": "application/json"},
+                json=body,
+            )
+        response.raise_for_status()
+        content = str(response.json()["choices"][0]["message"]["content"]).strip()
+        if content.startswith("```"):
+            content = content.strip("`")
+        array = json.loads(content[content.index("[") : content.rindex("]") + 1])
+        verdicts = [False] * len(pairs)
+        for entry in array:
+            index = int(entry.get("pair", -1))
+            if 0 <= index < len(pairs):
+                verdicts[index] = bool(entry.get("supersede"))
+        return verdicts
+    except Exception:
+        return [False] * len(pairs)
+
+
+# Pairs already adjudicated "keep both" this process lifetime. The inbox
+# resurfaces the same stable pairs every cycle; without this, the worker
+# re-buys the same LLM verdicts every 30 minutes. Process-lifetime is enough:
+# a restart re-judges once, and superseded pairs leave the inbox on their own.
+_adjudicated_keep: set[tuple[str, str]] = set()
+
+
+def consolidation_cycle() -> dict[str, Any]:
+    """One pass over recently-active entities. Returns a cycle report."""
+    report: dict[str, Any] = {"entities": 0, "pairs": 0, "superseded": 0, "skipped_projects": 0}
+    if not consolidation_env_enabled():
+        report["disabled"] = "env"
+        return report
+    params = _consolidation_params()
+    if not params["api_key"]:
+        # no adjudicator → no judgments → no supersession; stay silent but honest
+        report["disabled"] = "no_api_key"
+        return report
+
+    # imported here: store imports providers, and this module rides on store's
+    # public operations — a top-level import would create a cycle
+    from .store import stale_candidate_pairs, supersede_memory
+
+    settings_cache: dict[str, bool] = {}
+    supersedes_left = params["max_supersedes_per_cycle"]
+    for entity in _recently_active_entities(params["activity_window_hours"], params["max_entities"]):
+        project_id = entity["project_id"]
+        if project_id not in settings_cache:
+            settings_cache[project_id] = bool(get_project_settings(project_id).get("consolidation_enabled"))
+        if not settings_cache[project_id]:
+            report["skipped_projects"] += 1
+            continue
+        min_days = get_project_settings(project_id).get("temporal_min_days")
+        payload: dict[str, Any] = {
+            "filters": {entity["field"]: entity["value"]},
+            "top_n": params["max_pairs_per_entity"],
+            "project_id": project_id,
+        }
+        if min_days is not None:
+            payload["min_days"] = min_days
+        if params["min_similarity"] is not None:
+            payload["min_similarity"] = float(params["min_similarity"])
+        try:
+            pairs = (stale_candidate_pairs(payload, project_id=project_id) or {}).get("pairs") or []
+        except Exception:
+            continue
+        pairs = [
+            pair for pair in pairs
+            if ((pair.get("older") or {}).get("id"), (pair.get("newer") or {}).get("id")) not in _adjudicated_keep
+        ]
+        report["entities"] += 1
+        report["pairs"] += len(pairs)
+        for start in range(0, len(pairs), params["batch_size"]):
+            if supersedes_left <= 0:
+                break
+            batch = pairs[start : start + params["batch_size"]]
+            verdicts = _adjudicate_batch(batch, params)
+            for pair, verdict in zip(batch, verdicts):
+                pair_key = ((pair.get("older") or {}).get("id"), (pair.get("newer") or {}).get("id"))
+                if not verdict:
+                    _adjudicated_keep.add(pair_key)
+                    continue
+                if supersedes_left <= 0:
+                    continue
+                older, newer = pair.get("older") or {}, pair.get("newer") or {}
+                if not older.get("id") or not newer.get("id"):
+                    continue
+                try:
+                    supersede_memory(
+                        older["id"],
+                        {
+                            "superseded_by": newer["id"],
+                            "reason": "consolidation worker: newer state or completion supersedes",
+                        },
+                        project_id=project_id,
+                    )
+                    report["superseded"] += 1
+                    supersedes_left -= 1
+                except Exception:
+                    continue
+    return report

forget/crypto.py

@@ -0,0 +1,239 @@
+"""E2EE vault primitives: keys, wrapping, record sealing, recovery codes.
+
+Pure functions over libsodium (PyNaCl); no I/O and no key custody here —
+see docs/vault-design.md for the key hierarchy this implements and
+forget/keyring.py (future) for storage. Nothing in this module invents a
+cryptographic construction: every operation maps 1:1 onto a libsodium
+primitive.
+
+Requires the optional dependency: pip install forget-ai[vault]
+"""
+from __future__ import annotations
+
+import hashlib
+import secrets
+from dataclasses import dataclass
+
+try:
+    from nacl.bindings import (
+        crypto_aead_xchacha20poly1305_ietf_decrypt,
+        crypto_aead_xchacha20poly1305_ietf_encrypt,
+    )
+    from nacl.exceptions import CryptoError
+    from nacl.public import PrivateKey, PublicKey, SealedBox
+    from nacl.pwhash import argon2id
+    from nacl.signing import SigningKey, VerifyKey
+except ImportError as error:  # pragma: no cover
+    raise ImportError(
+        "forget.crypto needs PyNaCl. Install it with: pip install forget-ai[vault]"
+    ) from error
+
+KEY_BYTES = 32
+NONCE_BYTES = 24
+
+_RECOVERY_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567"  # RFC 4648 base32
+_RECOVERY_VERSION = "F1"
+_RECOVERY_DATA_CHARS = 26  # 130 bits of entropy
+_RECOVERY_CHECK_CHARS = 2
+
+
+class VaultCryptoError(Exception):
+    """Decryption or verification failed: wrong key, tampered data, or
+    mismatched envelope (AAD)."""
+
+
+@dataclass(frozen=True)
+class DeviceKeys:
+    """One device's key material. Private halves belong in the OS keychain."""
+
+    signing_seed: bytes  # Ed25519 seed (server-auth signing)
+    verify_key: bytes  # Ed25519 public
+    exchange_private: bytes  # X25519 private (master-key sealing)
+    exchange_public: bytes  # X25519 public
+
+
+# --- key generation -------------------------------------------------------
+
+def generate_master_key() -> bytes:
+    return secrets.token_bytes(KEY_BYTES)
+
+
+def generate_scope_key() -> bytes:
+    return secrets.token_bytes(KEY_BYTES)
+
+
+def generate_device_keys() -> DeviceKeys:
+    signing = SigningKey.generate()
+    exchange = PrivateKey.generate()
+    return DeviceKeys(
+        signing_seed=bytes(signing),
+        verify_key=bytes(signing.verify_key),
+        exchange_private=bytes(exchange),
+        exchange_public=bytes(exchange.public_key),
+    )
+
+
+# --- master key <-> device (sealed box) -----------------------------------
+
+def seal_to_device(secret: bytes, exchange_public: bytes) -> bytes:
+    """Encrypt a secret so only the holder of the device private key can
+    read it. Anyone (including the server relaying enrollment) can produce
+    this; only the device can open it."""
+    return SealedBox(PublicKey(exchange_public)).encrypt(secret)
+
+
+def open_from_device(sealed: bytes, exchange_private: bytes) -> bytes:
+    try:
+        return SealedBox(PrivateKey(exchange_private)).decrypt(sealed)
+    except CryptoError as error:
+        raise VaultCryptoError("sealed key does not open with this device key") from error
+
+
+# --- scope keys <-> master key (AEAD wrap) --------------------------------
+
+def _aead_encrypt(plaintext: bytes, key: bytes, aad: bytes) -> bytes:
+    nonce = secrets.token_bytes(NONCE_BYTES)
+    ciphertext = crypto_aead_xchacha20poly1305_ietf_encrypt(plaintext, aad, nonce, key)
+    return nonce + ciphertext
+
+
+def _aead_decrypt(blob: bytes, key: bytes, aad: bytes, what: str) -> bytes:
+    if len(blob) <= NONCE_BYTES:
+        raise VaultCryptoError(f"{what}: blob too short")
+    try:
+        return crypto_aead_xchacha20poly1305_ietf_decrypt(
+            blob[NONCE_BYTES:], aad, blob[:NONCE_BYTES], key
+        )
+    except CryptoError as error:
+        raise VaultCryptoError(f"{what}: wrong key, tampered data, or mismatched context") from error
+
+
+def wrap_key(key_to_wrap: bytes, master_key: bytes, *, context: str) -> bytes:
+    """Wrap a scope key under the master key. `context` (e.g. "scope:<uuid>")
+    binds the wrap to its purpose so a wrapped key cannot be replayed as a
+    different scope's key."""
+    return _aead_encrypt(key_to_wrap, master_key, context.encode())
+
+
+def unwrap_key(wrapped: bytes, master_key: bytes, *, context: str) -> bytes:
+    return _aead_decrypt(wrapped, master_key, context.encode(), "unwrap_key")
+
+
+# --- record sealing --------------------------------------------------------
+
+def record_aad(record_id: str, scope_id: str, schema_ver: int, seq: int) -> bytes:
+    """Canonical associated data binding a ciphertext to its envelope row.
+    A server that swaps scope_id or replays a record at a different seq
+    produces a blob that fails authentication."""
+    for name, value in (("record_id", record_id), ("scope_id", scope_id)):
+        if "|" in value:
+            raise ValueError(f"{name} must not contain '|'")
+    return f"{record_id}|{scope_id}|{schema_ver}|{seq}".encode()
+
+
+def seal_record(
+    plaintext: bytes,
+    scope_key: bytes,
+    *,
+    record_id: str,
+    scope_id: str,
+    schema_ver: int,
+    seq: int,
+) -> bytes:
+    """Encrypt one memory record (text, embedding, metadata — already
+    serialized) under its scope key. Returns nonce-prefixed ciphertext."""
+    return _aead_encrypt(
+        plaintext, scope_key, record_aad(record_id, scope_id, schema_ver, seq)
+    )
+
+
+def open_record(
+    blob: bytes,
+    scope_key: bytes,
+    *,
+    record_id: str,
+    scope_id: str,
+    schema_ver: int,
+    seq: int,
+) -> bytes:
+    return _aead_decrypt(
+        blob,
+        scope_key,
+        record_aad(record_id, scope_id, schema_ver, seq),
+        "open_record",
+    )
+
+
+# --- recovery code ---------------------------------------------------------
+
+def _recovery_checksum(data: str) -> str:
+    digest = hashlib.blake2b(data.encode(), digest_size=4).digest()
+    value = int.from_bytes(digest, "big")
+    first = _RECOVERY_ALPHABET[value % 32]
+    second = _RECOVERY_ALPHABET[(value // 32) % 32]
+    return first + second
+
+
+def normalize_recovery_code(code: str) -> str:
+    return code.replace("-", "").replace(" ", "").upper()
+
+
+def generate_recovery_code() -> str:
+    """One-time recovery code (130 bits + checksum), shown once at vault
+    creation. Format: F1-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXX."""
+    data = "".join(secrets.choice(_RECOVERY_ALPHABET) for _ in range(_RECOVERY_DATA_CHARS))
+    raw = _RECOVERY_VERSION + data + _recovery_checksum(_RECOVERY_VERSION + data)
+    groups = [raw[i : i + 5] for i in range(0, len(raw), 5)]
+    return "-".join(groups)
+
+
+def validate_recovery_code(code: str) -> bool:
+    raw = normalize_recovery_code(code)
+    expected_len = len(_RECOVERY_VERSION) + _RECOVERY_DATA_CHARS + _RECOVERY_CHECK_CHARS
+    if len(raw) != expected_len or not raw.startswith(_RECOVERY_VERSION):
+        return False
+    body, check = raw[:-_RECOVERY_CHECK_CHARS], raw[-_RECOVERY_CHECK_CHARS:]
+    if any(char not in _RECOVERY_ALPHABET for char in body[len(_RECOVERY_VERSION):]):
+        return False
+    return _recovery_checksum(body) == check
+
+
+def derive_recovery_key(
+    code: str,
+    salt: bytes,
+    *,
+    opslimit: int = argon2id.OPSLIMIT_MODERATE,
+    memlimit: int = argon2id.MEMLIMIT_MODERATE,
+) -> bytes:
+    """Argon2id-derive the recovery key that wraps the master key. The salt
+    is stored server-side next to the recovery-wrapped master key; the code
+    itself never leaves the user."""
+    if not validate_recovery_code(code):
+        raise ValueError("malformed recovery code")
+    if len(salt) != argon2id.SALTBYTES:
+        raise ValueError(f"salt must be {argon2id.SALTBYTES} bytes")
+    return argon2id.kdf(
+        KEY_BYTES,
+        normalize_recovery_code(code).encode(),
+        salt,
+        opslimit=opslimit,
+        memlimit=memlimit,
+    )
+
+
+def generate_recovery_salt() -> bytes:
+    return secrets.token_bytes(argon2id.SALTBYTES)
+
+
+# --- server auth (Ed25519 challenge-response) ------------------------------
+
+def sign_challenge(challenge: bytes, signing_seed: bytes) -> bytes:
+    return SigningKey(signing_seed).sign(challenge).signature
+
+
+def verify_challenge(challenge: bytes, signature: bytes, verify_key: bytes) -> bool:
+    try:
+        VerifyKey(verify_key).verify(challenge, signature)
+        return True
+    except CryptoError:
+        return False