memgres 0.12.0__tar.gz → 0.12.1__tar.gz

{memgres-0.12.0 → memgres-0.12.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memgres
-Version: 0.12.0
+Version: 0.12.1
 Summary: Drop-in memory for AI agents: one Postgres, lexical + semantic recall, diff-versioned history, GDPR-erasable.
 Author: mozgsml
 License-Expression: MIT

{memgres-0.12.0 → memgres-0.12.1}/memgres/_version.py

@@ -8,4 +8,4 @@ here at release; nowhere else carries the number.
 PEP 440: a ``.devN`` suffix marks an unreleased build ahead of the last tag.
 """
 
-__version__ = "0.12.0"
+__version__ = "0.12.1"

{memgres-0.12.0 → memgres-0.12.1}/memgres/links.py

@@ -52,19 +52,11 @@ from typing import Dict, List, Optional
 # edges so they are visible, never resolved — we do not own the address space.
 KNOWN_SCHEMES = ("idea", "file")
 
-# An ltree path: labels of [A-Za-z0-9_-] joined by dots. Deliberately strict —
-# this is what tells a path apart from a slug belonging to another store, and
-# from prose that happens to sit in double brackets.
-#
-# The hyphen is there because PATHS MAY CONTAIN ONE. Postgres has allowed `-` in
-# ltree labels since 13 (the minimum this project supports), `write` accepts such
-# a path without complaint, and real corpora are full of them —
-# `infra.servers.video-production`. While this pattern rejected the hyphen the
-# two halves of the product disagreed about what a path is: the link was stored
-# as prose, `_classify` returned "ignore", and the edge did not even become a
-# DANGLING one. It vanished, and `memory_links` answered "nothing points here",
-# which reads as a fact about the corpus rather than as a parser that quit.
-_PATH = re.compile(r"^[A-Za-z0-9_-]+(\.[A-Za-z0-9_-]+)*$")
+# What a path is lives in `paths.py`, so the parser and the store cannot drift
+# apart again — that drift is exactly what dropped every hyphenated link before
+# 0.12.0. Kept under the old name because the rest of this module reads better
+# with it.
+from .paths import PATH_RE as _PATH
 
 _LINK = re.compile(r"\[\[([^\[\]\n]+)\]\]")
 _FENCE = re.compile(r"```.*?```|~~~.*?~~~", re.S)

{memgres-0.12.0 → memgres-0.12.1}/memgres/mcp_server.py

@@ -32,8 +32,10 @@ from typing_extensions import Annotated
 
 try:  # mcp SDK >= 2.0 renamed the module fastmcp -> mcpserver
     from mcp.server.mcpserver import Context
+    from mcp.server.mcpserver.exceptions import ToolError
 except ImportError:  # mcp SDK 1.x
     from mcp.server.fastmcp import Context
+    from mcp.server.fastmcp.exceptions import ToolError
 
 from . import admin, identity
 from .config import Config, load
@@ -269,6 +271,40 @@ def _mcp(name: str, instructions: Optional[str] = None):
     return server
 
 
+# Refusals whose text is written FOR the caller and safe to show them: what is
+# missing, which namespace to name, why the diff did not apply, what they may
+# not do. Everything else — a psycopg error, a bug — stays masked, because those
+# messages carry schema and internals rather than instructions.
+_SPEAKABLE = (ValueError, PermissionError, LookupError)
+
+
+def _speaking(fn):
+    """Re-raise a domain refusal as the SDK's own error type, which is the only
+    kind whose message reaches the client.
+
+    Everything else the SDK catches becomes `Error executing tool <name>` with no
+    detail — and that is what the caller sees. The refusals here are written to
+    be read: "this deployment requires `source` … as an ADDRESS", "you can reach
+    2 namespaces, name the one you mean". Masking them turns a fixable mistake
+    into a mystery, and an agent that cannot see the reason repeats the same call
+    — which is exactly what happened: five identical edits in a row, then the
+    same on reads, against a server that was explaining itself into the void.
+    """
+    import functools
+
+    @functools.wraps(fn)
+    def wrapper(*args, **kwargs):
+        try:
+            return fn(*args, **kwargs)
+        except ToolError:
+            raise
+        except _SPEAKABLE as e:
+            # `from e` keeps the original in the server log, where the traceback
+            # belongs; the client gets the sentence, not the stack.
+            raise ToolError(str(e)) from e
+    return wrapper
+
+
 def _mem(m) -> dict:
     return m.to_dict(stringify_dates=True)      # MCP layer needs plain strings
 
@@ -292,6 +328,12 @@ def build_server(cfg: Optional[Config] = None):
     _worker, cfg, backend = wire_server(cfg, embedder)
     mcp = _mcp("memgres", instructions=_instruction_text())
 
+    def tool(*d_args, **d_kwargs):
+        """`mcp.tool()`, but the refusal text survives the trip to the client."""
+        def deco(fn):
+            return mcp.tool(*d_args, **d_kwargs)(_speaking(fn))
+        return deco
+
     import os as _os
 
     # The control-plane tools. `auto` registers them wherever there are
@@ -389,7 +431,7 @@ def build_server(cfg: Optional[Config] = None):
         """
         return identity.resolve(conn, cfg, token)
 
-    @mcp.tool()
+    @tool()
     def memory_write(body: Optional[str] = None, id: Optional[str] = None,
                      at: Optional[str] = None,
                      if_moved: IfMovedArg = "error",
@@ -445,7 +487,7 @@ def build_server(cfg: Optional[Config] = None):
                 reason=reason, valid_at=valid_at, space=space,
                 space_id=space_id))
 
