memgres 0.12.1__tar.gz → 0.12.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memgres
-Version: 0.12.1
+Version: 0.12.3
 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.1 → memgres-0.12.3}/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.1"
+__version__ = "0.12.3"

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

@@ -61,7 +61,11 @@ SourceArg = Annotated[Optional[str], Field(
                 "sender -> recipient, date, subject; messenger, who with whom, date; "
                 "machine + project + session/transcript for an agent run; full URL + "
                 "date read. 'email', 'the meeting', 'the user said' is not one — "
-                "nothing can be reached through it, so the fact can only be believed.")]
+                "nothing can be reached through it, so the fact can only be believed. "
+                "It is recorded on THIS revision, not on the memory: a memory has no "
+                "single origin, its edits do. So a later read does not carry it — "
+                "`memory_blame` says where a given line came from, `memory_history` "
+                "where each revision did.")]
 ReasonArg = Annotated[Optional[str], Field(
     default=None,
     description="Why this write happened — what changed and why, in one line. Kept "
@@ -503,6 +507,10 @@ def build_server(cfg: Optional[Config] = None):
         The answer carries `usage`: how often this memory has surfaced in search
         (`recalled`) and been fetched (`gets`), and when each last happened.
 
+        It carries NO `source`/`valid_at`, and that is deliberate: provenance
+        belongs to a revision, not to the document. Ask `memory_blame` where a
+        particular line came from, or `memory_history` where each revision did.
+
         `lines` ("40-80", "5", "1,10-12") returns only part of a long body. The
         answer is then marked `partial`, carries `total_lines`, and has NO
         `content_hash` — do not send a slice back as a whole `body`, or

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

@@ -251,12 +251,21 @@ class Memory:
     # 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.
+    # Echoed back on a write because a required field 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.
+    #
+    # `is_write` decides whether they are SERIALIZED at all, and that is the
+    # point: a read used to emit `"source": null`, which does not read as "this
+    # memory has no such field" but as "the value was there and is now gone".
+    # Two readers in a row concluded the field was being silently dropped and
+    # went looking for the bug — one of them spent a day on it and wrote the
+    # workaround into memory. So on a read the keys are ABSENT, and the question
+    # they answer belongs to `history`/`blame`, where the answer is per-revision
+    # and per-line rather than one value pretending to describe the document.
     source: Optional[str] = None
     valid_at: object = None
+    is_write: bool = False
 
     def to_dict(self, *, stringify_dates: bool = False) -> dict:
         """Serialize for an API layer. ``stringify_dates`` str()-coerces the
@@ -264,9 +273,8 @@ class Memory:
         datetimes itself, so the HTTP layer passes them through raw)."""
         def d(v):
             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,
+        out = {"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,
@@ -276,6 +284,12 @@ class Memory:
                            "last_recall_at": d(self.usage["last_recall_at"]),
                            "last_get_at": d(self.usage["last_get_at"])}
                           if self.usage else None)}
+        if self.is_write:
+            # Only here: the provenance of the revision just written, confirmed
+            # back to its author. A read carries no such keys (see `is_write`).
+            out["source"] = self.source
+            out["valid_at"] = d(self.valid_at)
+        return out
 
 
 def _sha(text: str) -> str:
@@ -437,6 +451,57 @@ def _slice_lines(m: "Memory", spec: str) -> "Memory":
     return m
 
 
