memware 0.2.0__tar.gz → 0.2.2__tar.gz

{memware-0.2.0 → memware-0.2.2}/CHANGELOG.md

@@ -6,9 +6,22 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.2.2] - 2026-09-03
+
+### Fixed
+- Backup retention now **promotes**: a snapshot ages forward through the 1/3/7/14-day tiers
+  instead of being pruned between them. The previous rule pruned every snapshot at age ~2, so a
+  daily-backup loop only ever kept a 0- and 1-day-old and never built a 3/7/14-day-old. Retention
+  keeps the newest plus the oldest per age band, always has a fresh ~1-day-old, drifts within
+  older tiers, prunes past the largest tier, and stays bounded (~5). Verified with a 30-day loop.
+
+
+## [0.2.1] - 2026-09-03
+
 ## [0.2.0] - 2026-09-03
 
 ### Added
+- Automatic backups with no scheduler: the Claude Code plugin and Hermes provider run a throttled `memware backup --if-stale` at session end (config `backup.auto`, `backup.auto_interval_hours`), so backups ride usage and survive a sleeping laptop. `--if-stale HOURS`/`--quiet` make `backup` safe to call from any hook or cron.
 - Backups: `memware backup` writes a consistent snapshot (VACUUM INTO) to a storage-agnostic
   folder (Dropbox/iCloud/Drive/external disk) with tiered retention (newest + 1/3/7/14-day),
   and mirrors transcripts into `<dest>/transcripts` so they outlive the OS's 30-day cleanup.

