memgres 0.1.0__py3-none-any.whl

memgres/migrations/0001_core.sql

@@ -0,0 +1,72 @@
+-- memgres core schema (config-independent parts).
+--
+-- This file is always applied. Parts that depend on runtime config are added by
+-- memgres/schema.py after this runs:
+--   * ltree `path` column + GiST index      — only when MEMGRES_TREE=true
+--   * pgvector `embedding` column + HNSW     — only when embeddings are enabled
+--   * the meta row is stamped/verified there — hard-fail on model/dim drift
+--
+-- Nothing here needs a contrib extension: tags (text[]+GIN), FTS (tsvector+GIN)
+-- and gen_random_uuid() are all core Postgres (>=13). ltree/vector are pulled in
+-- conditionally by schema.py so a deployment without them still migrates.
+
+-- ─── one memory = one mutable body ───────────────────────────────────────────
+CREATE TABLE IF NOT EXISTS memory (
+    id            uuid        PRIMARY KEY DEFAULT gen_random_uuid(),
+    namespace     text        NOT NULL DEFAULT '',   -- '' = single space; else hash(token)
+    body          text        NOT NULL,
+    content_hash  text        NOT NULL,              -- sha256(body) hex; OCC + dedup
+    tags          text[]      NOT NULL DEFAULT '{}', -- cross-cutting labels
+    fts           tsvector,                          -- store fills with the configured dict
+    seq           integer     NOT NULL DEFAULT 0,    -- current version; == latest history.seq
+    created_at    timestamptz NOT NULL DEFAULT now(),
+    updated_at    timestamptz NOT NULL DEFAULT now(),
+    expires_at    timestamptz                        -- NULL = keep forever
+);
+
+CREATE INDEX IF NOT EXISTS memory_ns_idx      ON memory (namespace);
+CREATE INDEX IF NOT EXISTS memory_tags_idx    ON memory USING gin (tags);
+CREATE INDEX IF NOT EXISTS memory_fts_idx     ON memory USING gin (fts);
+CREATE INDEX IF NOT EXISTS memory_expires_idx ON memory (expires_at) WHERE expires_at IS NOT NULL;
+
+-- ─── hash-chained, deletable history (git-like provenance, GDPR-erasable) ─────
+-- Deleted with the memory (ON DELETE CASCADE) → real erasure, not "hidden".
+-- row_hash chains over the *history* rows so tampering is detectable; the chain
+-- is for audit, it does not prevent deletion (that is the whole point vs git).
+CREATE TABLE IF NOT EXISTS memory_history (
+    id            bigint      GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+    memory_id     uuid        NOT NULL REFERENCES memory(id) ON DELETE CASCADE,
+    seq           integer     NOT NULL,              -- 1,2,3… per memory
+    op            text        NOT NULL,              -- create|diff|replace|move|retag|delete
+    diff          text,                              -- unified diff of body (NULL = metadata-only)
+    hash_before   text,                              -- body content_hash before (NULL on create)
+    hash_after    text,                              -- body content_hash after  (NULL on delete)
+    path_before   text,                              -- ltree as text; records a move
+    path_after    text,
+    tags_before   text[],
+    tags_after    text[],
+    source        text,                              -- provenance: where this change came from
+    reason        text,                              -- provenance: why
+    prev_row_hash text,                              -- previous row_hash (NULL for seq=1)
+    row_hash      text        NOT NULL,              -- H(prev_row_hash‖memory_id‖seq‖op‖…)
+    created_at    timestamptz NOT NULL DEFAULT now(),
+    UNIQUE (memory_id, seq)
+);
+
+CREATE INDEX IF NOT EXISTS memory_history_mid_idx ON memory_history (memory_id, seq);
+
+-- ─── single-row meta: stamps what the collection was built with ──────────────
+-- schema.py verifies config against this and HARD-FAILS on drift (indexing with
+-- one embedding model and querying with another silently returns garbage —
+-- a documented silent-failure class this guard exists to prevent).
+CREATE TABLE IF NOT EXISTS memgres_meta (
+    only_row       boolean     PRIMARY KEY DEFAULT true CHECK (only_row),
+    schema_version integer     NOT NULL,
+    embed_provider text        NOT NULL,
+    embed_model    text        NOT NULL DEFAULT '',
+    embed_dim      integer     NOT NULL DEFAULT 0,
+    fts_language   text        NOT NULL,
+    tree_enabled   boolean     NOT NULL,
+    created_at     timestamptz NOT NULL DEFAULT now(),
+    updated_at     timestamptz NOT NULL DEFAULT now()
+);