-    @mcp.tool()
+    @tool()
     def memory_get(id: Optional[str] = None, at: Optional[str] = None,
                    if_moved: Literal["follow", "error"] = "follow",
                    lines: Optional[str] = None,
@@ -471,7 +513,7 @@ def build_server(cfg: Optional[Config] = None):
                                          if_moved=if_moved, lines=lines,
                                          space=space, space_id=space_id))
 
-    @mcp.tool()
+    @tool()
     def memory_recall(query: str, k: int = 10,
                       mode: Literal["lexical", "semantic", "hybrid", "auto"] = "auto",
                       match: Optional[Literal["any", "all"]] = None,
@@ -515,7 +557,7 @@ def build_server(cfg: Optional[Config] = None):
                         snippet=snippet, full_body=full_body, bodies=bodies,
                         match_tags=match_tags, space=space, space_id=space_id)]
 
-    @mcp.tool()
+    @tool()
     def memory_list(path_prefix: Optional[str] = None,
                     tags: Optional[List[str]] = None, limit: int = 50,
                     offset: int = 0, bodies: bool = False,
@@ -543,7 +585,7 @@ def build_server(cfg: Optional[Config] = None):
                 limit=limit, offset=offset, bodies=bodies,
                 match_tags=match_tags, space=space, space_id=space_id)
 
-    @mcp.tool()
+    @tool()
     def memory_tags(prefix: Optional[str] = None, k: int = 50,
                     space: Spaces = None, space_id: Spaces = None,
                     ctx: Context = None) -> List[dict]:
@@ -558,7 +600,7 @@ def build_server(cfg: Optional[Config] = None):
             return _store(conn).tags(_token(ctx), prefix=prefix, k=k,
                                      space=space, space_id=space_id)
 
-    @mcp.tool()
+    @tool()
     def memory_links(id: Optional[str] = None, at: Optional[str] = None,
                      direction: Literal["in", "out", "both"] = "both",
                      space: Optional[str] = None, space_id: Optional[str] = None,
@@ -579,7 +621,7 @@ def build_server(cfg: Optional[Config] = None):
                                       at=at or None, direction=direction,
                                       space=space, space_id=space_id)
 
-    @mcp.tool()
+    @tool()
     def memory_server_info(ctx: Context = None) -> dict:
         """The server's version + schema_version and its effective limits and
         capabilities (write ceilings, embed provider/model/dim, available recall
@@ -589,7 +631,7 @@ def build_server(cfg: Optional[Config] = None):
         dim = embedder.dim if embedder is not None else None
         return server_info(cfg, embed_dim=dim)
 
-    @mcp.tool()
+    @tool()
     def memory_blame(id: Optional[str] = None, at: Optional[str] = None,
                      grouped: bool = True, lines: Optional[str] = None,
                      space: Optional[str] = None, space_id: Optional[str] = None,
@@ -609,7 +651,7 @@ def build_server(cfg: Optional[Config] = None):
             return s.annotate(tok, id, lines=want, at=at, space=space,
                               space_id=space_id)
 
-    @mcp.tool()
+    @tool()
     def memory_history(id: Optional[str] = None, at: Optional[str] = None,
                        space: Optional[str] = None,
                        space_id: Optional[str] = None,
@@ -622,7 +664,7 @@ def build_server(cfg: Optional[Config] = None):
             return _store(conn).history(_token(ctx), id, at=at,
                                         space=space, space_id=space_id)
 
-    @mcp.tool()
+    @tool()
     def memory_move(new_path: str, id: Optional[str] = None,
                     at: Optional[str] = None,
                     if_moved: Literal["error", "follow"] = "error",
@@ -638,7 +680,7 @@ def build_server(cfg: Optional[Config] = None):
                                           reason=reason, space=space,
                                           space_id=space_id))
 
-    @mcp.tool()
+    @tool()
     def memory_forget(id: Optional[str] = None, at: Optional[str] = None,
                       space: Optional[str] = None,
                       space_id: Optional[str] = None,
@@ -652,7 +694,7 @@ def build_server(cfg: Optional[Config] = None):
                 _token(ctx), id, at=at, space=space, space_id=space_id)}
 
     # ─── identity: spaces & tokens (open/managed modes) ─────────────────────
-    @mcp.tool()
+    @tool()
     def memory_list_spaces(ctx: Context = None) -> List[dict]:
         """List the namespaces you can reach — your own plus any shared with you —
         with each one's id, name, description, permission, and your `alias` for it
