memgres 0.11.0__tar.gz → 0.12.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memgres
-Version: 0.11.0
+Version: 0.12.0
 Summary: Drop-in memory for AI agents: one Postgres, lexical + semantic recall, diff-versioned history, GDPR-erasable.
 Author: mozgsml
 License-Expression: MIT
@@ -216,6 +216,7 @@ Everything is env, all optional (defaults suit a single-user embed). Full list i
 | `MEMGRES_TOKEN` | — | default token used when a call passes none (single-tenant endpoints) |
 | `MEMGRES_TOKEN_SINK` | — | absolute directory a minted secret is **written to** (`<token-id>.token`, `0600`) instead of being returned. Set it when provisioning is done by an agent — a secret in a tool result is a secret in a transcript. See [docs/TENANCY.md](docs/TENANCY.md) |
 | `MEMGRES_TREE` | `true` | `ltree` path column + GiST index (fast subtree select) |
+| `MEMGRES_REQUIRED_FIELDS` | — | comma-separated fields a content-storing write must carry (`source`, `reason`), refused by name when absent. A policy about a corpus, not a property of the software: a scratch database wants none, a corporate one wants `source`. `move`/`retag` are exempt. Announced in `server_info.write_requirements` |
 | `MEMGRES_REQUIRE_TITLE` | `true` | `true` = a write that stores content must supply `title`. Captions are what name a memory in results and what title-weighted ranking weighs; `move`/`retag` are exempt (they store no content) |
 | `MEMGRES_REQUIRE_PARENT` | `false` | `true` = a node's parent path must already exist |
 | `MEMGRES_HISTORY` | `true` | keep the hash-chained diff history (deleted with the record) |

{memgres-0.11.0 → memgres-0.12.0}/README.md

@@ -180,6 +180,7 @@ Everything is env, all optional (defaults suit a single-user embed). Full list i
 | `MEMGRES_TOKEN` | — | default token used when a call passes none (single-tenant endpoints) |
 | `MEMGRES_TOKEN_SINK` | — | absolute directory a minted secret is **written to** (`<token-id>.token`, `0600`) instead of being returned. Set it when provisioning is done by an agent — a secret in a tool result is a secret in a transcript. See [docs/TENANCY.md](docs/TENANCY.md) |
 | `MEMGRES_TREE` | `true` | `ltree` path column + GiST index (fast subtree select) |
+| `MEMGRES_REQUIRED_FIELDS` | — | comma-separated fields a content-storing write must carry (`source`, `reason`), refused by name when absent. A policy about a corpus, not a property of the software: a scratch database wants none, a corporate one wants `source`. `move`/`retag` are exempt. Announced in `server_info.write_requirements` |
 | `MEMGRES_REQUIRE_TITLE` | `true` | `true` = a write that stores content must supply `title`. Captions are what name a memory in results and what title-weighted ranking weighs; `move`/`retag` are exempt (they store no content) |
 | `MEMGRES_REQUIRE_PARENT` | `false` | `true` = a node's parent path must already exist |
 | `MEMGRES_HISTORY` | `true` | keep the hash-chained diff history (deleted with the record) |

{memgres-0.11.0 → memgres-0.12.0}/memgres/__init__.py