memgres/qdrant_backend.py

@@ -0,0 +1,82 @@
+"""Optional Qdrant vector backend (MEMGRES_VECTOR_BACKEND=qdrant).
+
+pgvector keeps vectors in the same Postgres and is the default. Qdrant is for
+when you already run it or want a dedicated ANN service. The split of labor:
+
+  * Qdrant holds only the vector + the `namespace` (so ranking never crosses
+    tenants) and ranks by cosine similarity.
+  * Postgres remains the source of truth for bodies and for every other filter
+    (tags, subtree, expiry) — semantic recall ranks in Qdrant, then fetches and
+    filters the candidates in Postgres.
+
+So tag/tree/TTL changes never need to touch Qdrant — only a body change re-embeds
+(upsert) and `forget` deletes the point. Config for the connection:
+
+  QDRANT_URL (default http://localhost:6333) · QDRANT_API_KEY ·
+  MEMGRES_QDRANT_COLLECTION (default "memgres")
+
+Needs the `[qdrant]` extra (qdrant-client).
+"""
+
+from __future__ import annotations
+
+import os
+from typing import List, Optional, Sequence, Tuple
+
+
+class QdrantIndex:
+    def __init__(self, dim: int, url: Optional[str] = None,
+                 api_key: Optional[str] = None, collection: Optional[str] = None):
+        from qdrant_client import QdrantClient
+
+        self.dim = dim
+        self.collection = collection or os.environ.get("MEMGRES_QDRANT_COLLECTION", "memgres")
+        url = url or os.environ.get("QDRANT_URL", "http://localhost:6333")
+        api_key = api_key or os.environ.get("QDRANT_API_KEY") or None
+        self.client = QdrantClient(url=url, api_key=api_key)
+        self._ensure()
+
+    def _ensure(self) -> None:
+        from qdrant_client.models import Distance, VectorParams
+
+        if not self.client.collection_exists(self.collection):
+            self.client.create_collection(
+                self.collection,
+                vectors_config=VectorParams(size=self.dim, distance=Distance.COSINE),
+            )
+            return
+        info = self.client.get_collection(self.collection)
+        size = info.config.params.vectors.size
+        if size != self.dim:
+            from .schema import SchemaMismatch
+            raise SchemaMismatch(
+                f"Qdrant collection '{self.collection}' has dim {size}, model emits "
+                f"{self.dim} — re-embed into a fresh collection, don't mix models."
+            )
+
+    def upsert(self, id: str, vector: Sequence[float], namespace: str) -> None:
+        from qdrant_client.models import PointStruct
+
+        self.client.upsert(
+            self.collection,
+            points=[PointStruct(id=id, vector=list(vector),
+                                payload={"namespace": namespace})],
+        )
+
+    def delete(self, id: str) -> None:
+        from qdrant_client.models import PointIdsList
+
+        self.client.delete(self.collection, points_selector=PointIdsList(points=[id]))
+
+    def query(self, vector: Sequence[float], k: int,
+              namespace: str) -> List[Tuple[str, float]]:
+        """Top-k point ids by cosine similarity, scoped to one namespace."""
+        from qdrant_client.models import FieldCondition, Filter, MatchValue
+
+        flt = Filter(must=[FieldCondition(key="namespace",
+                                          match=MatchValue(value=namespace))])
+        res = self.client.query_points(
+            self.collection, query=list(vector), limit=k,
+            query_filter=flt, with_payload=False,
+        ).points
+        return [(str(p.id), float(p.score)) for p in res]

memgres/schema.py

