memgres 0.1.0__py3-none-any.whl

memgres/__init__.py

@@ -0,0 +1,34 @@
+"""memgres — versioned document memory for AI agents, backed by one Postgres.
+
+Quick start::
+
+    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
+
+    store = Store(cfg, conn=conn)
+    m = store.write(body="remember this\n", tags=["note"], source="me")
+    store.write(id=m.id, diff=patch, base_hash=m.content_hash)   # authored edit
+    hits = store.recall(None, "what did I remember?")            # lexical or semantic
+"""
+
+from .config import Config, load as load_config
+from .diffing import apply_diff, content_hash, make_diff, DiffConflict
+from .embeddings import Embedder, get_embedder
+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
+
+__all__ = [
+    "Config", "load_config",
+    "Store", "Memory", "Conflict", "NotFound", "TooLarge", "NoParent",
+    "make_diff", "apply_diff", "content_hash", "DiffConflict",
+    "Embedder", "get_embedder",
+    "migrate", "SchemaMismatch", "SCHEMA_VERSION",
+    "Hit", "recall",
+    "annotate", "annotate_grouped", "reconstruct", "replay",
+]

memgres/blame.py

@@ -0,0 +1,143 @@
+"""Turn the diff history into an annotated document (git-blame) and reconstruct
+any past version — so callers never replay diffs themselves.
+
+Because the store keeps a canonical diff for *every* body change (create is a
+diff-from-empty), the history is a self-contained chain empty → current. We
+replay it forward line by line, carrying an attribution with each surviving line:
+
+  * an added line is attributed to the change that introduced it,
+  * a context (unchanged) line keeps the attribution it already had,
+  * a removed line drops out.
+
+That is exactly blame semantics — a modified line reads as remove+add, so the new
+text is credited to the change that wrote it. Metadata-only rows (move/retag)
+carry no diff and don't affect line attribution.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable, List, Optional, Tuple
+
+from .diffing import _HUNK
+
+_ATTR_KEYS = ("seq", "op", "source", "reason", "created_at")
+
+
+def _apply_attributed(src: List[Tuple[str, dict]], patch: str,
+                      attrib: dict) -> List[Tuple[str, dict]]:
+    """Apply one diff to a list of (line_text, attribution) pairs. Added lines get
+    `attrib`; context/removed lines are matched against src text exactly (the base
+    is exact, so hunks line up — a mismatch is a real bug, surfaced loudly)."""
+    out: List[Tuple[str, dict]] = []
+    i = 0
+    lines = patch.split("\n")
+    n = len(lines)
+    p = 0
+
+    def marker_next(idx: int) -> bool:
+        return idx + 1 < n and lines[idx + 1].startswith("\\ No newline")
+
+    while p < n:
+        line = lines[p]
+        if line.startswith(("--- ", "+++ ")):
+            p += 1
+            continue
+        m = _HUNK.match(line)
+        if not m:
+            p += 1
+            continue
+        old_start = int(m.group(1))
+        target = old_start - 1 if old_start > 0 else 0
+        out.extend(src[i:target])
+        i = target
+        p += 1
+        while p < n and not lines[p].startswith("@@"):
+            hl = lines[p]
+            if hl.startswith("\\ No newline") or hl.startswith(("--- ", "+++ ")) or hl == "":
+                p += 1
+                continue
+            tag, text = hl[0], hl[1:]
+            if tag == " ":
+                out.append(src[i]); i += 1
+            elif tag == "-":
+                i += 1
+            elif tag == "+":
+                out.append((text if marker_next(p) else text + "\n", attrib))
+            p += 1
+    out.extend(src[i:])
+    return out
+
+
+def replay(history: List[dict], upto_seq: Optional[int] = None) -> List[Tuple[str, dict]]:
+    """Forward-replay history (ordered by seq) into a list of (line, attribution).
+    `upto_seq` stops after that version (default: all → current body)."""
+    lines: List[Tuple[str, dict]] = []
+    for row in history:
+        if upto_seq is not None and row["seq"] > upto_seq:
+            break
+        diff = row.get("diff")
+        if not diff:
+            continue  # metadata-only change: no line touched
+        attrib = {k: row.get(k) for k in _ATTR_KEYS}
+        lines = _apply_attributed(lines, diff, attrib)
+    return lines
+
+
+def reconstruct(history: List[dict], upto_seq: Optional[int] = None) -> str:
+    """The exact body text at a version (default current)."""
+    return "".join(text for text, _ in replay(history, upto_seq))
+
+
+def annotate(history: List[dict], upto_seq: Optional[int] = None,
+             lines: Optional[Iterable[int]] = None) -> List[dict]:
+    """Blame view: one entry per line of the (reconstructed) body, each tagged
+    with the change that last wrote it.
+
+    Attribution always needs the full replay, but `lines` (an iterable of 1-based
+    line numbers) restricts the *returned* entries — so you can blame one line or
+    a slice without shipping the whole document. Out-of-range numbers are ignored.
+    """
+    want = set(lines) if lines is not None else None
+    result = []
+    for lineno, (text, attrib) in enumerate(replay(history, upto_seq), start=1):
+        if want is not None and lineno not in want:
+            continue
+        result.append({"line": lineno, "text": text, **attrib})
+    return result
+
+
+def annotate_grouped(history: List[dict], upto_seq: Optional[int] = None,
+                     include_text: bool = True) -> List[dict]:
+    """Blame as runs: consecutive lines with the same attribution collapse into one
+    block ``{start, end, lines, seq, op, source, reason, created_at[, text]}``.
+
+    A 5000-line document edited by two authors returns a handful of blocks, not
+    5000 rows. Set ``include_text=False`` for a pure ownership map (ranges only,
+    no body) — tiny even for huge documents.
+    """
+    blocks: List[dict] = []
+    cur: Optional[dict] = None
+    cur_texts: List[str] = []
+    for lineno, (text, attrib) in enumerate(replay(history, upto_seq), start=1):
+        key = (attrib.get("seq"), attrib.get("source"), attrib.get("reason"),
+               attrib.get("op"))
+        if cur is not None and key == cur["_key"]:
+            cur["end"] = lineno
+            cur["lines"] += 1
+            cur_texts.append(text)
+        else:
+            if cur is not None:
+                _finish_block(cur, cur_texts, include_text, blocks)
+            cur = {"_key": key, "start": lineno, "end": lineno, "lines": 1, **attrib}
+            cur_texts = [text]
+    if cur is not None:
+        _finish_block(cur, cur_texts, include_text, blocks)
+    return blocks
+
+
+def _finish_block(block: dict, texts: List[str], include_text: bool,
+                  out: List[dict]) -> None:
+    block.pop("_key", None)
+    if include_text:
+        block["text"] = "".join(texts)
+    out.append(block)

memgres/config.py

@@ -0,0 +1,111 @@
+"""All memgres settings, read from the environment.
+
+Every operational limit lives here so the same code serves two very different
+deployments from env alone:
+
+  * single-user / embedded — no namespaces, unlimited retention, write whole
+    bodies directly;
+  * multi-tenant / metered — token namespaces required, retention
+    capped, single writes capped small so large memories accrue over many
+    (paid) diffs.
+
+Nothing here is specific to a language or a project. The default embedding
+provider is ``none`` (lexical search still works); turn on a local or cloud
+model when you want semantic recall.
+
+Env is read in :func:`load`, not at import time, so a process that sets env
+after importing this module still gets the right values, and tests can vary it.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+def _int(name: str, default: int) -> int:
+    raw = os.environ.get(name)
+    return int(raw) if raw not in (None, "") else default
+
+
+def _bool(name: str, default: bool) -> bool:
+    raw = os.environ.get(name)
+    if raw in (None, ""):
+        return default
+    return raw.strip().lower() in ("1", "true", "yes", "on")
+
+
+def _str(name: str, default: str) -> str:
+    raw = os.environ.get(name)
+    return raw if raw not in (None, "") else default
+
+
+@dataclass(frozen=True)
+class Config:
+    # storage limits (bytes)
+    max_body_bytes: int          # whole-record ceiling; grows to this via diffs
+    max_write_bytes: int         # one write/diff payload ceiling (<= max_body)
+    # retention
+    retention_days: int          # 0 = forever; >0 = expire N days after last touch
+    renew_on_read: bool          # a read pushes the expiry clock forward
+    # multi-tenant isolation
+    namespaces_enabled: bool     # False = single space; True = secret-token namespaces
+    # organization
+    tree_enabled: bool           # ltree path column + GiST index for fast subtree selection
+    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
+    history_enabled: bool        # keep hash-chained diff history (deleted with record)
+    # search
+    fts_language: str            # Postgres FTS dict: simple | english | russian | …
+    vector_backend: str          # pgvector (default) | qdrant
+    # embeddings
+    embed_provider: str          # none | local | jina | openai | openai-compatible
+    embed_model: str
+    embed_dim: int               # 0 = infer from provider
+    embed_api_key: str
+    embed_api_base: str
+    # database
+    database_url: str
+
+    def validate(self) -> None:
+        if self.max_write_bytes > self.max_body_bytes:
+            raise ValueError(
+                "MEMGRES_MAX_WRITE_BYTES must be <= MEMGRES_MAX_BODY_BYTES"
+            )
+        if self.embed_provider not in (
+                "none", "local", "jina", "openai",
+                "openai-compatible", "compatible", "custom"):
+            raise ValueError(f"unknown MEMGRES_EMBED_PROVIDER: {self.embed_provider}")
+        if self.vector_backend not in ("pgvector", "qdrant"):
+            raise ValueError(f"unknown MEMGRES_VECTOR_BACKEND: {self.vector_backend}")
+        if self.embed_provider != "none" and self.vector_backend == "pgvector" \
+                and self.embed_dim <= 0:
+            raise ValueError(
+                "semantic search needs a vector dimension: set MEMGRES_EMBED_DIM "
+                "(or it is inferred once the provider loads)"
+            )
+
+
+def load() -> Config:
+    """Build Config from the current environment and validate it."""
+    cfg = Config(
+        max_body_bytes=_int("MEMGRES_MAX_BODY_BYTES", 262_144),      # 256 KB
+        max_write_bytes=_int("MEMGRES_MAX_WRITE_BYTES", 16_384),      # 16 KB
+        retention_days=_int("MEMGRES_RETENTION_DAYS", 0),
+        renew_on_read=_bool("MEMGRES_RENEW_ON_READ", True),
+        namespaces_enabled=_bool("MEMGRES_NAMESPACES", False),
+        tree_enabled=_bool("MEMGRES_TREE", True),
+        require_parent=_bool("MEMGRES_REQUIRE_PARENT", False),
+        history_enabled=_bool("MEMGRES_HISTORY", True),
+        fts_language=_str("MEMGRES_FTS_LANGUAGE", "simple"),
+        vector_backend=_str("MEMGRES_VECTOR_BACKEND", "pgvector"),
+        embed_provider=_str("MEMGRES_EMBED_PROVIDER", "none"),
+        embed_model=_str("MEMGRES_EMBED_MODEL", ""),
+        embed_dim=_int("MEMGRES_EMBED_DIM", 0),
+        embed_api_key=_str("MEMGRES_EMBED_API_KEY", ""),
+        embed_api_base=_str("MEMGRES_EMBED_API_BASE", ""),
+        database_url=_str("MEMGRES_DATABASE_URL", ""),
+    )
+    cfg.validate()
+    return cfg