@@ -23,7 +23,7 @@ from .schema import migrate, SchemaMismatch, SCHEMA_VERSION
 from .search import Hit, recall
 from .blame import annotate, annotate_grouped, reconstruct, replay
 from .store import (Store, Memory, Conflict, NotFound, TooLarge, NoParent,
-                    MissingTitle)
+                    MissingTitle, MissingField)
 from .identity import (
     Principal, AuthError, SpaceNotFound,
     resolve, resolve_space, new_token, valid_format,
@@ -38,6 +38,7 @@ __all__ = [
     "Config", "load_config",
     "Store", "Memory", "Conflict", "NotFound", "TooLarge", "NoParent",
     "MissingTitle",
+    "MissingField",
     "make_diff", "apply_diff", "content_hash", "DiffConflict",
     "Embedder", "get_embedder",
     "migrate", "SchemaMismatch", "SCHEMA_VERSION",

{memgres-0.11.0 → memgres-0.12.0}/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.11.0"
+__version__ = "0.12.0"

{memgres-0.11.0 → memgres-0.12.0}/memgres/config.py

@@ -79,6 +79,8 @@ class Config:
     # organization
     tree_enabled: bool           # ltree path column + GiST index for fast subtree selection
     require_title: bool          # True = a write that stores CONTENT must caption it
+    required_fields: tuple       # extra fields a content-storing write must carry
+                                 # (MEMGRES_REQUIRED_FIELDS=source), refused when absent
     require_parent: bool         # False = sparse paths (create food.apple with no food row);
                                  # True = a node's parent path must already exist as a memory
     # history
@@ -222,6 +224,10 @@ def load() -> Config:
         token_sink=_str("MEMGRES_TOKEN_SINK", ""),
         tree_enabled=_bool("MEMGRES_TREE", True),
         require_title=_bool("MEMGRES_REQUIRE_TITLE", True),
+        required_fields=tuple(
+            f for f in (x.strip().lower()
+                        for x in _str("MEMGRES_REQUIRED_FIELDS", "").split(","))
+            if f),
         require_parent=_bool("MEMGRES_REQUIRE_PARENT", False),
         history_enabled=_bool("MEMGRES_HISTORY", True),
         fts_language=_str("MEMGRES_FTS_LANGUAGE", "simple"),

{memgres-0.11.0 → memgres-0.12.0}/memgres/info.py

@@ -65,6 +65,14 @@ def server_info(cfg: Config, embed_dim: Optional[int] = None) -> dict:
             "renew_on_read": bool(days > 0 and cfg.renew_on_read),
             "policy": _retention_policy(days, cfg.renew_on_read),
         },
+        # What a write MUST carry here. Announced rather than discovered from a
+        # refusal: a client that learns the rule by being rejected has already
+        # composed the memory, and a rule nobody can see before writing is a rule
+        # that gets satisfied with junk on the second attempt.
+        "write_requirements": {
+            "title": cfg.require_title,
+            "fields": list(cfg.required_fields),
+        },
         "recall_modes": ["lexical"] if lexical_only
         else ["lexical", "semantic", "hybrid", "auto"],
         "vector_backend": cfg.vector_backend,

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

@@ -52,10 +52,19 @@ 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 —
+# 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.
-_PATH = re.compile(r"^[A-Za-z0-9_]+(\.[A-Za-z0-9_]+)*$")
+#
+# 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_-]+)*$")
 
 _LINK = re.compile(r"\[\[([^\[\]\n]+)\]\]")
 _FENCE = re.compile(r"```.*?```|~~~.*?~~~", re.S)
@@ -82,8 +91,58 @@ class Link:
     end: int = 0
 
 
+def _blank_indented(original: str, text: str) -> str:
+    """Blank markdown's OTHER code block: a run of lines indented by four spaces
+    (or a tab), opened by a blank line.
+
+    Fences are not the only way to show code, and the indented form is what a
+    hand-written example tends to use. A frp config pasted that way put
+    ``[[proxies]]`` — a TOML array-of-tables header, and a perfectly well-formed
+    path — into the link graph as a dangling edge to a memory nobody will ever
+    write. The parser must ignore code wherever markdown says code is.
+
+    A blank line inside the block does not end it; the first non-blank line back
+    at the margin does. Opening on a blank line is what keeps an ordinary list
+    item or a wrapped line — indented, but not preceded by a blank — from being
+    read as code.
+
+    🔴 Which lines are code is decided from `original`, and the blanking applied
+    to `text` — the copy where spans and fences are already spaces. Deciding from
+    the blanked copy instead made every line that STARTED with an inline code
+    span look indented: "`[[a]]` but [[b]] counts" became four-plus leading
+    spaces, the whole line was swallowed as a block, and a real link next to a
+    code span disappeared. Both strings are length-preserving, so their lines
+    correspond one to one.
+    """
+    def blank(line: str) -> str:
+        return "".join(" " if c != "\n" else "\n" for c in line)
+
+    src = original.splitlines(keepends=True)
+    dst = text.splitlines(keepends=True)
+    out, in_block, prev_blank = [], False, True
+    for i, line in enumerate(src):
+        stripped = line.strip("\n")
+        is_blank = not stripped.strip()
+        indented = stripped.startswith("    ") or stripped.startswith("\t")
+        current = dst[i] if i < len(dst) else line
+        if in_block:
+            if is_blank or indented:
+                out.append(current if is_blank else blank(current))
+            else:
+                in_block = False
+                out.append(current)
+        elif indented and prev_blank:
+            in_block = True
+            out.append(blank(current))
+        else:
+            out.append(current)
+        prev_blank = is_blank
+    return "".join(out)
+
+
 def _blank_code(body: str) -> str:
-    """Replace code spans and fenced blocks with spaces of the same length.
+    """Replace code spans and code blocks — fenced AND indented — with spaces of
+    the same length.
 
     Same length, not removal, so every offset in the returned text still lines up
     with the original — the parser does not need that today, but an anchor
@@ -92,7 +151,7 @@ def _blank_code(body: str) -> str:
     """
     def blank(m: re.Match) -> str:
         return "".join(" " if c != "\n" else "\n" for c in m.group(0))
-    return _CODE_SPAN.sub(blank, _FENCE.sub(blank, body))
+    return _blank_indented(body, _CODE_SPAN.sub(blank, _FENCE.sub(blank, body)))
 
 
 def _classify(target: str) -> Optional[str]:

memgres-0.12.0/memgres/migrations/0023_relink_after_parser_fix.sql

@@ -0,0 +1,16 @@
+-- Re-derive the link graph, because the PARSER changed, not the schema.
+--
+-- Until now `_PATH` rejected the hyphen, so every `[[infra.servers.video-production]]`
+-- was classified as prose and dropped — not stored as a dangling edge, dropped —
+-- while `[[proxies]]` from a TOML example indented as code was stored as a real
+-- one. Both halves are fixed in `links.py`; neither fix reaches a body that is
+-- already written, since edges are derived on write.
+--
+-- Clearing the flag makes the existing one-time backfill (`relink.rebuild`, run
+-- at startup by `maybe_backfill`) do the pass again over every body. It rewrites
+-- only the edge table: bodies, history and the hash chain are untouched, so this
+-- is repeatable and costs nothing but a scan.
+--
+-- Additive by nature — an older client reading this database is no worse off
+-- than it was, so the compatibility floor does not move.
+UPDATE memgres_meta SET links_built = false;

{memgres-0.11.0 → memgres-0.12.0}/memgres/schema.py

@@ -18,7 +18,7 @@ from pathlib import Path
 from .config import Config
 
 # The version this build migrates the database TO (the latest migration it carries).
-SCHEMA_VERSION = 23
+SCHEMA_VERSION = 24
 
 # The compatibility FLOOR: the schema version of the most recent backward-
 # INCOMPATIBLE migration — one that changed the shape/semantics old code relied on
@@ -74,6 +74,10 @@ SCHEMA_VERSION = 23
 #   v21 (0020): dropped 0019's foreign key from databases that already ran it →
 #     additive, floor stays 16. Nothing reads the constraint; removing it only
 #     stops a counted read from locking the memory row it counts.
+#   v24 (0023): cleared links_built so the link backfill runs again after the
+#     link PARSER was fixed (hyphens in paths were dropped, indented code was
+#     parsed) → additive, floor stays 16. It rebuilds a derived index from text
+#     that is already stored; an older client neither writes nor reads differently.
 SCHEMA_BREAKING_VERSION = 16
 
 # Dev layout: repo/migrations next to the package. When packaged, migrations are

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

@@ -95,6 +95,15 @@ def _as_date(value: object):
         f"the content was last known to be accurate")
 
 
+class MissingField(ValueError):
+    """A write left out a field this deployment declares mandatory.
+
+    Separate from `MissingTitle` on purpose: the title is required by a setting
+    of its own and has been since long before this, and folding it in would
+    change the exception a client already catches.
+    """
+
+
 class MissingTitle(ValueError):
     """A write stored content without a caption, and the deployment requires one
     (``MEMGRES_REQUIRE_TITLE``, default on).
@@ -238,6 +247,15 @@ class Memory:
     # how much this memory is used — set only by `get`, and only when the
     # deployment counts (see `_count_usage`). A write does not have it.
     usage: Optional[dict] = None
+    # Provenance of the REVISION this call just wrote — never of the memory,
+    # which has no single source: `source`/`reason`/`valid_at` live on the
+    # history row because different edits speak to different origins and dates.
+    # So these are set by `write` and stay None on a read, where the question
+    # belongs to `history`/`blame`. Echoed back because a required field that the
+    # answer does not confirm is a field whose absence nobody notices: four edits
+    # in a row went out with an empty `source` and every reply looked fine.
+    source: Optional[str] = None
+    valid_at: object = None
 
     def to_dict(self, *, stringify_dates: bool = False) -> dict:
         """Serialize for an API layer. ``stringify_dates`` str()-coerces the
@@ -247,6 +265,7 @@ class Memory:
             return (str(v) if v is not None else None) if stringify_dates else v
         return {"id": self.id, "content_hash": self.content_hash, "body": self.body,
                 "title": self.title, "tags": self.tags, "path": self.path,
+                "source": self.source, "valid_at": d(self.valid_at),
                 "seq": self.seq, "created_at": d(self.created_at),
                 "updated_at": d(self.updated_at), "expires_at": d(self.expires_at),
                 "created": self.created, "moved_from": self.moved_from,
@@ -595,6 +614,12 @@ class Store:
                                          need="write", for_write=True)
             self._check_provenance_size(source, reason)
             self._check_title_size(title)
+            # Content-storing is what the title rule already means by it: a body,
+            # a diff or a substring edit. A create always stores content.
+            self._require_fields(
+                stores_content=(id is None and at is None) or body is not None
+                               or diff is not None or replace is not None,
+                source=source, reason=reason, title=title)
             # One spelling per tag, decided here rather than in `_create` and
             # `_update` separately — two normalisation sites is how a tag ends up
             # stored one way and filtered another.
@@ -615,6 +640,8 @@ class Store:
             # Checked on the STORED body, not the request: a substring edit or a
             # diff can introduce the stray tag just as a whole body can.
             m.warnings = write_warnings(m.body)
+            # The revision's own provenance, straight back to whoever wrote it.
+            m.source, m.valid_at = source, valid_at
             return m
 
     def _check_path_free(self, ns: str, path: Optional[str],
@@ -699,6 +726,36 @@ class Store:
             f"(it is what names the memory in results and what title search "
             f"matches). Its first line is: {first!r}")
 
+    # What each declarable field is FOR — the refusal has to say this, or the
+    # requirement degenerates into filling the box: "from the email", "the user
+    # said", and a corpus of assertions nobody can check.
+    _FIELD_HELP = {
+        "source": ("where this knowledge came from, as an ADDRESS someone else "
+                   "can follow back to the original: host + absolute path + "
+                   "date; mailbox, sender -> recipient, date, subject; full URL "
+                   "+ date read. 'from the email' or 'the user said' is not one"),
+        "reason": ("why this write happened — what changed and why, in one line"),
+        "title": ("a short caption; it names the memory in results"),
+    }
+
+    def _require_fields(self, *, stores_content: bool, **values) -> None:
+        """Enforce `MEMGRES_REQUIRED_FIELDS` on a write that stores CONTENT.
+
+        Metadata-only edits are exempt, exactly as they are for the title: a move
+        or a retag asserts nothing new, and demanding provenance for one would
+        make re-filing a memory harder than writing one — friction unrelated to
+        the point, and the surest way to get a required field filled with junk.
+        """
+        if not stores_content:
+            return
+        for field in self.cfg.required_fields:
+            if (values.get(field) or "").strip():
+                continue
+            help_text = self._FIELD_HELP.get(field, "required by this deployment")
+            raise MissingField(
+                f"this deployment requires `{field}` on every write that stores "
+                f"content — {help_text}")
+
     def _check_title_size(self, title: Optional[str]):
         if title is not None and byte_len(title) > self.cfg.max_title_bytes:
             raise TooLarge(
@@ -1323,13 +1380,13 @@ class Store:
             "created_at, updated_at, namespace, "
             # Browsing is where usage becomes actionable: it is how you find the
             # subtree nobody reads. No row yet means never used, which is zero.
-            "COALESCE(u.recall_count, 0), COALESCE(u.get_count, 0) "
+            "COALESCE(u.recall_count, 0), COALESCE(u.get_count, 0), seq "
             "FROM memory LEFT JOIN memory_usage u ON u.memory_id = memory.id "
             f"WHERE {where} ORDER BY namespace, path, id "
             "LIMIT %s OFFSET %s",
             head + params + [limit, offset])
         cols = ["id", "path", "tags", "title", "shown", "created_at",
-                "updated_at", "space_id", "recalled", "gets"]
+                "updated_at", "space_id", "recalled", "gets", "seq"]
         budget = self.cfg.list_bodies_max_bytes
         rows, wanted = [], []
         for r in cur.fetchall():
@@ -1338,6 +1395,9 @@ class Store:
             d["tags"] = list(d["tags"]) if d["tags"] is not None else []
             d["space_id"] = str(d["space_id"])
             d["space"] = names.get(d["space_id"])
+            # Revisions after the creation. Comes off the row itself, so unlike
+            # the read counters it is exact and costs nothing.
+            d["edits"] = max(0, int(d.pop("seq")) - 1)
             if not self.cfg.usage_counters:
                 # Null, not zero. Nothing is being counted here, and reporting
                 # "0 recalls, 0 reads" would read as a measurement — on a
@@ -1543,6 +1603,13 @@ class Store:
         # the store working rather than the memory being used.
         if _count:
             m.usage = self._count_usage("get", [m.id], want=True)
+            if m.usage is not None:
+                # How often this memory has been REWRITTEN, which is a different
+                # question from how often it is read: a much-edited memory is a
+                # live one, a much-read one is a useful one, and ranking "what is
+                # hot" wants both. Free — `seq` counts the revisions already, and
+                # the first one is the creation, so edits are one fewer.
+                m.usage["edits"] = max(0, int(m.seq) - 1)
         return _slice_lines(m, lines) if lines else m
 
     def history(self, token: Optional[str], id: Optional[str] = None, *,

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memgres
-Version: 0.11.0
+Version: 0.12.0
 Summary: Drop-in memory for AI agents: one Postgres, lexical + semantic recall, diff-versioned history, GDPR-erasable.
 Author: mozgsml
 License-Expression: MIT
@@ -216,6 +216,7 @@ Everything is env, all optional (defaults suit a single-user embed). Full list i
 | `MEMGRES_TOKEN` | — | default token used when a call passes none (single-tenant endpoints) |
 | `MEMGRES_TOKEN_SINK` | — | absolute directory a minted secret is **written to** (`<token-id>.token`, `0600`) instead of being returned. Set it when provisioning is done by an agent — a secret in a tool result is a secret in a transcript. See [docs/TENANCY.md](docs/TENANCY.md) |
 | `MEMGRES_TREE` | `true` | `ltree` path column + GiST index (fast subtree select) |
+| `MEMGRES_REQUIRED_FIELDS` | — | comma-separated fields a content-storing write must carry (`source`, `reason`), refused by name when absent. A policy about a corpus, not a property of the software: a scratch database wants none, a corporate one wants `source`. `move`/`retag` are exempt. Announced in `server_info.write_requirements` |
 | `MEMGRES_REQUIRE_TITLE` | `true` | `true` = a write that stores content must supply `title`. Captions are what name a memory in results and what title-weighted ranking weighs; `move`/`retag` are exempt (they store no content) |
 | `MEMGRES_REQUIRE_PARENT` | `false` | `true` = a node's parent path must already exist |
 | `MEMGRES_HISTORY` | `true` | keep the hash-chained diff history (deleted with the record) |

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

@@ -58,6 +58,7 @@ memgres/migrations/0019_memory_usage.sql
 memgres/migrations/0020_memory_usage_no_fk.sql
 memgres/migrations/0021_enrollment_key.sql
 memgres/migrations/0022_user_disabled.sql
+memgres/migrations/0023_relink_after_parser_fix.sql
 memgres/vector/__init__.py
 memgres/vector/base.py
 memgres/vector/pgvector.py
@@ -90,6 +91,7 @@ tests/test_qdrant_ca.py
 tests/test_qdrant_integration.py
 tests/test_replace_build.py
 tests/test_require_title.py
+tests/test_required_fields.py
 tests/test_retention.py
 tests/test_roles_bootstrap.py
 tests/test_search_integration.py

{memgres-0.11.0 → memgres-0.12.0}/tests/test_links.py

@@ -147,7 +147,49 @@ def test_urls_and_prose_are_left_alone():
     assert parse_links("[[https://example.com/x]]") == []
     assert parse_links("[[mailto:someone@example.com]]") == []
     assert parse_links("[[some thing with spaces]]") == []
-    assert parse_links("[[has-hyphens]]") == []      # not an ltree label
+
+
+def test_a_hyphen_belongs_to_a_path():
+    """This assertion used to say the opposite, on the belief that a hyphen is
+    not an ltree label. It is: Postgres has allowed one since 13, `write` stores
+    such paths without complaint, and a real corpus is full of them. While the
+    parser disagreed, every `[[infra.servers.video-production]]` was silently
+    dropped — not kept as dangling, dropped — so `memory_links` reported an empty
+    graph and it read like a fact about the corpus."""
+    links = parse_links("see [[infra.servers.video-production]] and [[ops.frp.tunnel]]")
+    assert [l.raw_target for l in links] == ["infra.servers.video-production",
+                                             "ops.frp.tunnel"]
+    assert all(l.scheme is None for l in links)
+
+
+def test_code_indented_by_four_spaces_is_still_code():
+    """Fences are not the only way to show code. A frp config pasted with an
+    indent put `[[proxies]]` — a TOML array-of-tables header that happens to be a
+    well-formed path — into the graph as an edge to a memory nobody will write."""
+    body = ("Add a section:\n"
+            "\n"
+            "    [[proxies]]\n"
+            "    name = \"memgres\"\n"
+            "\n"
+            "then restart, see [[ops.frp.tunnel]].\n")
+    assert [l.raw_target for l in parse_links(body)] == ["ops.frp.tunnel"]
+
+
+def test_a_blank_line_inside_the_block_does_not_end_it():
+    body = ("Example:\n\n"
+            "    [[first]]\n"
+            "\n"
+            "    [[second]]\n"
+            "\n"
+            "back at the margin: [[real.one]]\n")
+    assert [l.raw_target for l in parse_links(body)] == ["real.one"]
+
+
+def test_an_indented_list_item_is_not_code():
+    """Two spaces is a list, not a block — and the link in it is a real one.
+    Blanking by indentation alone would have eaten it."""
+    body = "Пункты:\n  - см. [[ops.memory.onboarding]]\n"
+    assert [l.raw_target for l in parse_links(body)] == ["ops.memory.onboarding"]
 
 
 def test_known_schemes_point_at_other_stores():

{memgres-0.11.0 → memgres-0.12.0}/tests/test_list.py

@@ -66,7 +66,7 @@ def test_lists_subtree_ordered_by_path(store):
     # the ops row is NOT in the decisions subtree
     assert all(r["path"].startswith("decisions") for r in rows)
     # shape of each row
-    assert set(rows[0]) == {"id", "path", "tags", "title", "preview",
+    assert set(rows[0]) == {"id", "path", "tags", "title", "preview", "edits",
                             "created_at", "updated_at", "space_id", "space",
                             "recalled", "gets"}
 

memgres-0.12.0/tests/test_required_fields.py

@@ -0,0 +1,195 @@
+"""What a write MUST carry, and what the answer tells you about what it carried.
+
+Two failures of the same shape sit behind this file.
+
+The first: `source` is described to every client as mandatory — an address by
+which someone else finds the original — but nothing enforced it, so a corpus
+fills with assertions nobody can check. The requirement is now declarable per
+deployment (`MEMGRES_REQUIRED_FIELDS=source`), because it is a policy about a
+corpus, not a property of the software: a scratch database has no use for it.
+
+The second is subtler and is why the first went unnoticed for so long. The reply
+to a write did not echo the provenance it had just recorded, so four edits in a
+row went out with an empty `source` and every reply looked perfectly healthy.
+A required field that the answer does not confirm is a field whose absence
+nobody notices. It is echoed on WRITE only: provenance belongs to the revision,
+not to the memory, so a read has no business claiming one — that question is
+`history`/`blame`.
+
+Alongside them, `edits`: how often a memory has been rewritten, which is a
+different question from how often it is read, and the half of "what is hot"
+the usage counters were missing.
+"""
+
+import os
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+import pytest  # noqa: E402
+
+psycopg = pytest.importorskip("psycopg")
+
+from memgres.config import load  # noqa: E402
+from memgres.schema import migrate  # noqa: E402
+from memgres.store import MissingField, Store  # noqa: E402
+
+DSN = os.environ.get("MEMGRES_TEST_DSN",
+                     "postgresql://memgres:memgres@localhost:55432/memgres")
+
+
+def _reachable() -> bool:
+    try:
+        psycopg.connect(DSN, connect_timeout=2).close()
+        return True
+    except Exception:
+        return False
+
+
+pytestmark = pytest.mark.skipif(not _reachable(), reason="no test Postgres")
+
+
+@pytest.fixture
+def conn(monkeypatch):
+    with psycopg.connect(DSN, autocommit=True) as c, c.cursor() as cur:
+        cur.execute("DROP SCHEMA public CASCADE; CREATE SCHEMA public;")
+    for k in list(os.environ):
+        if k.startswith("MEMGRES_"):
+            monkeypatch.delenv(k, raising=False)
+    monkeypatch.setenv("MEMGRES_DATABASE_URL", DSN)
+    monkeypatch.setenv("MEMGRES_FTS_LANGUAGE", "simple")
+    monkeypatch.setenv("MEMGRES_EMBED_PROVIDER", "none")
+    c = psycopg.connect(DSN)
+    migrate(c, load())
+    yield c
+    c.close()
+
+
+def _store(conn, monkeypatch, required: str = "") -> Store:
+    """A store whose deployment declares — or doesn't — extra required fields.
+    Built on the SAME connection as its predecessor on purpose: that is how a
+    corpus written before the policy is modelled, old rows real, new rule live."""
+    monkeypatch.setenv("MEMGRES_REQUIRED_FIELDS", required)
+    return Store(load(), conn=conn)
+
+
+# ─── the default: nothing extra is required ──────────────────────────────────
+def test_nothing_is_required_unless_a_deployment_says_so(monkeypatch):
+    for k in list(os.environ):
+        if k.startswith("MEMGRES_"):
+            monkeypatch.delenv(k, raising=False)
+    monkeypatch.setenv("MEMGRES_DATABASE_URL", DSN)
+    assert load().required_fields == ()
+
+
+def test_without_the_policy_a_sourceless_write_is_fine(conn, monkeypatch):
+    s = _store(conn, monkeypatch, "")
+    m = s.write(body="один", path="a.b", title="A")
+    assert m.source is None
+
+
+# ─── the refusal ─────────────────────────────────────────────────────────────
+def test_creating_without_source_is_refused(conn, monkeypatch):
+    s = _store(conn, monkeypatch, "source")
+    with pytest.raises(MissingField) as e:
+        s.write(body="лимит имени OKX — 25", path="ops.okx", title="OKX")
+    msg = str(e.value)
+    assert "source" in msg
+    # The refusal must say what the field is FOR, or the requirement degenerates
+    # into filling the box: the second attempt would read "from the email".
+    assert "ADDRESS" in msg
+    assert "the user said" in msg
+
+
+def test_whitespace_is_not_a_source(conn, monkeypatch):
+    s = _store(conn, monkeypatch, "source")
+    with pytest.raises(MissingField):
+        s.write(body="один", path="a.b", title="A", source="   ")
+
+
+def test_an_edit_that_changes_the_body_needs_one_too(conn, monkeypatch):
+    s = _store(conn, monkeypatch, "")
+    s.write(body="один", path="a.b", title="A")
+    strict = _store(conn, monkeypatch, "source")
+    with pytest.raises(MissingField):
+        strict.write(at="a.b", body="два")
+    with pytest.raises(MissingField):
+        strict.write(at="a.b", replace=("два", "три"))
+
+
+def test_a_declared_field_can_be_something_other_than_source(conn, monkeypatch):
+    s = _store(conn, monkeypatch, "reason")
+    with pytest.raises(MissingField) as e:
+        s.write(body="один", path="a.b", title="A", source="host:/path 2026-08-27")
+    assert "reason" in str(e.value)
+    s.write(body="один", path="a.b", title="A",
+            source="host:/path 2026-08-27", reason="первая запись")
+
+
+# ─── what is exempt ──────────────────────────────────────────────────────────
+def test_moving_and_retagging_are_exempt(conn, monkeypatch):
+    """They store no content. Requiring provenance for re-filing would make a
+    memory harder to organise than to write — friction unrelated to the point,
+    and the surest way to get the field filled with junk."""
+    s = _store(conn, monkeypatch, "")
+    s.write(body="один", path="a.b", title="A")
+    strict = _store(conn, monkeypatch, "source")
+    strict.write(at="a.b", path="a.c")                    # move
+    strict.write(at="a.c", tags=["x"])                    # retag
+    assert strict.get(None, at="a.c").tags == ["x"]
+
+
+# ─── the echo ────────────────────────────────────────────────────────────────
+def test_the_answer_confirms_the_provenance_it_recorded(conn, monkeypatch):
+    s = _store(conn, monkeypatch, "source")
+    m = s.write(body="один", path="a.b", title="A",
+                source="192.168.1.121:/var/www/memgres 2026-08-27",
+                valid_at="2026-08-01")
+    assert m.source == "192.168.1.121:/var/www/memgres 2026-08-27"
+    assert str(m.valid_at) == "2026-08-01"
+    d = m.to_dict(stringify_dates=True)
+    assert d["source"] == "192.168.1.121:/var/www/memgres 2026-08-27"
+    assert d["valid_at"] == "2026-08-01"
+
+
+def test_a_read_claims_no_provenance(conn, monkeypatch):
+    """A memory has no single source — its revisions do. Reporting one on a read
+    would attribute the whole record to whichever edit happened to be last."""
+    s = _store(conn, monkeypatch, "")
+    s.write(body="один", path="a.b", title="A", source="первый источник")
+    s.write(at="a.b", body="два", source="второй источник")
+    got = s.get(None, at="a.b")
+    assert got.source is None and got.valid_at is None
+    # Oldest first, as history reads.
+    assert [h["source"] for h in s.history(None, at="a.b")] == [
+        "первый источник", "второй источник"]
+
+
+# ─── the edit counter ────────────────────────────────────────────────────────
+def test_edits_count_revisions_after_the_creation(conn, monkeypatch):
+    s = _store(conn, monkeypatch, "")
+    s.write(body="один", path="a.b", title="A")
+    assert s.get(None, at="a.b").usage["edits"] == 0
+    s.write(at="a.b", body="два")
+    s.write(at="a.b", body="три")
+    assert s.get(None, at="a.b").usage["edits"] == 2
+
+
+def test_browsing_reports_the_same_count(conn, monkeypatch):
+    """`list` is where "what is hot" gets asked over a whole subtree, so the
+    number has to be there too — and has to agree with the one `get` reports."""
+    s = _store(conn, monkeypatch, "")
+    s.write(body="один", path="a.b", title="A")
+    s.write(at="a.b", body="два")
+    row = [r for r in s.list(None) if r["path"] == "a.b"][0]
+    assert row["edits"] == 1 == s.get(None, at="a.b").usage["edits"]
+
+
+def test_a_move_is_a_revision_too(conn, monkeypatch):
+    """Deliberate: `seq` counts what the history holds, and a move IS an entry
+    there. A number that skipped them would disagree with `history`."""
+    s = _store(conn, monkeypatch, "")
+    s.write(body="один", path="a.b", title="A")
+    s.write(at="a.b", path="a.c")
+    assert s.get(None, at="a.c").usage["edits"] == 1

{memgres-0.11.0 → memgres-0.12.0}/tests/test_server_info.py

@@ -34,7 +34,8 @@ def test_top_level_keys_and_limits(monkeypatch):
     monkeypatch.setenv("MEMGRES_MAX_TITLE_BYTES", "128")
     info = server_info(load())
     assert set(info) == {"version", "schema_version", "limits", "embed",
-                         "retention", "recall_modes", "vector_backend",
+                         "retention", "write_requirements",
+                         "recall_modes", "vector_backend",
                          "key_mode", "fts_language"}
     monkeypatch.setenv("MEMGRES_LIST_BODIES_MAX_BYTES", "4096")
     info = server_info(load())
@@ -129,6 +130,24 @@ def test_renew_on_read_is_not_advertised_when_nothing_expires(monkeypatch):
     assert info["retention"]["renew_on_read"] is False
 
 
+def test_what_a_write_must_carry_is_announced(monkeypatch):
+    """A rule a client can only learn from a refusal is a rule it satisfies with
+    junk on the second attempt: it has already composed the memory by then."""
+    _clear(monkeypatch)
+    monkeypatch.setenv("MEMGRES_REQUIRED_FIELDS", "source")
+    info = server_info(load())
+    assert info["write_requirements"]["fields"] == ["source"]
+    # `_clear` turns captions off for this file, so the flag reports the
+    # deployment as configured — which is exactly the point of announcing it.
+    assert info["write_requirements"]["title"] is False
+
+
+def test_a_deployment_requiring_nothing_extra_says_so(monkeypatch):
+    _clear(monkeypatch)
+    info = server_info(load())
+    assert info["write_requirements"]["fields"] == []
+
+
 def test_no_secrets_leak(monkeypatch):
     _clear(monkeypatch)
     monkeypatch.setenv("MEMGRES_TOKEN", "mgk_supersecret_token")

{memgres-0.11.0 → memgres-0.12.0}/tests/test_server_integration.py

@@ -166,7 +166,8 @@ def test_list_memories_route(client):
 def test_info_route(client):
     info = client.get("/info").json()
     assert set(info) == {"version", "schema_version", "limits", "embed",
-                         "retention", "recall_modes", "vector_backend",
+                         "retention", "write_requirements",
+                         "recall_modes", "vector_backend",
                          "key_mode", "fts_language"}
     # the fixture keeps everything, and the route has to say so rather than
     # leaving a client to infer it from a missing field