@@ -0,0 +1,133 @@
+"""Apply the schema and reconcile it with the running config.
+
+`migrate(conn, cfg)` is idempotent: it applies the core SQL, then adds the
+config-dependent pieces (ltree tree, pgvector column) only when they're turned
+on, and finally *stamps* the collection with the embedding model/dim + FTS dict
+it was built with.
+
+The stamp is the safety rail. Indexing with one embedding model and querying
+with another returns meaningless results with no error — a silent-failure class
+we refuse to allow. On a mismatch `migrate` raises :class:`SchemaMismatch`
+instead of quietly corrupting recall.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .config import Config
+
+SCHEMA_VERSION = 1
+
+# Dev layout: repo/migrations next to the package. When packaged, migrations are
+# shipped inside the package (see pyproject) and this still resolves.
+_HERE = Path(__file__).resolve().parent
+for _cand in (_HERE / "migrations", _HERE.parent / "migrations"):
+    if _cand.is_dir():
+        MIGRATIONS_DIR = _cand
+        break
+else:  # pragma: no cover - packaging guarantees one of the above
+    MIGRATIONS_DIR = _HERE.parent / "migrations"
+
+
+class SchemaMismatch(RuntimeError):
+    """The DB was built with settings incompatible with the current config."""
+
+
+def _core_sql() -> str:
+    return (MIGRATIONS_DIR / "0001_core.sql").read_text(encoding="utf-8")
+
+
+def migrate(conn, cfg: Config) -> None:
+    """Bring the database at `conn` to the schema `cfg` describes.
+
+    `conn` is a psycopg connection. Runs in one transaction; raises
+    :class:`SchemaMismatch` (and rolls back) on an incompatible existing stamp.
+    """
+    with conn.transaction():
+        with conn.cursor() as cur:
+            cur.execute(_core_sql())
+            _apply_tree(cur, cfg)
+            _apply_vector(cur, cfg)
+            _stamp(cur, cfg)
+
+
+def _apply_tree(cur, cfg: Config) -> None:
+    if not cfg.tree_enabled:
+        return
+    cur.execute("CREATE EXTENSION IF NOT EXISTS ltree")
+    # Add the path column + its indexes only once; ALTER … ADD COLUMN IF NOT
+    # EXISTS keeps this idempotent across restarts.
+    cur.execute("ALTER TABLE memory ADD COLUMN IF NOT EXISTS path ltree")
+    cur.execute(
+        "CREATE INDEX IF NOT EXISTS memory_path_gist ON memory "
+        "USING gist (path) WHERE path IS NOT NULL"
+    )
+    # A path is a node's address: unique within a namespace when present.
+    cur.execute(
+        "CREATE UNIQUE INDEX IF NOT EXISTS memory_ns_path_uniq ON memory "
+        "(namespace, path) WHERE path IS NOT NULL"
+    )
+
+
+def _apply_vector(cur, cfg: Config) -> None:
+    if cfg.embed_provider == "none":
+        return
+    if cfg.vector_backend != "pgvector":
+        return  # qdrant holds vectors out-of-band; nothing to add here
+    if cfg.embed_dim <= 0:
+        # config.validate() already guards this; belt and suspenders.
+        raise SchemaMismatch("pgvector semantic search needs MEMGRES_EMBED_DIM > 0")
+    cur.execute("CREATE EXTENSION IF NOT EXISTS vector")
+    cur.execute(
+        f"ALTER TABLE memory ADD COLUMN IF NOT EXISTS embedding vector({cfg.embed_dim})"
+    )
+    cur.execute(
+        "CREATE INDEX IF NOT EXISTS memory_embedding_hnsw ON memory "
+        "USING hnsw (embedding vector_cosine_ops)"
+    )
+
+
+def _stamp(cur, cfg: Config) -> None:
+    """Insert the meta row, or verify the existing one and hard-fail on drift."""
+    cur.execute(
+        "SELECT embed_provider, embed_model, embed_dim, fts_language, tree_enabled "
+        "FROM memgres_meta WHERE only_row"
+    )
+    row = cur.fetchone()
+    if row is None:
+        cur.execute(
+            "INSERT INTO memgres_meta "
+            "(only_row, schema_version, embed_provider, embed_model, embed_dim, "
+            " fts_language, tree_enabled) VALUES (true, %s, %s, %s, %s, %s, %s)",
+            (SCHEMA_VERSION, cfg.embed_provider, cfg.embed_model, cfg.embed_dim,
+             cfg.fts_language, cfg.tree_enabled),
+        )
+        return
+
+    provider, model, dim, fts_lang, tree = row
+
+    if fts_lang != cfg.fts_language:
+        raise SchemaMismatch(
+            f"FTS dictionary changed: collection built with '{fts_lang}', config "
+            f"says '{cfg.fts_language}'. The stored tsvectors were computed with the "
+            f"old dictionary; recompute them (reindex) before switching."
+        )
+
+    # Embeddings: going none → enabled is fine (adopt the new stamp). But changing
+    # an *existing* model or dimension silently invalidates every stored vector.
+    had_vectors = dim > 0
+    if had_vectors and (model != cfg.embed_model or dim != cfg.embed_dim):
+        raise SchemaMismatch(
+            f"embedding model/dim changed: collection built with "
+            f"'{model}' (dim {dim}), config says '{cfg.embed_model}' (dim "
+            f"{cfg.embed_dim}). Existing vectors are meaningless under the new "
+            f"model — re-embed the corpus, don't mix models."
+        )
+
+    if not had_vectors and cfg.embed_provider != "none":
+        cur.execute(
+            "UPDATE memgres_meta SET embed_provider=%s, embed_model=%s, "
+            "embed_dim=%s, updated_at=now() WHERE only_row",
+            (cfg.embed_provider, cfg.embed_model, cfg.embed_dim),
+        )

memgres/search.py

@@ -0,0 +1,125 @@
+"""Recall: lexical (Postgres FTS), semantic (pgvector), or hybrid (RRF).
+
+All three share the same filters — namespace, tags (``@>`` contains-all), tree
+subtree (``path <@ prefix``), and not-expired — so you can scope any query to a
+branch of the tree or a set of tags. ``mode='auto'`` picks semantic when an
+embedder is configured, else lexical.
+
+Hybrid fuses the two ranked lists with Reciprocal Rank Fusion (RRF): exact
+identifiers that dense vectors fumble come in via lexical, meaning-based matches
+via vectors, and neither backend needs to know about the other.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Optional, Sequence
+
+RRF_K = 60  # standard RRF damping constant
+
+
+@dataclass
+class Hit:
+    id: str
+    body: str
+    tags: List[str]
+    path: Optional[str]
+    score: float
+
+
+def _filters(ns: str, tags: Optional[Sequence[str]], path_prefix: Optional[str]):
+    """Return (sql_fragment, params) for the shared WHERE tail."""
+    sql = ["namespace = %s", "(expires_at IS NULL OR expires_at > now())"]
+    params: list = [ns]
+    if tags:
+        sql.append("tags @> %s")           # row must contain all requested tags
+        params.append(list(tags))
+    if path_prefix:
+        sql.append("path <@ %s::ltree")     # subtree of the prefix
+        params.append(path_prefix)
+    return " AND ".join(sql), params
+
+
+def _lexical(conn, cfg, ns, query, k, tags, path_prefix) -> List[Hit]:
+    where, params = _filters(ns, tags, path_prefix)
+    sql = (
+        "SELECT id, body, tags, path::text, "
+        "ts_rank(fts, plainto_tsquery(%s::regconfig, %s)) AS score "
+        f"FROM memory WHERE {where} "
+        "AND fts @@ plainto_tsquery(%s::regconfig, %s) "
+        "ORDER BY score DESC LIMIT %s"
+    )
+    args = [cfg.fts_language, query] + params + [cfg.fts_language, query, k]
+    with conn.cursor() as cur:
+        cur.execute(sql, args)
+        return [Hit(str(r[0]), r[1], list(r[2]), r[3], float(r[4]))
+                for r in cur.fetchall()]
+
+
+def _semantic(conn, cfg, embedder, ns, query, k, tags, path_prefix, qdrant=None) -> List[Hit]:
+    if not embedder:
+        raise RuntimeError("semantic recall needs an embedder (MEMGRES_EMBED_PROVIDER)")
+    if qdrant is not None:
+        return _semantic_qdrant(conn, cfg, embedder, ns, query, k, tags, path_prefix, qdrant)
+    qv = "[" + ",".join(repr(float(x)) for x in embedder.embed_query(query)) + "]"
+    where, params = _filters(ns, tags, path_prefix)
+    sql = (
+        "SELECT id, body, tags, path::text, "
+        "1 - (embedding <=> %s::vector) AS score "
+        f"FROM memory WHERE {where} AND embedding IS NOT NULL "
+        "ORDER BY embedding <=> %s::vector ASC LIMIT %s"
+    )
+    args = [qv] + params + [qv, k]
+    with conn.cursor() as cur:
+        cur.execute(sql, args)
+        return [Hit(str(r[0]), r[1], list(r[2]), r[3], float(r[4]))
+                for r in cur.fetchall()]
+
+
+def _semantic_qdrant(conn, cfg, embedder, ns, query, k, tags, path_prefix, qdrant) -> List[Hit]:
+    """Rank in Qdrant (namespace-scoped), then fetch + filter bodies in Postgres.
+    Over-fetch when tag/subtree filters apply, since those are enforced in PG."""
+    qv = embedder.embed_query(query)
+    overfetch = k if not (tags or path_prefix) else min(max(k * 10, k), 500)
+    pairs = qdrant.query(qv, overfetch, ns)          # [(id, score)] cosine similarity
+    if not pairs:
+        return []
+    score = {pid: s for pid, s in pairs}
+    where, params = _filters(ns, tags, path_prefix)  # namespace, expiry, tags, subtree
+    sql = (f"SELECT id, body, tags, path::text FROM memory "
+           f"WHERE {where} AND id = ANY(%s)")
+    with conn.cursor() as cur:
+        cur.execute(sql, params + [list(score.keys())])
+        hits = [Hit(str(r[0]), r[1], list(r[2]), r[3], score[str(r[0])])
+                for r in cur.fetchall()]
+    hits.sort(key=lambda h: h.score, reverse=True)   # Qdrant order, minus PG-filtered
+    return hits[:k]
+
+
+def _rrf(lists: Sequence[List[Hit]], k: int) -> List[Hit]:
+    scores: dict = {}
+    keep: dict = {}
+    for hits in lists:
+        for rank, h in enumerate(hits):
+            scores[h.id] = scores.get(h.id, 0.0) + 1.0 / (RRF_K + rank + 1)
+            keep[h.id] = h
+    fused = sorted(keep.values(), key=lambda h: scores[h.id], reverse=True)
+    for h in fused:
+        h.score = scores[h.id]
+    return fused[:k]
+
+
+def recall(conn, cfg, embedder, ns: str, query: str, *, k: int = 10,
+           tags: Optional[Sequence[str]] = None, path_prefix: Optional[str] = None,
+           mode: str = "auto", qdrant=None) -> List[Hit]:
+    if mode == "auto":
+        mode = "semantic" if embedder else "lexical"
+    if mode == "lexical":
+        return _lexical(conn, cfg, ns, query, k, tags, path_prefix)
+    if mode == "semantic":
+        return _semantic(conn, cfg, embedder, ns, query, k, tags, path_prefix, qdrant)
+    if mode == "hybrid":
+        lex = _lexical(conn, cfg, ns, query, k, tags, path_prefix)
+        sem = _semantic(conn, cfg, embedder, ns, query, k, tags, path_prefix, qdrant)
+        return _rrf([sem, lex], k)
+    raise ValueError(f"unknown recall mode: {mode!r} (lexical|semantic|hybrid|auto)")

