agent-memory-git 0.1.2__tar.gz → 0.1.4__tar.gz

{agent_memory_git-0.1.2 → agent_memory_git-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-memory-git
-Version: 0.1.2
+Version: 0.1.4
 Summary: Shared, git-backed memory for Claude Code and Codex.
 Keywords: claude-code,codex,memory,agents,git
 Author: Shichao Song
@@ -88,7 +88,8 @@ mem install
 ```
 
 To upgrade, run `uv tool upgrade agent-memory-git` and then `mem install`, which refreshes the
-protocol copies; `mem doctor` says when they are out of date.
+protocol copies; `mem doctor` says when they are out of date. `mem ui` does both from Settings, with
+one click, when a newer release is out.
 
 `install` edits, and records in `~/.config/agent-memory/install-state.json`:
 
@@ -125,20 +126,33 @@ mem doctor                      check the installation
 
 ## Managing memories in a page
 
-`mem ui` starts a small server on `127.0.0.1` and opens a page listing every memory. Keep the
-terminal open while you use it. It needs `numpy`; the hooks do not.
+`mem ui` starts a small server on `127.0.0.1` and opens a page with three parts: Memories, Insights
+and Settings (the logo always leads back to Memories). Keep the terminal open while you use it. It
+needs `numpy`; the hooks do not.
 
 - **Find.** One search box (press `/`). Word matches appear as you type, with the matching words
   marked; a moment later the local model adds memories close in meaning, across Chinese and
   English. Filters narrow the list by type, where a memory loads (everywhere, or one project or
-  folder), which tool wrote it, keyword, age, and whether it needs tidying (what `mem lint`
-  reports, also listed on the open memory); the order is newest, oldest, recently changed or A to Z.
-- **Read.** Click a row, or move with `j`/`k` and press Enter. The memory opens on the right with
-  every frontmatter field (including each `source` entry), the body rendered as Markdown with
-  `[[links]]` that open other memories, the file exactly as stored, and the most similar memories.
+  folder), which tool wrote it, keyword, when it was added (a recent period or a date range), and
+  status (needs tidying, as `mem lint` reports and the open memory lists, or unchanged for 60
+  days). Tick several values in one filter to see memories that match any of them. The list's
+  header sets the order: newest, oldest, recently changed or A to Z.
+- **Read.** Click a memory, or move with `j`/`k`. It opens beside the list (drag the line between
+  them to resize) with the body rendered as Markdown, `[[links]]` that open other memories, where
+  it came from, every other frontmatter field, the most similar memories, and the file exactly as
+  stored. On a narrow window the list and the memory take turns.
 - **Change.** Edit (`e`) or delete from the open memory, add one with New (`n`), or tick several
-  rows (`x`) and delete them together. Every change is one git commit, pushed in the background,
-  with Undo. If an agent edits the same file meanwhile, saving is refused rather than overwriting.
+  memories (`x`) and delete them together. Every change is one git commit, pushed in the
+  background, with Undo. If an agent edits the same file meanwhile, saving is refused rather than
+  overwriting.
+- **Insights.** How many memories there are and how they change week by week, where they load and
+  which tool wrote them, pairs that read alike (compare them side by side and keep one), and the
+  index a session would get at a chosen place, against the 10,000-character hook limit.
+- **Settings.** Light or dark, updates, the data repository and a sync on demand, words never to
+  use as keywords, the embedding model, and the same checks as `mem doctor`. Once a day the page
+  asks PyPI whether a newer release is out (only the package name is sent; turn it off there); when
+  `uv tool` installed agent-memory, Update runs the upgrade and `mem install` and restarts the page
+  on the new version.
 
 Similar memories and search by meaning use Qwen3-Embedding-0.6B, int8 ONNX, on the CPU, in a
 separate `uv run --with onnxruntime --with tokenizers` environment; vectors are cached by content
@@ -147,7 +161,7 @@ pinned revision, checked by SHA-256). Without it, or with `--keywords-only`, sim
 come from keyword vectors and search matches words only.
 
 Keywords are the words that most set a memory apart from the others (TF-IDF). Words that should
-never be keywords, such as your own name, go in `keyword_stopwords` in
+never be keywords, such as your own name, go in Settings, which keeps them as `keyword_stopwords` in
 `~/.config/agent-memory/config.json`.
 
 The server only listens on loopback, and every request needs the one-time token from the link it
@@ -162,6 +176,17 @@ uv run ruff check .
 uv run ruff format .
 ```
 
+The page `mem ui` serves lives in `web/` (Svelte 5, TypeScript, Vite, Tailwind and bits-ui) and
+needs Node 20 or newer. `npm run build` there writes it into `src/agent_memory/webui/`, which the
+package ships; CI builds it before packaging, so the built files are not committed. While working on it, `npm run dev` serves the page with hot reload and passes API
+calls to a running `mem ui` (set `MEM_UI` if it is not on port 8790); open it with the `#t=…` part of
+the link `mem ui` printed.
+
+```bash
+cd web && npm ci && npm run build   # the page, into the package
+npm run check                       # svelte-check, warnings fail it
+```
+
 `uv run mem ...` runs the working copy without touching the installed one. To have every
 session use the working copy, install it in place of the release and rewire the hooks; go back
 the same way:

{agent_memory_git-0.1.2 → agent_memory_git-0.1.4}/README.md

@@ -68,7 +68,8 @@ mem install
 ```
 
 To upgrade, run `uv tool upgrade agent-memory-git` and then `mem install`, which refreshes the
-protocol copies; `mem doctor` says when they are out of date.
+protocol copies; `mem doctor` says when they are out of date. `mem ui` does both from Settings, with
+one click, when a newer release is out.
 
 `install` edits, and records in `~/.config/agent-memory/install-state.json`:
 
@@ -105,20 +106,33 @@ mem doctor                      check the installation
 
 ## Managing memories in a page
 
-`mem ui` starts a small server on `127.0.0.1` and opens a page listing every memory. Keep the
-terminal open while you use it. It needs `numpy`; the hooks do not.
+`mem ui` starts a small server on `127.0.0.1` and opens a page with three parts: Memories, Insights
+and Settings (the logo always leads back to Memories). Keep the terminal open while you use it. It
+needs `numpy`; the hooks do not.
 
 - **Find.** One search box (press `/`). Word matches appear as you type, with the matching words
   marked; a moment later the local model adds memories close in meaning, across Chinese and
   English. Filters narrow the list by type, where a memory loads (everywhere, or one project or
-  folder), which tool wrote it, keyword, age, and whether it needs tidying (what `mem lint`
-  reports, also listed on the open memory); the order is newest, oldest, recently changed or A to Z.
-- **Read.** Click a row, or move with `j`/`k` and press Enter. The memory opens on the right with
-  every frontmatter field (including each `source` entry), the body rendered as Markdown with
-  `[[links]]` that open other memories, the file exactly as stored, and the most similar memories.
+  folder), which tool wrote it, keyword, when it was added (a recent period or a date range), and
+  status (needs tidying, as `mem lint` reports and the open memory lists, or unchanged for 60
+  days). Tick several values in one filter to see memories that match any of them. The list's
+  header sets the order: newest, oldest, recently changed or A to Z.
+- **Read.** Click a memory, or move with `j`/`k`. It opens beside the list (drag the line between
+  them to resize) with the body rendered as Markdown, `[[links]]` that open other memories, where
+  it came from, every other frontmatter field, the most similar memories, and the file exactly as
+  stored. On a narrow window the list and the memory take turns.
 - **Change.** Edit (`e`) or delete from the open memory, add one with New (`n`), or tick several
-  rows (`x`) and delete them together. Every change is one git commit, pushed in the background,
-  with Undo. If an agent edits the same file meanwhile, saving is refused rather than overwriting.
+  memories (`x`) and delete them together. Every change is one git commit, pushed in the
+  background, with Undo. If an agent edits the same file meanwhile, saving is refused rather than
+  overwriting.
+- **Insights.** How many memories there are and how they change week by week, where they load and
+  which tool wrote them, pairs that read alike (compare them side by side and keep one), and the
+  index a session would get at a chosen place, against the 10,000-character hook limit.
+- **Settings.** Light or dark, updates, the data repository and a sync on demand, words never to
+  use as keywords, the embedding model, and the same checks as `mem doctor`. Once a day the page
+  asks PyPI whether a newer release is out (only the package name is sent; turn it off there); when
+  `uv tool` installed agent-memory, Update runs the upgrade and `mem install` and restarts the page
+  on the new version.
 
 Similar memories and search by meaning use Qwen3-Embedding-0.6B, int8 ONNX, on the CPU, in a
 separate `uv run --with onnxruntime --with tokenizers` environment; vectors are cached by content
@@ -127,7 +141,7 @@ pinned revision, checked by SHA-256). Without it, or with `--keywords-only`, sim
 come from keyword vectors and search matches words only.
 
 Keywords are the words that most set a memory apart from the others (TF-IDF). Words that should
-never be keywords, such as your own name, go in `keyword_stopwords` in
+never be keywords, such as your own name, go in Settings, which keeps them as `keyword_stopwords` in
 `~/.config/agent-memory/config.json`.
 
 The server only listens on loopback, and every request needs the one-time token from the link it
@@ -142,6 +156,17 @@ uv run ruff check .
 uv run ruff format .
 ```
 
+The page `mem ui` serves lives in `web/` (Svelte 5, TypeScript, Vite, Tailwind and bits-ui) and
+needs Node 20 or newer. `npm run build` there writes it into `src/agent_memory/webui/`, which the
+package ships; CI builds it before packaging, so the built files are not committed. While working on it, `npm run dev` serves the page with hot reload and passes API
+calls to a running `mem ui` (set `MEM_UI` if it is not on port 8790); open it with the `#t=…` part of
+the link `mem ui` printed.
+
+```bash
+cd web && npm ci && npm run build   # the page, into the package
+npm run check                       # svelte-check, warnings fail it
+```
+
 `uv run mem ...` runs the working copy without touching the installed one. To have every
 session use the working copy, install it in place of the release and rewire the hooks; go back
 the same way:

{agent_memory_git-0.1.2 → agent_memory_git-0.1.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-memory-git"
-version = "0.1.2"
+version = "0.1.4"
 description = "Shared, git-backed memory for Claude Code and Codex."
 readme = "README.md"
 license = "MIT"

{agent_memory_git-0.1.2 → agent_memory_git-0.1.4}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "agent-memory-git"
-version = "0.1.2"
+version = "0.1.4"
 description = "Shared, git-backed memory for Claude Code and Codex."
 readme = "README.md"
 license = "MIT"

{agent_memory_git-0.1.2 → agent_memory_git-0.1.4}/src/agent_memory/install.py

@@ -479,13 +479,12 @@ def recent_hook_errors(log_text, now=None, days=ERROR_DAYS):
     return out
 
 
-def doctor():
-    ok = True
+def doctor_checks():
+    """Every check as (passed, description), for `mem doctor` and the page's Health section."""
+    results = []
 
     def check(cond, msg):
-        nonlocal ok
-        print(("ok   " if cond else "FAIL ") + msg)
-        ok &= bool(cond)
+        results.append((bool(cond), msg))
 
     data = config.data_dir()
     check(data and (data / ".git").exists(), f"data repository: {data}")
@@ -528,4 +527,11 @@ def doctor():
         errors = recent_hook_errors(_read(logf) or "")
         latest = f"; latest: {errors[-1]} (details in {logf})" if errors else ""
         check(not errors, f"no hook errors in the last {ERROR_DAYS} days ({len(errors)}{latest})")
-    return 0 if ok else 1
+    return results
+
+
+def doctor():
+    results = doctor_checks()
+    for passed, msg in results:
+        print(("ok   " if passed else "FAIL ") + msg)
+    return 0 if all(passed for passed, _ in results) else 1

{agent_memory_git-0.1.2 → agent_memory_git-0.1.4}/src/agent_memory/ui_server.py

@@ -10,7 +10,10 @@ background like hook commits; Undo reverts that commit.
 """
 
 import hashlib
+import importlib.metadata
 import json
+import os
+import re
 import secrets
 import subprocess
 import sys
@@ -21,18 +24,35 @@ from urllib.parse import parse_qs, urlparse
 
 import numpy as np
 
-from . import frontmatter, gitsync, store, ui
-from .context import detect, hostname
+from . import config, frontmatter, gitsync, select, store, ui, update
+from .context import detect, hostname, normalize_remote
 from .util import SCOPES, TYPES, atomic_write, id_path, log_exc, new_id, now_iso, slugify
 
-STATIC = Path(__file__).with_name("webui")
-MIME = {".html": "text/html; charset=utf-8", ".css": "text/css; charset=utf-8", ".js": "text/javascript; charset=utf-8"}
+STATIC = Path(__file__).with_name("webui")  # the page, built from web/ by `npm run build`
+MIME = {
+    ".html": "text/html; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".woff2": "font/woff2",
+}
 CSP = (
     "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; "
     "connect-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'"
 )
+NOT_BUILT = (
+    "<!doctype html><meta charset=utf-8><title>agent-memory</title>"
+    "<p style='font:15px/1.6 system-ui;margin:3rem auto;max-width:36rem'>This copy of agent-memory has no built page. "
+    "In a checkout, build it with <code>cd web &amp;&amp; npm ci &amp;&amp; npm run build</code>, then reload.</p>"
+)
+RESTART_TOKEN = "AGENT_MEMORY_UI_TOKEN"
 PLACE_FIELDS = ("cwd", "git_root", "git_remote", "git_branch")
 SEARCH_HITS = 8
+ACTIVITY_COMMITS = 2000
+HOOK_LIMIT = 10000  # what Claude Code injects at most from a hook
+COUNTS = re.compile(r"memory: \+(\d+) ~(\d+) -(\d+)")
+UI_SUBJECT = re.compile(r"memory: (add|edit|delete|undo) (?:(\d+) memories)?")
 
 
 class ApiError(Exception):
@@ -57,11 +77,13 @@ class UiApp:
 
     def stamp(self):
         head = gitsync.git(self.data, "rev-parse", "--short", "HEAD", timeout=5).stdout.strip()
+        # a push in the background moves the upstream ref but not HEAD; without it a stale "not pushed" would stay
+        pushed = gitsync.git(self.data, "rev-parse", "--short", "@{u}", timeout=5).stdout.strip()
         newest, count = 0, 0
         for path in self.mdir.rglob("*.md"):
             count += 1
             newest = max(newest, path.stat().st_mtime_ns)
-        return f"{head}:{count}:{newest}"
+        return f"{head}:{pushed}:{count}:{newest}"
 
     def refresh(self):
         with self.lock:
@@ -84,6 +106,116 @@ class UiApp:
         ahead = int(r.stdout.strip()) if r.returncode == 0 and r.stdout.strip().isdigit() else 0
         return {"remote": True, "ahead": ahead}
 
+    # ------------------------------------------------------------ insights and settings
+
+    def activity(self):
+        """Commits to the data repository, newest first: when, which tool, how many memories added, changed, deleted."""
+        fmt = "%H%x1f%aI%x1f%s%x1f%(trailers:key=Tool,valueonly,separator=%x2C)%x1e"
+        r = gitsync.git(self.data, "log", f"--format={fmt}", "-n", str(ACTIVITY_COMMITS), timeout=10)
+        commits = []
+        for record in r.stdout.split("\x1e") if r.returncode == 0 else []:
+            parts = record.strip("\n").split("\x1f")
+            if len(parts) != 4 or not parts[2].startswith("memory: "):
+                continue
+            sha, when, subject, tool = parts
+            counts = COUNTS.match(subject)
+            if counts:
+                added, changed, deleted = map(int, counts.groups())
+            else:
+                ui_change = UI_SUBJECT.match(subject)
+                verb, many = ui_change.groups() if ui_change else ("", None)
+                n = int(many) if many else 1
+                added, changed, deleted = (
+                    (n if verb == "add" else 0),
+                    (n if verb in ("edit", "undo") else 0),
+                    (n if verb == "delete" else 0),
+                )
+            commits.append(
+                {
+                    "sha": sha[:10],
+                    "date": when,
+                    "subject": subject,
+                    "tool": tool.strip() or None,
+                    "added": added,
+                    "changed": changed,
+                    "deleted": deleted,
+                }
+            )
+        return {"commits": commits}
+
+    def index_preview(self, place):
+        """The index a session gets at one of the known places, or with no place only the global part."""
+        ctx = {}
+        if place:
+            known = {p["key"]: p.get("ctx", {}) for p in self.current().get("places", [])}
+            if place not in known:
+                raise ApiError(404, "unknown place")
+            ctx = dict(known[place])
+        memories = store.load_all(self.data)
+        paths = {
+            "memories": str(self.mdir),
+            "staging": str(self.data / "staging" / "<session>"),
+            "mem": str(config.BIN),
+        }
+        text = select.render(memories, ctx, paths)
+        globals_, here = select.visible(memories, ctx)
+        return {"text": text, "chars": len(text), "limit": HOOK_LIMIT, "global": len(globals_), "here": len(here)}
+
+    def settings(self):
+        remote = gitsync.git(self.data, "remote", "get-url", "origin", timeout=5)
+        try:
+            version = importlib.metadata.version("agent-memory-git")
+        except importlib.metadata.PackageNotFoundError:
+            version = "dev"
+        return {
+            "version": version,
+            "dataDir": ui._short(str(self.data)),
+            "remote": normalize_remote(remote.stdout.strip()) if remote.returncode == 0 else None,
+            "sync": self.sync_status(),
+            "keywordStopwords": config.load().get("keyword_stopwords", []),
+            "model": {
+                "name": ui.MODEL["name"],
+                "ready": ui.model_ready(),
+                "dir": ui._short(str(ui.model_dir())),
+                "fetch": "mem ui --fetch-model",
+                "size": "about 625 MB",
+            },
+            "semantic": bool(self.state.get("semantic")),
+        }
+
+    def set_settings(self, p):
+        """Change keyword_stopwords, check_updates, or both."""
+        cfg = config.load()
+        if "keyword_stopwords" in p:
+            words = p["keyword_stopwords"]
+            if not isinstance(words, list) or not all(isinstance(w, str) for w in words):
+                raise ApiError(400, "keyword_stopwords must be a list of words")
+            cfg["keyword_stopwords"] = sorted({w.strip().lower() for w in words if w.strip()})
+        if "check_updates" in p:
+            if not isinstance(p["check_updates"], bool):
+                raise ApiError(400, "check_updates must be true or false")
+            cfg["check_updates"] = p["check_updates"]
+        config.save(cfg)
+        if "keyword_stopwords" in p:
+            self.refresh()  # keywords are chosen when the state is built
+        return self.settings()
+
+    def check_update(self, p):
+        return update.status(force=True)
+
+    def run_update(self, p):
+        return update.upgrade()
+
+    def doctor(self):
+        from .install import doctor_checks
+
+        return {"checks": [{"ok": passed, "text": text} for passed, text in doctor_checks()]}
+
+    def sync(self, p):
+        ok = gitsync.sync(self.data)
+        self.refresh()
+        return {"ok": ok, "sync": self.state["sync"]}
+
     def search(self, query):
         """Memories closest in meaning to the query (the page does word matching itself)."""
         query = (query or "").strip()
@@ -300,7 +432,16 @@ class UiApp:
 
 class Handler(BaseHTTPRequestHandler):
     server_version = "agent-memory"
-    POSTS = {"/api/create": "create", "/api/edit": "edit", "/api/delete": "delete", "/api/undo": "undo"}
+    POSTS = {
+        "/api/create": "create",
+        "/api/edit": "edit",
+        "/api/delete": "delete",
+        "/api/undo": "undo",
+        "/api/settings": "set_settings",
+        "/api/sync": "sync",
+        "/api/update/check": "check_update",
+        "/api/update": "run_update",
+    }
 
     def log_message(self, *args):
         pass
@@ -351,25 +492,44 @@ class Handler(BaseHTTPRequestHandler):
         if not self._guard(api):
             return
         if not api:
-            name = "index.html" if url.path in ("/", "/index.html") else url.path.lstrip("/")
-            path = STATIC / name
-            if "/" in name or not path.is_file() or path.suffix not in MIME:
-                return self._send(404, {"error": "not found"})
-            return self._send(200, path.read_bytes(), MIME[path.suffix])
+            return self._page(url.path.lstrip("/"))
         app, q = self.server.app, {k: v[0] for k, v in parse_qs(url.query).items()}
         routes = {
             "/api/state": app.current,
             "/api/stamp": lambda: {"stamp": app.stamp()},
             "/api/search": lambda: app.search(q.get("q")),
+            "/api/activity": app.activity,
+            "/api/index-preview": lambda: app.index_preview(q.get("place", "")),
+            "/api/settings": app.settings,
+            "/api/doctor": app.doctor,
+            "/api/update": update.status,
         }
         if url.path not in routes:
             return self._send(404, {"error": "not found"})
         self._run(routes[url.path])
 
+    def _page(self, rel):
+        """The page's files, and index.html for any other path so the page can route."""
+        root = STATIC.resolve()
+        target = (root / rel).resolve() if rel else None
+        if target and target.is_file() and root in target.parents and target.suffix in MIME:
+            return self._send(200, target.read_bytes(), MIME[target.suffix])
+        index = root / "index.html"
+        if not index.is_file():  # a checkout where the page was never built
+            return self._send(503, NOT_BUILT.encode(), MIME[".html"])
+        if rel.startswith("assets/"):
+            return self._send(404, {"error": "not found"})
+        return self._send(200, index.read_bytes(), MIME[".html"])
+
     def do_POST(self):
         url = urlparse(self.path)
         if not self._guard(True):
             return
+        if url.path == "/api/restart":  # after an update: answer, then serve_forever ends and run() starts the new code
+            self.server.restart = True
+            self._send(200, {"restarting": True})
+            threading.Thread(target=self.server.shutdown, daemon=True).start()
+            return
         method = self.POSTS.get(url.path)
         if not method:
             return self._send(404, {"error": "not found"})
@@ -389,7 +549,9 @@ def make_server(data_dir, port=8790, semantic=True):
         server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
     port = server.server_address[1]
     server.hosts = {f"127.0.0.1:{port}", f"localhost:{port}"}
-    server.token = secrets.token_urlsafe(18)
+    # a restart after an update keeps the token, so the open page carries on
+    server.token = os.environ.pop(RESTART_TOKEN, None) or secrets.token_urlsafe(18)
+    server.restart = False
     server.app = app
     server.url = f"http://127.0.0.1:{port}/#t={server.token}"
     return server
@@ -418,3 +580,8 @@ def run(data_dir, port=8790, open_browser=True, semantic=True):
         server.server_close()
         if server.app.encoder:
             server.app.encoder.close()
+    if server.restart:
+        args = ["ui", "--port", str(server.server_address[1]), "--no-open"] + ([] if semantic else ["--keywords-only"])
+        print("Restarting with the updated version...", flush=True)
+        os.environ[RESTART_TOKEN] = server.token
+        os.execv(sys.executable, [sys.executable, "-m", "agent_memory", *args])

agent_memory_git-0.1.4/src/agent_memory/update.py

@@ -0,0 +1,156 @@
+"""Whether a newer release is out, and updating this copy when `uv tool` installed it.
+
+The check asks PyPI for the package's latest version (only the package name goes out) and keeps the
+answer for a day. Automatic checks can be turned off with `check_updates: false` in config.json.
+"""
+
+import datetime as _dt
+import importlib.metadata
+import json
+import re
+import shutil
+import subprocess
+import sys
+import time
+import urllib.request
+from pathlib import Path
+
+from . import config
+
+PACKAGE = "agent-memory-git"
+INDEX = f"https://pypi.org/pypi/{PACKAGE}/json"
+CHECK_EVERY = 24 * 3600
+CACHE_NAME = "update-check.json"
+# how to update, by how this copy was installed
+COMMANDS = {
+    "uv-tool": f"uv tool upgrade {PACKAGE} && mem install",
+    "uvx": f'uvx --refresh --from "{PACKAGE}[ui]" mem ui',
+    "dev": "git pull && (cd web && npm ci && npm run build) && mem install",  # run in the checkout
+    "other": f'pip install -U "{PACKAGE}[ui]" && mem install',
+}
+
+
+def _cache():
+    return config.CONFIG_DIR / CACHE_NAME
+
+
+def current():
+    try:
+        return importlib.metadata.version(PACKAGE)
+    except importlib.metadata.PackageNotFoundError:
+        return None
+
+
+def _key(version):
+    """A version as numbers to compare: 0.1.10 > 0.1.9; a pre-release sorts before its release."""
+    out = []
+    for part in version.split("."):
+        m = re.match(r"(\d+)(.*)", part)
+        if not m:
+            break
+        out += [int(m.group(1)), 0 if m.group(2) else 1]
+    return out
+
+
+def newer(latest, cur):
+    return bool(latest and cur) and _key(latest) > _key(cur)
+
+
+def fetch_latest(timeout=5):
+    """The latest release on PyPI, or None when PyPI cannot be reached."""
+    try:
+        with urllib.request.urlopen(INDEX, timeout=timeout) as r:
+            return json.load(r)["info"]["version"]
+    except Exception:  # some machines only reach PyPI through the system's certificates; curl uses those
+        pass
+    curl = shutil.which("curl")
+    if not curl:
+        return None
+    try:
+        r = subprocess.run([curl, "-fsSL", "--max-time", str(timeout), INDEX], capture_output=True, text=True)
+        return json.loads(r.stdout)["info"]["version"] if r.returncode == 0 else None
+    except (OSError, ValueError, KeyError):
+        return None
+
+
+def _inside(path, root):
+    try:
+        return Path(path).resolve().is_relative_to(Path(root).resolve())
+    except OSError:
+        return False
+
+
+def how_installed():
+    """'uv-tool' when `uv tool upgrade` can update this copy; else 'dev', 'uvx' or 'other'."""
+    try:
+        direct = importlib.metadata.distribution(PACKAGE).read_text("direct_url.json")
+    except importlib.metadata.PackageNotFoundError:
+        return "dev"
+    if direct and json.loads(direct).get("dir_info", {}).get("editable"):
+        return "dev"
+    uv = shutil.which("uv")
+    if uv:
+        for kind, args in (("uv-tool", ["tool", "dir"]), ("uvx", ["cache", "dir"])):
+            r = subprocess.run([uv, *args], capture_output=True, text=True, timeout=10)
+            if r.returncode == 0 and r.stdout.strip() and _inside(sys.prefix, r.stdout.strip()):
+                return kind
+    return "other"
+
+
+def status(force=False):
+    """What the page shows: this version, the latest one known, and how to update."""
+    auto = config.load().get("check_updates", True)
+    try:
+        cached = json.loads(_cache().read_text("utf-8"))
+    except (OSError, ValueError):
+        cached = {}
+    if force or (auto and time.time() - cached.get("checked", 0) > CHECK_EVERY):
+        latest = fetch_latest()
+        if latest:
+            cached = {"checked": time.time(), "latest": latest}
+            _cache().parent.mkdir(parents=True, exist_ok=True)
+            _cache().write_text(json.dumps(cached), "utf-8")
+    cur, latest, method = current(), cached.get("latest"), how_installed()
+    checked = cached.get("checked")
+    return {
+        "current": cur,
+        "latest": latest,
+        "available": newer(latest, cur),
+        "checked": _dt.datetime.fromtimestamp(checked).astimezone().isoformat() if checked else None,
+        "auto": auto,
+        "method": method,
+        "command": COMMANDS[method],
+        "oneClick": method == "uv-tool",
+    }
+
+
+def _tail(*outputs, lines=12):
+    text = "\n".join(o.strip() for o in outputs if o and o.strip())
+    return "\n".join(text.splitlines()[-lines:])
+
+
+def upgrade():
+    """`uv tool upgrade`, then `mem install` from the upgraded code. Returns what happened."""
+    if how_installed() != "uv-tool":
+        return {"ok": False, "error": "This copy was not installed with `uv tool`; update it with the command shown."}
+    before = current()
+    up = subprocess.run([shutil.which("uv"), "tool", "upgrade", PACKAGE], capture_output=True, text=True, timeout=600)
+    if up.returncode != 0:
+        return {"ok": False, "error": "uv tool upgrade failed.", "log": _tail(up.stdout, up.stderr)}
+    # a new process, so both run the upgraded code
+    after = subprocess.run(
+        [sys.executable, "-c", f"import importlib.metadata as m; print(m.version({PACKAGE!r}))"],
+        capture_output=True,
+        text=True,
+    ).stdout.strip()
+    inst = subprocess.run(
+        [sys.executable, "-m", "agent_memory", "install"], capture_output=True, text=True, timeout=120
+    )
+    return {
+        "ok": inst.returncode == 0,
+        "from": before,
+        "to": after or before,
+        "changed": bool(after) and after != before,
+        "error": None if inst.returncode == 0 else "mem install failed after the upgrade.",
+        "log": _tail(up.stdout, up.stderr, inst.stdout, inst.stderr),
+    }