{memware-0.2.0 → memware-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: memware
-Version: 0.2.0
+Version: 0.2.2
 Summary: Memory for AI agents that only remembers the latest truth: a bi-temporal belief ledger plus a transcript index, in one SQLite file.
 Project-URL: Homepage, https://github.com/ericwalisko/memware
 Project-URL: Issues, https://github.com/ericwalisko/memware/issues
@@ -172,7 +172,8 @@ Prompt-time injection (the hooks) stays deterministic and only injects beliefs w
 Transcripts are deleted by the OS after ~30 days, so an aged session lives only in the store —
 **back it up, and never wipe-and-re-backfill** (backfill only re-indexes transcripts still on
 disk). memware guards this: migrations snapshot first, and `backfill` warns if a backup is
-larger than the store.
+larger than the store. Once a destination is set, backups happen **automatically at session
+end (~once a day)** — no cron, and immune to a laptop sleeping through a scheduled time.
 
 ```bash
 memware setup                              # pick a folder: Dropbox / iCloud / Drive / external disk

{memware-0.2.0 → memware-0.2.2}/README.md

@@ -141,7 +141,8 @@ Prompt-time injection (the hooks) stays deterministic and only injects beliefs w
 Transcripts are deleted by the OS after ~30 days, so an aged session lives only in the store —
 **back it up, and never wipe-and-re-backfill** (backfill only re-indexes transcripts still on
 disk). memware guards this: migrations snapshot first, and `backfill` warns if a backup is
-larger than the store.
+larger than the store. Once a destination is set, backups happen **automatically at session
+end (~once a day)** — no cron, and immune to a laptop sleeping through a scheduled time.
 
 ```bash
 memware setup                              # pick a folder: Dropbox / iCloud / Drive / external disk

{memware-0.2.0 → memware-0.2.2}/docs/backup.md

@@ -35,23 +35,50 @@ memware backup         # writes memware-YYYYMMDD-HHMMSS.db, prunes to the retent
                        # and (by default) mirrors transcripts into <dest>/transcripts
 ```
 
-**Retention** keeps the newest snapshot plus the newest one at least 1, 3, 7 and 14 days old —
-roughly a 1-, 3-, 7- and 14-day-old backup at all times, not an unbounded pile. Tune with
-`backup.keep_days`.
+**Retention promotes.** Because memware only ever *creates* fresh snapshots, retention lets a
+snapshot **age forward** through the tiers rather than pruning it in between: it keeps the newest
+snapshot and the oldest one in each age band `(0,1] (1,3] (3,7] (7,14]`, so the same file serves
+as the ~1-day-old, then the ~3-, ~7-, ~14-day-old as time passes. You always have a fresh
+~1-day-old; the older tiers drift a little (that is fine and expected); anything past the largest
+tier is pruned. The pile stays bounded (~5). Tune the tiers with `backup.keep_days`.
 
 **Transcripts.** `backup.include_transcripts` (on by default) mirrors your transcript source
 (default `~/.claude/projects`) into `<dest>/transcripts`, additively — an append-only archive
 that outlives the 30-day cleanup. Already back transcripts up elsewhere? Point memware at that
 location with `backup.transcript_src` and it will read from there too.
 
-## Schedule it
-
-Any scheduler works; memware just needs to run `memware backup` daily. macOS `launchd`, Linux
-`cron`, or a coding-agent cron all do. Example (cron, 3 a.m.):
-
-```cron
-0 3 * * * /path/to/memware backup >/dev/null 2>&1
-```
+## How it stays current on its own (no scheduler)
+
+Once a backup destination is set (`memware setup`), the Claude Code plugin and the Hermes
+provider back up **automatically at session end, at most once per `backup.auto_interval_hours`
+(default 20)**. This rides your usage rather than a clock, so it is immune to the sleep problem:
+a laptop only needs to be awake *while you are using it*, which it is. Nothing to schedule, and
+a missed day simply catches up on your next session. Turn it off with
+`memware config backup.auto false`.
+
+Both the snapshot and the transcript mirror happen in that one throttled run, so a laptop user
+who never sets up a cron still gets: the store snapshotted off-machine, and transcripts archived
+before the OS's 30-day cleanup can reach them.
+
+## Scheduling on an always-on machine (optional)
+
+If a box is always on and you want backups on a fixed clock regardless of whether anyone used
+it that day, add a scheduled job. Pick the one that fits — and note that **plain `cron` skips
+runs that fall while the machine is asleep or off**, so it is the wrong choice for a laptop:
+
+- **macOS — `launchd`** (sleep-tolerant: a missed `StartCalendarInterval` runs on wake):
+  a `~/Library/LaunchAgents/*.plist` with `StartCalendarInterval` (hour 3) calling
+  `memware backup`.
+- **Linux — `systemd` timer** with `Persistent=true` (runs a missed timer on next boot/wake):
+  a `memware-backup.timer` + `.service` pair, `OnCalendar=daily`.
+- **Linux — `anacron`** if the machine is often off: a daily job that runs when the box is next
+  up. Plain `cron` does not do this.
+- **Coding-agent cron** (e.g. a Hermes `--no-agent` job): fine on an always-on host; same sleep
+  caveat as `cron`.
+
+`memware backup --if-stale HOURS` is safe to call from any of these too — it no-ops if a recent
+snapshot already exists, so the automatic session-end backup and a scheduled one never
+double up.
 
 ## Restore
 

memware-0.2.2/integrations/claude-code/hooks/hooks.json

@@ -0,0 +1,42 @@
+{
+  "hooks": {
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "memware sync --harness claude-code --from-hook",
+            "timeout": 30
+          },
+          {
+            "type": "command",
+            "command": "memware backup --if-stale 20 --quiet",
+            "timeout": 120
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "memware sync --harness claude-code --from-hook",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "memware context --from-hook -k 6",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

{memware-0.2.0 → memware-0.2.2}/integrations/hermes/memware/__init__.py

@@ -266,6 +266,31 @@ class MemwareProvider(MemoryProvider):
         self._sync_thread = threading.Thread(target=_run, daemon=True)
         self._sync_thread.start()
 
+    def _auto_backup(self) -> None:
+        """Ride usage: after a session, snapshot at most once per configured interval when a
+        backup dest is set. No cron needed — the machine only needs to be on while in use."""
+        try:
+            from memware import backup as bk
+            from memware.config import get_dotted, load_config
+
+            cfg = load_config()
+            dest = get_dotted(cfg, "backup.dest")
+            if not dest or not get_dotted(cfg, "backup.auto"):
+                return
+            interval = float(get_dotted(cfg, "backup.auto_interval_hours") or 20)
+            age = bk.newest_age_hours(dest)
+            if age is not None and age < interval:
+                return
+            keep = get_dotted(cfg, "backup.keep_days") or [1, 3, 7, 14]
+            bk.snapshot(self._db, dest)
+            bk.apply_retention(dest, keep)
+            if get_dotted(cfg, "backup.include_transcripts"):
+                bk.mirror_transcripts(
+                    get_dotted(cfg, "backup.transcript_src") or "~/.claude/projects", dest
+                )
+        except Exception as e:
+            logger.warning("memware auto-backup failed: %s", e)
+
     def on_session_end(self, messages: list[dict[str, Any]], **kwargs: Any) -> None:
         self.shutdown()
         # turns were captured incrementally; re-sync the file once for anything missed
@@ -279,6 +304,7 @@ class MemwareProvider(MemoryProvider):
                     sync_file(s, path, harness="generic")
         except Exception as e:
             logger.warning("memware on_session_end failed: %s", e)
+        self._auto_backup()
 
     def on_pre_compress(self, messages: list[dict[str, Any]], **kwargs: Any) -> None:
         self.on_session_end(messages, **kwargs)

{memware-0.2.0 → memware-0.2.2}/src/memware/__init__.py

@@ -22,4 +22,4 @@ __all__ = [
     "history",
     "reject",
 ]
-__version__ = "0.2.0"
+__version__ = "0.2.2"

{memware-0.2.0 → memware-0.2.2}/src/memware/backup.py

@@ -54,24 +54,43 @@ def _stamp(p: Path) -> datetime:
     return datetime.strptime(m.group(1), "%Y%m%d-%H%M%S").replace(tzinfo=UTC)
 
 
-def apply_retention(dest_dir: str | os.PathLike[str], keep_days: list[int]) -> list[Path]:
-    """Tiered retention. Always keep the newest snapshot; then for each age bucket in
-    ``keep_days`` (e.g. [1,3,7,14]) keep the newest snapshot at least that old. Delete the
-    rest. Returns the deleted paths. This yields, over time, roughly one 1-, 3-, 7- and
-    14-day-old backup plus the latest — not an unbounded pile."""
+def newest_age_hours(dest_dir: str | os.PathLike[str]) -> float | None:
+    """Hours since the newest snapshot in ``dest_dir``, or None if there are none."""
     snaps = list_snapshots(dest_dir)
+    if not snaps:
+        return None
+    return (_now().timestamp() - _stamp(snaps[0]).timestamp()) / 3600.0
+
+
+def _age_days(p: Path, now: datetime) -> float:
+    return (now.timestamp() - _stamp(p).timestamp()) / 86400.0
+
+
+def apply_retention(dest_dir: str | os.PathLike[str], keep_days: list[int]) -> list[Path]:
+    """Promotion retention: since we only ever *create* fresh snapshots, a snapshot must be
+    allowed to **age forward** into the next tier rather than be pruned between tiers.
+
+    Bands are the contiguous intervals ``(0, d0], (d0, d1], …`` for sorted ``keep_days``
+    (default 1,3,7,14). We keep the newest snapshot overall (tomorrow's ~1-day-old) and the
+    *oldest* snapshot in each band — the oldest is the one on the leading edge, so as days
+    pass it crosses into the next band and stays kept, i.e. the same file serves as the ~1-,
+    then ~3-, ~7-, ~14-day-old. Everything else, and anything older than the largest tier,
+    is pruned. Result: always a ~1-day-old, roughly one per tier (they drift; that's fine),
+    and a bounded pile of ~len(keep_days)+1. Returns the deleted paths."""
+    snaps = list_snapshots(dest_dir)  # newest first
     if not snaps:
         return []
     now = _now()
-    keep: set[Path] = {snaps[0]}  # newest always
-    for days in sorted(set(keep_days)):
-        cutoff = now.timestamp() - days * 86400
-        aged = [p for p in snaps if _stamp(p).timestamp() <= cutoff]
-        if aged:
-            keep.add(aged[0])  # newest that is at least `days` old
+    days = sorted(set(int(d) for d in keep_days))
+    keep: set[Path] = {snaps[0]}  # always the freshest
+    edges = [0.0, *[float(d) for d in days]]
+    for lo, hi in zip(edges, edges[1:], strict=False):
+        band = [p for p in snaps if lo < _age_days(p, now) <= hi]
+        if band:
+            keep.add(band[-1])  # oldest in the band (snaps are newest-first) -> promotes forward
     deleted = []
     for p in snaps:
-        if p not in keep:
+        if p not in keep:  # includes anything older than the largest tier
             p.unlink(missing_ok=True)
             deleted.append(p)
     return deleted

{memware-0.2.0 → memware-0.2.2}/src/memware/cli.py

@@ -286,12 +286,24 @@ def cmd_backup(a: argparse.Namespace) -> int:
     cfg = load_config()
     dest = a.dest or get_dotted(cfg, "backup.dest")
     if not dest:
+        if a.if_stale is not None:
+            return 0  # hook-driven: no destination configured yet, stay silent
         print(
             "no backup destination — pass --dest DIR or run `memware setup` "
             "(point it at a Dropbox/iCloud/Drive folder or an external disk)",
             file=sys.stderr,
         )
         return 2
+    if a.if_stale is not None:
+        # throttle: skip if a snapshot already exists within the window (so this is safe to
+        # call from every session-end hook — the backup rides usage, not a clock).
+        if not get_dotted(cfg, "backup.auto") and not a.dest:
+            return 0
+        age = bk.newest_age_hours(dest)
+        if age is not None and age < a.if_stale:
+            if not a.quiet:
+                _out({"skipped": "recent", "age_hours": round(age, 1)}, a.json)
+            return 0
     keep = a.keep or get_dotted(cfg, "backup.keep_days") or [1, 3, 7, 14]
     out = bk.snapshot(a.db, dest)
     deleted = bk.apply_retention(dest, keep)
@@ -306,7 +318,8 @@ def cmd_backup(a: argparse.Namespace) -> int:
     if include:
         src = a.transcript_src or get_dotted(cfg, "backup.transcript_src") or "~/.claude/projects"
         result["transcripts_mirrored"] = bk.mirror_transcripts(src, dest)
-    _out(result, a.json)
+    if not a.quiet:
+        _out(result, a.json)
     return 0
 
 
@@ -563,6 +576,14 @@ def build_parser() -> argparse.ArgumentParser:
     )
     s.add_argument("--no-transcripts", dest="transcripts", action="store_false")
     s.add_argument("--transcript-src", metavar="DIR")
+    s.add_argument(
+        "--if-stale",
+        type=float,
+        metavar="HOURS",
+        help="only back up if the newest snapshot is older than HOURS "
+        "(safe to call from every session-end hook; no-op when no dest is set)",
+    )
+    s.add_argument("--quiet", action="store_true", help="print nothing on success")
     s.set_defaults(fn=cmd_backup)
 
     s = add("restore", "replace the store with a snapshot (the current store is saved aside first)")

{memware-0.2.0 → memware-0.2.2}/src/memware/config.py

@@ -28,6 +28,8 @@ DEFAULTS: dict[str, Any] = {
         "keep_days": [1, 3, 7, 14],  # tiered retention: newest snapshot per age bucket
         "include_transcripts": True,  # also mirror the transcript source into <dest>/transcripts
         "transcript_src": "~/.claude/projects",  # what to mirror / where backfill also reads
+        "auto": True,  # when a dest is set, the session-end hook backs up ~once/day (no cron needed)
+        "auto_interval_hours": 20,  # minimum gap between automatic backups
     },
 }
 

{memware-0.2.0 → memware-0.2.2}/tests/test_backup.py

@@ -31,20 +31,60 @@ def test_snapshot_is_consistent_and_restore_round_trips(tmp_path):
         assert s.stats()["turns"] == 5
 
 
-def test_tiered_retention_keeps_one_per_bucket(tmp_path):
+def _age_all(dest):
+    """Rename every snapshot one day older — how we advance the clock against the real _now()."""
+    import datetime as dt
+
+    for p in sorted(dest.glob("memware-*.db")):
+        stamp = bk._stamp(p) - dt.timedelta(days=1)
+        p.rename(dest / f"memware-{stamp.strftime('%Y%m%d-%H%M%S')}.db")
+
+
+def _ages(dest):
+    import datetime as dt
+
+    now = dt.datetime.now(dt.UTC)
+    return sorted((now - bk._stamp(p)).total_seconds() / 86400.0 for p in bk.list_snapshots(dest))
+
+
+def test_retention_promotes_and_stays_bounded_over_a_daily_loop(tmp_path):
+    """The real usage pattern: one new snapshot per day, retention each day. A snapshot must age
+    forward through the tiers (not be pruned between them), there is always a ~1-day-old, the pile
+    stays small, and nothing lingers far past the largest tier. Files are dated in real time and
+    aged by renaming, so this exercises the true `_now()`-based logic."""
     import datetime as dt
 
     dest = tmp_path / "b"
     dest.mkdir()
-    now = dt.datetime.now(dt.UTC)
-    # one snapshot per day for 20 days
-    for age in range(20):
-        stamp = (now - dt.timedelta(days=age)).strftime("%Y%m%d-%H%M%S")
+    for _day in range(30):
+        _age_all(dest)  # yesterday's snapshots become a day older
+        stamp = dt.datetime.now(dt.UTC).strftime("%Y%m%d-%H%M%S")  # a fresh age-0 today
         (dest / f"memware-{stamp}.db").write_bytes(b"x")
+        bk.apply_retention(dest, [1, 3, 7, 14])
+
+    ages = _ages(dest)
+    assert min(ages) < 1  # always a fresh ~1-day-old
+    assert len(ages) <= 6  # bounded, not an unbounded pile
+    assert max(ages) <= 15  # nothing lingers far past the largest tier
+    assert any(2 <= a <= 9 for a in ages)  # a snapshot promoted into the mid tiers (drift ok)
+    assert any(a >= 10 for a in ages)  # and one aged into the oldest tier
+
+
+def test_retention_prunes_snapshots_older_than_the_largest_tier(tmp_path):
+    dest = tmp_path / "b"
+    dest.mkdir()
+    for age in (0, 2, 6, 13, 20, 40):  # 20 and 40 are past the 14-day tier
+        _write_dated(dest, age)
     bk.apply_retention(dest, [1, 3, 7, 14])
-    kept = bk.list_snapshots(dest)
-    # newest + one each at >=1,>=3,>=7,>=14 days = at most 5, far fewer than 20
-    assert 4 <= len(kept) <= 5
+    assert all(a <= 15 for a in _ages(dest))
+
+
+def _write_dated(dest, age_days):
+    import datetime as dt
+
+    dest.mkdir(parents=True, exist_ok=True)
+    stamp = (dt.datetime.now(dt.UTC) - dt.timedelta(days=age_days)).strftime("%Y%m%d-%H%M%S")
+    (dest / f"memware-{stamp}.db").write_bytes(b"x")
 
 
 def test_backup_cli_uses_config_dest_and_mirrors_transcripts(tmp_path, capsys, monkeypatch):
@@ -100,3 +140,21 @@ def test_backfill_warns_when_backup_is_larger(tmp_path, capsys, monkeypatch):
     main(["--db", str(db), "backfill", str(proj)])
     err = capsys.readouterr().err
     assert "restore" in err and "400" in err
+
+
+def test_if_stale_throttles_and_no_dest_is_silent_noop(tmp_path, capsys, monkeypatch):
+    monkeypatch.setenv("MEMWARE_HOME", str(tmp_path / "home"))
+    db = _seed(tmp_path / "m.db", 2)
+    # no dest configured yet: --if-stale is a silent no-op (safe from a hook)
+    assert main(["--db", str(db), "backup", "--if-stale", "20", "--quiet"]) == 0
+    assert capsys.readouterr().out == ""
+    dest = tmp_path / "bk"
+    main(["--db", str(db), "config", "backup.dest", str(dest)])
+    capsys.readouterr()
+    # first stale-check has no snapshot yet -> it backs up
+    assert main(["--db", str(db), "backup", "--if-stale", "20", "--no-transcripts", "--json"]) == 0
+    n1 = len(bk.list_snapshots(dest))
+    assert n1 == 1
+    # immediate second call is within the window -> skipped, no new snapshot
+    assert main(["--db", str(db), "backup", "--if-stale", "20", "--no-transcripts", "--json"]) == 0
+    assert len(bk.list_snapshots(dest)) == n1

memware-0.2.0/integrations/claude-code/hooks/hooks.json

@@ -1,13 +0,0 @@
-{
-  "hooks": {
-    "SessionEnd": [
-      { "hooks": [ { "type": "command", "command": "memware sync --harness claude-code --from-hook", "timeout": 30 } ] }
-    ],
-    "PreCompact": [
-      { "hooks": [ { "type": "command", "command": "memware sync --harness claude-code --from-hook", "timeout": 30 } ] }
-    ],
-    "UserPromptSubmit": [
-      { "hooks": [ { "type": "command", "command": "memware context --from-hook -k 6", "timeout": 10 } ] }
-    ]
-  }
-}