superb-memory 0.2.1__py3-none-any.whl

cli.py

@@ -0,0 +1,310 @@
+#!/usr/bin/env python3
+"""mdb — command-line access to a MemoryDB server for scripts, cron jobs and CI.
+
+Connection comes from --url or MEMORYDB_URL (accepts http://host:port plus
+MEMORYDB_TOKEN, or a memorydb://TOKEN@host:port connection string).
+`mdb serve` installs and starts the server itself, so pip is the only thing you need.
+Every command prints the JSON response on stdout; errors exit non-zero.
+"""
+import argparse
+import hashlib
+import json
+import os
+import platform
+import secrets
+import shutil
+import subprocess
+import sys
+import tarfile
+import urllib.error
+import urllib.request
+from urllib.parse import urlparse
+
+sys.path.insert(0, str(os.path.dirname(os.path.abspath(__file__))))
+from memorydb import MemoryDB, MemoryDBError  # noqa: E402
+
+SERVER_VERSION = "0.2.1"          # the release tag mdb serve downloads by default
+REPO = "humaniods/MemoryDB"
+
+
+def load_db(args):
+    url = args.url or os.environ.get("MEMORYDB_URL", "http://127.0.0.1:8080")
+    if url.startswith("memorydb"):
+        return MemoryDB.from_url(url)
+    token = args.token or os.environ.get("MEMORYDB_TOKEN")
+    if not token:
+        sys.exit("no token: pass --token or set MEMORYDB_TOKEN/MEMORYDB_URL")
+    return MemoryDB(url, token=token)
+
+
+def read_json_arg(value, path):
+    if path:
+        with open(path) as fh:
+            return json.load(fh)
+    if value:
+        return json.loads(value)
+    sys.exit("provide --json or --file")
+
+
+def emit(obj):
+    print(json.dumps(obj, indent=2, default=str))
+
+
+# -- mdb serve: the database itself, installed over pip, with no Go or git -----------------
+def home():
+    path = os.environ.get("MEMORYDB_HOME") or os.path.join(os.path.expanduser("~"), ".memorydb")
+    os.makedirs(path, exist_ok=True)
+    return path
+
+
+def platform_target():
+    system = platform.system()
+    if system == "Windows" or system.startswith(("MINGW", "MSYS", "CYGWIN")):
+        sys.exit("mdb serve: no native Windows build (the database lock is Unix-only); "
+                 "run the server in WSL, Docker or on your app host.")
+    osname = {"Linux": "linux", "Darwin": "darwin"}.get(system)
+    if osname is None:
+        sys.exit(f"mdb serve: unsupported operating system: {system}")
+    arch = {"x86_64": "amd64", "amd64": "amd64", "aarch64": "arm64", "arm64": "arm64"}.get(
+        platform.machine().lower())
+    if arch is None:
+        sys.exit(f"mdb serve: unsupported CPU architecture: {platform.machine()}")
+    return osname, arch
+
+
+def fetch(url, dest):
+    """Copy a release archive down over https, or from a local path/file:// URL."""
+    if url.startswith("https://"):
+        with urllib.request.urlopen(url, timeout=120) as response, open(dest, "wb") as out:
+            shutil.copyfileobj(response, out)
+        return
+    source = urlparse(url).path if url.startswith("file://") else url
+    if not os.path.exists(source):
+        raise FileNotFoundError(source)
+    shutil.copyfile(source, dest)
+
+
+def checksum(path):
+    digest = hashlib.sha256()
+    with open(path, "rb") as fh:
+        for block in iter(lambda: fh.read(1 << 20), b""):
+            digest.update(block)
+    return digest.hexdigest()
+
+
+def extract_binary(archive, dest):
+    """Unpack only the memorydb member, so a crafted path in a tar entry cannot write elsewhere."""
+    with tarfile.open(archive) as tar:
+        member = next((m for m in tar.getmembers()
+                       if m.isfile() and os.path.basename(m.name) == "memorydb"), None)
+        if member is None:
+            sys.exit(f"mdb serve: {os.path.basename(archive)} holds no memorydb binary")
+        with tar.extractfile(member) as src, open(dest, "wb") as out:
+            shutil.copyfileobj(src, out)
+    os.chmod(dest, 0o755)
+    return dest
+
+
+def check_against_sidecar(archive, sidecar):
+    """A checksums file that exists but does not name this archive is treated as a mismatch."""
+    if not sidecar or not os.path.exists(sidecar):
+        return
+    wanted = {}
+    with open(sidecar) as fh:
+        for line in fh:
+            parts = line.split(None, 1)
+            if len(parts) == 2:
+                wanted[parts[1].strip().lstrip("*")] = parts[0]
+    name = os.path.basename(archive)
+    if name not in wanted:
+        sys.exit(f"mdb serve: {name} is not listed in {sidecar}; refusing to install it")
+    if checksum(archive) != wanted[name]:
+        sys.exit(f"mdb serve: sha256 mismatch for {name}; refusing to install it")
+
+
+def install_from_archive(archive, version):
+    check_against_sidecar(archive, os.path.join(os.path.dirname(archive), "sha256sums.txt"))
+    staged = os.path.join(home(), "bin", f"memorydb-{version}.tmp")
+    target = binary_path(version)
+    extract_binary(archive, staged)
+    os.replace(staged, target)
+    return target
+
+
+def binary_path(version):
+    return os.path.join(home(), "bin", f"memorydb-{version}")
+
+
+def ensure_binary(args):
+    if args.bin:
+        return os.path.abspath(args.bin)
+    target = binary_path(args.version)
+    if os.path.exists(target) and not args.force:
+        return target
+    os.makedirs(os.path.join(home(), "bin"), exist_ok=True)
+    if args.from_archive:
+        return install_from_archive(args.from_archive, args.version)
+    if args.source:
+        if shutil.which("go") is None:
+            sys.exit("mdb serve: --source needs Go on PATH")
+        built = os.path.join(home(), "bin", f"memorydb-{args.version}.tmp")
+        subprocess.run(["go", "build", "-trimpath", "-o", built, "."], cwd=args.source, check=True)
+        os.replace(built, target)
+        return target
+    osname, arch = platform_target()
+    name = f"memorydb-{args.version}-{osname}-{arch}.tar.gz"
+    base = args.dist_base.format(repo=REPO, version=args.version)
+    archive = os.path.join(home(), "bin", name)
+    print(f"downloading {base}/{name}")
+    try:
+        fetch(base + "/" + name, archive)
+        try:
+            fetch(base + "/sha256sums.txt", os.path.join(os.path.dirname(archive), "sha256sums.txt"))
+        except FileNotFoundError:
+            sys.exit("mdb serve: this release publishes no sha256sums.txt; refusing to run an "
+                     "unverified binary. Use --from <archive>, --source <tree> or --bin <path>.")
+    except (OSError, urllib.error.URLError) as exc:
+        sys.exit(f"mdb serve: could not fetch a release binary for {osname}/{arch} "
+                 f"({exc.__class__.__name__}). If this version is not released yet, use "
+                 f"--source <path-to-checkout> or --bin <path-to-memorydb>.")
+    return install_from_archive(archive, args.version)
+
+
+def serve_token(explicit):
+    if explicit:
+        return explicit
+    if os.environ.get("MEMORYDB_TOKEN"):
+        return os.environ["MEMORYDB_TOKEN"]
+    path = os.path.join(home(), "token")
+    if os.path.exists(path):
+        with open(path) as fh:
+            token = fh.read().strip()
+        if token:
+            return token
+    token = secrets.token_urlsafe(32)
+    handle = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(handle, "w") as fh:
+        fh.write(token + "\n")
+    return token
+
+
+def serve(args):
+    binary = ensure_binary(args)
+    data = args.data or os.path.join(home(), "data", "memory.wal")
+    os.makedirs(os.path.dirname(os.path.abspath(data)), exist_ok=True)
+    token = serve_token(args.token)
+    env = dict(os.environ, MEMORYDB_TOKEN=token)
+    command = [binary, "-addr", args.addr, "-data", data]
+    if args.worker:
+        command.append("-worker")
+    command += args.extra
+    scheme = "memorydbs" if args.extra and "-tls-cert" in args.extra else "memorydb"
+    host = args.addr if "://" not in args.addr else urlparse(args.addr).netloc
+    print(f"starting MemoryDB on {host}")
+    print(f"  data:    {data}")
+    print(f"  connect: {scheme}://{token}@{host}")
+    print(f"  console: http{'s' if scheme == 'memorydbs' else ''}://{host}  "
+          f"studio: http{'s' if scheme == 'memorydbs' else ''}://{host}/studio/")
+    sys.stdout.flush()
+    return subprocess.run(command, env=env).returncode
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="mdb", description=__doc__.splitlines()[0])
+    parser.add_argument("--url", help="http://host:port or memorydb://TOKEN@host:port")
+    parser.add_argument("--token")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    sub.add_parser("health")
+
+    p = sub.add_parser("collections"); p.add_argument("action", choices=["ls", "create"])
+    p.add_argument("name", nargs="?"); p.add_argument("--json", help="schema JSON")
+    p.add_argument("--file")
+
+    p = sub.add_parser("doc"); p.add_argument("action", choices=["add", "get", "rm", "patch"])
+    p.add_argument("collection"); p.add_argument("id", nargs="?")
+    p.add_argument("--json"); p.add_argument("--file"); p.add_argument("--version", type=int)
+
+    p = sub.add_parser("query"); p.add_argument("collection")
+    p.add_argument("--where", default="[]"); p.add_argument("--order"); p.add_argument("--desc", action="store_true")
+    p.add_argument("--limit", type=int, default=50); p.add_argument("--fields", help="comma-separated projection")
+
+    p = sub.add_parser("memory"); p.add_argument("action", choices=["add", "ls", "history"])
+    p.add_argument("--kind", default="fact"); p.add_argument("--content"); p.add_argument("--id")
+    p.add_argument("--source", default="cli"); p.add_argument("--q", default=""); p.add_argument("--limit", type=int, default=50)
+
+    p = sub.add_parser("search"); p.add_argument("text")
+    p.add_argument("--kind", default=""); p.add_argument("--limit", type=int, default=10)
+
+    p = sub.add_parser("ingest"); p.add_argument("--file", required=True)
+    p = sub.add_parser("tx"); p.add_argument("--file", required=True); p.add_argument("--key")
+
+    p = sub.add_parser("serve", help="install (if needed) and run the MemoryDB server")
+    p.add_argument("--addr", default="127.0.0.1:8080")
+    p.add_argument("--data", help="journal path (default ~/.memorydb/data/memory.wal)")
+    p.add_argument("--token", default=argparse.SUPPRESS, help="admin token (default MEMORYDB_TOKEN or a generated one)")
+    p.add_argument("--version", default=SERVER_VERSION, help="release binary to fetch")
+    p.add_argument("--bin", help="run this already-built server binary")
+    p.add_argument("--from", dest="from_archive", help="install the server from this release archive")
+    p.add_argument("--source", help="build the server from this source tree (needs Go)")
+    p.add_argument("--dist-base", default="https://github.com/{repo}/releases/download/v{version}",
+                   help="release download base; {repo} and {version} are substituted")
+    p.add_argument("--worker", action="store_true", help="also run durable ingestion jobs")
+    p.add_argument("--force", action="store_true", help="re-download even when the binary is cached")
+    p.add_argument("extra", nargs=argparse.REMAINDER,
+                   help="more server flags, e.g. -- -tls-cert cert.pem -tls-key key.pem")
+
+    args = parser.parse_args(argv)
+    if args.cmd == "serve":
+        return serve(args)
+    db = load_db(args)
+    try:
+        if args.cmd == "health":
+            emit(db.request("GET", "health/"))
+        elif args.cmd == "collections":
+            if args.action == "ls":
+                emit(db.collections.all())
+            else:
+                schema = read_json_arg(args.json, args.file) if (args.json or args.file) else {}
+                emit(db.collections.create(args.name, **schema))
+        elif args.cmd == "doc":
+            if args.action == "add":
+                emit(db.collection(args.collection).objects.create(data=read_json_arg(args.json, args.file)))
+            elif args.action == "get":
+                emit(db.collection(args.collection).objects.get(pk=args.id))
+            elif args.action == "patch":
+                emit(db.collection(args.collection).objects.update(pk=args.id, version=args.version, **read_json_arg(args.json, args.file)))
+            else:
+                emit(db.collection(args.collection).objects.delete(pk=args.id, version=args.version))
+        elif args.cmd == "query":
+            q = {"where": json.loads(args.where), "limit": args.limit}
+            if args.order:
+                q["order_by"] = args.order
+                q["descending"] = args.desc
+            if args.fields:
+                q["projection"] = args.fields.split(",")
+            emit(db.request("POST", "query/" + args.collection + "/", q))
+        elif args.cmd == "memory":
+            if args.action == "add":
+                emit(db.objects.create(kind=args.kind, content=args.content, source=args.source))
+            elif args.action == "ls":
+                emit(db.objects.filter(kind=args.kind if args.kind != "fact" else "", source=args.source, q=args.q, limit=args.limit))
+            else:
+                emit(db.objects.history(pk=args.id)["results"])
+        elif args.cmd == "search":
+            emit(db.objects.search(args.text, kind=args.kind, limit=args.limit))
+        elif args.cmd == "ingest":
+            with open(args.file) as fh:
+                payload = json.load(fh)
+            emit(db.ingest(payload["messages"], facts=payload.get("facts"), source=payload.get("source", "cli")))
+        elif args.cmd == "tx":
+            with open(args.file) as fh:
+                payload = json.load(fh)
+            emit(db.transaction(payload["changes"], idempotency_key=args.key))
+    except MemoryDBError as exc:
+        sys.exit(f"mdb error [{exc.status}]: {exc}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

memorydb.py

@@ -0,0 +1,354 @@
+"""Django-style, dependency-free HTTP client for the original Go engine.
+This is not a Django ORM backend: custom QuerySet support, but no SQL, migrations or joins.
+"""
+import json
+import os
+from urllib.error import HTTPError
+from urllib.parse import quote, unquote, urlencode, urlsplit
+from urllib.request import Request, urlopen
+
+class MemoryDBError(Exception):
+    def __init__(self, status, message):
+        self.status = status
+        super().__init__(message)
+
+class MemoryManager:
+    def __init__(self, client):
+        self.client = client
+
+    def create(self, *, kind="fact", content, **fields):
+        return self.client.request("POST", "memories/", {"kind": kind, "content": content, **fields})
+
+    def filter(self, *, kind="", source="", q="", limit=50):
+        return self.client.request("GET", "memories/?" + urlencode(dict(kind=kind, source=source, q=q, limit=limit)))["results"]
+
+    def get(self, *, pk):
+        return self.client.request("GET", "memories/" + quote(pk, safe="") + "/")
+
+    def update(self, *, pk, version, **fields):
+        record = self.get(pk=pk)
+        if record["version"] != version:
+            raise MemoryDBError(409, "version conflict; reload the record")
+        record.update(fields)
+        record["version"] = version
+        return self.client.request("PUT", "memories/" + quote(pk, safe="") + "/", record)
+
+    def delete(self, *, pk, version):
+        return self.client.request("DELETE", "memories/" + quote(pk, safe="") + "/", headers={"If-Match": str(version)})
+
+    def history(self, *, pk):
+        return self.client.request("GET", "memories/" + quote(pk, safe="") + "/history/")["results"]
+
+    def search(self, text="", *, vector=None, kind="", source="", embedding_model="", agent="", limit=10):
+        return self.client.request("POST", "search/", dict(text=text, vector=vector or [], kind=kind, source=source, embedding_model=embedding_model, agent=agent, limit=limit))["results"]
+
+def parse_connection_string(connection_string):
+    """memorydb://TOKEN@host:port (plain HTTP) or memorydbs://TOKEN@host:port (TLS).
+
+    The port defaults to 8080. This mirrors the mongodb:// and redis:// convention so
+    deployments can hand one env var (MEMORYDB_URL) to every client.
+    """
+    parts = urlsplit(connection_string)
+    if parts.scheme not in ("memorydb", "memorydbs"):
+        raise ValueError("connection string must start with memorydb:// or memorydbs://")
+    if not parts.username:
+        raise ValueError("connection string must carry the token: memorydb://TOKEN@host:port")
+    host = parts.hostname or "127.0.0.1"
+    port = parts.port or 8080
+    scheme = "https" if parts.scheme == "memorydbs" else "http"
+    return scheme + "://" + host + ":" + str(port), unquote(parts.username)
+
+
+class MemoryDB:
+    def __init__(self, url="http://127.0.0.1:8080", *, token=None, timeout=35):
+        if token is None:
+            if url.startswith(("memorydb://", "memorydbs://")):
+                connection_string = url
+            else:
+                connection_string = os.environ.get("MEMORYDB_URL", "")
+            if not connection_string:
+                raise ValueError("pass a url with token=, a memorydb:// connection string, or set MEMORYDB_URL")
+            url, token = parse_connection_string(connection_string)
+        self.url = url.rstrip("/") + "/api/v1/"
+        self.token = token
+        self.timeout = timeout
+        self.objects = MemoryManager(self)
+        self.collections = CollectionManager(self)
+
+    @classmethod
+    def from_url(cls, connection_string, **fields):
+        """MemoryDB.from_url("memorydb://TOKEN@127.0.0.1:8080")"""
+        url, token = parse_connection_string(connection_string)
+        return cls(url, token=token, **fields)
+
+    def collection(self, name):
+        return Collection(self, name)
+
+    def transaction(self, changes, *, idempotency_key=None):
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        return self.request("POST", "transactions/", {"changes": changes}, headers=headers)["results"]
+
+    def ingest(self, messages, *, facts=None, extract=False, source="python", context="", tools=None):
+        return self.request("POST", "ingest/", {"messages": messages, "facts": facts or [], "extract": extract,
+                            "source": source, "context": context, "tools": tools or []})["results"]
+
+    def queue_ingest(self, **payload):
+        return self.request("POST", "jobs/", payload)
+
+    def request(self, method, path, body=None, headers=None):
+        req = Request(self.url + path, data=json.dumps(body).encode() if body is not None else None,
+                      headers={"Authorization": "Bearer " + self.token, "Content-Type": "application/json", **(headers or {})}, method=method)
+        try:
+            with urlopen(req, timeout=self.timeout) as response:
+                return json.load(response)
+        except HTTPError as exc:
+            try:
+                message = json.load(exc).get("error", str(exc))
+            except (ValueError, AttributeError):
+                message = str(exc)
+            raise MemoryDBError(exc.code, message) from exc
+
+SUPPORTED_LOOKUPS = {"eq", "ne", "gt", "gte", "lt", "lte", "in", "contains", "icontains",
+                    "prefix", "exists", "iequals", "iexact"}
+
+
+def _predicates(lookups):
+    """Turn Django-style kwargs into engine predicates; iexact is the Django spelling of iequals."""
+    predicates = []
+    for key, value in lookups.items():
+        parts = key.split("__")
+        op = parts.pop() if parts[-1] in SUPPORTED_LOOKUPS else "eq"
+        if op == "iexact":
+            op = "iequals"
+        predicates.append({"field": ".".join(parts), "op": op, "value": value})
+    return predicates
+
+
+def _aggregate(fn, field, as_=None):
+    expr = {"fn": fn, "field": field}
+    if as_:
+        expr["as"] = as_
+    return expr
+
+
+def Sum(field, as_=None):
+    return _aggregate("sum", field, as_)
+
+
+def Avg(field, as_=None):
+    return _aggregate("avg", field, as_)
+
+
+def Min(field, as_=None):
+    return _aggregate("min", field, as_)
+
+
+def Max(field, as_=None):
+    return _aggregate("max", field, as_)
+
+
+class QuerySet:
+    """Lazy immutable query builder. Pagination rejects concurrent DB changes."""
+    def __init__(self, manager, query=None):
+        self.manager = manager
+        self.query = dict(query or {"where": [], "limit": 100})
+
+    def filter(self, **lookups):
+        predicates = list(self.query.get("where", []))
+        predicates.extend(_predicates(lookups))
+        return QuerySet(self.manager, {**self.query, "where": predicates})
+
+    def exclude(self, **lookups):
+        predicates = list(self.query.get("not", []))
+        predicates.extend(_predicates(lookups))
+        return QuerySet(self.manager, {**self.query, "not": predicates})
+
+    def or_q(self, *groups):
+        """Require the filters above plus at least one of these lookup groups.
+
+        Each group is ANDed on its own, so or_q({"email": x}, {"username": x}) means
+        "either field matches" - something a flat where list cannot say.
+        """
+        or_groups = list(self.query.get("or", []))
+        for group in groups:
+            predicates = _predicates(group)
+            if not predicates:
+                raise ValueError("each or_q group needs at least one lookup")
+            or_groups.append(predicates)
+        return QuerySet(self.manager, {**self.query, "or": or_groups})
+
+    def aggregate(self, *exprs, **named):
+        """Fold the whole filtered set, not the current page.
+
+        projects.aggregate(total=Sum("views"), best=Max("views")) reads like Django's
+        aggregate(); the keyword becomes the output alias.
+        """
+        entries = list(self.query.get("aggregate", []))
+        entries.extend(exprs)
+        for alias, expr in named.items():
+            entries.append({**expr, "as": alias})
+        return QuerySet(self.manager, {**self.query, "aggregate": entries})
+
+    def group_by(self, *fields):
+        grouped = list(self.query.get("group_by", []))
+        grouped.extend(fields)
+        return QuerySet(self.manager, {**self.query, "group_by": grouped})
+
+    def groups(self):
+        """Return one {group, count, values} row per aggregate group."""
+        return self.page(limit=1).get("groups", [])
+
+    def order_by(self, *fields):
+        """Sort by one or more fields, prefixing a name with "-" for descending.
+
+        A single field keeps the compact wire form; several fields travel as a list so
+        ties fall through, the way "trending" needs likes, then views, then newest.
+        """
+        terms = [{"field": f.lstrip("-"), "descending": f.startswith("-")} for f in fields]
+        if not terms:
+            raise ValueError("order_by needs at least one field")
+        if len(terms) == 1:
+            return QuerySet(self.manager, {**self.query, "order_by": terms[0]["field"],
+                                           "descending": terms[0]["descending"]})
+        return QuerySet(self.manager, {**self.query, "order_by": terms, "descending": False})
+
+    def offset(self, n):
+        if n < 0:
+            raise ValueError("offset cannot be negative")
+        return QuerySet(self.manager, {**self.query, "offset": n})
+
+    def only(self, *fields):
+        return QuerySet(self.manager, {**self.query, "projection": list(fields)})
+
+    def page(self, cursor=None, limit=None):
+        query = dict(self.query)
+        if cursor:
+            query["cursor"] = cursor
+        if limit is not None:
+            query["limit"] = limit
+        return self.manager.client.request("POST", "query/" + self.manager.name + "/", query)
+
+    def count(self):
+        return self.page(limit=1)["total"]
+
+    def first(self):
+        results = self.page(limit=1)["results"]
+        return results[0] if results else None
+
+    def __iter__(self):
+        cursor = None
+        while True:
+            page = self.page(cursor=cursor)
+            yield from page["results"]
+            cursor = page.get("next_cursor")
+            if not cursor:
+                break
+
+    def all(self):
+        return list(self)
+
+class DocumentManager:
+    def __init__(self, client, name):
+        import re
+        if not re.fullmatch(r"[A-Za-z][A-Za-z0-9_-]{0,63}", name):
+            raise ValueError("Invalid collection name")
+        self.client, self.name = client, name
+        self.path = "documents/" + name + "/"
+
+    def create(self, *, data=None, idempotency_key=None, **fields):
+        if data is not None and fields:
+            raise ValueError("Pass data or keyword fields, not both")
+        return self.client.request("POST", self.path, {"data": fields if data is None else data},
+                                   headers={"Idempotency-Key": idempotency_key} if idempotency_key else None)
+
+    def get(self, *, pk):
+        return self.client.request("GET", self.path + quote(pk, safe="") + "/")
+
+    def filter(self, **lookups):
+        return QuerySet(self).filter(**lookups)
+
+    def exclude(self, **lookups):
+        return QuerySet(self).exclude(**lookups)
+
+    def or_q(self, *groups):
+        return QuerySet(self).or_q(*groups)
+
+    def aggregate(self, *exprs, **named):
+        return QuerySet(self).aggregate(*exprs, **named)
+
+    def group_by(self, *fields):
+        return QuerySet(self).group_by(*fields)
+
+    def order_by(self, *fields):
+        return QuerySet(self).order_by(*fields)
+
+    def offset(self, n):
+        return QuerySet(self).offset(n)
+
+    def all(self):
+        return QuerySet(self)
+
+    def update(self, *, pk, version=None, unset=None, inc=None, **fields):
+        """Patch a record. Pass version for a compare-and-set, or inc to add onto
+        numeric fields server-side; inc re-reads the record under the engine lock, so
+        counters like page views cannot lose a concurrent write and need no version."""
+        body = {"version": version, "set": fields, "unset": unset or []}
+        if inc:
+            body["inc"] = inc
+        return self.client.request("PATCH", self.path + quote(pk, safe="") + "/", body)
+
+    def increment(self, *, pk, **steps):
+        """Atomically add to numeric fields, e.g. increment(pk=pid, views=1)."""
+        return self.update(pk=pk, inc=steps)
+
+    def delete(self, *, pk, version):
+        return self.client.request("DELETE", self.path + quote(pk, safe="") + "/", headers={"If-Match": str(version)})
+
+    def bulk_create(self, documents, *, idempotency_key=None):
+        return self.client.transaction([{"record": {"kind": "document", "collection": self.name, "data": d, "visibility": "team"}, "expected": 0} for d in documents], idempotency_key=idempotency_key)
+
+class Collection:
+    def __init__(self, client, name):
+        self.objects = DocumentManager(client, name)
+
+class CollectionManager:
+    def __init__(self, client):
+        self.client = client
+
+    def create(self, name, *, fields=None, unique=None, indexes=None, strict=False):
+        return self.client.request("POST", "collections/", {"name": name, "schema": {"fields": fields or {}, "unique": unique or [], "indexes": indexes or [], "strict": strict}})
+
+    def all(self):
+        return self.client.request("GET", "collections/")["results"]
+
+    def schema(self, name):
+        """The collection record, which carries both its schema and the revision to change it."""
+        for record in self.all():
+            if record["collection"] == name:
+                return record
+        raise MemoryDBError(404, f"collection {name} does not exist")
+
+    def alter(self, name, *, fields=None, unique=None, indexes=None, strict=None):
+        """Widen a collection in place, which is what ALTER TABLE ADD COLUMN amounts to here.
+
+        Only new declarations are added and an existing field may not be restated with a
+        different type. Rows written before an added field gain that field at its zero value,
+        so a reader never meets a document missing a column the schema promises. A required
+        or unique field that the stored rows cannot satisfy is refused by the engine.
+        """
+        record = self.schema(name)
+        schema = record["data"]
+        for path, field in (fields or {}).items():
+            current = schema.setdefault("fields", {}).get(path)
+            if current is not None and current != field:
+                raise MemoryDBError(409, f"{name}.{path} already has a different schema")
+            schema["fields"][path] = field
+        for key, added in (("unique", unique), ("indexes", indexes)):
+            existing = schema.setdefault(key, [])
+            for path in added or []:
+                if path not in existing:
+                    existing.append(path)
+        if strict is not None:
+            schema["strict"] = strict
+        return self.client.request("PUT", "memories/" + quote(record["id"], safe="") + "/",
+                                   {**record, "data": schema})

memorydb_mcp.py

@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""MCP (Model Context Protocol) server for MemoryDB over stdio JSON-RPC.
+
+Lets any MCP-capable agent (Claude Desktop, Qoder, IDE assistants) read and write
+MemoryDB memories without custom glue code. Dependency-free apart from the MemoryDB
+client; point it at a server with MEMORYDB_URL=memorydb://TOKEN@host:port.
+
+Register in an MCP client config, e.g.:
+  {"mcpServers": {"memorydb": {"command": "python3", "args": ["memorydb_mcp.py"],
+   "env": {"MEMORYDB_URL": "memorydb://TOKEN@127.0.0.1:8080"}}}}
+"""
+import json
+import sys
+from urllib.parse import urlencode
+
+sys.path.insert(0, str(__import__("pathlib").Path(__file__).resolve().parent))
+from memorydb import MemoryDB  # noqa: E402
+
+PROTOCOL_VERSION = "2024-11-05"
+SERVER_INFO = {"name": "memorydb", "version": "0.2.1"}
+
+TOOL_DEFS = [
+    {"name": "memorydb_health", "description": "Server status, identity and transaction sequence.",
+     "inputSchema": {"type": "object", "properties": {}}},
+    {"name": "memorydb_search", "description": "Hybrid BM25 + vector search over readable memories.",
+     "inputSchema": {"type": "object", "properties": {
+         "text": {"type": "string"}, "vector": {"type": "array", "items": {"type": "number"}},
+         "kind": {"type": "string", "description": "chat|fact|summary|profile|intention|experience|skill|wiki|code|revision"},
+         "source": {"type": "string"}, "limit": {"type": "integer", "default": 10}}, "required": ["text"]}},
+    {"name": "memorydb_list_memories", "description": "List/search memories by kind, source and text.",
+     "inputSchema": {"type": "object", "properties": {
+         "kind": {"type": "string"}, "source": {"type": "string"}, "q": {"type": "string"},
+         "limit": {"type": "integer", "default": 50}}}},
+    {"name": "memorydb_add_memory", "description": "Store one memory record (kind + content, optional source/layer/metadata).",
+     "inputSchema": {"type": "object", "properties": {
+         "kind": {"type": "string", "default": "fact"}, "content": {"type": "string"},
+         "source": {"type": "string", "default": "mcp"}, "layer": {"type": "string"},
+         "metadata": {"type": "object", "additionalProperties": {"type": "string"}}}, "required": ["content"]}},
+    {"name": "memorydb_ingest", "description": "Ingest a conversation with evidence-linked facts. Each fact quote must appear verbatim in the referenced user message.",
+     "inputSchema": {"type": "object", "properties": {
+         "source": {"type": "string", "default": "mcp"},
+         "messages": {"type": "array", "items": {"type": "object", "properties": {
+             "role": {"type": "string"}, "content": {"type": "string"}}, "required": ["role", "content"]}},
+         "facts": {"type": "array", "items": {"type": "object", "properties": {
+             "subject": {"type": "string"}, "predicate": {"type": "string"}, "value": {"type": "string"},
+             "quote": {"type": "string"}, "message_index": {"type": "integer"},
+             "confidence": {"type": "number", "default": 1.0}},
+             "required": ["subject", "predicate", "value", "quote", "message_index"]}}},
+         "required": ["messages"]}},
+    {"name": "memorydb_create_collection", "description": "Create a document collection with a JSON schema (admin role required).",
+     "inputSchema": {"type": "object", "properties": {
+         "name": {"type": "string"},
+         "schema": {"type": "object", "properties": {
+             "fields": {"type": "object"}, "unique": {"type": "array", "items": {"type": "string"}},
+             "indexes": {"type": "array", "items": {"type": "string"}}, "strict": {"type": "boolean"}}}},
+         "required": ["name", "schema"]}},
+    {"name": "memorydb_query_documents", "description": "Query a collection: where[op eq|ne|gt|gte|lt|lte|in|contains|prefix|exists], order_by, descending, projection, limit.",
+     "inputSchema": {"type": "object", "properties": {
+         "collection": {"type": "string"},
+         "where": {"type": "array", "items": {"type": "object", "properties": {
+             "field": {"type": "string"}, "op": {"type": "string"}, "value": {}}}},
+         "order_by": {"type": "string"}, "descending": {"type": "boolean"},
+         "projection": {"type": "array", "items": {"type": "string"}},
+         "limit": {"type": "integer", "default": 50}}, "required": ["collection"]}},
+]
+
+
+def handle(db, method, params):
+    if method == "memorydb_health":
+        return db.request("GET", "health/")
+    if method == "memorydb_search":
+        return db.objects.search(text=params.get("text", ""), vector=params.get("vector"),
+                         kind=params.get("kind", ""), source=params.get("source", ""),
+                         limit=params.get("limit", 10))
+    if method == "memorydb_list_memories":
+        return db.request("GET", "memories/?" + urlencode({"kind": params.get("kind", ""),
+                "source": params.get("source", ""), "q": params.get("q", ""), "limit": params.get("limit", 50)}))
+    if method == "memorydb_add_memory":
+        body = {"kind": params.get("kind", "fact"), "content": params["content"],
+                "source": params.get("source", "mcp")}
+        if params.get("layer"):
+            body["layer"] = params["layer"]
+        if params.get("metadata"):
+            body["metadata"] = params["metadata"]
+        return db.request("POST", "memories/", body)
+    if method == "memorydb_ingest":
+        return db.ingest(params["messages"], facts=params.get("facts"), source=params.get("source", "mcp"))
+    if method == "memorydb_create_collection":
+        schema = params["schema"]
+        return db.collections.create(params["name"], fields=schema.get("fields"),
+                                     unique=schema.get("unique"), indexes=schema.get("indexes"),
+                                     strict=schema.get("strict", False))
+    if method == "memorydb_query_documents":
+        q = {k: v for k, v in params.items() if k != "collection"}
+        return db.request("POST", "query/" + params["collection"] + "/", q)
+    raise ValueError("unknown tool " + method)
+
+
+def serve():
+    import os
+    env_url = os.environ.get("MEMORYDB_URL", "")
+    if env_url.startswith("memorydb"):
+        db = MemoryDB.from_url(env_url)
+    else:
+        db = MemoryDB(env_url or "http://127.0.0.1:8080", token=os.environ.get("MEMORYDB_TOKEN"))
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            msg = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        method, params, msg_id = msg.get("method"), msg.get("params", {}), msg.get("id")
+        if method == "initialize":
+            reply(msg_id, {"protocolVersion": PROTOCOL_VERSION, "capabilities": {"tools": {}}, "serverInfo": SERVER_INFO})
+        elif method == "notifications/initialized" or msg_id is None:
+            continue
+        elif method == "tools/list":
+            reply(msg_id, {"tools": TOOL_DEFS})
+        elif method == "tools/call":
+            tool, arguments = params.get("name"), params.get("arguments", {})
+            try:
+                result = handle(db, tool, arguments)
+                reply(msg_id, {"content": [{"type": "text", "text": json.dumps(result, default=str)}]})
+            except Exception as exc:  # MCP convention: tool errors are results, not protocol faults
+                reply(msg_id, {"content": [{"type": "text", "text": str(exc)}], "isError": True})
+        elif method == "ping":
+            reply(msg_id, {})
+        else:
+            reply(msg_id, None, error={"code": -32601, "message": "method not found: " + str(method)})
+
+
+def reply(msg_id, result, error=None):
+    out = {"jsonrpc": "2.0", "id": msg_id}
+    if error:
+        out["error"] = error
+    else:
+        out["result"] = result
+    sys.stdout.write(json.dumps(out) + "\n")
+    sys.stdout.flush()
+
+
+if __name__ == "__main__":
+    serve()

superb_memory-0.2.1.dist-info/METADATA

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: superb-memory
+Version: 0.2.1
+Summary: Python client, mdb CLI and MCP server for the MemoryDB Go document and agent memory database
+Author: humaniods
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/humaniods/MemoryDB
+Project-URL: Repository, https://github.com/humaniods/MemoryDB
+Project-URL: Issues, https://github.com/humaniods/MemoryDB/issues
+Keywords: database,document-database,agent-memory,langchain,mcp,vector-search
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# MemoryDB Python client
+
+`superb-memory` gives you the Python client, the `mdb` command-line tool and the
+`memorydb-mcp` stdio server for [MemoryDB](https://github.com/humaniods/MemoryDB) — a single-binary
+Go document database that also stores AI-agent memory (facts with evidence, summaries, tool
+traces, hybrid BM25 + vector search).
+
+## One line to a running database
+
+```bash
+pip install superb-memory
+mdb serve                    # fetches the server binary, starts it on 127.0.0.1:8080
+```
+
+`mdb serve` prints the connection string; every client reads it from the environment:
+
+```bash
+export MEMORYDB_URL=memorydb://TOKEN@127.0.0.1:8080
+```
+
+## Documents
+
+```python
+from memorydb import MemoryDB
+
+db = MemoryDB()                       # reads MEMORYDB_URL
+db.collections.create("customers",
+                      fields={"email": {"type": "string", "required": True},
+                              "age": {"type": "integer"}},
+                      unique=["email"], indexes=["age"])
+
+customers = db.collection("customers")
+row = customers.objects.create(email="demo@example.com", age=24, idempotency_key="customer-demo-1")
+customers.objects.filter(age__gte=18).order_by("-age").only("email").all()
+customers.objects.increment(pk=row["id"], views=1)     # atomic counter, no version needed
+```
+
+Django-style lookups: `eq ne gt gte lt lte in contains icontains prefix iequals exists`,
+plus `or_q`, `Sum/Avg/Min/Max` with `group_by`, cursor pagination and optimistic `version` checks.
+
+## Agent memory
+
+```python
+db.ingest([{"role": "user", "content": "I prefer terse answers in Hindi"}],
+          facts=[{"subject": "user", "predicate": "answer_style", "value": "terse Hindi",
+                  "quote": "terse answers in Hindi", "message_index": 0, "confidence": 0.95}])
+db.objects.search("terse")
+```
+
+Facts need an exact quote from a user message, so a stored memory always carries its evidence.
+
+## CLI and MCP
+
+```bash
+mdb health; mdb search "fridays"; mdb memory add --content "user ships on fridays"
+memorydb-mcp          # stdio MCP server for Claude Desktop, Qoder, IDE agents
+```
+
+Companion packages: `memorydb-django` (cache + session backends) and `memorydb-langchain`
+(chat message history). Docs: `docs/QUICKSTART.md` and `docs/CONNECTING.md` in the repository.

superb_memory-0.2.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+cli.py,sha256=mW-LQGy5RJIXp6zEqQUaClTSfv1NBxjspbr6NA1_Av8,13559
+memorydb.py,sha256=zuFKR7yPyOMwpDM7FsSCmd7po5HGoP1Vn5roAbFqURs,14919
+memorydb_mcp.py,sha256=Te1vEHs_nN-6SGcBqjATufzY2SGyrw4bVbdO95LtL7U,7937
+superb_memory-0.2.1.dist-info/METADATA,sha256=KSS0KxZSdd4449aCcasUTDSHRGC-PukgmDqADkjYF_M,3094
+superb_memory-0.2.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+superb_memory-0.2.1.dist-info/entry_points.txt,sha256=XWmBm9A9zHw1CRISdSwJgCPElj0uz_fQqPpIEukuw_o,67
+superb_memory-0.2.1.dist-info/top_level.txt,sha256=xOmN1kE5-YB-FTPMUSBidF9Z7oeKDxb7agowyTMe2Sw,26
+superb_memory-0.2.1.dist-info/RECORD,,

superb_memory-0.2.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

superb_memory-0.2.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+mdb = cli:main
+memorydb-mcp = memorydb_mcp:serve

superb_memory-0.2.1.dist-info/top_level.txt

@@ -0,0 +1,3 @@
+cli
+memorydb
+memorydb_mcp