memgres/diffing.py

@@ -0,0 +1,130 @@
+"""Content hashing and unified-diff make/apply.
+
+A write can arrive two ways: the whole new body, or a *diff* (a unified diff, the
+same text ``git diff`` prints). Either way we store a unified diff in history, so
+every change is replayable and attributable.
+
+Concurrency is guarded by content hash, not locks: the caller passes the hash of
+the body it started from; the store applies the change only if the current body
+still hashes to that value (optimistic locking). Because the base is thus exact,
+diff application never needs fuzz — a hunk that does not line up is a real
+conflict and raises, rather than corrupting the body silently.
+
+Trailing newlines are preserved exactly via the ``\``
+marker, the way git does it; without it a body that does/doesn't end in a
+newline would not survive a make→apply round-trip.
+"""
+
+from __future__ import annotations
+
+import difflib
+import hashlib
+import re
+
+_HUNK = re.compile(r"^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@")
+_NO_NL = "\"
+
+
+def content_hash(body: str) -> str:
+    """Stable identifier of a body's exact content. Used for optimistic
+    locking and as the link in the history hash-chain."""
+    return hashlib.sha256(body.encode("utf-8")).hexdigest()
+
+
+def make_diff(old: str, new: str) -> str:
+    """Unified diff turning ``old`` into ``new``. Empty string if identical."""
+    if old == new:
+        return ""
+    a = old.splitlines(keepends=True)
+    b = new.splitlines(keepends=True)
+    out: list[str] = []
+    for line in difflib.unified_diff(a, b, lineterm=""):
+        if line.startswith(("--- ", "+++ ", "@@")):
+            out.append(line + "\n")
+        elif line.endswith("\n"):
+            out.append(line)
+        else:  # a content line with no trailing newline = last line of file
+            out.append(line + "\n")
+            out.append(_NO_NL + "\n")
+    return "".join(out)
+
+
+class DiffConflict(Exception):
+    """A patch hunk did not match the body it was applied to."""
+
+
+def apply_diff(old: str, patch: str) -> str:
+    """Apply a unified diff to ``old`` and return the new body.
+
+    Raises DiffConflict if a hunk's context/removed lines do not match — with
+    an exact base (enforced by the hash check upstream) this only happens on a
+    malformed or stale patch, never as normal fuzz.
+    """
+    if patch.strip() == "":
+        return old
+
+    src = old.splitlines(keepends=True)
+    out: list[str] = []
+    i = 0                       # index into src (0-based)
+    lines = patch.split("\n")
+    n = len(lines)
+    p = 0
+
+    def marker_next(idx: int) -> bool:
+        return idx + 1 < n and lines[idx + 1].startswith("\\ No newline")
+
+    while p < n:
+        line = lines[p]
+        if line.startswith("--- ") or line.startswith("+++ "):
+            p += 1
+            continue
+        m = _HUNK.match(line)
+        if not m:
+            p += 1
+            continue
+
+        old_start = int(m.group(1))
+        # @@ lines are 1-based; a hunk adding to an empty side uses -0 → 0.
+        target = old_start - 1 if old_start > 0 else 0
+        if target < i:
+            raise DiffConflict(f"hunk out of order at source line {old_start}")
+        out.extend(src[i:target])
+        i = target
+        p += 1
+
+        while p < n and not lines[p].startswith("@@"):
+            hl = lines[p]
+            if hl.startswith("\\ No newline") or hl.startswith(("--- ", "+++ ")):
+                p += 1
+                continue
+            if hl == "":                    # trailing split artifact
+                p += 1
+                continue
+            tag, text = hl[0], hl[1:]
+            if tag == " ":                  # context: copy exact source bytes
+                _expect(src, i, text)
+                out.append(src[i]); i += 1
+            elif tag == "-":                # removal: verify then drop
+                _expect(src, i, text)
+                i += 1
+            elif tag == "+":                # addition: marker decides newline
+                out.append(text if marker_next(p) else text + "\n")
+            else:
+                raise DiffConflict(f"unexpected patch line: {hl!r}")
+            p += 1
+
+    out.extend(src[i:])
+    return "".join(out)
+
+
+def _expect(src: list[str], i: int, text: str) -> None:
+    if i >= len(src):
+        raise DiffConflict(f"patch expects a line past end of body: {text!r}")
+    if src[i].rstrip("\n") != text.rstrip("\n"):
+        raise DiffConflict(f"context mismatch at line {i + 1}: "
+                           f"have {src[i]!r}, patch expects {text!r}")
+
+
+def byte_len(text: str) -> int:
+    """UTF-8 byte length — what limits are measured in."""
+    return len(text.encode("utf-8"))