memgres/server.py

@@ -0,0 +1,222 @@
+"""Thin HTTP layer over the store (FastAPI).
+
+Deliberately a straight mapping from store operations to REST, so an auth or
+billing layer can wrap these routes without touching store logic:
+
+    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      convenience reparent
+    DELETE /memories/{id}           forget (hard-erase + history)
+    GET    /memories/{id}/history   provenance chain
+    GET    /recall                  lexical / semantic / hybrid recall
+    GET    /healthz                 liveness
+
+The namespace token (when MEMGRES_NAMESPACES is on) comes in as a bearer token or
+`X-Memgres-Token` header; recall/read are the cheap ops, writes the expensive ones
+— the natural place for per-route pricing/metering later.
+
+Concurrency: a psycopg_pool hands each request its own connection; the embedder
+is built once and shared. Requires the `[server]` extra (fastapi, uvicorn,
+psycopg_pool).
+"""
+
+from typing import List, Optional
+
+from .config import Config, load
+from .diffing import DiffConflict
+from .embeddings import get_embedder
+from .schema import migrate
+from .store import Conflict, NoParent, NotFound, Store, TooLarge
+
+
+def _parse_lines(spec: Optional[str]) -> Optional[List[int]]:
+    """Parse a line selector like '2' or '1,3-5' into [2] / [1,3,4,5]. None → all."""
+    if not spec:
+        return None
+    out: List[int] = []
+    for part in spec.split(","):
+        part = part.strip()
+        if not part:
+            continue
+        if "-" in part:
+            a, b = part.split("-", 1)
+            out.extend(range(int(a), int(b) + 1))
+        else:
+            out.append(int(part))
+    return out or None
+
+
+def create_app(cfg: Optional[Config] = None):
+    from contextlib import asynccontextmanager
+
+    from fastapi import Depends, FastAPI, Header, HTTPException, Query
+    from psycopg_pool import ConnectionPool
+    from pydantic import BaseModel
+
+    cfg = cfg or load()
+    embedder = get_embedder(cfg)
+    pool = ConnectionPool(cfg.database_url or "", min_size=1, open=False)
+
+    @asynccontextmanager
+    async def lifespan(app):
+        pool.open()
+        with pool.connection() as conn:
+            migrate(conn, cfg)          # idempotent; stamps embed model/dim
+        yield
+        pool.close()
+
+    app = FastAPI(title="memgres", version="0.1.0", lifespan=lifespan)
+
+    # ─── request bodies ─────────────────────────────────────────────────────
+    class CreateBody(BaseModel):
+        body: str
+        path: Optional[str] = None
+        tags: Optional[List[str]] = None
+        source: Optional[str] = None
+        reason: Optional[str] = None
+        ttl_days: Optional[int] = None
+
+    class EditBody(BaseModel):
+        body: Optional[str] = None
+        diff: Optional[str] = None
+        base_hash: Optional[str] = None
+        path: Optional[str] = None
+        tags: Optional[List[str]] = None
+        source: Optional[str] = None
+        reason: Optional[str] = None
+        ttl_days: Optional[int] = None
+
+    class MoveBody(BaseModel):
+        path: str
+        source: Optional[str] = None
+        reason: Optional[str] = None
+
+    # ─── auth: extract the namespace token ──────────────────────────────────
+    def token(authorization: Optional[str] = Header(None),
+              x_memgres_token: Optional[str] = Header(None)) -> Optional[str]:
+        tok = x_memgres_token
+        if not tok and authorization and authorization.lower().startswith("bearer "):
+            tok = authorization[7:]
+        if cfg.namespaces_enabled and not tok:
+            raise HTTPException(401, "namespace token required")
+        return tok
+
+    def _mem(m) -> dict:
+        return {"id": m.id, "content_hash": m.content_hash, "body": m.body,
+                "tags": m.tags, "path": m.path, "seq": m.seq,
+                "created_at": m.created_at, "updated_at": m.updated_at,
+                "expires_at": m.expires_at}
+
+    def _store(conn):
+        return Store(cfg, embedder=embedder, conn=conn)
+
+    def _guard(fn):
+        """Run a store call, mapping store exceptions to HTTP codes."""
+        try:
+            return fn()
+        except NotFound:
+            raise HTTPException(404, "not found")
+        except (Conflict, DiffConflict) as e:
+            raise HTTPException(409, str(e))
+        except NoParent as e:
+            raise HTTPException(409, str(e))
+        except TooLarge as e:
+            raise HTTPException(413, str(e))
+        except PermissionError as e:
+            raise HTTPException(401, str(e))
+        except ValueError as e:
+            raise HTTPException(422, str(e))
+
+    # ─── routes ─────────────────────────────────────────────────────────────
+    @app.get("/healthz")
+    def healthz():
+        return {"ok": True}
+
+    @app.post("/memories", status_code=201)
+    def create(req: CreateBody, tok: Optional[str] = Depends(token)):
+        with pool.connection() as conn:
+            m = _guard(lambda: _store(conn).write(
+                tok, body=req.body, path=req.path, tags=req.tags,
+                source=req.source, reason=req.reason, ttl_days=req.ttl_days))
+            return _mem(m)
+
+    @app.get("/memories/{mid}")
+    def read(mid: str, tok: Optional[str] = Depends(token)):
+        with pool.connection() as conn:
+            return _mem(_guard(lambda: _store(conn).get(tok, mid)))
+
+    @app.patch("/memories/{mid}")
+    def edit(mid: str, req: EditBody, tok: Optional[str] = Depends(token)):
+        with pool.connection() as conn:
+            m = _guard(lambda: _store(conn).write(
+                tok, id=mid, body=req.body, diff=req.diff, base_hash=req.base_hash,
+                path=req.path, tags=req.tags, source=req.source, reason=req.reason,
+                ttl_days=req.ttl_days))
+            return _mem(m)
+
+    @app.post("/memories/{mid}/move")
+    def move(mid: str, req: MoveBody, tok: Optional[str] = Depends(token)):
+        with pool.connection() as conn:
+            m = _guard(lambda: _store(conn).move(
+                tok, mid, req.path, source=req.source, reason=req.reason))
+            return _mem(m)
+
+    @app.delete("/memories/{mid}", status_code=204)
+    def forget(mid: str, tok: Optional[str] = Depends(token)):
+        with pool.connection() as conn:
+            ok = _guard(lambda: _store(conn).forget(tok, mid))
+            if not ok:
+                raise HTTPException(404, "not found")
+
+    @app.get("/memories/{mid}/history")
+    def history(mid: str, tok: Optional[str] = Depends(token)):
+        with pool.connection() as conn:
+            return _guard(lambda: _store(conn).history(tok, mid))
+
+    @app.get("/memories/{mid}/blame")
+    def blame(mid: str, upto_seq: Optional[int] = None,
+              group: bool = True, text: bool = True,
+              lines: Optional[str] = Query(None, description="e.g. '2' or '1,3-5'"),
+              tok: Optional[str] = Depends(token)):
+        """Who last changed each line. Grouped into author-blocks by default
+        (`group=false` for per-line); `text=false` drops bodies for a pure
+        ownership map; `lines` selects specific 1-based lines/ranges (per-line)."""
+        want = _parse_lines(lines)
+        with pool.connection() as conn:
+            s = _store(conn)
+            if want is not None or not group:
+                return _guard(lambda: s.annotate(tok, mid, upto_seq, want))
+            return _guard(lambda: s.annotate_grouped(tok, mid, upto_seq, text))
+
+    @app.get("/memories/{mid}/at/{seq}")
+    def at_version(mid: str, seq: int, tok: Optional[str] = Depends(token)):
+        """The exact body as it was at version `seq` (reconstructed from history)."""
+        with pool.connection() as conn:
+            body = _guard(lambda: _store(conn).reconstruct(tok, mid, seq))
+            return {"seq": seq, "body": body}
+
+    @app.get("/recall")
+    def recall(q: str, k: int = 10, mode: str = "auto",
+               tags: Optional[str] = Query(None, description="comma-separated"),
+               path_prefix: Optional[str] = None,
+               tok: Optional[str] = Depends(token)):
+        taglist = [t for t in (tags.split(",") if tags else []) if t]
+        with pool.connection() as conn:
+            hits = _guard(lambda: _store(conn).recall(
+                tok, q, k=k, tags=taglist or None, path_prefix=path_prefix, mode=mode))
+            return [{"id": h.id, "body": h.body, "tags": h.tags,
+                     "path": h.path, "score": h.score} for h in hits]
+
+    return app
+
+
+def main():  # pragma: no cover - entrypoint
+    import os
+    import uvicorn
+    uvicorn.run(create_app(), host=os.environ.get("MEMGRES_HTTP_HOST", "0.0.0.0"),
+                port=int(os.environ.get("MEMGRES_HTTP_PORT", "8080")))
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()