@@ -661,7 +703,7 @@ def build_server(cfg: Optional[Config] = None):
         with pool.connection() as conn, conn.transaction():
             return identity.list_spaces(conn, _uid(conn, _token(ctx)))
 
-    @mcp.tool()
+    @tool()
     def memory_create_space(name: str, description: str = "",
                             instruction: str = "",
                             ctx: Context = None) -> dict:
@@ -675,7 +717,7 @@ def build_server(cfg: Optional[Config] = None):
                 description=description, instruction=instruction)
         return {"id": nsid, "name": name}
 
-    @mcp.tool()
+    @tool()
     def memory_set_alias(alias: str, space_id: str,
                          ctx: Context = None) -> dict:
         """Give a namespace a name of your own, for when a bare name is ambiguous
@@ -688,7 +730,7 @@ def build_server(cfg: Optional[Config] = None):
             identity.create_alias(conn, uid, alias, space_id)
         return {"alias": alias, "space_id": space_id}
 
-    @mcp.tool()
+    @tool()
     def memory_drop_alias(alias: str,
                           ctx: Context = None) -> dict:
         """Remove one of your namespace aliases. The namespace itself is
@@ -698,7 +740,7 @@ def build_server(cfg: Optional[Config] = None):
             return {"dropped": identity.drop_alias(conn, uid, alias)}
 
     if cfg.key_mode == "managed":
-        @mcp.tool()
+        @tool()
         def memory_enroll(key: EnrollKeyArg, ctx: Context = None) -> dict:
             """Claim an account with a one-time enrollment key.
 
@@ -734,7 +776,7 @@ def build_server(cfg: Optional[Config] = None):
                            "tools you can now use are not showing yet.")
             return out
 
-    @mcp.tool()
+    @tool()
     def memory_issue_token(permission: str = "write", space: Optional[str] = None,
                            space_id: Optional[str] = None, label: str = "",
                            expires_days: Optional[int] = None,
@@ -789,7 +831,7 @@ def build_server(cfg: Optional[Config] = None):
         out.update({"permission": permission, "namespace_id": nsid})
         return out
 
-    @mcp.tool()
+    @tool()
     def memory_request_access(space_id: str, permission: str = "read",
                               ctx: Context = None) -> dict:
         """Ask the owner of a namespace to let you in.
@@ -804,14 +846,14 @@ def build_server(cfg: Optional[Config] = None):
                                         namespace_id=space_id,
                                         permission=permission)
 
-    @mcp.tool()
+    @tool()
     def memory_list_tokens(ctx: Context = None) -> List[dict]:
         """List your tokens (metadata only — never the secret)."""
         with pool.connection() as conn, conn.transaction():
             out = identity.list_tokens(conn, _admin_uid(conn, _token(ctx)))
         return _iso(out, *_TOKEN_TIMES)
 
-    @mcp.tool()
+    @tool()
     def memory_revoke_token(token_id: str,
                             ctx: Context = None) -> dict:
         """Revoke one of your tokens by id (kills it immediately)."""
@@ -822,7 +864,7 @@ def build_server(cfg: Optional[Config] = None):
                 raise identity.AuthError("not your token")
             return {"revoked": identity.revoke_token(conn, token_id)}
 