memgres/embeddings.py

@@ -0,0 +1,144 @@
+"""Pluggable embedding providers, selected by env.
+
+    MEMGRES_EMBED_PROVIDER = none | local | jina | openai
+
+``none`` disables semantic recall entirely (lexical FTS still works, no model,
+no API, no GPU). ``local`` runs a sentence-transformers model in-process.
+``jina`` / ``openai`` call a hosted API. All are behind one tiny interface so
+the store never cares which is configured::
+
+    emb = get_embedder(cfg)          # -> Embedder | None
+    if emb:
+        vecs = emb.embed_documents(["…"])   # for writes
+        q    = emb.embed_query("…")          # for recall
+        dim  = emb.dim
+
+The document/query split matters: several models (and Jina) want an explicit
+"is this a passage or a search query?" hint, and mixing them up quietly hurts
+recall. Cloud calls use stdlib urllib so the base install stays dependency-light
+(only ``local`` pulls in sentence-transformers, via the ``[local]`` extra).
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.request
+from typing import List, Optional, Sequence
+
+from .config import Config
+
+
+class Embedder:
+    """Interface: implementations return unit-normalized float lists."""
+
+    dim: int
+
+    def embed_documents(self, texts: Sequence[str]) -> List[List[float]]:
+        raise NotImplementedError
+
+    def embed_query(self, text: str) -> List[float]:
+        raise NotImplementedError
+
+
+# ─── local: sentence-transformers ────────────────────────────────────────────
+class _LocalEmbedder(Embedder):
+    def __init__(self, model_name: str, want_dim: int):
+        from sentence_transformers import SentenceTransformer  # lazy: heavy import
+
+        if not model_name:
+            raise ValueError("MEMGRES_EMBED_MODEL is required for the local provider")
+        self._model = SentenceTransformer(model_name, device="cpu")
+        self.dim = self._model.get_sentence_embedding_dimension()
+        if want_dim and want_dim != self.dim:
+            raise ValueError(
+                f"MEMGRES_EMBED_DIM={want_dim} but '{model_name}' emits {self.dim}"
+            )
+
+    def embed_documents(self, texts: Sequence[str]) -> List[List[float]]:
+        vecs = self._model.encode(
+            list(texts), normalize_embeddings=True, convert_to_numpy=True
+        )
+        return [v.tolist() for v in vecs]
+
+    def embed_query(self, text: str) -> List[float]:
+        return self.embed_documents([text])[0]
+
+
+# ─── cloud: Jina and OpenAI share an OpenAI-shaped /embeddings endpoint ───────
+class _HttpEmbedder(Embedder):
+    def __init__(self, model: str, dim: int, api_key: str, api_base: str,
+                 query_task: Optional[str] = None, passage_task: Optional[str] = None,
+                 require_key: bool = True):
+        if not model:
+            raise ValueError("MEMGRES_EMBED_MODEL is required for HTTP providers")
+        if not api_base:
+            raise ValueError("MEMGRES_EMBED_API_BASE (server URL) is required")
+        if require_key and not api_key:
+            raise ValueError("MEMGRES_EMBED_API_KEY is required for this provider")
+        if dim <= 0:
+            raise ValueError("MEMGRES_EMBED_DIM must be set for HTTP providers")
+        self.dim = dim
+        self._model = model
+        self._key = api_key
+        self._base = api_base.rstrip("/")
+        self._query_task = query_task
+        self._passage_task = passage_task
+
+    def _post(self, inputs: Sequence[str], task: Optional[str]) -> List[List[float]]:
+        payload = {"model": self._model, "input": list(inputs)}
+        if task:  # Jina uses task to distinguish passage vs query; OpenAI ignores it
+            payload["task"] = task
+        headers = {"Content-Type": "application/json"}
+        if self._key:  # local servers (LM Studio/Ollama) often need no key
+            headers["Authorization"] = f"Bearer {self._key}"
+        req = urllib.request.Request(
+            f"{self._base}/embeddings",
+            data=json.dumps(payload).encode(),
+            headers=headers,
+            method="POST",
+        )
+        with urllib.request.urlopen(req, timeout=60) as resp:
+            body = json.loads(resp.read())
+        rows = sorted(body["data"], key=lambda d: d.get("index", 0))
+        out = [r["embedding"] for r in rows]
+        for v in out:
+            if len(v) != self.dim:
+                raise ValueError(
+                    f"provider returned dim {len(v)}, config says {self.dim} — "
+                    f"fix MEMGRES_EMBED_DIM to match the model"
+                )
+        return out
+
+    def embed_documents(self, texts: Sequence[str]) -> List[List[float]]:
+        return self._post(texts, self._passage_task)
+
+    def embed_query(self, text: str) -> List[float]:
+        return self._post([text], self._query_task)[0]
+
+
+def get_embedder(cfg: Config) -> Optional[Embedder]:
+    """Build the embedder the config asks for, or None for lexical-only."""
+    p = cfg.embed_provider
+    if p == "none":
+        return None
+    if p == "local":
+        return _LocalEmbedder(cfg.embed_model, cfg.embed_dim)
+    if p == "jina":
+        return _HttpEmbedder(
+            cfg.embed_model, cfg.embed_dim, cfg.embed_api_key,
+            cfg.embed_api_base or "https://api.jina.ai/v1",
+            query_task="retrieval.query", passage_task="retrieval.passage",
+        )
+    if p == "openai":
+        return _HttpEmbedder(
+            cfg.embed_model, cfg.embed_dim, cfg.embed_api_key,
+            cfg.embed_api_base or "https://api.openai.com/v1",
+        )
+    if p in ("openai-compatible", "compatible", "custom"):
+        # any OpenAI-shaped /embeddings server: LM Studio, Ollama, vLLM, TEI,
+        # LocalAI, … base URL required, key optional.
+        return _HttpEmbedder(
+            cfg.embed_model, cfg.embed_dim, cfg.embed_api_key, cfg.embed_api_base,
+            require_key=False,
+        )
+    raise ValueError(f"unknown embed provider: {p}")  # config.validate guards this

memgres/mcp_server.py

@@ -0,0 +1,114 @@
+"""MCP server exposing memgres as agent tools (stdio).
+
+Thin wrapper over the same `Store` the HTTP layer uses — an MCP client (Claude
+Desktop, etc.) gets write / recall / get / blame / history / move / forget as
+tools. Run it:
+
+    memgres-mcp            # after: pip install "memgres[mcp]"
+
+Requires MEMGRES_DATABASE_URL (or libpq PG* env) pointing at a Postgres the
+schema can migrate into; migration runs once on startup.
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+import psycopg
+
+from .config import Config, load
+from .embeddings import get_embedder
+from .schema import migrate
+from .store import Store
+
+
+def _mcp(name: str):
+    # The SDK renamed FastMCP -> MCPServer; support both.
+    try:
+        from mcp.server.mcpserver import MCPServer
+        return MCPServer(name)
+    except ImportError:
+        from mcp.server.fastmcp import FastMCP
+        return FastMCP(name)
+
+
+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": str(m.created_at), "updated_at": str(m.updated_at),
+            "expires_at": str(m.expires_at) if m.expires_at else None}
+
+
+def build_server(cfg: Optional[Config] = None):
+    cfg = cfg or load()
+    conn = psycopg.connect(cfg.database_url or "")
+    migrate(conn, cfg)
+    store = Store(cfg, embedder=get_embedder(cfg), conn=conn)
+    mcp = _mcp("memgres")
+
+    @mcp.tool()
+    def memory_write(body: Optional[str] = None, id: 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,
+                     token: Optional[str] = None) -> dict:
+        """Create or edit a memory. Omit `id` to create (needs `body`). To edit,
+        pass `id` plus either a whole new `body` or a unified `diff` with the
+        `base_hash` it was cut from (stale base -> conflict). `path`/`tags` set
+        the tree position and labels; `source`/`reason` record provenance."""
+        return _mem(store.write(token, id=id or None, body=body, diff=diff,
+                                base_hash=base_hash, path=path, tags=tags,
+                                source=source, reason=reason, ttl_days=ttl_days))
+
+    @mcp.tool()
+    def memory_get(id: str, token: Optional[str] = None) -> dict:
+        """Fetch one memory by id (renews its TTL)."""
+        return _mem(store.get(token, id))
+
+    @mcp.tool()
+    def memory_recall(query: str, k: int = 10, mode: str = "auto",
+                      tags: Optional[List[str]] = None,
+                      path_prefix: Optional[str] = None,
+                      token: Optional[str] = None) -> List[dict]:
+        """Search memories. `mode`: lexical | semantic | hybrid | auto. Optionally
+        scope to a tag set (`tags`) or a subtree (`path_prefix`, e.g. 'ops.postgres')."""
+        return [{"id": h.id, "body": h.body, "tags": h.tags, "path": h.path,
+                 "score": h.score}
+                for h in store.recall(token, query, k=k, tags=tags,
+                                      path_prefix=path_prefix, mode=mode)]
+
+    @mcp.tool()
+    def memory_blame(id: str, grouped: bool = True,
+                     token: Optional[str] = None) -> List[dict]:
+        """Who last changed each line. Grouped into author-blocks by default;
+        set grouped=false for per-line attribution."""
+        if grouped:
+            return store.annotate_grouped(token, id)
+        return store.annotate(token, id)
+
+    @mcp.tool()
+    def memory_history(id: str, token: Optional[str] = None) -> List[dict]:
+        """The full change chain (diffs, provenance, hashes) for a memory."""
+        return store.history(token, id)
+
+    @mcp.tool()
+    def memory_move(id: str, new_path: str, reason: Optional[str] = None,
+                    token: Optional[str] = None) -> dict:
+        """Move a memory to a new tree path (cascades its subtree)."""
+        return _mem(store.move(token, id, new_path, reason=reason))
+
+    @mcp.tool()
+    def memory_forget(id: str, token: Optional[str] = None) -> dict:
+        """Permanently delete a memory and its history (GDPR erasure)."""
+        return {"forgotten": store.forget(token, id)}
+
+    return mcp
+
+
+def main():  # pragma: no cover - entrypoint
+    build_server().run()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()