chat-memory-sync 0.1.3__py3-none-any.whl

chat_memory_sync/__init__.py

@@ -0,0 +1,2 @@
+"""chat-memory-sync: unified, searchable memory bank of your AI coding chats."""
+__version__ = "0.1.3"

chat_memory_sync/__main__.py

@@ -0,0 +1,5 @@
+import sys
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main() or 0)

chat_memory_sync/cli.py

@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+"""Unified `chat-memory` CLI."""
+import sys
+from . import __version__
+
+USAGE = """chat-memory - unified memory bank of your AI coding chats
+
+usage: chat-memory <command> [options]
+
+commands:
+  install     set up config, data repo, daily background job, recall command
+  sync        pull -> export all harnesses -> commit -> push (what the job runs)
+  export      export only (no git)
+  recall      search past chats (also available as the `recall` command)
+  doctor      show config, detected harnesses, and chat counts
+  version     print version
+
+examples:
+  chat-memory install --data-remote git@github.com:you/chat-memory.git
+  chat-memory sync
+  chat-memory recall "auth token refresh"
+  recall "rate limiting" --all
+"""
+
+
+def doctor():
+    import os, glob, shutil
+    from . import cmlib
+    print(f"chat-memory-sync {__version__}")
+    print(f"config file : {cmlib.CONFIG_PATH} ({'exists' if os.path.exists(cmlib.CONFIG_PATH) else 'missing'})")
+    print(f"data dir    : {cmlib.data_dir()} ({'ok' if os.path.isdir(cmlib.data_dir()) else 'missing'})")
+    print(f"client      : {cmlib.client_id()}  platform={cmlib.PLATFORM}")
+    print(f"recall idx  : {cmlib.index_db()} ({'built' if os.path.exists(cmlib.index_db()) else 'not built'})")
+    print(f"recall cmd  : {shutil.which('recall') or 'not on PATH'}")
+    n = len(glob.glob(os.path.join(cmlib.projects_dir(), '*', '*', '*.md')))
+    print(f"chats stored: {n}")
+
+
+def main():
+    argv = sys.argv[1:]
+    if not argv or argv[0] in ("-h", "--help", "help"):
+        print(USAGE); return 0
+    cmd, rest = argv[0], argv[1:]
+    if cmd in ("version", "--version", "-V"):
+        print(f"chat-memory-sync {__version__}"); return 0
+    if cmd == "install":
+        from . import install; return install.main(rest)
+    if cmd in ("sync", "run"):
+        from . import run; return run.main()
+    if cmd == "export":
+        from . import sync; return sync.main()
+    if cmd == "recall":
+        from . import recall; return recall.main(rest)
+    if cmd in ("doctor", "status"):
+        return doctor()
+    print(f"unknown command: {cmd}\n", file=sys.stderr)
+    print(USAGE, file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main() or 0)