-    @mcp.tool()
+    @tool()
     def memory_whoami(ctx: Context = None) -> dict:
         """Who you are and what you may do: user id, service role, this
         credential's permission ceiling and namespace scope, plus the
@@ -834,7 +876,7 @@ def build_server(cfg: Optional[Config] = None):
     # ─── control plane: provisioning (authorized in `admin`, not here) ───────
     if admin_surface:
 
-        @mcp.tool()
+        @tool()
         def memory_admin_list_users(role: Optional[str] = None, limit: int = 50,
                                     offset: int = 0,
                                     ctx: Context = None) -> List[dict]:
@@ -846,7 +888,7 @@ def build_server(cfg: Optional[Config] = None):
                                        role=role, limit=limit, offset=offset)
             return _iso(out, "created_at")
 
-        @mcp.tool()
+        @tool()
         def memory_admin_create_user(name: str = "", description: str = "",
                                      role: str = "user",
                                      can_create_namespace: bool = False,
@@ -872,7 +914,7 @@ def build_server(cfg: Optional[Config] = None):
                                         department=department, position=position)
             return {"id": uid}
 
-        @mcp.tool()
+        @tool()
         def memory_admin_edit_user(user_id: str,
                                    name: Optional[str] = None,
                                    description: Optional[str] = None,
@@ -891,7 +933,7 @@ def build_server(cfg: Optional[Config] = None):
                     conn, _principal(conn, _token(ctx)), user_id=user_id,
                     **{k: v for k, v in fields.items() if v is not None})
 
-        @mcp.tool()
+        @tool()
         def memory_admin_set_can_create_namespace(user_id: str, allowed: bool,
                                                   ctx: Context = None) -> dict:
             """Grant or withdraw a user's right to create namespaces. Without it
@@ -902,7 +944,7 @@ def build_server(cfg: Optional[Config] = None):
                     conn, _principal(conn, _token(ctx)),
                     user_id=user_id, allowed=allowed)
 
-        @mcp.tool()
+        @tool()
         def memory_admin_set_role(user_id: str, role: str,
                                   ctx: Context = None) -> dict:
             """Set a user's service role (user | user_manager | superadmin).
@@ -912,7 +954,7 @@ def build_server(cfg: Optional[Config] = None):
                 return admin.set_role(conn, _principal(conn, _token(ctx)),
                                       user_id=user_id, role=role)
 
-        @mcp.tool()
+        @tool()
         def memory_admin_list_namespaces(owner_user_id: Optional[str] = None,
                                          limit: int = 50, offset: int = 0,
                                          ctx: Context = None) -> List[dict]:
@@ -925,7 +967,7 @@ def build_server(cfg: Optional[Config] = None):
                     owner_user_id=owner_user_id, limit=limit, offset=offset)
             return _iso(out, "created_at")
 
-        @mcp.tool()
+        @tool()
         def memory_admin_create_namespace(name: str, owner_user_id: str,
                                           description: str = "",
                                           instruction: str = "",
@@ -940,7 +982,7 @@ def build_server(cfg: Optional[Config] = None):
                     description=description, instruction=instruction)
             return {"id": nsid}
 
-        @mcp.tool()
+        @tool()
         def memory_admin_edit_namespace(space_id: str,
                                         description: Optional[str] = None,
                                         instruction: Optional[str] = None,
@@ -959,7 +1001,7 @@ def build_server(cfg: Optional[Config] = None):
                     namespace_id=space_id, description=description,
                     instruction=instruction, name=name)
 
-        @mcp.tool()
+        @tool()
         def memory_admin_count_orphans(ctx: Context = None) -> dict:
             """How many memories are stranded in the pre-identity namespace.
             `single` mode stores everything under one nameless namespace; after a
@@ -969,7 +1011,7 @@ def build_server(cfg: Optional[Config] = None):
             with pool.connection() as conn:
                 return admin.count_orphans(conn, _principal(conn, _token(ctx)))
 
-        @mcp.tool()
+        @tool()
         def memory_admin_adopt_orphans(space_id: str,
                                        ctx: Context = None) -> dict:
             """Move every stranded `single`-mode memory into a real namespace.
@@ -981,7 +1023,7 @@ def build_server(cfg: Optional[Config] = None):
                     conn, _principal(conn, _token(ctx)),
                     namespace_id=space_id, vectors=backend)
 
-        @mcp.tool()
+        @tool()
         def memory_admin_add_member(space_id: str, user_id: str,
                                     permission: str = "read",
                                     ctx: Context = None) -> dict:
@@ -994,7 +1036,7 @@ def build_server(cfg: Optional[Config] = None):
                                         namespace_id=space_id, user_id=user_id,
                                         permission=permission)
 
-        @mcp.tool()
+        @tool()
         def memory_admin_remove_member(space_id: str, user_id: str,
                                        ctx: Context = None) -> dict:
             """Take a shared namespace away again. `removed: false` means they