+
+# How much body text a "why did my replace miss" hint may quote, per side.
+_HINT_CONTEXT = 48
+
+
+def _why_replace_missed(body: str, old: str) -> str:
+    """Say WHY a substring edit found nothing — the refusal alone sends the author
+    to re-read the whole record, when the useful answer is almost always "your
+    quote is not what the body says, here is what it says".
+
+    Three causes, in the order they actually happen:
+
+    1. **Whitespace.** Bodies are hard-wrapped, so a phrase that reads as one line
+       on screen contains a newline. Retyped as a space, it can never match.
+    2. **Case.**
+    3. **Everything else** — then the most useful thing is the point where the
+       quote stops agreeing with the body, and what the body has instead.
+
+    The quote itself is usually reconstructed by eye rather than copied, which is
+    why the hint ends by naming the one reliable source: `memory_get`. A recall
+    snippet is a slice of the body (`lines` says which) EXCEPT on the ts_headline
+    path, where Postgres rebuilds the text from tokens and `lines` is null — that
+    one is not quotable at all.
+    """
+    squashed_old = " ".join(old.split())
+    if squashed_old and squashed_old in " ".join(body.split()):
+        return (" — the text IS in the body, but the whitespace differs: bodies "
+                "wrap, so a line break in the record reads as a space on screen. "
+                "Copy the line from `memory_get`, not from a recall snippet")
+    if old.lower() in body.lower():
+        return (" — it is there in a different case. Copy it from `memory_get`, "
+                "not from a recall snippet")
+    # Longest prefix of `old` the body still agrees with: the point of divergence
+    # is what the author needs to see. Binary search — bodies are capped, but a
+    # linear scan would re-scan the whole body once per character.
+    lo, hi = 0, len(old)
+    while lo < hi:
+        mid = (lo + hi + 1) // 2
+        if old[:mid] in body:
+            lo = mid
+        else:
+            hi = mid - 1
+    if lo == 0:
+        return (" — not one character of it is in the body; wrong memory, or the "
+                "quote was written from memory rather than copied from `memory_get`")
+    at = body.find(old[:lo])
+    reads = body[at:at + lo + _HINT_CONTEXT]
+    return (f" — the first {lo} chars match, then they part: the body reads "
+            f"{reads!r}. Copy from `memory_get`, not from a recall snippet")
+
+
 class Store:
     def __init__(self, cfg: Config, embedder: Optional[Embedder] = None,
                  conn: Optional["psycopg.Connection"] = None,
@@ -643,7 +708,8 @@ class Store:
             # 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
+            # `is_write` is what puts these on the wire; a read leaves them off.
+            m.source, m.valid_at, m.is_write = source, valid_at, True
             return m
 
     def _check_path_free(self, ns: str, path: Optional[str],
@@ -758,11 +824,38 @@ class Store:
                 f"this deployment requires `{field}` on every write that stores "
                 f"content — {help_text}")
 
+    # How much of the title to quote either side of the cut. Enough to recognise
+    # the words, short enough that a pathological title cannot turn the refusal
+    # into a wall of text.
+    _TITLE_CUT_CONTEXT = 40
+
     def _check_title_size(self, title: Optional[str]):
-        if title is not None and byte_len(title) > self.cfg.max_title_bytes:
-            raise TooLarge(
-                f"title is {byte_len(title)}B > MEMGRES_MAX_TITLE_BYTES "
-                f"{self.cfg.max_title_bytes}")
+        """Refuse an oversized title, and SHOW WHERE IT STOPS FITTING.
+
+        The ceiling is in bytes because that is what storage and the wire count,
+        but the author is writing characters — and in UTF-8 the exchange rate
+        depends on the script: Latin runs ~1 B/char, Cyrillic ~2, so the same 256
+        B is ~256 characters in one language and ~148 in another. A refusal that
+        names only bytes leaves the author trimming blind, one attempt at a time
+        (observed: four rejected writes in a row on one record). So the message
+        carries the character counts and quotes the cut itself, marked with ✂ —
+        what survives on the left, what has to go on the right."""
+        if title is None:
+            return
+        size, cap = byte_len(title), self.cfg.max_title_bytes
+        if size <= cap:
+            return
+        # Truncating BYTES can land mid-character; decoding with "ignore" drops
+        # that partial character, which is exactly the last one that does NOT fit.
+        fits = title.encode("utf-8")[:cap].decode("utf-8", "ignore")
+        over = title[len(fits):]
+        ctx = self._TITLE_CUT_CONTEXT
+        left = ("…" if len(fits) > ctx else "") + fits[-ctx:]
+        right = over[:ctx] + ("…" if len(over) > ctx else "")
+        raise TooLarge(
+            f"title is {size}B > MEMGRES_MAX_TITLE_BYTES {cap}: "
+            f"{len(title)} chars, {len(fits)} fit, drop {len(over)} — "
+            f"{left}[✂]{right}")
 
     def _create(self, ns, author, body, path, tags, source, reason,
                 title=None, valid_at=None) -> Memory:
@@ -853,7 +946,9 @@ class Store:
                 raise Conflict(f"stale replace: base {base_hash[:12]} != current {cur_hash[:12]}")
             count = cur_body.count(old)
             if count == 0:
-                raise ReplaceNotFound(f"replace text not found in body: {old[:60]!r}")
+                raise ReplaceNotFound(
+                    f"replace text not found in body: {old[:60]!r}"
+                    f"{_why_replace_missed(cur_body, old)}")
             if count > 1 and not replace_all:
                 raise AmbiguousReplace(
                     f"replace text occurs {count}× — pass replace_all, or add "

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

@@ -66,6 +66,12 @@ class Hit:
     # set by a backend's grouped search: the (start, end) char offsets of the
     # winning chunk, so attach_snippets slices the snippet with no re-embedding.
     chunk_span: Optional[Tuple[int, int]] = None
+    # When the memory was last changed. Carried because recall is where staleness
+    # is decided: a caller picks which hit to read from the ranked list, and
+    # without a date the choice is made on wording alone. Every other read
+    # (`get`, `list`, `history`) already says when — this was the one that did
+    # not, and it is the one that ranks.
+    updated_at: object = None
 
     def to_recall_dict(self) -> dict:
         """The recall wire shape — one definition, so the HTTP and MCP layers
@@ -74,6 +80,10 @@ class Hit:
         return {"id": self.id, "title": self.title, "tags": self.tags,
                 "path": self.path, "score": self.score, "snippet": self.snippet,
                 "kind": self.kind, "lines": self.lines,
+                # str() rather than a datetime: the MCP layer needs plain
+                # strings, and FastAPI passes a string through unchanged, so one
+                # shape serves both transports.
+                "updated_at": str(self.updated_at) if self.updated_at else None,
                 "space_id": self.namespace, "space": self.space}
 
 
@@ -86,13 +96,13 @@ def _vec_literal(vec: Sequence[float]) -> str:
 # definition so lexical and both chunk backends SELECT the same set and adding a
 # field is one edit. When a backend ranks in SQL and appends its score column
 # AFTER these, the score is row[len(HIT_COLUMNS)].
-HIT_COLUMNS = "id, body, tags, path::text, title, namespace"
+HIT_COLUMNS = "id, body, tags, path::text, title, namespace, updated_at"
 
 
 def row_to_hit(row, score: float) -> "Hit":
     """Build a Hit from a (HIT_COLUMNS) row plus a separately-supplied score."""
     return Hit(str(row[0]), row[1], list(row[2]), row[3], float(score),
-               title=row[4], namespace=str(row[5]))
+               title=row[4], namespace=str(row[5]), updated_at=row[6])
 
 
 def as_namespaces(ns) -> List[str]:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memgres
-Version: 0.12.1
+Version: 0.12.3
 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.1 → memgres-0.12.3}/tests/test_require_title.py

@@ -26,7 +26,7 @@ psycopg = pytest.importorskip("psycopg")
 
 from memgres.config import load  # noqa: E402
 from memgres.schema import migrate  # noqa: E402
-from memgres.store import MissingTitle, Store  # noqa: E402
+from memgres.store import MissingTitle, Store, TooLarge  # noqa: E402
 
 DSN = os.environ.get("MEMGRES_TEST_DSN",
                      "postgresql://memgres:memgres@localhost:55432/memgres")
@@ -181,3 +181,36 @@ def test_a_create_with_no_body_blames_the_body(conn, monkeypatch):
     s = _store(conn, monkeypatch, True)
     with pytest.raises(ValueError, match="needs a body"):
         s.write(path="a.b")
+
+
+# ─── the size ceiling explains itself ────────────────────────────────────────
+def test_an_oversized_title_shows_where_it_stops_fitting(conn, monkeypatch):
+    """The ceiling counts bytes, the author counts characters, and in UTF-8 the
+    rate depends on the script — so a refusal naming only bytes leaves them
+    trimming blind. The message quotes the cut: what fits, what has to go."""
+    monkeypatch.setenv("MEMGRES_MAX_TITLE_BYTES", "40")
+    s = _store(conn, monkeypatch, True)
+    title = "Лимит заголовка меряется в байтах, а не в символах"
+    with pytest.raises(TooLarge) as e:
+        s.write(body="one", path="a.b", title=title)
+    msg = str(e.value)
+    # counts in BOTH units, and how much to drop
+    assert f"{len(title.encode())}B" in msg and "40" in msg
+    assert f"{len(title)} chars" in msg
+    # the cut is quoted, and the two sides really are the two sides
+    assert "[✂]" in msg
+    fits = title.encode()[:40].decode("utf-8", "ignore")
+    assert f"{len(fits)} fit" in msg
+    assert f"drop {len(title) - len(fits)}" in msg
+    assert fits[-10:] + "[✂]" in msg          # left of the cut survives
+    assert "[✂]" + title[len(fits):][:10] in msg   # right of it is what to drop
+
+
+def test_a_title_that_only_just_fits_is_accepted(conn, monkeypatch):
+    """The boundary itself is not an error — byte_len == cap must pass, or the
+    limit silently means one byte less than it says."""
+    monkeypatch.setenv("MEMGRES_MAX_TITLE_BYTES", "40")
+    s = _store(conn, monkeypatch, True)
+    title = "я" * 20                      # exactly 40 bytes
+    assert len(title.encode()) == 40
+    assert s.write(body="one", path="a.b", title=title).title == title

{memgres-0.12.1 → memgres-0.12.3}/tests/test_required_fields.py

@@ -166,6 +166,26 @@ def test_a_read_claims_no_provenance(conn, monkeypatch):
         "первый источник", "второй источник"]
 
 
+def test_a_read_does_not_even_carry_the_keys(conn, monkeypatch):
+    """`"source": null` on a read does not say "no such field here" — it reads as
+    "the value was there and is gone". Two readers concluded exactly that and went
+    hunting for a bug that did not exist; one spent a day on it. So a read omits
+    the keys outright, and the question belongs to `history`/`blame`."""
+    s = _store(conn, monkeypatch, "")
+    s.write(body="один", path="a.b", title="A", source="источник")
+    d = s.get(None, at="a.b").to_dict(stringify_dates=True)
+    assert "source" not in d and "valid_at" not in d
+
+
+def test_a_write_carries_them_even_when_empty(conn, monkeypatch):
+    """The other half: on a write the keys are always there, because a required
+    field the answer does not confirm is one whose absence nobody notices. Null
+    here means "you sent nothing", which is exactly what the writer must see."""
+    s = _store(conn, monkeypatch, "")
+    d = s.write(body="один", path="a.b", title="A").to_dict(stringify_dates=True)
+    assert d["source"] is None and d["valid_at"] is None
+
+
 # ─── the edit counter ────────────────────────────────────────────────────────
 def test_edits_count_revisions_after_the_creation(conn, monkeypatch):
     s = _store(conn, monkeypatch, "")

{memgres-0.12.1 → memgres-0.12.3}/tests/test_store_integration.py

@@ -230,6 +230,38 @@ def test_replace_not_found_leaves_record_untouched(store):
     assert again.body == "alpha\nbeta\n" and again.seq == 1
 
 
+def test_a_missed_replace_says_the_quote_crossed_a_line_break(store):
+    """The commonest miss: the body wraps, the phrase reads as one line on
+    screen, and the quote comes back with a space where the record has \n. The
+    refusal has to name that, or the author goes re-reading the whole record."""
+    store.write(body="хвост ниши по деньгам — перепродажа\nExa через x402\n",
+                path="a.b", title="A")
+    with pytest.raises(ReplaceNotFound) as e:
+        store.write(at="a.b", replace=("перепродажа Exa", "перепродажа Exa Search"))
+    msg = str(e.value)
+    assert "whitespace differs" in msg and "memory_get" in msg
+
+
+def test_a_missed_replace_shows_where_the_quote_parts_from_the_body(store):
+    """When it is not whitespace, the useful answer is the point of divergence
+    and what the body actually says there."""
+    store.write(body="верх ниши — **«rail dead»** значит другое\n",
+                path="a.c", title="A")
+    with pytest.raises(ReplaceNotFound) as e:
+        store.write(at="a.c", replace=("верх ниши — «rail dead»", "x"))
+    msg = str(e.value)
+    assert "chars match" in msg and "«rail dead»**" in msg
+
+
+def test_a_replace_of_something_absent_says_so_plainly(store):
+    """No prefix at all is a different mistake — wrong record, or a quote written
+    from memory — and must not be dressed up as a near miss."""
+    store.write(body="alpha\nbeta\n", path="a.d", title="A")
+    with pytest.raises(ReplaceNotFound) as e:
+        store.write(at="a.d", replace=("zzz", "x"))
+    assert "not one character" in str(e.value)
+
+
 def test_replace_ambiguous_requires_all_or_context(store):
     m = store.write(body="x x x\n")
     with pytest.raises(AmbiguousReplace):
@@ -362,6 +394,17 @@ def test_the_light_pass_returns_no_text(store):
     assert row["snippet"] is None and row["title"] == "Fruit Notes"
 
 
+def test_a_recall_hit_says_when_the_memory_last_changed(store):
+    """Recall is where staleness is decided — the caller picks what to read from
+    the ranked list. Without a date that choice is made on wording alone, and a
+    fact from July reads exactly like one from yesterday."""
+    m = store.write(body="the body mentions apples\n", title="Fruit Notes",
+                    path="notes.fruit")
+    [hit] = store.recall(None, "fruit")
+    assert hit.updated_at is not None
+    assert hit.to_recall_dict()["updated_at"] == str(m.updated_at)
+
+
 def test_recall_respects_tag_filter(store):
     store.write(body="x\n", title="alpha report", tags=["keep"])
     store.write(body="y\n", title="alpha summary", tags=["drop"])