memgres 0.1.0__py3-none-any.whl

memgres/store.py

@@ -0,0 +1,402 @@
+"""The store: create / edit / move / read / forget a memory, with history.
+
+One memory = one mutable body plus metadata (`tags`, tree `path`, TTL). You
+change it by sending a whole new body **or** a unified diff; a diff must carry
+the `base_hash` it was cut against, so a stale diff is rejected with
+:class:`Conflict` (optimistic concurrency, the 409 an HTTP layer maps to).
+
+Every state change appends one hash-chained row to ``memory_history`` with
+`source`/`reason` provenance. ``forget`` hard-deletes the row and (by cascade)
+its whole history — real erasure, not a tombstone.
+
+Tree moves cascade: changing a node's `path` rewrites every descendant's path in
+one ``ltree`` update, so the subtree stays consistent. Search lives in
+``search.py``; this module owns mutation and retrieval-by-id.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+from typing import List, Optional, Sequence
+
+import psycopg
+
+from .config import Config
+from .diffing import apply_diff, byte_len, content_hash, make_diff
+from .embeddings import Embedder, get_embedder
+
+
+class Conflict(RuntimeError):
+    """base_hash didn't match the current body — re-read and retry (HTTP 409)."""
+
+
+class NotFound(KeyError):
+    """No such memory in this namespace."""
+
+
+class TooLarge(ValueError):
+    """A write or resulting body exceeds the configured ceiling."""
+
+
+class NoParent(ValueError):
+    """MEMGRES_REQUIRE_PARENT is on and the node's parent path doesn't exist."""
+
+
+@dataclass
+class Memory:
+    id: str
+    body: str
+    content_hash: str
+    tags: List[str]
+    path: Optional[str]
+    seq: int
+    created_at: object
+    updated_at: object
+    expires_at: object
+
+
+def _vec_literal(vec: Sequence[float]) -> str:
+    return "[" + ",".join(repr(float(x)) for x in vec) + "]"
+
+
+def _row_hash(prev: Optional[str], memory_id: str, seq: int, op: str,
+              diff: Optional[str], hash_after: Optional[str],
+              path_after: Optional[str], tags_after: Optional[Sequence[str]],
+              source: Optional[str], reason: Optional[str]) -> str:
+    h = hashlib.sha256()
+    parts = [prev or "", memory_id, str(seq), op, diff or "", hash_after or "",
+             path_after or "", ",".join(tags_after or []), source or "", reason or ""]
+    h.update("\x1f".join(parts).encode("utf-8"))
+    return h.hexdigest()
+
+
+class Store:
+    def __init__(self, cfg: Config, embedder: Optional[Embedder] = None,
+                 conn: Optional["psycopg.Connection"] = None):
+        self.cfg = cfg
+        self.embedder = embedder if embedder is not None else get_embedder(cfg)
+        self._own_conn = conn is None
+        self._conn = conn or psycopg.connect(cfg.database_url or "")
+        # Qdrant holds vectors out-of-band; pgvector keeps them in-row (default).
+        self._use_qdrant = (cfg.vector_backend == "qdrant" and self.embedder is not None)
+        self._qdrant = None
+        if self._use_qdrant:
+            from .qdrant_backend import QdrantIndex
+            self._qdrant = QdrantIndex(self.embedder.dim)
+
+    def close(self):
+        if self._own_conn:
+            self._conn.close()
+
+    # ─── namespace / ttl helpers ────────────────────────────────────────────
+    def _ns(self, token: Optional[str]) -> str:
+        if not self.cfg.namespaces_enabled:
+            return ""
+        if not token:
+            raise PermissionError("MEMGRES_NAMESPACES is on: a token is required")
+        return hashlib.sha256(token.encode("utf-8")).hexdigest()
+
+    def _expiry_sql(self, ttl_days: Optional[int]) -> str:
+        days = ttl_days if ttl_days is not None else self.cfg.retention_days
+        return "NULL" if not days or days <= 0 else f"now() + interval '{int(days)} days'"
+
+    def _check_parent(self, cur, ns: str, path: Optional[str]):
+        """When MEMGRES_REQUIRE_PARENT is on, a non-root node's parent path must
+        already exist as a memory. Root nodes (nlevel 1) have no parent to check."""
+        if not (self.cfg.require_parent and path):
+            return
+        cur.execute(
+            "SELECT nlevel(%s::ltree) > 1 AND NOT EXISTS ("
+            "  SELECT 1 FROM memory WHERE namespace=%s "
+            "  AND path = subpath(%s::ltree, 0, nlevel(%s::ltree)-1))",
+            (path, ns, path, path))
+        if cur.fetchone()[0]:
+            raise NoParent(f"parent of '{path}' does not exist "
+                           f"(MEMGRES_REQUIRE_PARENT is on)")
+
+    def _raw_vec(self, body: str) -> "Optional[list]":
+        if not self.embedder:
+            return None
+        return self.embedder.embed_documents([body])[0]
+
+    def _embed(self, body: str) -> Optional[str]:
+        """pgvector literal for the in-row embedding column. Returns None when
+        embeddings are off OR vectors live in Qdrant (out-of-band)."""
+        if not self.embedder or self._use_qdrant:
+            return None
+        return _vec_literal(self.embedder.embed_documents([body])[0])
+
+    # ─── write: create, replace, diff, move, retag (one entrypoint) ─────────
+    def write(self, token: Optional[str] = None, *, id: Optional[str] = None,
+              body: Optional[str] = None, diff: Optional[str] = None,
+              base_hash: Optional[str] = None, path: Optional[str] = None,
+              tags: Optional[Sequence[str]] = None, source: Optional[str] = None,
+              reason: Optional[str] = None, ttl_days: Optional[int] = None) -> Memory:
+        ns = self._ns(token)
+        with self._conn.transaction():
+            if id is None:
+                return self._create(ns, body, path, tags, source, reason, ttl_days)
+            return self._update(ns, id, body, diff, base_hash, path, tags,
+                                source, reason, ttl_days)
+
+    def _check_write_size(self, payload: Optional[str]):
+        if payload is not None and byte_len(payload) > self.cfg.max_write_bytes:
+            raise TooLarge(
+                f"write is {byte_len(payload)}B > MEMGRES_MAX_WRITE_BYTES "
+                f"{self.cfg.max_write_bytes}")
+
+    def _check_body_size(self, body: str):
+        if byte_len(body) > self.cfg.max_body_bytes:
+            raise TooLarge(
+                f"body would be {byte_len(body)}B > MEMGRES_MAX_BODY_BYTES "
+                f"{self.cfg.max_body_bytes}")
+
+    def _create(self, ns, body, path, tags, source, reason, ttl_days) -> Memory:
+        if body is None:
+            raise ValueError("create needs a body (diffs apply to an existing memory)")
+        self._check_write_size(body)
+        self._check_body_size(body)
+        chash = content_hash(body)
+        tags = list(tags or [])
+        cur = self._conn.cursor()
+        self._check_parent(cur, ns, path)
+        emb = self._embed(body)
+        emb_col = ", embedding" if emb else ""
+        emb_val = ", %s::vector" if emb else ""
+        params = [ns, body, chash, tags, path, self.cfg.fts_language, body]
+        if emb:
+            params.append(emb)
+        cur.execute(
+            f"""INSERT INTO memory (namespace, body, content_hash, tags, path, fts{emb_col},
+                    seq, expires_at)
+                VALUES (%s, %s, %s, %s, %s::ltree,
+                        to_tsvector(%s::regconfig, %s){emb_val},
+                        1, {self._expiry_sql(ttl_days)})
+                RETURNING id, created_at, updated_at, expires_at""",
+            params,
+        )
+        mid, created, updated, expires = cur.fetchone()
+        if self._use_qdrant:
+            self._qdrant.upsert(str(mid), self._raw_vec(body), ns)
+        # store create as a diff-from-empty so the whole history is a self-contained
+        # chain (empty → current), replayable forward for reconstruct/annotate.
+        self._append_history(str(mid), 1, "create", make_diff("", body), None, chash,
+                             None, path, None, tags, source, reason)
+        return Memory(str(mid), body, chash, tags, path, 1, created, updated, expires)
+
+    def _load(self, cur, ns, id) -> tuple:
+        cur.execute(
+            "SELECT body, content_hash, tags, path::text, seq FROM memory "
+            "WHERE id=%s AND namespace=%s FOR UPDATE", (id, ns))
+        row = cur.fetchone()
+        if row is None:
+            raise NotFound(id)
+        return row  # body, content_hash, tags, path, seq
+
+    def _update(self, ns, id, body, diff, base_hash, path, tags,
+                source, reason, ttl_days) -> Memory:
+        cur = self._conn.cursor()
+        cur_body, cur_hash, cur_tags, cur_path, seq = self._load(cur, ns, id)
+
+        # decide the new body
+        if diff is not None:
+            if base_hash is None:
+                raise ValueError("a diff must carry base_hash (the body it was cut from)")
+            if base_hash != cur_hash:
+                raise Conflict(f"stale diff: base {base_hash[:12]} != current {cur_hash[:12]}")
+            self._check_write_size(diff)
+            new_body = apply_diff(cur_body, diff)
+            op = "diff"
+        elif body is not None:
+            if base_hash is not None and base_hash != cur_hash:
+                raise Conflict(f"stale replace: base {base_hash[:12]} != current {cur_hash[:12]}")
+            self._check_write_size(body)
+            new_body = body
+            op = "replace"
+        else:
+            new_body = cur_body           # metadata-only
+            op = None
+
+        new_hash = content_hash(new_body)
+        new_path = path if path is not None else cur_path
+        new_tags = list(tags) if tags is not None else list(cur_tags)
+        body_changed = new_hash != cur_hash
+        path_changed = new_path != cur_path
+        tags_changed = new_tags != list(cur_tags)
+
+        if op is None:  # nothing content-y: classify the metadata change
+            if path_changed:
+                op = "move"
+            elif tags_changed:
+                op = "retag"
+            else:
+                # pure touch: renew TTL, no history row
+                cur.execute(
+                    f"UPDATE memory SET updated_at=now(), expires_at={self._expiry_sql(ttl_days)} "
+                    "WHERE id=%s", (id,))
+                return self.get(None, id, _ns=ns, renew=False)
+
+        if body_changed:
+            self._check_body_size(new_body)
+
+        if path_changed:
+            self._check_parent(cur, ns, new_path)
+
+        # a path change cascades to the whole subtree (keep ltree consistent)
+        if path_changed and cur_path is not None:
+            cur.execute(
+                "UPDATE memory SET path = %s::ltree || subpath(path, nlevel(%s::ltree)) "
+                "WHERE namespace=%s AND path <@ %s::ltree AND id <> %s",
+                (new_path, cur_path, ns, cur_path, id))
+
+        emb = self._embed(new_body) if body_changed else None
+        set_embedding = ", embedding=%s::vector" if emb else ""
+        params = [new_body, new_hash, new_tags, new_path,
+                  self.cfg.fts_language, new_body]
+        if emb:
+            params.append(emb)
+        params.append(id)
+        cur.execute(
+            f"""UPDATE memory SET body=%s, content_hash=%s, tags=%s, path=%s::ltree,
+                    fts=to_tsvector(%s::regconfig, %s){set_embedding},
+                    seq=seq+1, updated_at=now(), expires_at={self._expiry_sql(ttl_days)}
+                WHERE id=%s
+                RETURNING seq, created_at, updated_at, expires_at""",
+            params)
+        new_seq, created, updated, expires = cur.fetchone()
+        if self._use_qdrant and body_changed:
+            self._qdrant.upsert(str(id), self._raw_vec(new_body), ns)
+        # store the canonical diff (recomputed) even for a whole-body replace, so
+        # every body change is line-attributable and the chain stays replayable.
+        stored_diff = make_diff(cur_body, new_body) if body_changed else None
+        self._append_history(str(id), new_seq, op, stored_diff,
+                             cur_hash, new_hash,
+                             cur_path if path_changed else None,
+                             new_path if path_changed else None,
+                             list(cur_tags) if tags_changed else None,
+                             new_tags if tags_changed else None,
+                             source, reason)
+        return Memory(str(id), new_body, new_hash, new_tags, new_path, new_seq,
+                      created, updated, expires)
+
+    def _append_history(self, memory_id, seq, op, diff, hash_before, hash_after,
+                        path_before, path_after, tags_before, tags_after,
+                        source, reason):
+        cur = self._conn.cursor()
+        cur.execute("SELECT row_hash FROM memory_history WHERE memory_id=%s "
+                    "ORDER BY seq DESC LIMIT 1", (memory_id,))
+        prev = cur.fetchone()
+        prev_hash = prev[0] if prev else None
+        rhash = _row_hash(prev_hash, memory_id, seq, op, diff, hash_after,
+                          path_after, tags_after, source, reason)
+        cur.execute(
+            """INSERT INTO memory_history (memory_id, seq, op, diff, hash_before,
+                   hash_after, path_before, path_after, tags_before, tags_after,
+                   source, reason, prev_row_hash, row_hash)
+               VALUES (%s,%s,%s,%s,%s,%s,%s::ltree,%s::ltree,%s,%s,%s,%s,%s,%s)""",
+            (memory_id, seq, op, diff, hash_before, hash_after, path_before,
+             path_after, tags_before, tags_after, source, reason, prev_hash, rhash))
+
+    # ─── recall: lexical / semantic / hybrid ────────────────────────────────
+    def recall(self, token: Optional[str], query: str, *, k: int = 10,
+               tags: Optional[Sequence[str]] = None,
+               path_prefix: Optional[str] = None, mode: str = "auto"):
+        from .search import recall as _recall
+        return _recall(self._conn, self.cfg, self.embedder, self._ns(token),
+                       query, k=k, tags=tags, path_prefix=path_prefix, mode=mode,
+                       qdrant=self._qdrant)
+
+    # ─── convenience: move ──────────────────────────────────────────────────
+    def move(self, token: Optional[str], id: str, new_path: str,
+             *, source: Optional[str] = None, reason: Optional[str] = None) -> Memory:
+        return self.write(token, id=id, path=new_path, source=source, reason=reason)
+
+    # ─── read ───────────────────────────────────────────────────────────────
+    def get(self, token: Optional[str], id: str, *, renew: bool = True,
+            _ns: Optional[str] = None) -> Memory:
+        ns = _ns if _ns is not None else self._ns(token)
+        cur = self._conn.cursor()
+        cur.execute(
+            "SELECT id, body, content_hash, tags, path::text, seq, created_at, "
+            "updated_at, expires_at FROM memory WHERE id=%s AND namespace=%s",
+            (id, ns))
+        row = cur.fetchone()
+        if row is None:
+            raise NotFound(id)
+        if renew and self.cfg.renew_on_read and self.cfg.retention_days > 0:
+            with self._conn.transaction():
+                cur.execute(
+                    f"UPDATE memory SET expires_at={self._expiry_sql(None)} WHERE id=%s",
+                    (id,))
+        return Memory(str(row[0]), row[1], row[2], list(row[3]), row[4], row[5],
+                      row[6], row[7], row[8])
+
+    def history(self, token: Optional[str], id: str) -> List[dict]:
+        ns = self._ns(token)
+        cur = self._conn.cursor()
+        cur.execute("SELECT 1 FROM memory WHERE id=%s AND namespace=%s", (id, ns))
+        if cur.fetchone() is None:
+            raise NotFound(id)
+        cur.execute(
+            "SELECT seq, op, diff, hash_before, hash_after, path_before::text, "
+            "path_after::text, tags_before, tags_after, source, reason, "
+            "prev_row_hash, row_hash, created_at FROM memory_history "
+            "WHERE memory_id=%s ORDER BY seq", (id,))
+        cols = ["seq", "op", "diff", "hash_before", "hash_after", "path_before",
+                "path_after", "tags_before", "tags_after", "source", "reason",
+                "prev_row_hash", "row_hash", "created_at"]
+        return [dict(zip(cols, r)) for r in cur.fetchall()]
+
+    def annotate(self, token: Optional[str], id: str,
+                 upto_seq: Optional[int] = None,
+                 lines: Optional[Sequence[int]] = None) -> List[dict]:
+        """Blame: the body with each line tagged by who last changed it. Pass
+        `lines` (1-based line numbers) to return only those lines."""
+        from .blame import annotate as _annotate
+        return _annotate(self.history(token, id), upto_seq, lines)
+
+    def annotate_grouped(self, token: Optional[str], id: str,
+                         upto_seq: Optional[int] = None,
+                         include_text: bool = True) -> List[dict]:
+        """Blame as runs: consecutive same-author lines collapse into one block.
+        `include_text=False` returns a pure ownership map (ranges, no body)."""
+        from .blame import annotate_grouped as _grouped
+        return _grouped(self.history(token, id), upto_seq, include_text)
+
+    def reconstruct(self, token: Optional[str], id: str,
+                    upto_seq: Optional[int] = None) -> str:
+        """The exact body text at a past version (default current)."""
+        from .blame import reconstruct as _reconstruct
+        return _reconstruct(self.history(token, id), upto_seq)
+
+    def verify_history(self, token: Optional[str], id: str) -> bool:
+        """Recompute the chain; True if untampered."""
+        rows = self.history(token, id)
+        prev = None
+        for r in rows:
+            expect = _row_hash(prev, id, r["seq"], r["op"], r["diff"],
+                               r["hash_after"], r["path_after"], r["tags_after"],
+                               r["source"], r["reason"])
+            if expect != r["row_hash"] or (r["prev_row_hash"] or None) != prev:
+                return False
+            prev = r["row_hash"]
+        return True
+
+    # ─── forget: real erasure ───────────────────────────────────────────────
+    def forget(self, token: Optional[str], id: str) -> bool:
+        ns = self._ns(token)
+        with self._conn.transaction():
+            cur = self._conn.cursor()
+            cur.execute("DELETE FROM memory WHERE id=%s AND namespace=%s", (id, ns))
+            deleted = cur.rowcount > 0
+        if deleted and self._use_qdrant:
+            self._qdrant.delete(id)      # drop the out-of-band vector too
+        return deleted
+
+    def purge_expired(self) -> int:
+        with self._conn.transaction():
+            cur = self._conn.cursor()
+            cur.execute("DELETE FROM memory WHERE expires_at IS NOT NULL "
+                        "AND expires_at < now()")
+            return cur.rowcount