@@ -1009,7 +1051,7 @@ def build_server(cfg: Optional[Config] = None):
                 return admin.remove_member(conn, _principal(conn, _token(ctx)),
                                            namespace_id=space_id, user_id=user_id)
 
-        @mcp.tool()
+        @tool()
         def memory_admin_transfer_namespace(
                 space_id: str, new_owner_user_id: str,
                 keep_previous_owner: Optional[str] = "admin",
@@ -1028,7 +1070,7 @@ def build_server(cfg: Optional[Config] = None):
                     new_owner_user_id=new_owner_user_id,
                     keep_previous_owner=keep_previous_owner)
 
-        @mcp.tool()
+        @tool()
         def memory_admin_list_requests(space_id: str,
                                        ctx: Context = None) -> List[dict]:
             """Pending requests to join a namespace you administer — who asked,
@@ -1038,7 +1080,7 @@ def build_server(cfg: Optional[Config] = None):
                                           namespace_id=space_id)
             return _iso(out, "created_at")
 
-        @mcp.tool()
+        @tool()
         def memory_admin_decide_access(request_id: str, approve: bool = True,
                                        expect_permission: Optional[str] = None,
                                        ctx: Context = None) -> dict:
@@ -1056,7 +1098,7 @@ def build_server(cfg: Optional[Config] = None):
                                     expect_permission=expect_permission)
             return {"request_id": request_id, "approved": approve}
 
-        @mcp.tool()
+        @tool()
         def memory_admin_set_disabled(user_id: str, disabled: bool = True,
                                       ctx: Context = None) -> dict:
             """Switch an account off, or back on.
@@ -1070,7 +1112,7 @@ def build_server(cfg: Optional[Config] = None):
                 return admin.set_disabled(conn, _principal(conn, _token(ctx)),
                                           user_id=user_id, disabled=disabled)
 
-        @mcp.tool()
+        @tool()
         def memory_admin_list_members(space_id: str,
                                       ctx: Context = None) -> List[dict]:
             """Who can reach a namespace — the owner first, then everyone shared
@@ -1080,7 +1122,7 @@ def build_server(cfg: Optional[Config] = None):
                                          namespace_id=space_id)
             return _iso(out, "created_at")
 
-        @mcp.tool()
+        @tool()
         def memory_admin_issue_token(user_id: str, permission: str = "write",
                                      space_id: Optional[str] = None,
                                      label: str = "",
@@ -1112,7 +1154,7 @@ def build_server(cfg: Optional[Config] = None):
                 out["warning"] = minted["warning"]
             return out
 
-        @mcp.tool()
+        @tool()
         def memory_admin_create_enrollment(
                 user_id: str, permission: str = "write",
                 space_id: Optional[str] = None, label: str = "",
@@ -1146,7 +1188,7 @@ def build_server(cfg: Optional[Config] = None):
             out["expires_at"] = out["expires_at"].isoformat()
             return admin.deliver_key(out, cfg.token_sink)
 
-        @mcp.tool()
+        @tool()
         def memory_admin_list_enrollments(user_id: Optional[str] = None,
                                           ctx: Context = None) -> List[dict]:
             """Enrollment keys and what became of them — `state` is pending,
@@ -1158,7 +1200,7 @@ def build_server(cfg: Optional[Config] = None):
                                              user_id=user_id)
             return _iso(out, "created_at", "expires_at", "used_at", "revoked_at")
 
-        @mcp.tool()
+        @tool()
         def memory_admin_revoke_enrollment(enrollment_id: str,
                                            ctx: Context = None) -> dict:
             """Kill an unredeemed enrollment key. False means it was already
@@ -1169,7 +1211,7 @@ def build_server(cfg: Optional[Config] = None):
                     conn, _principal(conn, _token(ctx)),
                     enrollment_id=enrollment_id)}
 
-        @mcp.tool()
+        @tool()
         def memory_admin_list_tokens(user_id: str,
                                      ctx: Context = None) -> List[dict]:
             """A user's tokens — metadata only, never the secret."""
@@ -1178,7 +1220,7 @@ def build_server(cfg: Optional[Config] = None):
                                         user_id=user_id)
             return _iso(out, *_TOKEN_TIMES)
 