chat_memory_sync/cmlib.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""
+Shared config/paths for chat-memory-sync.
+
+Decouples the (public) tooling from the (private) data repo:
+
+  - data repo location:  $CHAT_MEMORY_DATA_DIR > config.json "data_dir" > ~/chat-memory
+  - machine-local state: $CHAT_MEMORY_HOME     > ~/.config/chat-memory
+      (holds config.json, index.db, client, sync.log -- never in the data repo)
+  - client name:         $CHAT_MEMORY_CLIENT   > config.json "client" > hostname
+"""
+import os, json, re, platform, socket
+
+HOME = os.path.expanduser("~")
+CONFIG_DIR = os.path.expanduser(os.environ.get("CHAT_MEMORY_HOME") or os.path.join(HOME, ".config", "chat-memory"))
+CONFIG_PATH = os.path.join(CONFIG_DIR, "config.json")
+
+PLATFORM = {"Darwin": "mac", "Windows": "pc", "Linux": "linux"}.get(platform.system(), platform.system().lower())
+
+
+def load_config():
+    try:
+        return json.load(open(CONFIG_PATH))
+    except Exception:
+        return {}
+
+
+def save_config(cfg):
+    os.makedirs(CONFIG_DIR, exist_ok=True)
+    json.dump(cfg, open(CONFIG_PATH, "w"), indent=2)
+
+
+def state_dir():
+    os.makedirs(CONFIG_DIR, exist_ok=True)
+    return CONFIG_DIR
+
+
+def data_dir():
+    v = os.environ.get("CHAT_MEMORY_DATA_DIR")
+    if v:
+        return os.path.abspath(os.path.expanduser(v))
+    c = load_config().get("data_dir")
+    if c:
+        return os.path.abspath(os.path.expanduser(c))
+    return os.path.join(HOME, "chat-memory")
+
+
+def projects_dir():
+    return os.path.join(data_dir(), "projects")
+
+
+def index_db():
+    return os.path.join(state_dir(), "index.db")
+
+
+def _cslug(s):
+    s = re.sub(r"[^\w\-]", "-", (s or "").strip().lower())
+    s = re.sub(r"-+", "-", s).strip("-")
+    return s[:40] or "unknown-client"
+
+
+def client_id():
+    v = os.environ.get("CHAT_MEMORY_CLIENT")
+    if v and v.strip():
+        return _cslug(v)
+    c = load_config().get("client")
+    if c:
+        return _cslug(c)
+    name = socket.gethostname().split(".")[0]
+    cfg = load_config()
+    cfg["client"] = name
+    try:
+        save_config(cfg)
+    except Exception:
+        pass
+    return _cslug(name)

chat_memory_sync/install.py

@@ -0,0 +1,221 @@
+#!/usr/bin/env python3
+"""
+Installer: config + data repo + background job + recall command.
+
+Invoked as `chat-memory install ...`. Registers a daily job that runs
+`chat-memory sync` via the OS scheduler (launchd / Task Scheduler / systemd|cron).
+"""
+import os, sys, subprocess, platform, argparse, getpass, shutil
+from . import cmlib
+
+PY = sys.executable or "python3"
+LABEL = "com.user.chat-memory-sync"
+
+
+def sh(cmd, **kw):
+    print("+", " ".join(cmd) if isinstance(cmd, list) else cmd)
+    return subprocess.run(cmd, **kw)
+
+
+def sync_command():
+    """The command the scheduler should run to perform a sync."""
+    exe = shutil.which("chat-memory")
+    if exe:
+        return [exe, "sync"]
+    return [PY, "-m", "chat_memory_sync", "sync"]
+
+
+def recall_command_str():
+    exe = shutil.which("recall")
+    if exe:
+        return None  # already on PATH via the package entry point
+    return f'"{PY}" -m chat_memory_sync.recall'
+
+
+# ----------------------------------------------------------- schedulers ------
+
+def _mac_launcher(cmd):
+    """Compile a Mach-O named 'chat-memory-sync' so Login Items shows a friendly
+    name instead of the interpreter. Returns its path or None."""
+    cc = shutil.which("cc") or shutil.which("clang")
+    if not cc:
+        return None
+    bindir = os.path.expanduser("~/bin")
+    srcdir = os.path.join(bindir, ".src")
+    os.makedirs(srcdir, exist_ok=True)
+    src = os.path.join(srcdir, "chat-memory-sync.c")
+    out = os.path.join(bindir, "chat-memory-sync")
+    argv = ", ".join(['"chat-memory-sync"'] + [f'"{a}"' for a in cmd[1:]] + ["(char*)0"])
+    open(src, "w").write(
+        "#include <unistd.h>\n#include <sys/wait.h>\nint main(void){\n"
+        "  pid_t p=fork();\n  if(p==0){\n"
+        f"    char *a[]={{{argv}}};\n"
+        f'    execv("{cmd[0]}",a);\n    _exit(127);\n  }}\n'
+        "  int s=0; waitpid(p,&s,0);\n  return WIFEXITED(s)?WEXITSTATUS(s):1;\n}\n")
+    if subprocess.run([cc, "-O2", "-o", out, src], capture_output=True).returncode == 0:
+        return out
+    return None
+
+
+def install_mac(hh, mm):
+    cmd = sync_command()
+    launcher = _mac_launcher(cmd)
+    if launcher:
+        prog = f"<array><string>{launcher}</string></array>"
+    else:
+        prog = "<array>" + "".join(f"<string>{a}</string>" for a in cmd) + "</array>"
+    state = cmlib.state_dir()
+    plist = f"""<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key><string>{LABEL}</string>
+    <key>ProgramArguments</key>
+    {prog}
+    <key>StartCalendarInterval</key>
+    <dict><key>Hour</key><integer>{hh}</integer><key>Minute</key><integer>{mm}</integer></dict>
+    <key>RunAtLoad</key><false/>
+    <key>StandardOutPath</key><string>{state}/launchd.out.log</string>
+    <key>StandardErrorPath</key><string>{state}/launchd.err.log</string>
+</dict>
+</plist>
+"""
+    dest = os.path.expanduser(f"~/Library/LaunchAgents/{LABEL}.plist")
+    os.makedirs(os.path.dirname(dest), exist_ok=True)
+    open(dest, "w").write(plist)
+    uid = os.getuid()
+    subprocess.run(["launchctl", "bootout", f"gui/{uid}/{LABEL}"], capture_output=True)
+    subprocess.run(["launchctl", "load", dest])
+    print(f"launchd job installed -> {dest}  (daily {hh:02d}:{mm:02d})")
+
+
+def install_windows(hh, mm):
+    cmd = sync_command()
+    tr = " ".join(f'"{a}"' if " " in a else a for a in cmd)
+    sh(["schtasks", "/Create", "/F", "/TN", "ChatMemorySync",
+        "/SC", "DAILY", "/ST", f"{hh:02d}:{mm:02d}", "/TR", tr])
+    print(f"Task Scheduler job 'ChatMemorySync' installed (daily {hh:02d}:{mm:02d})")
+
+
+def install_linux(hh, mm):
+    cmd = " ".join(sync_command())
+    unit_dir = os.path.expanduser("~/.config/systemd/user")
+    have_systemd = subprocess.run(["systemctl", "--user", "--version"],
+                                  capture_output=True).returncode == 0
+    if have_systemd:
+        os.makedirs(unit_dir, exist_ok=True)
+        open(os.path.join(unit_dir, "chat-memory-sync.service"), "w").write(
+            f"[Unit]\nDescription=chat-memory sync\n\n[Service]\nType=oneshot\n"
+            f"ExecStart={cmd}\n")
+        open(os.path.join(unit_dir, "chat-memory-sync.timer"), "w").write(
+            f"[Unit]\nDescription=daily chat-memory sync\n\n[Timer]\n"
+            f"OnCalendar=*-*-* {hh:02d}:{mm:02d}:00\nPersistent=true\n\n"
+            f"[Install]\nWantedBy=timers.target\n")
+        sh(["systemctl", "--user", "daemon-reload"])
+        sh(["systemctl", "--user", "enable", "--now", "chat-memory-sync.timer"])
+        print(f"systemd user timer installed (daily {hh:02d}:{mm:02d}). "
+              f"Tip: `loginctl enable-linger {getpass.getuser()}` to run while logged out.")
+        return
+    line = f"{mm} {hh} * * * {cmd} >> {cmlib.state_dir()}/cron.log 2>&1"
+    cur = subprocess.run(["crontab", "-l"], capture_output=True, text=True).stdout
+    lines = [l for l in cur.splitlines() if "chat-memory" not in l]
+    lines.append(line + "  # chat-memory")
+    subprocess.run(["crontab", "-"], input="\n".join(lines) + "\n", text=True)
+    print(f"cron job installed (daily {hh:02d}:{mm:02d})")
+
+
+def install_recall_launcher():
+    if shutil.which("recall"):
+        print("recall command already on PATH (package entry point)")
+        return
+    cmd = recall_command_str()
+    home = os.path.expanduser("~")
+    if platform.system() == "Windows":
+        bindir = os.path.join(home, "bin")
+        os.makedirs(bindir, exist_ok=True)
+        p = os.path.join(bindir, "recall.cmd")
+        open(p, "w").write(f'@echo off\r\n{cmd} %*\r\n')
+        print(f"recall command -> {p}  (ensure {bindir} is on PATH)")
+        return
+    path_dirs = os.environ.get("PATH", "").split(":")
+    prefs = [os.path.join(home, ".local/bin"), os.path.join(home, "bin")]
+    bindir = next((d for d in prefs if d in path_dirs), os.path.join(home, "bin"))
+    os.makedirs(bindir, exist_ok=True)
+    p = os.path.join(bindir, "recall")
+    open(p, "w").write(f'#!/bin/bash\nexec {cmd} "$@"\n')
+    os.chmod(p, 0o755)
+    print(f"recall command -> {p}" + ("" if bindir in path_dirs else f"  (add {bindir} to PATH)"))
+
+
+# ----------------------------------------------------------- data repo -------
+
+def setup_data_repo(data_dir, remote):
+    if os.path.isdir(os.path.join(data_dir, ".git")):
+        print(f"data repo already present: {data_dir}")
+        return
+    os.makedirs(os.path.dirname(os.path.abspath(data_dir)) or ".", exist_ok=True)
+    if remote:
+        if sh(["git", "clone", remote, data_dir]).returncode != 0:
+            print("clone failed; initializing empty repo instead")
+            _init_repo(data_dir, remote)
+    else:
+        _init_repo(data_dir, None)
+
+
+def _init_repo(data_dir, remote):
+    os.makedirs(data_dir, exist_ok=True)
+    sh(["git", "init", "-q", data_dir])
+    if remote:
+        sh(["git", "-C", data_dir, "remote", "add", "origin", remote])
+
+
+# ----------------------------------------------------------------- main ------
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="chat-memory install")
+    ap.add_argument("--data-remote", help="git URL of your private data repo (recommended)")
+    ap.add_argument("--data-dir", help="where the data repo lives (default ~/chat-memory)")
+    ap.add_argument("--client", help="name for this machine (default: hostname)")
+    ap.add_argument("--time", default="21:00", help="daily run time HH:MM (default 21:00)")
+    ap.add_argument("--no-job", action="store_true", help="skip registering the background job")
+    args = ap.parse_args(argv)
+
+    cfg = cmlib.load_config()
+    data_dir = os.path.abspath(os.path.expanduser(
+        args.data_dir or cfg.get("data_dir") or os.path.join(cmlib.HOME, "chat-memory")))
+    cfg["data_dir"] = data_dir
+    if args.client:
+        cfg["client"] = args.client.strip()
+    cmlib.save_config(cfg)
+    print(f"config -> {cmlib.CONFIG_PATH}\n  data_dir = {data_dir}\n  client   = {cmlib.client_id()}")
+
+    try:
+        hh, mm = [int(x) for x in args.time.split(":")]
+    except Exception:
+        print("bad --time, expected HH:MM"); sys.exit(1)
+
+    print("\n== data repo ==")
+    setup_data_repo(data_dir, args.data_remote)
+
+    print("\n== first run ==")
+    if subprocess.run(sync_command()).returncode != 0:
+        print("first run returned non-zero; check the log in", cmlib.state_dir())
+
+    if not args.no_job:
+        print("\n== background job ==")
+        s = platform.system()
+        (install_mac if s == "Darwin" else install_windows if s == "Windows" else install_linux)(hh, mm)
+
+    print("\n== recall command ==")
+    install_recall_launcher()
+
+    print("\nDone. The background job keeps this machine's chats synced daily.")
+    has_origin = subprocess.run(["git", "remote", "get-url", "origin"],
+                                cwd=data_dir, capture_output=True).returncode == 0
+    if not has_origin:
+        print("NOTE: data repo has no 'origin' remote - chats commit locally but won't push.\n"
+              f"      git -C {data_dir} remote add origin <url> && git -C {data_dir} push -u origin HEAD")
+
+
+if __name__ == "__main__":
+    main()

chat_memory_sync/recall.py

@@ -0,0 +1,231 @@
+#!/usr/bin/env python3
+"""
+recall - find relevant past chats without scanning the whole repo.
+
+Builds a local SQLite full-text index (BM25) over all chat markdown and queries
+it, auto-scoped to the current project. The index (.sync/index.db) is rebuilt
+automatically when chats change; it is machine-local (gitignored).
+
+Usage:
+  recall "affiliate tier rebate"              # auto-scope to CWD's project
+  recall "worktree flow" --project based-one-mono
+  recall "nesting model" --all                # search every project
+  recall "payout bug" --harness cursor --since 2026-09 -k 10
+  recall "..." --full                         # print file paths only (for piping)
+  recall --reindex                            # force rebuild the index
+
+Agents: run this from inside the repo you're working on, read the top hits,
+then open those files for full context.
+"""
+import os, sys, re, glob, sqlite3, argparse, datetime
+from . import cmlib
+
+REPO = cmlib.data_dir()
+PROJ_DIR = cmlib.projects_dir()
+DB = cmlib.index_db()
+
+WS_MARKERS = ["/ws/", "/pspace/", "/src/", "/code/", "/projects/", "/Developer/"]
+
+def _slug(s, n=60):
+    s = re.sub(r"\s+", " ", (s or "").strip())
+    s = re.sub(r"[^\w\- ]", "", s).strip().replace(" ", "-")
+    return s[:n] or ""
+
+def canonical_project(path):
+    if not path:
+        return ""
+    p = os.path.abspath(path).rstrip("/")
+    for m in WS_MARKERS:
+        i = p.find(m)
+        if i != -1:
+            rest = [x for x in p[i + len(m):].split("/") if x]
+            if not rest:
+                continue
+            if rest[0] == ".worktrees" and len(rest) > 1:
+                return _slug(rest[1])
+            return _slug(rest[0])
+    return _slug(os.path.basename(p))
+
+def read_frontmatter(path):
+    fm = {}
+    try:
+        with open(path, encoding="utf-8", errors="ignore") as f:
+            if f.readline().strip() != "---":
+                return fm
+            for _ in range(40):
+                line = f.readline()
+                if not line or line.strip() == "---":
+                    break
+                m = re.match(r"^(\w+):\s*(.*)$", line.rstrip("\n"))
+                if m:
+                    k, v = m.group(1), m.group(2).strip().strip('"')
+                    fm[k] = v
+    except Exception:
+        pass
+    return fm
+
+def has_fts5():
+    try:
+        c = sqlite3.connect(":memory:")
+        c.execute("CREATE VIRTUAL TABLE t USING fts5(x)")
+        c.close()
+        return True
+    except Exception:
+        return False
+
+def newest_md_mtime():
+    mt = 0.0
+    for p in glob.glob(os.path.join(PROJ_DIR, "*", "*", "*.md")):
+        try:
+            mt = max(mt, os.path.getmtime(p))
+        except OSError:
+            pass
+    return mt
+
+def build_index():
+    """Contentless FTS5 index: we store only metadata + the inverted index, never
+    a copy of the chat text. Snippets are generated from the source files at query
+    time. Keeps the DB small (no duplicated transcripts)."""
+    if os.path.exists(DB):
+        os.remove(DB)
+    con = sqlite3.connect(DB)
+    con.execute("""CREATE TABLE d(
+        rowid INTEGER PRIMARY KEY, project TEXT, harness TEXT, client TEXT,
+        date TEXT, title TEXT, path TEXT)""")
+    con.execute("CREATE INDEX idx_proj ON d(project)")
+    fts = has_fts5()
+    if fts:
+        con.execute("CREATE VIRTUAL TABLE fts USING fts5(body, content='')")
+    rid = 0
+    for p in glob.glob(os.path.join(PROJ_DIR, "*", "*", "*.md")):
+        fm = read_frontmatter(p)
+        proj = os.path.basename(os.path.dirname(os.path.dirname(p)))
+        try:
+            body = open(p, encoding="utf-8", errors="ignore").read()
+        except Exception:
+            continue
+        rid += 1
+        con.execute("INSERT INTO d VALUES(?,?,?,?,?,?,?)",
+                    (rid, proj, fm.get("harness", ""), fm.get("client", ""),
+                     (fm.get("updated") or fm.get("created") or "")[:10],
+                     fm.get("title", ""), os.path.relpath(p, REPO)))
+        if fts:
+            con.execute("INSERT INTO fts(rowid, body) VALUES(?,?)", (rid, fm.get("title", "") + "\n" + body))
+    con.commit()
+    con.execute("PRAGMA user_version=2")
+    con.commit()
+    con.close()
+    return rid
+
+def ensure_index(force=False):
+    if force or not os.path.exists(DB) or os.path.getmtime(DB) < newest_md_mtime():
+        n = build_index()
+        return n
+    return None
+
+def make_snippet(path, query, width=180):
+    """Pull a short context window around the first query term from the file."""
+    terms = [t for t in re.split(r"\W+", query.lower()) if len(t) > 1]
+    try:
+        text = open(os.path.join(REPO, path), encoding="utf-8", errors="ignore").read()
+    except Exception:
+        return ""
+    # start searching after the YAML frontmatter so snippets show real content
+    body_start = 0
+    if text.startswith("---"):
+        end = text.find("\n---", 3)
+        if end != -1:
+            body_start = end + 4
+    low = text.lower()
+    hits = [low.find(t, body_start) for t in terms if low.find(t, body_start) != -1]
+    pos = min(hits) if hits else body_start
+    s = max(body_start, pos - width // 3)
+    seg = re.sub(r"\s+", " ", text[s:s + width]).strip()
+    for t in terms:
+        seg = re.sub("(" + re.escape(t) + ")", r">>\1<<", seg, flags=re.I)
+    return seg
+
+def search(query, project=None, harness=None, since=None, k=8):
+    con = sqlite3.connect(DB)
+    con.row_factory = sqlite3.Row
+    fts = has_fts5()
+    where, params = [], []
+    if project:
+        where.append("d.project = ?"); params.append(project)
+    if harness:
+        where.append("d.harness = ?"); params.append(harness)
+    if since:
+        where.append("d.date >= ?"); params.append(since)
+    filt = (" AND " + " AND ".join(where)) if where else ""
+    rows = []
+    if fts:
+        try:
+            sql = (f"SELECT d.*, bm25(fts) AS score FROM fts JOIN d ON d.rowid = fts.rowid "
+                   f"WHERE fts MATCH ?{filt} ORDER BY score LIMIT ?")
+            rows = con.execute(sql, [query] + params + [k]).fetchall()
+        except sqlite3.OperationalError:
+            rows = []
+    if not rows:  # fallback: read files and score by term frequency
+        terms = [t for t in re.split(r"\s+", query.lower()) if t]
+        cand = con.execute(f"SELECT d.* FROM d WHERE 1=1{filt}", params).fetchall()
+        scored = []
+        for r in cand:
+            try:
+                b = open(os.path.join(REPO, r["path"]), encoding="utf-8", errors="ignore").read().lower()
+            except Exception:
+                continue
+            sc = sum(b.count(t) for t in terms)
+            if sc:
+                scored.append((sc, r))
+        scored.sort(key=lambda x: -x[0])
+        rows = [r for _, r in scored[:k]]
+    con.close()
+    return [(r, make_snippet(r["path"], query)) for r in rows]
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="recall", description="find relevant past chats")
+    ap.add_argument("query", nargs="?", default="")
+    ap.add_argument("--project", help="project to scope to (default: infer from CWD)")
+    ap.add_argument("--all", action="store_true", help="search all projects")
+    ap.add_argument("--harness", help="cursor|cursor-agent|claude-code|opencode|pi|codex|gemini")
+    ap.add_argument("--since", help="YYYY-MM or YYYY-MM-DD lower bound")
+    ap.add_argument("-k", type=int, default=8, help="max results (default 8)")
+    ap.add_argument("--full", action="store_true", help="print file paths only")
+    ap.add_argument("--reindex", action="store_true", help="force rebuild index")
+    args = ap.parse_args(argv)
+
+    n = ensure_index(force=args.reindex)
+    if args.reindex or n is not None:
+        print(f"[indexed {n if n is not None else '?'} chats]", file=sys.stderr)
+    if not args.query:
+        if args.reindex:
+            return
+        ap.error("provide a search query")
+
+    project = None if args.all else (args.project or canonical_project(os.getcwd()) or None)
+    if project and not args.all:
+        # only scope if that project actually exists in the repo
+        if not os.path.isdir(os.path.join(PROJ_DIR, project)):
+            print(f"[no chats for project '{project}'; searching all]", file=sys.stderr)
+            project = None
+
+    rows = search(args.query, project=project, harness=args.harness,
+                  since=args.since, k=args.k)
+    if not rows:
+        print("No matches.", file=sys.stderr)
+        return
+    if args.full:
+        for r, _ in rows:
+            print(os.path.join(REPO, r["path"]))
+        return
+    scope = f"project={project}" if project else "all projects"
+    print(f"Top {len(rows)} for \"{args.query}\" ({scope}):\n")
+    for i, (r, snip) in enumerate(rows, 1):
+        print(f"{i}. {r['date']}  [{r['harness']}/{r['client']}]  {r['title']}")
+        print(f"   {r['path']}")
+        if snip:
+            print(f"   … {snip} …")
+        print()
+
+if __name__ == "__main__":
+    main()