memgres-0.1.0.dist-info/METADATA

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: memgres
+Version: 0.1.0
+Summary: Drop-in memory for AI agents: one Postgres, lexical + semantic recall, diff-versioned history, GDPR-erasable.
+Author: mozgsml
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mozgsml/memgres
+Project-URL: Repository, https://github.com/mozgsml/memgres
+Project-URL: Issues, https://github.com/mozgsml/memgres/issues
+Keywords: agent,memory,postgres,pgvector,qdrant,embeddings,semantic-search,llm,mcp,rag
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: psycopg[binary]>=3.1
+Provides-Extra: local
+Requires-Dist: sentence-transformers>=3.0; extra == "local"
+Provides-Extra: qdrant
+Requires-Dist: qdrant-client>=1.7; extra == "qdrant"
+Provides-Extra: server
+Requires-Dist: fastapi>=0.110; extra == "server"
+Requires-Dist: uvicorn>=0.29; extra == "server"
+Requires-Dist: psycopg-pool>=3.2; extra == "server"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# memgres
+
+[![CI](https://github.com/mozgsml/memgres/actions/workflows/ci.yml/badge.svg)](https://github.com/mozgsml/memgres/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**Versioned document memory for AI agents — one Postgres, lexical *or* semantic recall, diff-based history, GDPR-erasable.**
+
+> Status: early. Core library, search, HTTP API and MCP server are implemented and tested against a live pgvector Postgres.
+
+memgres is a lightweight, drop-in memory layer — a Python library plus an optional HTTP/MCP service — backed by a single PostgreSQL database. You store **documents** (bodies of text an agent owns and edits), not facts an LLM guessed at. Every change is an authored diff with provenance, kept in a tamper-evident history that you can still delete when the law says you must.
+
+---
+
+## Why memgres exists
+
+memgres is a **document** store where **you** own the write path — not a fact store that lets a model decide what to remember for you.
+
+- You write the **whole body** or a **unified diff** — nothing re-interprets your text on the way in.
+- Concurrency is guarded by **content hash** (optimistic locking): you send the hash of the body you edited; the write applies only if the current body still matches, otherwise you get a `409` and re-read. No lost updates, no silent overwrites.
+- Every change is stored as a **hash-chained unified diff** with `source`/`reason` provenance — git-like history you can replay and attribute line by line.
+- **History rows are deletable**: real GDPR erasure, not "hidden from results but still on disk".
+
+Reach for memgres when you want **auditable, authored, versioned text memory**.
+
+---
+
+## Advantages
+
+| Advantage | Why it matters |
+|---|---|
+| **No LLM on the write path** | Writes are instant and free; nothing invents, summarizes, or drops your content behind your back. |
+| **Authored unified-diff writes** | You control exactly what changes; the diff *is* the audit record. |
+| **Content-hash optimistic concurrency (409)** | Concurrent writers can't silently clobber each other — a stale write is rejected, not merged blind. |
+| **Postgres on disk** | The corpus can far exceed RAM, and concurrent writes are safe — no in-memory bound, no single-writer lock. |
+| **Hash-chained, GDPR-deletable history** | Tamper-evident provenance you can *still* erase: `forget()` hard-deletes the row, its vectors, and crypto-shreds the chain — no ["ghost vectors" left reconstructible in the index](https://arxiv.org/pdf/2606.18497). |
+| **Lexical works with zero embeddings** | Deploy with no model, no API, no GPU — Postgres full-text search out of the box. Turn on semantic recall only when you want it. |
+| **Lexical *and* semantic (hybrid)** | Exact identifiers/codes go to lexical (where [dense retrieval alone stumbles](https://tianpan.co/blog/2026-04-12-hybrid-search-production-bm25-dense-embeddings)); meaning-based queries go to vectors; hybrid fuses both with RRF. |
+| **Embedding-model safety by construction** | The model id + dimension are stamped into the schema; a mismatch **hard-fails** instead of silently returning garbage. |
+| **TTL renewed on read** | Active memory persists because it's used; abandoned memory expires itself. Storage self-cleans instead of growing forever. |
+| **Optional token namespaces** | Multi-tenant isolation when you need it (secret token → namespace); nothing to configure for single-user. |
+| **Fast subtree recall via `ltree`** | Memories form a real tree; `path <@ 'a.b'` pulls a whole subtree in one GiST index scan, no recursive walk that degrades with depth. |
+| **Git-blame + version reconstruct** | Every line carries who last changed it (grouped into author-blocks); any past version reconstructs from history — no replaying diffs yourself. |
+| **One Postgres, one backup** | The whole thing is `pg_dump`-able; the vector index rebuilds from the source of truth. No second datastore to run or back up. |
+| **Drop-in module, not a framework** | `pip install`, or `docker compose up`, or point at your own Postgres. No platform to adopt. |
+
+---
+
+## Design at a glance
+
+```
+memgres (core library, no HTTP dependency)
+  ├─ store        write (whole body OR unified diff) · get · recall · move · forget
+  ├─ diffing      unified diff make/apply + content hash (optimistic locking)
+  ├─ blame        line-attributed document + reconstruct any past version
+  ├─ organize     tags (text[] + GIN) · tree (ltree path + GiST, fast subtree select)
+  ├─ search       lexical (Postgres FTS)  +  semantic (pgvector or Qdrant)  +  hybrid
+  ├─ embeddings   provider via env: none | local (sentence-transformers) | cloud (Jina/OpenAI)
+  └─ config       every limit via env (body/write size, TTL, namespaces, …)
+
+optional layers on top of the same core:
+  ├─ HTTP API (FastAPI)   REST + OpenAPI
+  └─ MCP server           write/recall/get/blame/move/forget as MCP tools
+```
+
+**Record model:** one memory = one mutable body (up to a configurable ceiling, default 256 KB) plus metadata — `tags` (cross-cutting labels, `text[]` + GIN), a `path` (its place in an `ltree` tree), timestamps, and per-diff provenance (`source`/`reason`, kept in history). A single write/diff is capped smaller (default 16 KB), so large bodies accrue over many authored diffs. **Organization is two orthogonal axes:** the tree is *where a memory lives* (one place, subtree-selectable); tags are *what it's about* (many, overlapping). Both filter either search — narrow a semantic query to a subtree, or list a tag across the tree.
+
+**Isolation:** optional token *namespaces* keep tenants from seeing each other's memories (namespace = hash of a secret token, so one wallet can back many clients). Encryption at rest is left to the deployment — Postgres/managed-PG/disk TDE stays transparent to queries, so search keeps working; memgres deliberately does **not** encrypt bodies application-side (that would make them unsearchable, which is why no comparable tool does it either). GDPR erasure is real: `forget()` hard-deletes the row, its vectors, and crypto-shreds the history chain. All limits are env-configurable, so the same code serves a single-user embed and a capped multi-tenant service.
+
+---
+
+## Quickstart
+
+**The whole thing, one command** — brings up `pgvector` + the memgres service on `http://localhost:8080`, schema auto-migrated on startup:
+
+```bash
+docker compose up            # → http://localhost:8080  (GET /healthz → {"ok":true})
+```
+
+```bash
+# create a memory
+curl -sX POST localhost:8080/memories \
+  -H 'content-type: application/json' \
+  -d '{"body":"Postgres tuning notes\nshared_buffers = 25% RAM\n","tags":["db"],"path":"ops.postgres","source":"me"}'
+# → {"id":"…","content_hash":"…","seq":1, …}
+
+# recall (lexical out of the box; semantic once you set an embedding provider)
+curl -s 'localhost:8080/recall?q=postgres%20tuning'
+
+# edit by unified diff, guarded by the hash you edited (409 if stale)
+curl -sX PATCH localhost:8080/memories/$ID \
+  -H 'content-type: application/json' \
+  -d '{"diff":"--- \n+++ \n@@ -2 +2 @@\n-shared_buffers = 25% RAM\n+shared_buffers = 40% RAM\n","base_hash":"'$HASH'","source":"me","reason":"bump"}'
+
+# who wrote each line (grouped into author-blocks by default)
+curl -s localhost:8080/memories/$ID/blame
+```
+
+### As a Python library (no HTTP)
+
+```python
+from memgres import Store, load_config, migrate
+import psycopg
+
+cfg  = load_config()                       # reads MEMGRES_* env
+conn = psycopg.connect(cfg.database_url)
+migrate(conn, cfg)                         # idempotent; stamps embed model/dim
+
+s = Store(cfg, conn=conn)
+m = s.write(body="remember this\n", tags=["note"], path="misc.reminder", source="me")
+
+# edit: whole body OR a diff carrying the base hash (optimistic concurrency)
+m = s.write(id=m.id, body="remember this, updated\n", base_hash=m.content_hash, reason="tweak")
+
+hits  = s.recall(None, "what did I remember?", k=5)          # lexical / semantic / hybrid / auto
+blame = s.annotate_grouped(None, m.id)                        # [{start,end,source,reason,…}]
+old   = s.reconstruct(None, m.id, 1)                          # body as of version 1
+s.forget(None, m.id)                                          # hard-erase + history
+```
+
+### Install
+
+> Not on PyPI yet — install from git (or clone and `pip install -e .`):
+
+```bash
+pip install "git+https://github.com/mozgsml/memgres"            # core library
+pip install "memgres[server] @ git+https://github.com/mozgsml/memgres"   # + HTTP API
+pip install "memgres[mcp]   @ git+https://github.com/mozgsml/memgres"    # + MCP server
+# extras: local (sentence-transformers), qdrant (Qdrant backend)
+```
+
+Or pull the container image:
+
+```bash
+docker pull ghcr.io/mozgsml/memgres:latest
+```
+
+### Three ways to run it
+
+1. **`docker compose up`** — `pgvector` + service, nothing to configure. For a dedicated vector service instead, `docker compose --profile qdrant up` and set `MEMGRES_VECTOR_BACKEND=qdrant` (Qdrant ranks vectors; Postgres still holds bodies and does tag/subtree/TTL filtering).
+2. **Your own Postgres** — install the `[server]` extra (above), point `MEMGRES_DATABASE_URL` at it, run `memgres-server` (migrates on startup).
+3. **Embedded library** — install the core package, use `Store` directly, no HTTP at all.
+
+Semantic recall is optional: the default `MEMGRES_EMBED_PROVIDER=none` gives you lexical FTS with zero models. Turn on `local` (sentence-transformers), a cloud API (`openai`/`jina`), or any OpenAI-compatible server (LM Studio, Ollama, …) when you want meaning-based search — see [docs/BACKENDS.md](docs/BACKENDS.md) for copy-paste setups. The model id + dimension get stamped into the schema and a later mismatch hard-fails instead of silently returning garbage.
+
+## Configuration
+
+Everything is env, all optional (defaults suit a single-user embed). Full list in [`.env.example`](.env.example).
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `MEMGRES_DATABASE_URL` | libpq env | Postgres connection string |
+| `MEMGRES_MAX_BODY_BYTES` | `262144` | ceiling for a whole record body (256 KB) |
+| `MEMGRES_MAX_WRITE_BYTES` | `16384` | ceiling for one write/diff payload (≤ body) |
+| `MEMGRES_RETENTION_DAYS` | `0` | `0` = keep forever; `>0` = expire N days after last touch |
+| `MEMGRES_RENEW_ON_READ` | `true` | a read pushes the expiry clock forward |
+| `MEMGRES_NAMESPACES` | `false` | `true` = each caller sends a secret token; namespace = its hash |
+| `MEMGRES_TREE` | `true` | `ltree` path column + GiST index (fast subtree select) |
+| `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_FTS_LANGUAGE` | `simple` | Postgres FTS dictionary (`simple`/`english`/…) |
+| `MEMGRES_VECTOR_BACKEND` | `pgvector` | `pgvector` (same DB) or `qdrant` (set `QDRANT_URL`, `QDRANT_API_KEY`, `MEMGRES_QDRANT_COLLECTION`) |
+| `MEMGRES_EMBED_PROVIDER` | `none` | `none` / `local` / `openai` / `jina` / `openai-compatible` (LM Studio, Ollama, vLLM, TEI…) |
+| `MEMGRES_EMBED_MODEL` / `_DIM` / `_API_KEY` / `_API_BASE` | — | model id · dimension (HTTP providers require it, `local` infers) · token · server URL |
+
+## HTTP API
+
+| Method | Path | Purpose |
+|---|---|---|
+| `POST` | `/memories` | create |
+| `GET` | `/memories/{id}` | read (renews TTL) |
+| `PATCH` | `/memories/{id}` | edit: whole `body` **or** `diff`+`base_hash`; move; retag |
+| `POST` | `/memories/{id}/move` | reparent a node (cascades its subtree) |
+| `DELETE` | `/memories/{id}` | forget (hard-erase + history) |
+| `GET` | `/memories/{id}/history` | raw change chain |
+| `GET` | `/memories/{id}/blame` | line attribution; `?group`, `?text`, `?lines=1,3-5` |
+| `GET` | `/memories/{id}/at/{seq}` | body reconstructed at a version |
+| `GET` | `/recall` | `?q=&k=&mode=&tags=&path_prefix=` |
+| `GET` | `/healthz` | liveness |
+
+Namespace token (when `MEMGRES_NAMESPACES=true`) goes in `Authorization: Bearer <token>` or `X-Memgres-Token`. OpenAPI/Swagger is served at `/docs`. Store errors map to status codes: `409` stale-hash conflict, `404` not found, `413` too large, `401` missing token.
+
+## MCP server
+
+The same store is exposed to MCP clients (Claude Desktop, etc.) over stdio:
+
+```bash
+pip install "memgres[mcp] @ git+https://github.com/mozgsml/memgres"
+memgres-mcp                    # needs MEMGRES_DATABASE_URL; migrates on startup
+```
+
+Tools: `memory_write` (create or edit by body/diff), `memory_get`, `memory_recall`, `memory_blame`, `memory_history`, `memory_move`, `memory_forget`. Point your MCP client's config at the `memgres-mcp` command.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE). Fully self-hostable, no gated features.

memgres-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+memgres/__init__.py,sha256=dR2Y_pbU3YA63QlfgzHMN1o5P-cBZhjQ7i_CByvHGLI,1382
+memgres/blame.py,sha256=PvhSIaxRkvnoBCgx8GS3M2VrJfiBZCn2iKlOsuyP8c0,5623
+memgres/config.py,sha256=qwcIyUmkTQT4RRiOM19QuUmNJUA4ENMuqsl3SVbniWg,4679
+memgres/diffing.py,sha256=31_WFRSMeZzvTz9YeP9iCxWaSiV0ye9UF9Mi0XT78zg,4693
+memgres/embeddings.py,sha256=XkTmGR2XDlVf6nnkhedKVRkjTzNbqtgT9fYIywuhkD0,5990
+memgres/mcp_server.py,sha256=Xt7LufWFQ3jrapGWpV3zIk1RyD24RA_eicYVfsR8x9M,4566
+memgres/qdrant_backend.py,sha256=FLjYxd7QroU48HbNpHmOQzj5qVgLxF3ect2I-wNZrhQ,3417
+memgres/schema.py,sha256=BLctBO24eYoaSazi12SNhX9OspyhaRmFu266kDZp9yA,5201
+memgres/search.py,sha256=1nbC3pu-B6ns9PZvhJVniFAdKsu6uRXExpXMicuFFDM,5187
+memgres/server.py,sha256=_hRQ_0nYKV83vWdq49ORgghCkJo-JttAzelNov7GFCY,9165
+memgres/store.py,sha256=iGy4JdqlOHIU0HrulMJw-XuVYQ-p2M_iS_xcABovrqk,19149
+memgres/migrations/0001_core.sql,sha256=vJ951yh3z9ncxsh7IHUraIhwFioryRBscgUDVpcumIk,4452
+memgres-0.1.0.dist-info/licenses/LICENSE,sha256=dcR7Im4-m7tPgEJ89OAqe1Hz75X79H5JAntVATnKEb8,1079
+memgres-0.1.0.dist-info/METADATA,sha256=Hl2fDMDiypxiRRF3nHnKzSaIXrWHtL3wXmCnn5YaAFY,14214
+memgres-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+memgres-0.1.0.dist-info/entry_points.txt,sha256=5B59ZQnqTZpFl-kd4I8QDINvAhN9_0wGr7wuIebYLa8,93
+memgres-0.1.0.dist-info/top_level.txt,sha256=8qNyfB6IdNlUo4bRZnoRdfqKqJIYuByrdAMiKUDA2uY,8
+memgres-0.1.0.dist-info/RECORD,,

memgres-0.1.0.dist-info/WHEEL

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

memgres-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+memgres-mcp = memgres.mcp_server:main
+memgres-server = memgres.server:main