-        @mcp.tool()
+        @tool()
         def memory_admin_revoke_token(token_id: str,
                                       ctx: Context = None) -> dict:
             """Kill any user's token immediately. False means it was already

memgres-0.12.1/memgres/paths.py

@@ -0,0 +1,49 @@
+"""What a tree path is — in ONE place.
+
+The shape was written down twice before, in the link parser and in whatever SQL
+happened to cast a string to `ltree`, and the two disagreed: a hyphen was legal
+to store and illegal to link, so half the links in a real corpus silently
+vanished (fixed in 0.12.0). This module exists so a third definition does not
+appear.
+
+It also gives the check a place to happen BEFORE the value reaches Postgres. An
+unvalidated prefix arrived at the database as `%s::ltree` and came back as
+`psycopg.errors.SyntaxError: ltree syntax error at character 1` — a message
+about our schema, not about their input, and one the caller can do nothing with.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+# Labels of word characters (letters in ANY script, digits, underscore) or
+# hyphens, joined by dots.
+#
+# Two things had to be widened here, each because a real path was being called
+# invalid. The hyphen: Postgres has allowed it in ltree labels since 13, the
+# minimum this project supports. Non-ASCII letters: `ops.тариф` stores and reads
+# perfectly well, and an existing test says so — a check that rejected it would
+# have made a working path unwritable, which is worse than the error it prevents.
+#
+# The parser for `[[links]]` uses the SAME alphabet on purpose. When it was
+# narrower, every hyphenated link was dropped as prose; a narrower rule here
+# would recreate that, only for Cyrillic.
+PATH_RE = re.compile(r"^[\w-]+(\.[\w-]+)*$", re.UNICODE)
+
+
+def is_path(value: Optional[str]) -> bool:
+    return bool(value) and bool(PATH_RE.match(value))
+
+
+def check_path(value: Optional[str], field: str = "path") -> Optional[str]:
+    """Return `value` unchanged, or raise ValueError naming the field and the
+    shape. Empty/None passes — "no path given" is not a malformed one."""
+    if value is None or value == "":
+        return value
+    if not PATH_RE.match(value):
+        raise ValueError(
+            f"`{field}` is not a tree path: {value!r}. A path is labels of "
+            f"letters (any script), digits, `_` or `-` joined by dots, like "
+            f"`ops.memory.onboarding` — no spaces, slashes or leading dots.")
+    return value

{memgres-0.12.0 → memgres-0.12.1}/memgres/store.py

@@ -35,6 +35,7 @@ from . import identity
 from .config import Config
 from .delimiters import write_warnings
 from .lines import parse_line_spec
+from .paths import check_path
 from .diffing import DiffConflict, apply_diff, byte_len, content_hash, make_diff
 from .embeddings import Embedder, get_embedder
 from .links import parse_links, rewrite_targets
@@ -625,6 +626,7 @@ class Store:
             # stored one way and filtered another.
             tags = normalize_tags(tags)
             valid_at = _as_date(valid_at)
+            check_path(path, "path")
             if id is None and at is None:
                 self._check_path_free(ns, path, if_moved)
                 m = self._create(ns, author, body, path, tags, source, reason,

{memgres-0.12.0 → memgres-0.12.1}/memgres/vector/base.py

@@ -139,8 +139,12 @@ def build_filters(ns, tags: Optional[Sequence[str]], path_prefix: Optional[str],
     # input would filter nothing or everything depending on a mode flag the
     # caller may not have set. Neither is an answer; "no tags requested" is.
     if path_prefix:
+        # Checked here, not by Postgres: an unvalidated prefix came back as
+        # `ltree syntax error at character 1`, which tells the caller nothing
+        # about what they passed.
+        from ..paths import check_path
         sql.append("path <@ %s::ltree")     # subtree of the prefix
-        params.append(path_prefix)
+        params.append(check_path(path_prefix, "path_prefix"))
     return " AND ".join(sql), params
 
 

{memgres-0.12.0 → memgres-0.12.1}/memgres.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memgres
-Version: 0.12.0
+Version: 0.12.1
 Summary: Drop-in memory for AI agents: one Postgres, lexical + semantic recall, diff-versioned history, GDPR-erasable.
 Author: mozgsml
 License-Expression: MIT

{memgres-0.12.0 → memgres-0.12.1}/memgres.egg-info/SOURCES.txt

@@ -19,6 +19,7 @@ memgres/info.py
 memgres/lines.py
 memgres/links.py
 memgres/mcp_server.py
+memgres/paths.py
 memgres/periodic.py
 memgres/reembed.py
 memgres/relink.py
@@ -79,6 +80,7 @@ tests/test_limits.py
 tests/test_links.py
 tests/test_list.py
 tests/test_mcp_admin_tools.py
+tests/test_mcp_error_messages.py
 tests/test_mcp_http_transport.py
 tests/test_mcp_instructions.py
 tests/test_mcp_recall_schema.py

memgres-0.12.1/tests/test_mcp_error_messages.py

@@ -0,0 +1,207 @@
+"""A refusal the caller cannot read is a refusal that gets repeated.
+
+The server was already answering carefully — "this deployment requires `source`
+… as an ADDRESS", "you can reach 2 namespaces, name the one you mean" — and the
+caller saw `Error executing tool memory_write` with nothing else. The MCP SDK
+masks every exception except its own `ToolError`, so all that text went to the
+server log and nowhere else. In production an agent hit the same wall five times
+in a row with the same edit, then moved on to reads and hit it again.
+
+So the tools now re-raise domain refusals as `ToolError` — and only those. A
+psycopg error or a genuine bug stays masked, because those messages describe our
+schema rather than the caller's mistake.
+
+The second half is the one that produced no sentence at all: a `path_prefix`
+that is not a path reached Postgres as `%s::ltree` and came back as `ltree
+syntax error at character 1`. Validated up front now, in the one place that says
+what a path is.
+"""
+
+import json
+import os
+import socket
+import subprocess
+import sys
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+import pytest  # noqa: E402
+
+psycopg = pytest.importorskip("psycopg")
+
+from memgres.paths import check_path, is_path  # noqa: E402
+
+DSN = os.environ.get("MEMGRES_TEST_DSN",
+                     "postgresql://memgres:memgres@localhost:55432/memgres")
+
+
+# ─── what a path is, in one place ────────────────────────────────────────────
+def test_a_path_is_labels_joined_by_dots():
+    assert is_path("ops.memory.onboarding")
+    assert is_path("infra.servers.video-production")   # hyphen: ltree allows it
+    assert is_path("ops.тариф")                        # any script: so does ltree
+    assert check_path("ops.x", "path") == "ops.x"
+
+
+def test_what_is_not_a_path_is_refused_with_a_sentence():
+    for bad in ("not a path", "ops/x", ".leading", "ops..x", "конец "):
+        with pytest.raises(ValueError) as e:
+            check_path(bad, "path_prefix")
+        msg = str(e.value)
+        assert "path_prefix" in msg          # which argument
+        assert repr(bad) in msg              # what they passed
+        assert "joined by dots" in msg       # what it should look like
+
+
+def test_no_path_is_not_a_bad_path():
+    """`None`/empty means "not filtering", and refusing it would break every
+    unfiltered list."""
+    assert check_path(None, "path_prefix") is None
+    assert check_path("", "path_prefix") == ""
+
+
+# ─── the wrapper: which failures may speak ───────────────────────────────────
+def test_domain_refusals_become_the_error_type_the_client_sees():
+    from memgres.mcp_server import ToolError, _speaking
+
+    def refuses():
+        raise ValueError("say which namespace you mean")
+
+    with pytest.raises(ToolError) as e:
+        _speaking(refuses)()
+    assert "say which namespace you mean" in str(e.value)
+
+
+def test_internal_failures_stay_masked():
+    """A psycopg error or a bug describes our schema, not their mistake. It must
+    NOT be handed to the caller — it stays whatever it was, and the SDK masks it."""
+    from memgres.mcp_server import ToolError, _speaking
+
+    def breaks():
+        raise RuntimeError("relation \"memory\" does not exist")
+
+    with pytest.raises(RuntimeError):
+        _speaking(breaks)()
+    try:
+        _speaking(breaks)()
+    except Exception as e:                    # noqa: BLE001 - asserting the type
+        assert not isinstance(e, ToolError)
+
+
+def test_a_refusal_is_not_wrapped_twice():
+    from memgres.mcp_server import ToolError, _speaking
+
+    def refuses():
+        raise ToolError("already speakable")
+
+    with pytest.raises(ToolError) as e:
+        _speaking(refuses)()
+    assert str(e.value) == "already speakable"
+
+
+# ─── on the wire, which is the only proof that matters ───────────────────────
+def _reachable() -> bool:
+    try:
+        psycopg.connect(DSN, connect_timeout=2).close()
+        return True
+    except Exception:
+        return False
+
+
+def _free_port() -> int:
+    s = socket.socket()
+    s.bind(("127.0.0.1", 0))
+    port = s.getsockname()[1]
+    s.close()
+    return port
+
+
+def _rpc(url: str, payload: dict, session: str = "") -> tuple:
+    body = json.dumps(payload).encode()
+    req = urllib.request.Request(url, data=body, method="POST")
+    req.add_header("Content-Type", "application/json")
+    req.add_header("Accept", "application/json, text/event-stream")
+    if session:
+        req.add_header("Mcp-Session-Id", session)
+    with urllib.request.urlopen(req, timeout=15) as r:
+        return r.read().decode(), r.headers.get("Mcp-Session-Id", "")
+
+
+@pytest.mark.skipif(not _reachable(), reason="no test Postgres")
+def test_every_registered_tool_is_wrapped():
+    """The version-independent half of the proof.
+
+    Whether a bare `ValueError` reaches the client is up to the SDK, and it
+    CHANGED under us: 2.0.0 put the message into its own error text, 2.1.1 raises
+    `UnexpectedToolError("Error executing tool <name>")` and drops it. So the
+    wire test below passes on one version whether or not the fix is present. This
+    one asserts the fix itself — that what got registered is the wrapper — and
+    fails on every SDK generation if the wrapping is removed."""
+    os.environ.setdefault("MEMGRES_DATABASE_URL", DSN)
+    os.environ["MEMGRES_KEY_MODE"] = "single"
+    os.environ["MEMGRES_EMBED_PROVIDER"] = "none"
+    from memgres.mcp_server import ToolError, build_server
+
+    srv = build_server()
+    mgr = getattr(srv, "_tool_manager", None)
+    tools = getattr(mgr, "_tools", None)
+    assert tools, "could not reach the registered tools"
+    with pytest.raises(ToolError) as e:
+        tools["memory_list"].fn(path_prefix="not a path")
+    assert "not a tree path" in str(e.value)
+
+
+@pytest.mark.skipif(not _reachable(), reason="no test Postgres")
+def test_the_reason_reaches_the_client_over_http():
+    """In-process assertions cannot prove this: the masking happens in the SDK's
+    tool layer, on the way out. So this drives a real server over real HTTP and
+    reads what a caller would actually be told."""
+    port = _free_port()
+    env = {**os.environ,
+           "MEMGRES_DATABASE_URL": DSN,
+           "MEMGRES_KEY_MODE": "single",
+           "MEMGRES_EMBED_PROVIDER": "none",
+           "MEMGRES_MCP_TRANSPORT": "http",
+           "MEMGRES_MCP_HOST": "127.0.0.1",
+           "MEMGRES_MCP_PORT": str(port)}
+    root = str(Path(__file__).resolve().parent.parent)
+    env["PYTHONPATH"] = root + os.pathsep + env.get("PYTHONPATH", "")
+    proc = subprocess.Popen([sys.executable, "-m", "memgres.mcp_server"],
+                            env=env, stdout=subprocess.PIPE,
+                            stderr=subprocess.STDOUT, text=True)
+    url = f"http://127.0.0.1:{port}/mcp"
+    try:
+        deadline = time.time() + 30
+        session = ""
+        while time.time() < deadline:
+            if proc.poll() is not None:
+                out = proc.stdout.read() if proc.stdout else ""
+                pytest.fail(f"server exited early ({proc.returncode}):\n{out}")
+            try:
+                _, session = _rpc(url, {
+                    "jsonrpc": "2.0", "id": 1, "method": "initialize",
+                    "params": {"protocolVersion": "2025-06-18", "capabilities": {},
+                               "clientInfo": {"name": "t", "version": "0"}}})
+                break
+            except (urllib.error.URLError, ConnectionError, OSError):
+                time.sleep(0.5)
+        assert session, "server never completed a handshake"
+        _rpc(url, {"jsonrpc": "2.0", "method": "notifications/initialized"}, session)
+
+        text, _ = _rpc(url, {
+            "jsonrpc": "2.0", "id": 2, "method": "tools/call",
+            "params": {"name": "memory_list",
+                       "arguments": {"path_prefix": "not a path"}}}, session)
+        # The point of the fix, in one assertion: the sentence, not the mask.
+        assert "not a tree path" in text, text[:400]
+        assert "joined by dots" in text
+    finally:
+        proc.terminate()
+        try:
+            proc.wait(timeout=10)
+        except subprocess.TimeoutExpired:
+            proc.kill()